camofox-browser

camofox-browser 技能

Camofox 是一个基于 Camoufox + Playwright 构建的反检测浏览器自动化系统，提供：

• 用于操作员工作流的 CLI（camofox）
• 用于程序化控制的 REST API（默认端口为 9377）
• OpenClaw 插件集成（plugin.ts），包含 18 个插件工具

此技能针对默认浏览器自动化容易被标记的规避机器人检测工作流进行了优化。

Camofox 与通用浏览器技能的区别

满足以下任一条件时，请使用此技能，而不是通用浏览器工具：

• 你需要跨会话保持反检测浏览器身份的一致性。
• 你需要支持代理的地理位置行为和区域预设。
• 你需要兼容 OpenClaw 插件，并使用专用的 camofox 工具名称。
• 你需要通过 CLI 和 REST API 两种方式控制同一个运行时。

如果你只需要一个简单的本地静态页面脚本，且无需考虑反检测，请勿使用此技能。

快速选择接口

以下情况使用 CLI：

• 你要在终端中进行交互式运维或调试。
• 你希望通过本地加密保险库提示输入凭据。
• 你希望利用当前标签页记忆快速串联一次性命令。

以下情况使用 REST API：

• 你要从其他服务或 Agent 运行时进行集成。
• 你需要严格控制请求和响应，并显式指定 userId 和 tabId。
• 你需要兼容 OpenClaw 的路由格式（/tabs/open、/act、/snapshot）。

1) 核心工作流（CLI + API 双接口）

按照以下循环进行可靠的自动化：

1. 创建或打开标签页
2. 获取快照，以取得最新的 eN 引用
3. 使用引用进行交互
4. DOM 或导航发生变化后，重新获取快照
5. 保持 userId 稳定，以延续会话

CLI：

camofox open https://example.com --user agent1
camofox snapshot --user agent1
camofox click e5 --user agent1
camofox type e7 "hello world" --user agent1

API：

curl -X POST http://localhost:9377/tabs \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","sessionKey":"default","url":"https://example.com"}'

curl "http://localhost:9377/tabs/<tabId>/snapshot?userId=agent1"

curl -X POST http://localhost:9377/tabs/<tabId>/click \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","ref":"e5"}'

双接口映射（最常见路径）：

意图	CLI	API
打开标签页	camofox open <url>	POST /tabs
获取快照引用	camofox snapshot	GET /tabs/:tabId/snapshot
点击元素	camofox click <ref>	POST /tabs/:tabId/click
输入文本	camofox type <ref> <text>	POST /tabs/:tabId/type
导航	camofox navigate <url>	POST /tabs/:tabId/navigate
截图	camofox screenshot	GET /tabs/:tabId/screenshot

引用格式提醒：

• 常规命令中，Camofox 引用的格式为 eN（例如 e1、e2）。
• 某些子命令在表单赋值中接受带方括号的值（[e1]="value"）。

2) 反检测概述（Camoufox 专属）

Camofox 使用 Camoufox 启动选项和按配置文件持久化的指纹，与通用浏览器工具有所不同：

• 通过 camoufox-js 启动 Camoufox（launchOptions）
• 生成的指纹（generateFingerprint）会按配置文件目录持久化
• 启用拟人化（humanize: true）
• 支持代理的地理位置行为（配置代理时设置 geoip: true）
• 每个用户都使用持久化上下文，保存在 ~/.camofox/profiles/ 下；Linux/macOS 保留可读的默认用户名称，而 Windows 使用可避免冲突的哈希内部配置文件键

反检测运行行为：

• 每个 userId 使用稳定的身份
• 可选使用来自 PROXY_HOST/PORT/USERNAME/PASSWORD 的代理凭据
• 可选使用有头或虚拟显示模式；Linux 上可回退到 Xvfb

有助于规避脆弱机器人检测的执行行为：

• 持久化配置文件目录可避免每次运行都使用全新的设备指纹。
• 重复使用一致的会话可减少存储或令牌的突然变化。
• 引擎级欺骗可避免因网站更新导致脆弱的 JS 补丁出现竞争条件。

详见深入介绍：references/anti-detection.md。

3) 必备 CLI 命令（快速参考）

核心命令：

camofox open <url> [--user <user>] [--viewport <WxH>] [--geo <preset>]
camofox close [tabId] [--user <user>]
camofox snapshot [tabId] [--user <user>]
camofox click <ref> [tabId] [--user <user>]
camofox type <ref> <text> [tabId] [--user <user>]

导航与交互：

camofox navigate <url> [tabId] [--user <user>]
camofox screenshot [tabId] [--output <file>] [--full-page] [--user <user>]
camofox fill '[e1]="john" [e2]="[email protected]"' [tabId] [--user <user>]
camofox press Enter [tabId] [--user <user>]

检查：

camofox get-text [tabId] [--selector <css>] [--user <user>]
camofox get-links [tabId] [--user <user>]
camofox eval '<js expression>' [tabId] [--user <user>]
camofox wait <selector|navigation|networkidle> [tabId] [--timeout <ms>] [--user <user>]

搜索：

camofox search "openclaw plugin" --engine github [tabId] [--user <user>]

完整目录（全部 50 条）：references/cli-commands.md。

全局标志提醒：

--user <user>
--port <port>
--format json|text|plain

4) 核心 API 端点（快速参考）

API 文档：

• 交互式文档：GET /api/docs（Swagger UI）
• 代表性路由子集的 OpenAPI 3.1.0 规范：GET /openapi.json

核心标签页流程：

POST   /tabs
GET    /tabs
POST   /tabs/:tabId/navigate
GET    /tabs/:tabId/snapshot
POST   /tabs/:tabId/click
POST   /tabs/:tabId/type
DELETE /tabs/:tabId

状态与资源：

POST   /sessions/:userId/cookies
GET    /tabs/:tabId/cookies
GET    /tabs/:tabId/screenshot
GET    /tabs/:tabId/downloads
GET    /users/:userId/downloads

高级功能：

POST   /tabs/:tabId/evaluate
POST   /tabs/:tabId/evaluate-extended
POST   /tabs/:tabId/extract-resources
POST   /tabs/:tabId/batch-download
POST   /tabs/:tabId/resolve-blobs

OpenClaw 兼容路由：

GET    /
POST   /tabs/open
POST   /start
POST   /stop
POST   /navigate
GET    /snapshot
POST   /act

完整端点列表（全部 54 个）：references/api-endpoints.md。

兼容性警告：

• camofox_youtube_transcript 工具已从 plugin.ts 中移除。服务端路由和插件工具均不提供此功能。

5) 常见模式

A) 填写并提交表单

命令行：

camofox snapshot --user agent1
camofox fill '[e4]="Jane Doe" [e5]="[email protected]"' --user agent1
camofox press Enter --user agent1

安全注意事项：

• 如果表单在填写不同字段期间发生变化，请重新生成快照。
• 每一步都使用相同的 --user，以保留标签页所有权。

API：

curl -X POST http://localhost:9377/tabs/<tabId>/type \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","ref":"e5","text":"[email protected]"}'

B) 隐蔽抓取循环

camofox open https://target.example --user scraper-us
camofox snapshot --user scraper-us
camofox get-text --selector "main" --user scraper-us
camofox get-links --user scraper-us

建议的循环流程：

1. 打开页面
2. 生成快照
3. 捕获文本、链接和资源
4. 翻页或导航至下一个 URL
5. 再次生成快照

C) 搜索工作流（命令行引擎）

camofox search "best playwright anti-detection" --engine duckduckgo --user research1

使用命令行搜索时：

• 引擎列表固定为已实现的 8 个命令行引擎。
• 在支持的情况下，使用 API 宏导航访问 14 个宏目标。

D) API 宏导航

curl -X POST http://localhost:9377/tabs/<tabId>/navigate \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","macro":"@google_search","query":"camoufox js"}'

6) 身份验证（Auth Vault）

Auth Vault 是用于命令行工作流的本地加密凭据存储。

命令：

camofox auth save <profile-name> [--url <url>] [--notes <notes>]
camofox auth load <profile-name>
camofox auth load <profile-name> --inject [tabId] --username-ref <ref> --password-ref <ref> [--user <user>]
camofox auth list [--format <format>]
camofox auth delete <profile-name>
camofox auth change-password <profile-name>

安全模型（已实现）：

• 负载加密：AES-256-GCM
• KDF：优先使用 Argon2id，回退时使用 PBKDF2
• Salt：16 字节
• IV：12 字节
• Vault 目录权限：0700
• 密钥文件权限：0600

操作指南：

• 避免在 shell 历史记录中以脚本形式写入原始密码。
• 在共享的 Agent 日志中的登录工作流里，优先使用 Vault 注入。
• 对于长期运行的机器人，定期轮换 Vault 配置文件主密码。

参见：references/authentication.md。

7) 会话管理（userId 隔离）

会话身份由 userId 和持久化配置文件目录共同限定：

• 浏览器上下文以 userId 为键
• Cookie、配置文件和指纹连续性均与同一 userId 绑定
• 在同一工作流中混用用户会破坏标签页查找的一致性

命令行模式：

camofox open https://example.com --user account-a
camofox snapshot --user account-a
camofox click e9 --user account-a

Cookie 会话文件助手：

camofox session save checkout-flow --user account-a
camofox session load checkout-flow --user account-a

隔离提醒：

• tabId 查找受用户范围限制。
• 使用错误的 userId 和有效的 tabId 会返回未找到行为。

8) 搜索宏（命令行与 API 是不同的系统）

重要区别：

• 命令行 search 支持 8 个引擎： google、youtube、amazon、bing、reddit、duckduckgo、github、stackoverflow

• API navigate 宏在 src/utils/macros.ts 中支持 14 个宏： @google_search、@youtube_search、@amazon_search、@reddit_search、@reddit_subreddit、@wikipedia_search、@twitter_search、@yelp_search、@spotify_search、@netflix_search、@linkedin_search、@instagram_search、@tiktok_search、@twitch_search

命令行示例：

camofox search "vite plugin" --engine github --user dev1

API 宏示例：

curl -X POST http://localhost:9377/tabs/<tabId>/navigate \
  -H 'Content-Type: application/json' \
  -d '{"userId":"dev1","macro":"@google_search","query":"vite plugin github"}'

注意：API 宏和命令行搜索引擎是不同的系统。请将命令行和 API 的行为区分开来。

宏不匹配提醒：

• 命令行包含 github 和 stackoverflow 引擎。
• 当前宏实现中，API 宏集合未定义 @github_search 或 @stackoverflow_search。

9) 地理位置预设（8 个预设）

内置预设名称：

• us-east
• us-west
• japan
• uk
• germany
• vietnam
• singapore
• australia

命令行：

camofox open https://example.com --geo japan --user jp-agent

API：

curl -X POST http://localhost:9377/tabs \
  -H 'Content-Type: application/json' \
  -d '{"userId":"jp-agent","sessionKey":"default","preset":"japan","url":"https://example.com"}'

预设最佳实践：

• 确保预设与代理区域相符，避免出现明显的区域设置与网络不匹配。

10) 安全（代理、反检测设置）

使用环境变量强化运行安全：

export CAMOFOX_API_KEY='<api-key>'
export CAMOFOX_ADMIN_KEY='<admin-key>'
export PROXY_HOST='proxy.example.net'
export PROXY_PORT='8080'
export PROXY_USERNAME='proxy-user'
export PROXY_PASSWORD='proxy-pass'

行为说明：

• 受保护的核心端点和 OpenClaw 操作/调试端点仅在配置了 CAMOFOX_API_KEY 时强制执行 bearer 身份验证（包括 Cookie 导入/导出、evaluate、标签页/会话生命周期、导航、交互、下载、跟踪、控制台和错误）。
• OpenClaw /stop 需要管理员密钥授权。
• CLI 中的 camofox download 当前为存根/占位实现（这是有意记录的）。

建议的基线环境：

export CAMOFOX_PORT=9377
export CAMOFOX_HEADLESS=virtual
export CAMOFOX_MAX_SESSIONS=20
export CAMOFOX_MAX_TABS=10

11）脚本（camofox run）

camofox run 是一个顺序脚本运行器（不是 DAG／编排流水线）。

camofox run script.txt
camofox run script.txt --continue-on-error
cat script.txt | camofox run -

脚本格式：

• 每行一条命令
• 支持 # 注释
• 支持带引号的参数
• 不允许嵌套 run

脚本示例（login-and-capture.cf）：

# open login page
open https://example.com/login --user ops1
snapshot --user ops1
fill '[e3]="[email protected]" [e4]="not-stored-here"' --user ops1
press Enter --user ops1
wait networkidle --timeout 12000 --user ops1
screenshot --output login-result.png --user ops1

12）深入文档

• references/cli-commands.md — CLI 命令完整目录及用法模式。
• references/api-endpoints.md — REST API 路由完整映射及请求／响应说明。
• references/openclaw-tools.md — OpenClaw 插件工具列表及路由／工具映射。
• references/anti-detection.md — Camoufox 反检测模型、指纹连续性及隐身指南。
• references/authentication.md — Auth Vault 加密模型及凭据工作流。
• references/session-management.md — userId 隔离、上下文生命周期及会话连续性。
• references/search-macros.md — CLI 搜索引擎与 API 宏导航行为。
• references/proxy-presets.md — 地理位置预设、代理设置及区域对齐实践。
• references/scripting.md — camofox run 脚本格式、限制及执行行为。
• references/snapshot-refs.md — 快照引用（eN）处理、刷新规则及元素定位可靠性。
• references/media-extraction.md — 屏幕截图／下载／资源提取及媒体工作流。
• references/display-vnc.md — 有头／虚拟显示模式及 VNC 操作指南。

13）开箱即用的模板

• templates/stealth-scraping.sh — 使用默认反检测设置的隐身抓取工作流。
• templates/search-and-extract.sh — 跨搜索引擎搜索并提取结构化结果。
• templates/authenticated-session.sh — Auth Vault 登录及已认证会话流程。
• templates/form-automation.sh — 使用快照－交互－验证循环的表单自动化。
• templates/multi-session-pipeline.sh — 并行多会话采集流水线。
• templates/screenshot-capture.sh — 用于审计和取证的屏幕截图工作流。

14）重要说明

• 此仓库中的插件系统是 OpenClaw 插件工具，而非 MCP 工具。
• 此代码库中没有 MCP 服务实现。
• OpenClaw 插件目前在 plugin.ts 中定义了 18 个工具。
• camofox_youtube_transcript 工具已从 plugin.ts 中移除。服务路由和插件工具均不提供此功能。
• CLI 元素引用为 eN（例如 e1、e2），而不是 @eN。
• 开发决策的权威依据：AGENTS.md。

高置信度故障排查清单：

1. camofox health --format json
2. 使用 camofox get-tabs --user <user> --format json 确认标签页存在
3. 使用 camofox snapshot 刷新引用
4. 使用相同的 --user 重新运行失败的操作
5. 如果显示模式已更改，请创建新标签页（旧标签页 ID 无效）

附录 A — 50 条命令速查索引

核心（5）：

• open
• close
• snapshot
• click
• type

导航（4）：

• navigate
• screenshot
• go-back
• go-forward

内容（7）：

• get-text
• get-url
• get-links
• get-tabs
• eval
• wait
• search

交互（6）：

• fill
• scroll
• select
• hover
• press
• drag

控制台／错误捕获（2）：

• console
• errors

跟踪（5）：

• trace start
• trace stop
• trace chunk-start
• trace chunk-stop
• trace status

会话（4）：

• session save
• session load
• session list
• session delete

下载／Cookie（4）：

• cookie export
• cookie import
• download（占位实现）
• downloads

身份验证（5）：

• auth save
• auth load
• auth list
• auth delete
• auth change-password

服务（3）：

• server start
• server stop
• server status

高级（4）：

• annotate
• health
• version
• info

流水线（1）：

• run

附录 B — API 端点系列

核心 REST 路由（core.ts）：

• Cookie：按用户／标签页导入／导出
• 生命周期：健康状态、预设、标签页创建／列表／关闭、会话关闭
• 交互：导航、快照、等待、点击、输入、按键、滚动、滚动元素
• 求值：evaluate + evaluate-extended
• 导航状态：后退、前进、刷新
• 提取：链接、截图、统计信息、extract-resources、batch-download、resolve-blobs
• 下载跟踪：列表／获取／内容／删除
• 显示模式：切换显示

OpenClaw 路由（openclaw.ts）：

• /、/tabs/open、/start、/stop、/navigate、/snapshot、/act

附录 C — 响应处理建议

CLI 输出处理：

• 优先使用 --format json 进行机器解析。
• 仅在预期结果为单个标量（例如直接路径或状态字符串）时使用 plain。
• 避免使用脆弱的 Shell 分割方式解析文本输出。

API 响应处理：

• 遇到 4xx 错误时，首先检查是否存在请求／用户／标签页不匹配等可处理的问题。
• 默认只重试幂等读取请求（GET）。
• 对 evaluate-extended，应明确处理 429 和 408。

附录 D — 不匹配与兼容性防护措施

此仓库修订版中记录的防护措施：

• OpenClaw 插件工具系统已存在，并且是一等功能。
• 此代码库中不存在 MCP 服务实现。
• camofox_youtube_transcript 工具已从 plugin.ts 中移除。路由 POST /youtube/transcript 仍未注册。
• CLI download 仍是占位桩，应视为不可用的直接下载命令。

附录 E — 最低安全自动化契约

如果需要构建可靠的自动化，请在 Agent 逻辑中强制执行此契约：

1. 每个命令／调用都必须显式传入 userId（或 --user）。
2. 执行依赖 refs 的操作前，必须先获取快照。
3. 导航或发生重大动态更新后，必须重新获取 refs。
4. 长时间运行的系统在拆除时，必须关闭用户会话（DELETE /sessions/:userId）。
5. 必须通过保险库或 Cookie 导入持久化身份验证信息／Cookie，而不是使用明文脚本。