Back to Details

camofox-browser

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

camofox-browser Skill

camofox-browser 技能

Camofox is an anti-detection browser automation system built on Camoufox + Playwright with:
  • CLI (
    camofox
    ) for operator workflows
  • REST API (port 
    9377
    by default) for programmatic control
  • OpenClaw plugin integration (
    plugin.ts
    ) with 19 plugin tools
This skill is optimized for bot-evasion workflows where default browser automation gets flagged.
Camofox是基于Camoufox + Playwright构建的反检测浏览器自动化系统，具备以下特性：
  • 面向运维工作流的CLI（
    camofox
    ）工具
  • 支持程序化控制的REST API（默认端口
    9377
    ）
  • 集成OpenClaw插件（
    plugin.ts
    ），包含19个插件工具
本技能针对默认浏览器自动化会被标记拦截的机器人规避工作流做了优化。

Camofox vs generic browser skills

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

Use this skill instead of generic browser tooling when at least one applies:
  • You need anti-detection browser identity continuity across sessions.
  • You need proxy-aware geolocation behavior and region presets.
  • You need OpenClaw plugin compatibility with dedicated camofox tool names.
  • You need both CLI and REST API control paths against the same runtime.
Do not use this skill if you only need a simple local static page script and anti-detection is irrelevant.
满足以下任意条件时，优先使用本技能而非通用浏览器工具：
  • 需要跨会话保持反检测浏览器身份连续性
  • 需要代理感知的地理位置行为和区域预设
  • 需要OpenClaw插件兼容性，适配专属camofox工具名称
  • 需要针对同一运行时同时支持CLI和REST API两种控制路径
如果你仅需要简单的本地静态页面脚本，且不需要反检测能力，不要使用本技能。

Fast interface chooser

快速接口选择指南

Use CLI when:
  • You are running interactive ops/debugging from terminal.
  • You want local encrypted vault prompts for credentials.
  • You want quick one-shot command chaining with active tab memory.
Use REST API when:
  • You are integrating from another service/agent runtime.
  • You need strict request/response control with explicit 
    userId
    and 
    tabId
    .
  • You need OpenClaw-compatible route shape (
    /tabs/open
    , 
    /act
    , 
    /snapshot
    ).
符合以下场景时使用CLI：
  • 你在终端执行交互式操作/调试
  • 你需要本地加密凭证库的凭证输入提示
  • 你需要支持活跃标签页记忆的快速单次命令链执行
符合以下场景时使用REST API：
  • 你需要从其他服务/Agent运行时集成调用
  • 你需要严格的请求/响应控制，明确指定
    userId
    和
    tabId
  • 你需要兼容OpenClaw的路由格式（
    /tabs/open
    、
    /act
    、
    /snapshot
    ）

1) Core Workflow (CLI + API dual interface)

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

Follow this loop for reliable automation:
  1. Create/open tab
  2. Snapshot to get fresh 
    eN
    refs
  3. Interact using refs
  4. Re-snapshot after DOM/navigation changes
  5. Keep 
    userId
    stable for session continuity
CLI:
bash
camofox open https://example.com --user agent1
camofox snapshot --user agent1
camofox click e5 --user agent1
camofox type e7 "hello world" --user agent1
API:
bash
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"}'
Dual interface mapping (most common path):
IntentCLIAPI
Open tab
camofox open <url>
POST /tabs
Snapshot refs
camofox snapshot
GET /tabs/:tabId/snapshot
Click element
camofox click <ref>
POST /tabs/:tabId/click
Type text
camofox type <ref> <text>
POST /tabs/:tabId/type
Navigate
camofox navigate <url>
POST /tabs/:tabId/navigate
Screenshot
camofox screenshot
GET /tabs/:tabId/screenshot
Ref format reminder:
  • Camofox refs are 
    eN
    values (example 
    e1
    , 
    e2
    ) in normal command usage.
  • Some subcommands accept bracketed values in form assignments (
    [e1]="value"
    ).
遵循以下循环实现可靠的自动化：
  1. 创建/打开标签页
  2. 执行快照获取最新的
    eN
    引用
  3. 使用引用执行交互操作
  4. DOM/导航变更后重新执行快照
  5. 保持
    userId
    稳定以维持会话连续性
CLI示例：
bash
camofox open https://example.com --user agent1
camofox snapshot --user agent1
camofox click e5 --user agent1
camofox type e7 "hello world" --user agent1
API示例：
bash
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"}'
双接口映射（最常用路径）：
操作意图CLIAPI
打开标签页
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) Anti-Detection Overview (Camoufox-specific)

2) 反检测能力概览（Camoufox专属特性）

Camofox differs from generic browser tools by using Camoufox launch options and per-profile fingerprint persistence:
  • Camoufox launch via 
    camoufox-js
    (
    launchOptions
    )
  • Generated fingerprint (
    generateFingerprint
    ) persisted per profile dir
  • Humanization enabled (
    humanize: true
    )
  • Proxy-aware geo behavior (
    geoip: true
    when proxy configured)
  • Persistent contexts per user (
    ~/.camofox/profiles/<user>
    ) to keep believable identity continuity
Operational anti-detection behaviors:
  • Stable identity per 
    userId
  • Optional proxy credentials from 
    PROXY_HOST/PORT/USERNAME/PASSWORD
  • Optional headed/virtual display modes with Xvfb fallback on Linux
Execution behavior that helps evade brittle bot checks:
  • Persistent profile directories avoid fresh-device fingerprints every run.
  • Consistent session reuse lowers abrupt storage/token churn.
  • Engine-level spoofing avoids fragile JS-patch race with site updates.
See deep-dive: 
references/anti-detection.md
.
Camofox与通用浏览器工具的区别在于使用Camoufox启动参数和按配置文件持久化指纹：
  • 通过
    camoufox-js
    启动Camoufox（
    launchOptions
    ）
  • 生成的指纹（
    generateFingerprint
    ）按配置文件目录持久化存储
  • 启用拟人化操作模拟（
    humanize: true
    ）
  • 代理感知的地理位置行为（配置代理时
    geoip: true
    ）
  • 按用户持久化上下文（
    ~/.camofox/profiles/<user>
    ），保持可信的身份连续性
运行时反检测行为：
  • 每个
    userId
    对应稳定的身份
  • 支持从
    PROXY_HOST/PORT/USERNAME/PASSWORD
    环境变量读取代理凭证
  • 支持可选的有头/虚拟显示模式，Linux下默认降级为Xvfb
帮助绕过脆弱机器人校验的执行特性：
  • 持久化配置文件目录避免每次运行都生成新设备指纹
  • 一致的会话复用减少存储/令牌的异常变动
  • 引擎级别的伪造避免站点更新导致脆弱的JS补丁失效
深入了解请参考：
references/anti-detection.md

3) Essential CLI Commands (quick reference)

3) 核心CLI命令（快速参考）

Core:
bash
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>]
Navigation + interaction:
bash
camofox navigate <url> [tabId] [--user <user>]
camofox screenshot [tabId] [--output <file>] [--full-page] [--user <user>]
camofox fill '[e1]="john" [e2]="john@example.com"' [tabId] [--user <user>]
camofox press Enter [tabId] [--user <user>]
Inspection:
bash
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>]
Search:
bash
camofox search "openclaw plugin" --engine github [tabId] [--user <user>]
Full catalog (all 50): 
references/cli-commands.md
.
Global flag reminders:
bash
--user <user>
--port <port>
--format json|text|plain
基础命令：
bash
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>]
导航与交互命令：
bash
camofox navigate <url> [tabId] [--user <user>]
camofox screenshot [tabId] [--output <file>] [--full-page] [--user <user>]
camofox fill '[e1]="john" [e2]="john@example.com"' [tabId] [--user <user>]
camofox press Enter [tabId] [--user <user>]
内容检查命令：
bash
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>]
搜索命令：
bash
camofox search "openclaw plugin" --engine github [tabId] [--user <user>]
完整命令列表（共50个）：
references/cli-commands.md
全局参数说明：
bash
--user <user>
--port <port>
--format json|text|plain

4) Essential API Endpoints (quick reference)

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

Core tab flow:
bash
POST   /tabs
GET    /tabs
POST   /tabs/:tabId/navigate
GET    /tabs/:tabId/snapshot
POST   /tabs/:tabId/click
POST   /tabs/:tabId/type
DELETE /tabs/:tabId
State + assets:
bash
POST   /sessions/:userId/cookies
GET    /tabs/:tabId/cookies
GET    /tabs/:tabId/screenshot
GET    /tabs/:tabId/downloads
GET    /users/:userId/downloads
Advanced:
bash
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 compatibility routes:
bash
GET    /
POST   /tabs/open
POST   /start
POST   /stop
POST   /navigate
GET    /snapshot
POST   /act
Full endpoint map (all 48): 
references/api-endpoints.md
.
Compatibility warning:
  • plugin.ts
    includes a tool targeting 
    /youtube/transcript
    , but current server route registration does not expose this endpoint.
基础标签页流程：
bash
POST   /tabs
GET    /tabs
POST   /tabs/:tabId/navigate
GET    /tabs/:tabId/snapshot
POST   /tabs/:tabId/click
POST   /tabs/:tabId/type
DELETE /tabs/:tabId
状态与资源：
bash
POST   /sessions/:userId/cookies
GET    /tabs/:tabId/cookies
GET    /tabs/:tabId/screenshot
GET    /tabs/:tabId/downloads
GET    /users/:userId/downloads
高级功能：
bash
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兼容路由：
bash
GET    /
POST   /tabs/open
POST   /start
POST   /stop
POST   /navigate
GET    /snapshot
POST   /act
完整端点映射（共48个）：
references/api-endpoints.md
兼容性警告：
  • plugin.ts
    包含一个指向
    /youtube/transcript
    的工具，但当前服务端路由注册未暴露该端点。

5) Common Patterns

5) 常用场景示例

A) Form fill + submit

A) 表单填充与提交

CLI:
bash
camofox snapshot --user agent1
camofox fill '[e4]="Jane Doe" [e5]="jane@example.com"' --user agent1
camofox press Enter --user agent1
Safety notes:
  • Re-snapshot if the form mutates between fields.
  • Keep same 
    --user
    on every step to preserve tab ownership.
API:
bash
curl -X POST http://localhost:9377/tabs/<tabId>/type \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","ref":"e5","text":"jane@example.com"}'
CLI示例：
bash
camofox snapshot --user agent1
camofox fill '[e4]="Jane Doe" [e5]="jane@example.com"' --user agent1
camofox press Enter --user agent1
安全提示：
  • 如果表单在字段填充之间发生变更，需重新执行快照
  • 所有步骤保持
    --user
    参数一致以保留标签页所有权
API示例：
bash
curl -X POST http://localhost:9377/tabs/<tabId>/type \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","ref":"e5","text":"jane@example.com"}'

B) Stealth scraping loop

B) 隐秘爬取循环

bash
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
Recommended loop shape:
  1. open page
  2. snapshot
  3. capture text/links/resources
  4. paginate or navigate next URL
  5. snapshot again
bash
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) Search workflow (CLI engines)

C) 搜索工作流（CLI引擎）

bash
camofox search "best playwright anti-detection" --engine duckduckgo --user research1
When using CLI search:
  • Engine list is fixed to the 8 implemented CLI engines.
  • Use API macro navigate for 14 macro targets where supported.
bash
camofox search "best playwright anti-detection" --engine duckduckgo --user research1
使用CLI搜索时注意：
  • 引擎列表固定为已实现的8个CLI引擎
  • 支持的14个宏目标请使用API宏导航功能

D) API macro navigation

D) API宏导航

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

6) Authentication (Auth Vault)

6) 身份认证（凭证库）

Auth Vault is local encrypted credential storage for CLI workflows.
Commands:
bash
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>
Security model (implemented):
  • Payload encryption: AES-256-GCM
  • KDF: Argon2id preferred, PBKDF2 fallback
  • Salt: 16 bytes
  • IV: 12 bytes
  • Vault dir mode: 
    0700
  • Secret file mode: 
    0600
Operational guidance:
  • Avoid scripting raw passwords in shell history.
  • Prefer vault injection for login workflows in shared-agent logs.
  • Rotate vault profile master password regularly for long-lived bots.
See: 
references/authentication.md
.
凭证库是面向CLI工作流的本地加密凭证存储工具。
相关命令：
bash
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>
已实现的安全模型：
  • payload加密：AES-256-GCM
  • 密钥派生函数：优先使用Argon2id，降级方案为PBKDF2
  • 盐值：16字节
  • 初始化向量：12字节
  • 凭证库目录权限：
    0700
  • 密钥文件权限：
    0600
使用指南：
  • 避免在Shell历史中记录明文密码
  • 共享Agent日志的登录工作流优先使用凭证库注入功能
  • 长期运行的机器人请定期轮换凭证库配置文件的主密码
详见：
references/authentication.md

7) Session Management (
userId
isolation)

7) 会话管理（
userId
隔离）

Session identity is scoped by 
userId
and persistent profile dir:
  • Browser context keyed by 
    userId
  • Cookies, profile, fingerprint continuity tied to same 
    userId
  • Mixing users in one flow breaks tab lookup consistency
CLI pattern:
bash
camofox open https://example.com --user account-a
camofox snapshot --user account-a
camofox click e9 --user account-a
Cookie session file helpers:
bash
camofox session save checkout-flow --user account-a
camofox session load checkout-flow --user account-a
Isolation reminder:
  • tabId
    lookup is user-scoped.
  • Using wrong 
    userId
    with valid 
    tabId
    returns not found behavior.
会话身份由
userId
和持久化配置文件目录共同限定：
  • 浏览器上下文以
    userId
    为键
  • Cookie、配置文件、指纹连续性与同一个
    userId
    绑定
  • 同一个流程中混用不同用户会破坏标签页查找一致性
CLI示例：
bash
camofox open https://example.com --user account-a
camofox snapshot --user account-a
camofox click e9 --user account-a
Cookie会话文件辅助命令：
bash
camofox session save checkout-flow --user account-a
camofox session load checkout-flow --user account-a
隔离提示：
  • tabId
    查找是用户级隔离的
  • 有效的
    tabId
    搭配错误的
    userId
    会返回未找到的响应

8) Search Macros (CLI vs API — distinct systems)

8) 搜索宏（CLI与API — 两套独立系统）

Important distinction:
  • CLI 
    search
    supports 8 engines: 
    google
    , 
    youtube
    , 
    amazon
    , 
    bing
    , 
    reddit
    , 
    duckduckgo
    , 
    github
    , 
    stackoverflow
  • API 
    navigate
    macro supports 14 macros in 
    src/utils/macros.ts
    : 
    @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
CLI example:
bash
camofox search "vite plugin" --engine github --user dev1
API macro example:
bash
curl -X POST http://localhost:9377/tabs/<tabId>/navigate \
  -H 'Content-Type: application/json' \
  -d '{"userId":"dev1","macro":"@google_search","query":"vite plugin github"}'
Note: API macros and CLI search engines are different systems. Keep CLI/API behavior separate.
Macro mismatch reminder:
  • CLI has 
    github
    and 
    stackoverflow
    engines.
  • API macro set does not define 
    @github_search
    or 
    @stackoverflow_search
    in current macro implementation.
重要区别：
  • CLI 
    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
CLI示例：
bash
camofox search "vite plugin" --engine github --user dev1
API宏示例：
bash
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宏和CLI搜索引擎是两套独立系统，请分开处理CLI/API行为。
宏不匹配提示：
  • CLI支持
    github
    和
    stackoverflow
    引擎
  • 当前API宏实现中未定义
    @github_search
    或
    @stackoverflow_search

9) Geo Presets (8 presets)

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

Built-in preset names:
  • us-east
  • us-west
  • japan
  • uk
  • germany
  • vietnam
  • singapore
  • australia
CLI:
bash
camofox open https://example.com --geo japan --user jp-agent
API:
bash
curl -X POST http://localhost:9377/tabs \
  -H 'Content-Type: application/json' \
  -d '{"userId":"jp-agent","sessionKey":"default","preset":"japan","url":"https://example.com"}'
Preset best practice:
  • Keep preset and proxy region coherent to avoid obvious locale/network mismatch.
内置预设名称：
  • us-east
  • us-west
  • japan
  • uk
  • germany
  • vietnam
  • singapore
  • australia
CLI示例：
bash
camofox open https://example.com --geo japan --user jp-agent
API示例：
bash
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) Security (proxy, anti-detection settings)

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

Use environment variables for hardened operation:
bash
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'
Behavior notes:
  • Cookie import/export and evaluate endpoints enforce bearer auth only when 
    CAMOFOX_API_KEY
    is configured.
  • OpenClaw 
    /stop
    requires admin key authorization.
  • camofox download
    is currently a stub/placeholder in CLI (documented intentionally).
Suggested baseline environment:
bash
export CAMOFOX_PORT=9377
export CAMOFOX_HEADLESS=virtual
export CAMOFOX_MAX_SESSIONS=20
export CAMOFOX_MAX_TABS=10
使用环境变量实现加固运行：
bash
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'
行为说明：
  • 仅当配置
    CAMOFOX_API_KEY
    时，Cookie导入/导出和执行端点会强制Bearer认证
  • OpenClaw 
    /stop
    接口需要管理员密钥授权
  • CLI中
    camofox download
    目前是存根/占位功能（已明确文档说明）
推荐基础环境配置：
bash
export CAMOFOX_PORT=9377
export CAMOFOX_HEADLESS=virtual
export CAMOFOX_MAX_SESSIONS=20
export CAMOFOX_MAX_TABS=10

11) Scripting (
camofox run
)

11) 脚本执行（
camofox run
）

camofox run
is a sequential script runner (not a DAG/orchestration pipeline).
bash
camofox run script.txt
camofox run script.txt --continue-on-error
cat script.txt | camofox run -
Script format:
  • One command per line
  • #
    comments supported
  • Supports quoted args
  • Nested 
    run
    is rejected
Example script (
login-and-capture.cf
):
text
undefined
camofox run
是顺序脚本执行器（非DAG/编排流水线）。
bash
camofox run script.txt
camofox run script.txt --continue-on-error
cat script.txt | camofox run -
脚本格式：
  • 每行一个命令
  • 支持
    #
    注释
  • 支持带引号的参数
  • 不支持嵌套
    run
    命令
脚本示例（
login-and-capture.cf
）：
text
undefined

open login page

open login page

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

12) Deep-Dive Documentation

12) 深入文档

  • references/cli-commands.md
    — Full CLI command catalog and usage patterns.
  • references/api-endpoints.md
    — Complete REST API route map and request/response notes.
  • references/openclaw-tools.md
    — OpenClaw plugin tool list and route/tool mapping.
  • references/anti-detection.md
    — Camoufox anti-detection model, fingerprint continuity, and stealth guidance.
  • references/authentication.md
    — Auth Vault encryption model and credential workflows.
  • references/session-management.md
    — 
    userId
    isolation, context lifecycle, and session continuity.
  • references/search-macros.md
    — CLI search engines vs API macro navigation behavior.
  • references/proxy-presets.md
    — Geo presets, proxy settings, and region-alignment practices.
  • references/scripting.md
    — 
    camofox run
    script format, constraints, and execution behavior.
  • references/snapshot-refs.md
    — Snapshot reference handling (
    eN
    ), refresh rules, and element targeting reliability.
  • references/media-extraction.md
    — Screenshot/download/resource extraction and media workflows.
  • references/display-vnc.md
    — Headed/virtual display modes and VNC operation guidance.
  • references/cli-commands.md
    — 完整CLI命令目录与使用模式
  • references/api-endpoints.md
    — 完整REST API路由映射与请求/响应说明
  • references/openclaw-tools.md
    — OpenClaw插件工具列表与路由/工具映射
  • references/anti-detection.md
    — Camoufox反检测模型、指纹连续性与隐秘操作指南
  • references/authentication.md
    — 凭证库加密模型与凭证工作流
  • 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) Ready-to-Use Templates

13) 开箱即用模板

  • templates/stealth-scraping.sh
    — Stealth scraping workflow with anti-detection defaults.
  • templates/search-and-extract.sh
    — Search across engines and extract structured results.
  • templates/authenticated-session.sh
    — Auth Vault login and authenticated session flow.
  • templates/form-automation.sh
    — Form automation using snapshot-interact-verify loops.
  • templates/multi-session-pipeline.sh
    — Parallel multi-session collection pipeline.
  • templates/screenshot-capture.sh
    — Screenshot capture workflow for audits and evidence.
  • templates/stealth-scraping.sh
    — 带反检测默认配置的隐秘爬取工作流
  • templates/search-and-extract.sh
    — 跨引擎搜索并提取结构化结果
  • templates/authenticated-session.sh
    — 凭证库登录与认证会话流程
  • templates/form-automation.sh
    — 使用快照-交互-校验循环的表单自动化
  • templates/multi-session-pipeline.sh
    — 并行多会话采集流水线
  • templates/screenshot-capture.sh
    — 用于审计和存证的截图采集工作流

14) Important Notes

14) 重要说明

  • Plugin system in this repository is OpenClaw plugin tools, not MCP tools.
  • There is no MCP server implementation in this codebase.
  • OpenClaw plugin currently defines 19 tools in 
    plugin.ts
    .
  • A plugin tool references 
    /youtube/transcript
    , but this route is not registered in current server routes (
    core.ts
    , 
    openclaw.ts
    ). Treat it as unavailable endpoint.
  • CLI element refs are 
    eN
    (for example 
    e1
    , 
    e2
    ), not 
    @eN
    .
  • Source of truth for development decisions: 
    AGENTS.md
    .
High-confidence troubleshooting checklist:
  1. camofox health --format json
  2. Confirm tab exists with 
    camofox get-tabs --user <user> --format json
  3. Refresh refs with 
    camofox snapshot
  4. Re-run failing action with same 
    --user
  5. If display mode changed, create new tab (old tab ids invalid)
  • 本仓库的插件系统是OpenClaw插件工具，而非MCP工具
  • 本代码库未实现MCP服务端
  • 当前OpenClaw插件在
    plugin.ts
    中定义了19个工具
  • 有一个插件工具引用了
    /youtube/transcript
    ，但该路由未注册在当前服务端路由（
    core.ts
    、
    openclaw.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失效）

Appendix A — 50-command quick index

附录A — 50个命令快速索引

Core (5):
  • open
  • close
  • snapshot
  • click
  • type
Navigation (4):
  • navigate
  • screenshot
  • go-back
  • go-forward
Content (7):
  • get-text
  • get-url
  • get-links
  • get-tabs
  • eval
  • wait
  • search
Interaction (6):
  • fill
  • scroll
  • select
  • hover
  • press
  • drag
Console/error capture (2):
  • console
  • errors
Tracing (5):
  • trace start
  • trace stop
  • trace chunk-start
  • trace chunk-stop
  • trace status
Session (4):
  • session save
  • session load
  • session list
  • session delete
Download/cookie (4):
  • cookie export
  • cookie import
  • download
    (stub)
  • downloads
Auth (5):
  • auth save
  • auth load
  • auth list
  • auth delete
  • auth change-password
Server (3):
  • server start
  • server stop
  • server status
Advanced (4):
  • annotate
  • health
  • version
  • info
Pipeline (1):
  • run
基础命令（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

Appendix B — API endpoint families

附录B — API端点分类

Core REST routes (
core.ts
):
  • Cookies: import/export by user/tab
  • Lifecycle: health, presets, tab create/list/close, session close
  • Interaction: navigate, snapshot, wait, click, type, press, scroll, scroll-element
  • Eval: evaluate + evaluate-extended
  • Navigation state: back, forward, refresh
  • Extraction: links, screenshot, stats, extract-resources, batch-download, resolve-blobs
  • Download tracking: list/get/content/delete
  • Display mode: toggle-display
OpenClaw routes (
openclaw.ts
):
  • /
    , 
    /tabs/open
    , 
    /start
    , 
    /stop
    , 
    /navigate
    , 
    /snapshot
    , 
    /act
核心REST路由（
core.ts
）：
  • Cookie：按用户/标签页导入/导出
  • 生命周期：健康检查、预设、标签页创建/列表/关闭、会话关闭
  • 交互：导航、快照、等待、点击、输入、按键、滚动、滚动元素
  • 执行：evaluate + evaluate-extended
  • 导航状态：后退、前进、刷新
  • 提取：链接、截图、统计信息、资源提取、批量下载、Blob解析
  • 下载跟踪：列表/获取/内容/删除
  • 显示模式：切换显示
OpenClaw路由（
openclaw.ts
）：
  • /
    、
    /tabs/open
    、
    /start
    、
    /stop
    、
    /navigate
    、
    /snapshot
    、
    /act

Appendix C — response handling recommendations

附录C — 响应处理建议

CLI output handling:
  • Prefer 
    --format json
    for machine parsing.
  • Use 
    plain
    only when expecting one scalar (for example direct path or status string).
  • Avoid parsing text output with fragile shell splitting.
API response handling:
  • Treat 4xx errors as actionable request/user/tab mismatch first.
  • Retry only idempotent reads (
    GET
    ) by default.
  • For 
    evaluate-extended
    , handle 
    429
    and 
    408
    explicitly.
CLI输出处理：
  • 机器解析优先使用
    --format json
  • 仅当需要单个标量结果时使用
    plain
    格式（例如直接路径或状态字符串）
  • 避免使用脆弱的Shell分割解析文本输出
API响应处理：
  • 4xx错误优先视为可修复的请求/用户/标签页不匹配问题
  • 默认仅重试幂等读请求（
    GET
    ）
  • 针对
    evaluate-extended
    接口，显式处理
    429
    和
    408
    错误

Appendix D — mismatch and compatibility guardrails

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

Documented guardrails for this repository revision:
  • OpenClaw plugin tool system exists and is first-class.
  • MCP server implementation does not exist in this codebase.
  • Plugin tool 
    camofox_youtube_transcript
    references a route not currently registered in route files.
  • CLI 
    download
    remains placeholder/stub and should be treated as non-functional direct download command.
本仓库版本的已记录防护规则：
  • OpenClaw插件工具系统已存在且为一等特性
  • 本代码库未实现MCP服务端
  • 插件工具
    camofox_youtube_transcript
    引用的路由当前未在路由文件中注册
  • CLI 
    download
    仍为占位符/存根，应视为不可用的直接下载命令

Appendix E — minimum safe automation contract

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

If you need robust automations, enforce this contract in your agent logic:
  1. Always pass explicit 
    userId
    (or 
    --user
    ) for every command/call.
  2. Always obtain snapshot before actions that depend on refs.
  3. Always reacquire refs after navigation or major dynamic update.
  4. Always close user sessions (
    DELETE /sessions/:userId
    ) on teardown in long-running systems.
  5. Always persist auth/cookies via vault or cookie import rather than plaintext scripts.
如果需要实现健壮的自动化，请在你的Agent逻辑中强制执行以下契约：
  1. 每个命令/调用始终传递显式的
    userId
    （或
    --user
    ）参数
  2. 执行依赖引用的操作前始终先获取快照
  3. 导航或重大动态更新后始终重新获取引用
  4. 长期运行系统销毁时始终关闭用户会话（
    DELETE /sessions/:userId
    ）
  5. 始终通过凭证库或Cookie导入持久化认证信息/Cookie，而非明文脚本