camoufox-cli

使用 camoufox-cli 进行反检测浏览器自动化

核心工作流

每项浏览器自动化任务都遵循以下模式：

1. 导航：camoufox-cli open <url>
2. 快照：camoufox-cli snapshot -i（获取元素引用，如 @e1、@e2）
3. 交互：使用引用执行点击、填充和选择操作
4. 重新获取快照：导航或 DOM 发生变化后，获取新的引用
5. 关闭：整个任务完成后运行 camoufox-cli close — 使用与其他命令相同的 --tab/--session 标志。如果用户可能会提供后续指示，则保持浏览器打开。

camoufox-cli open https://example.com/form
camoufox-cli snapshot -i
# Output: - textbox "Email" [ref=e1]
#         - textbox "Password" [ref=e2]
#         - button "Submit" [ref=e3]

camoufox-cli fill @e1 "[email protected]"
camoufox-cli fill @e2 "password123"
camoufox-cli click @e3
camoufox-cli snapshot -i  # Check result

命令串联

可在一次 Shell 调用中使用 && 串联命令。浏览器会通过后台守护进程在命令之间保持运行，因此串联命令既安全又比单独调用更高效。

# Chain open + snapshot in one call
camoufox-cli open https://example.com && camoufox-cli snapshot -i

# Chain multiple interactions
camoufox-cli fill @e1 "[email protected]" && camoufox-cli fill @e2 "password123" && camoufox-cli click @e3

# Navigate and capture
camoufox-cli open https://example.com && camoufox-cli screenshot page.png

**何时串联：**如果无需读取中间命令的输出即可继续（例如，打开页面并截图），请使用 &&。如果需要先解析输出（例如，先通过快照发现引用，再使用这些引用进行交互），则应分别运行命令。

基本命令

# Navigation
camoufox-cli open <url>              # Navigate to URL (starts daemon if needed)
camoufox-cli back                    # Go back
camoufox-cli forward                 # Go forward
camoufox-cli reload                  # Reload page
camoufox-cli url                     # Print current URL
camoufox-cli title                   # Print page title
camoufox-cli close                   # Close your tab (browser exits when the last tab closes)
camoufox-cli close --all             # Force-close all sessions

# Snapshot
camoufox-cli snapshot                # Full aria tree of page
camoufox-cli snapshot -i             # Interactive elements only (recommended)
camoufox-cli snapshot -s "#selector" # Scope to CSS selector

# Interaction (use @refs from snapshot)
camoufox-cli click @e1               # Click element
camoufox-cli fill @e1 "text"         # Clear + type into input
camoufox-cli type @e1 "text"         # Type without clearing (append)
camoufox-cli select @e1 "option"     # Select dropdown option
camoufox-cli check @e1               # Toggle checkbox
camoufox-cli hover @e1               # Hover over element
camoufox-cli mouse click 660 380     # Click at viewport coordinates (no ref needed)
camoufox-cli press Enter             # Press keyboard key
camoufox-cli press "Control+a"       # Key combination

# Data Extraction
camoufox-cli text @e1                # Get text content of element
camoufox-cli text body               # Get all page text (CSS selector)
camoufox-cli eval "document.title"   # Execute JavaScript

# Capture
camoufox-cli screenshot              # Screenshot as JSON {"base64": "..."}
camoufox-cli screenshot page.png     # Screenshot to file
camoufox-cli screenshot --full p.png # Full page screenshot
camoufox-cli pdf output.pdf          # Save page as PDF

# Scroll & Wait
camoufox-cli scroll down             # Scroll down 500px
camoufox-cli scroll up               # Scroll up 500px
camoufox-cli scroll down 1000        # Scroll down 1000px
camoufox-cli wait @e1                # Wait for element to appear
camoufox-cli wait 2000               # Wait milliseconds
camoufox-cli wait --url "*/dashboard" # Wait for URL pattern

# Tabs
camoufox-cli tabs                    # List open tabs (with owner names)
camoufox-cli switch 2                # Switch to tab by index
camoufox-cli --tab <unique-name> open <url> # Named tab: shared browser + login, own page/refs

# Cookies & State
camoufox-cli cookies                 # Dump cookies as JSON
camoufox-cli cookies import file.json # Import cookies
camoufox-cli cookies export file.json # Export cookies

# Sessions
camoufox-cli sessions                # List active sessions
camoufox-cli --session work open <url> # Use named session
camoufox-cli close --all             # Force-close all sessions

# Setup
camoufox-cli install                 # Download Camoufox browser
camoufox-cli install --with-deps     # Download browser + system libs (Linux)

常见模式

提交表单

camoufox-cli open https://example.com/signup
camoufox-cli snapshot -i
camoufox-cli fill @e1 "Jane Doe"
camoufox-cli fill @e2 "[email protected]"
camoufox-cli select @e3 "California"
camoufox-cli check @e4
camoufox-cli click @e5
camoufox-cli snapshot -i  # Verify submission result

提取数据

camoufox-cli open https://example.com/products
camoufox-cli snapshot -i
camoufox-cli text @e5                # Get specific element text
camoufox-cli eval "document.title"   # Get page title via JS
camoufox-cli screenshot results.png  # Visual capture

Cookie 管理（保持登录状态）

# Login and export cookies
camoufox-cli open https://app.example.com/login
camoufox-cli snapshot -i
camoufox-cli fill @e1 "user"
camoufox-cli fill @e2 "pass"
camoufox-cli click @e3
camoufox-cli cookies export auth.json

# Restore in future session
camoufox-cli open https://app.example.com
camoufox-cli cookies import auth.json
camoufox-cli reload

对于网站还会验证设备稳定性（而不只是 Cookie）的长期账号，请同时使用 --persistent，使指纹与 Cookie 一同保持固定 — 请参阅下文的“持久身份”部分。

多个标签页

camoufox-cli open https://site-a.com
camoufox-cli eval "window.open('https://site-b.com')"
camoufox-cli tabs                    # List tabs
camoufox-cli switch 1                # Switch to second tab
camoufox-cli snapshot -i

并行标签页（共享身份，使用同一浏览器）

在一个会话中，命名标签页共享同一个浏览器 — 使用相同的指纹和 Cookie/登录状态 — 但每个标签页都有自己的页面、元素引用和导航历史，因此并发 Agent 不会互相覆盖。这是一种低成本的并行化方式：总共只需一个 Firefox，每增加一个标签页大约占用 50-150MB。

camoufox-cli --tab inbox-scan-x4q open https://app.example.com/inbox
camoufox-cli --tab report-pull-9kf open https://app.example.com/reports
camoufox-cli --tab inbox-scan-x4q snapshot -i   # refs are per tab
camoufox-cli tabs                               # Lists every tab with its owner name
camoufox-cli --tab inbox-scan-x4q close         # Frees only this tab; browser stays for the others

**选择标签页名称。**系统不会强制名称唯一 — 两个 Agent 使用相同名称时会共享同一个页面指针，并互相覆盖。在任务开始时生成一次名称：使用一个描述具体任务的简短标识，再加上由 Shell 生成的随机后缀 — 不要自行编造后缀，LLM 生成的“随机”字符会有偏差，并发 Agent 也可能生成相同的字符。之后的每条命令都应原样使用打印出的名称。（如果指示明确为你指定了标签页名称，则使用该名称。）

TAB="price-scan-$(openssl rand -hex 2)" && echo "$TAB" && camoufox-cli --tab "$TAB" open https://example.com
# prints e.g. price-scan-9f3c — use that exact name in every later command:
camoufox-cli --tab price-scan-9f3c snapshot -i

如果子 Agent 应以同一身份操作（例如，所有 Agent 都操作同一个已登录账号），请使用标签页。清理工作无需协调：每个 Agent 完成后，都对自己的标签页运行 close（camoufox-cli --tab <name> close）— 这只会释放该标签页；最后一个标签页关闭后，浏览器会自动退出。

多个标签页共享一个浏览器进程，因此不同标签页的命令可能会排在耗时较长的导航或 wait 操作之后；不同会话则作为独立进程运行，可完全并行执行。如果少数 Agent 的命令特别密集，可为它们分配各自的会话，其余 Agent 继续使用标签页。

并行会话（隔离身份）

每个命名会话都是一个独立的浏览器进程，因此会各自获得随机生成的指纹和 Cookie。当 Agent 不得共享身份（多账号任务）时，请使用此方式 — 每个会话都需要完整运行一个 Firefox（约 300-500MB）：

camoufox-cli --session s1 open https://site-a.com
camoufox-cli --session s2 open https://site-b.com
camoufox-cli sessions                # List both
camoufox-cli --session s1 snapshot -i
camoufox-cli --session s2 snapshot -i

仅使用独立会话只能隔离浏览器端。对于需要经受严格审查的多账号任务，还应为每个会话配置各自的代理（网站会通过 IP 关联账号 — 使用配置文件中的 sessions.<name>.proxy），并启用 --persistent（否则每次启动时指纹都会重新随机生成，看起来就像每次登录都换了一台新设备）。

可视化浏览器（调试）

camoufox-cli --headed open https://example.com
camoufox-cli snapshot -i
camoufox-cli screenshot debug.png

会话管理和清理

同时运行多个 Agent 或自动化任务时，请为每个 Agent 指定自己的名称，以免冲突。提供两个隔离级别：

• --tab <name>（共享身份，推荐默认选项）：所有 Agent 共用一个浏览器——指纹和登录状态相同——但每个 Agent 都有独立的标签页。开销低：总共只需一个 Firefox。
• --session <name>（隔离身份）：每个 Agent 都有自己的浏览器，并使用独立的指纹和 Cookie。开销高：每个会话都需要完整的 Firefox。仅在身份必须相互隔离时使用。

# Shared identity: 3 agents, one browser, one login
camoufox-cli --tab orders-audit-p2m open https://app.example.com/a
camoufox-cli --tab user-export-j8w open https://app.example.com/b
camoufox-cli --tab billing-check-r4t open https://app.example.com/c

# Isolated identities: 2 agents, two browsers
camoufox-cli --session shop-a-buyer open https://site-a.com
camoufox-cli --session shop-b-buyer open https://site-b.com
camoufox-cli sessions                  # Check active sessions

名称只是字符串，不会强制要求唯一——请遵循上文的“选择标签页名称”规则（任务 slug + shell 生成的随机后缀，选定后不再更改）。会话名称也一样。

完成后务必运行 close，以避免遗留进程——使用与其他命令相同的 --tab/--session 标志，因为 close 会释放该命令所指向的标签页。最后一个标签页关闭后，浏览器就会退出，因此每个 Agent 都能以相同方式清理，无需了解其他 Agent 的情况：

camoufox-cli --tab orders-audit-p2m close       # Free this tab; browser exits if it was the last
camoufox-cli close                              # Same, for the default tab
camoufox-cli --session shop-a-buyer close       # Same, within a named session
camoufox-cli close --all                        # Force-close all sessions (cleanup escape hatch)

如果之前的会话未能正常关闭，守护进程可能仍在运行。开始新任务前，请使用 camoufox-cli close（或 close --all）进行清理。

超时和加载缓慢的页面

有些页面需要时间才能完全加载，尤其是包含动态内容或大量 JavaScript 的页面。创建快照前，请使用显式等待：

# Wait for a specific element to appear
camoufox-cli wait @e1
camoufox-cli snapshot -i

# Wait for a URL pattern (useful after redirects)
camoufox-cli wait --url "*/dashboard"
camoufox-cli snapshot -i

# Wait a fixed duration as a last resort
camoufox-cli wait 3000
camoufox-cli snapshot -i

处理加载缓慢的页面时，创建快照前务必先等待。如果过早创建快照，输出中可能会缺少某些元素。

Refs 生命周期（重要）

Refs（@e1、@e2 等）是在每次创建快照时按顺序分配的临时标识符。页面发生变化后，Refs 就会失效。

以下操作后务必重新创建快照：

• 点击会跳转页面的链接或按钮
• 提交表单
• 动态内容加载（下拉菜单、模态框、延迟加载的内容）
• 滚动并触发新内容加载

# CORRECT: re-snapshot after navigation
camoufox-cli click @e5              # Navigates to new page
camoufox-cli snapshot -i            # MUST re-snapshot
camoufox-cli click @e1              # Use new refs

# CORRECT: re-snapshot after dynamic changes
camoufox-cli click @e1              # Opens dropdown
camoufox-cli snapshot -i            # See dropdown items
camoufox-cli click @e7              # Select item

# WRONG: using refs without snapshot
camoufox-cli open https://example.com
camoufox-cli click @e1              # Ref doesn't exist yet!

# WRONG: using old refs after navigation
camoufox-cli click @e5              # Navigates away
camoufox-cli click @e3              # STALE REF - wrong element!

导航或页面发生变化后，与元素交互前务必重新创建快照。

故障排除

“未找到 Ref @eN”

该 Ref 已失效。请重新创建快照以获取新的 Refs：

camoufox-cli snapshot -i

快照中未显示元素

# Scroll down to reveal element
camoufox-cli scroll down 1000
camoufox-cli snapshot -i

# Or wait for dynamic content
camoufox-cli wait 2000
camoufox-cli snapshot -i

元素在屏幕上可见，但未出现在快照中

跨域 iframe 中的复选框（例如 Cloudflare Turnstile 的“Verify you are human”小组件）没有 Ref。请在截图中找到该元素，然后通过坐标点击。坐标为视口 CSS 像素。在默认的 devicePixelRatio 为 1 时，坐标与非 --full 截图中的像素相同。

camoufox-cli screenshot page.png     # Locate the checkbox in the image
camoufox-cli mouse click 660 380     # Click its center
camoufox-cli wait 3000
camoufox-cli screenshot page.png     # Confirm the check passed

快照中的元素过多

# Scope to a specific container
camoufox-cli snapshot -s "#main-content"
camoufox-cli snapshot -i -s "form.login"

页面未完全加载

# Wait for URL pattern after redirect
camoufox-cli wait --url "*/dashboard"
camoufox-cli snapshot -i

# Wait a fixed duration as last resort
camoufox-cli wait 3000
camoufox-cli snapshot -i

全局标志

--session <name>       Named session (default: "default")
--tab <name>           Named tab within the session's shared browser: same
                       fingerprint and cookies/login, independent page/refs/
                       history (default: "default")
--headed               Show browser window (default: headless)
--timeout <seconds>    Daemon idle timeout (default: 1800)
--json                 Output as JSON instead of human-readable
--persistent [path]    Persistent identity — reuse the same fingerprint + cookies across launches
                       (default path: ~/.camoufox-cli/profiles/<session>)
--proxy <url>          Proxy server (http:// or https://; auth: http://user:pass@host:port)
--no-geoip             Disable automatic GeoIP spoofing (auto-enabled with --proxy)
--locale <tag>         Force browser locale (e.g. "en-US" or "en-US,zh-CN")
--version              Print version and exit

配置文件（可选）。 若要避免重复设置标志，请在 ~/.camoufox-cli/config.json 中设置默认值（使用 $CAMOUFOX_CLI_CONFIG 覆盖路径）：default 块适用于所有会话；可选的 sessions.<name> 块会在每次运行 --session <name> 时叠加额外的覆盖设置（名称就是传递给 --session 的任意值——会话不会预先注册）。可设置的键：proxy、locale、geoip、persistent（true/false/路径）、headed、timeout、json。命令行标志始终优先于文件中的设置。只有在会话的守护进程首次启动时才会读取配置。

{
  "default": { "persistent": true, "timeout": 3600 },
  "sessions": { "<your-session-name>": { "proxy": "socks5://127.0.0.1:1080", "locale": "zh-CN" } }
}

持久化身份

默认情况下，每次启动都会获得一个新的随机指纹。添加 --persistent [path]，即可在多次启动之间复用同一指纹和 Cookie——指纹、操作系统、Canvas 和字体种子会在首次启动时冻结（删除目录即可重置）；--locale 和从代理推导出的时区／地理位置会被保存，但每次传入该标记时都会刷新；--proxy／--no-geoip 从不保存，因此每次启动都要传入。

适用场景：同一设备在多次访问中应保持相同指纹（与账号绑定的任务、并行使用的独立身份，或仅靠 cookies import/export 不够，因为网站还会检查设备是否稳定）。不适用场景：一次性抓取或快速调试。

# Parallel identities, each with its own fingerprint + cookies
camoufox-cli --session a --persistent ~/.camoufox-cli/profiles/alice open https://app.example.com
camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob   open https://app.example.com

# Reset an identity: just remove the directory
rm -rf ~/.camoufox-cli/profiles/alice

文档

• camoufox-cli 文档 ——完整的 README、设置指南、安装说明和命令参考