camofox-browser

camofox-browser

通过 REST API 为 AI Agent 提供无头浏览器自动化服务，底层封装 Camoufox（基于 C++ 级指纹伪装的 Firefox 分支）。默认端口为 9377。源代码：https://github.com/jo-inc/camofox-browser

它是什么

这是一个 Node.js/Express 服务（server.js），通过 HTTP 端点提供 Camoufox 浏览器引擎。Agent 可以创建标签页、获取节省令牌的无障碍快照（其中包含稳定的元素引用，如 e1、e2……），并通过引用而非 CSS 选择器或原始坐标进行交互。内置 Cookie、代理、搜索宏、YouTube 字幕提取和会话持久化功能。插件可为服务扩展新路由、生命周期钩子和 Prometheus 指标。

架构

Browser Instance (Camoufox)
└── User Session (BrowserContext)   — isolated cookies/storage per userId
    ├── Tab Group (sessionKey)      — groups tabs by conversation/task
    │   ├── Tab (google.com)
    │   └── Tab (github.com)
    └── Tab Group
        └── Tab

主要行为：

• 延迟启动浏览器。浏览器空闲超过 BROWSER_IDLE_TIMEOUT_MS（默认 5min）后会关闭，并在下次请求时重新启动。空闲时内存占用约为 40 MB。
• 会话会在 SESSION_TIMEOUT_MS（默认 30 min）后自动过期。
• 当会话达到 MAX_TABS_PER_SESSION 时，会回收最早打开或最少使用的标签页，而不是报错。
• 所有日志均为每行一个 JSON 对象（{ts, level, msg, reqId, …}）。/health 不会记录请求日志。

安装和运行

独立运行：

git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
npm install
npm start            # downloads Camoufox on first run (~300MB)
# → http://localhost:9377

作为 OpenClaw 插件：

openclaw plugins install @askjo/camofox-browser

Docker（使用随附的 Makefile，它会通过绑定挂载在构建前预下载 Camoufox 和 yt-dlp）：

make up              # auto-detects ARCH (aarch64 on M1/M2, x86_64 on Intel)
make down
make reset           # clean rebuild
make fetch           # only download binaries
make up ARCH=x86_64 VERSION=135.0.1 RELEASE=beta.24

切勿直接运行 docker build——Dockerfile 依赖由 make fetch 填充的绑定挂载。

Fly.io / Railway：已包含 railway.toml。对于 Fly.io，请使用在构建时下载二进制文件的 Dockerfile（基于绑定挂载的 Dockerfile 无法用于远程 CI）。参考：jo-browser。

包含 with-plugins Docker 阶段、scripts/install-plugin-deps.sh 和 railway.toml 在内的完整部署详情：references/deployment.md。

Agent 核心工作流

POST /tabs                          → { tabId }
GET  /tabs/:tabId/snapshot          → accessibility tree with element refs e1, e2, …
POST /tabs/:tabId/click  { ref }    → interact
POST /tabs/:tabId/type   { ref }    → interact
POST /tabs/:tabId/navigate          → URL or search macro
DELETE /tabs/:tabId                 → cleanup

元素引用在同一快照中保持稳定，但导航后会重置——导航后务必重新获取快照。快照基于无障碍树构建，因此比原始 HTML 小约 90%。

完整工作流模式（使用 offset 翻页、通过 includeScreenshot=true 截图、CSS 选择器回退、pressEnter 等）：references/agent-usage.md。

身份验证

两个密钥均为可选项，且都从环境变量读取（绝不从配置文件读取）：

变量	启用功能	未设置时的行为
CAMOFOX_API_KEY	Cookie 导入端点（POST /sessions/:userId/cookies）以及任何使用 ctx.auth() 的路由	服务会对这些路由返回 403
CAMOFOX_ADMIN_KEY	POST /stop	端点会被拒绝

请求通过 Authorization: Bearer <key> 进行身份验证。来自回环地址（127.0.0.1）的请求可绕过 Bearer 检查。使用 openssl rand -hex 32 生成密钥。

REST API 概览

主要分组——完整的架构和查询参数见：references/api-reference.md。

分组	端点
标签页生命周期	POST /tabs、GET /tabs、GET /tabs/:id/stats、DELETE /tabs/:id、DELETE /tabs/group/:groupId、DELETE /sessions/:userId
页面交互	GET /tabs/:id/snapshot、POST /tabs/:id/click、/type、/press、/scroll、/navigate、/wait、GET /tabs/:id/links、/images、/downloads、/screenshot、POST /tabs/:id/back、/forward、/refresh
YouTube	POST /youtube/transcript（yt-dlp 快速路径，浏览器回退）
会话	POST /sessions/:userId/cookies、GET /sessions/:userId/storage_state
服务	GET /health、POST /start、POST /stop

搜索宏

使用 {"macro": "@<name>", "query": "…"} 导航，而不是构造搜索 URL：

@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

Reddit 宏会直接返回 JSON（无需解析 HTML）。使用查询词 "programming" 的 @reddit_subreddit 会获取 /r/programming.json。

会话、Cookie、代理、VNC

• 按用户隔离会话：通过 userId 实现；通过 sessionKey 对标签页分组（旧版别名：listItemId）。
• 导入 Cookie：将 Netscape 格式的文件放在 ~/.camofox/cookies/ 下（使用 CAMOFOX_COOKIES_DIR 覆盖）。每次请求最多 500 个 Cookie，每个文件最大 5 MB；字段会按 Playwright 允许列表进行清理，并阻止路径遍历。
• 会话持久化：persistence 插件会将每位用户的 storage_state.json 写入 ~/.camofox/profiles/<hashed-userId>/。可在 camofox.config.json 中设置 "persistence": { "enabled": false } 禁用，或使用 CAMOFOX_PROFILE_DIR 覆盖路径。
• 代理模式：simple（通过 PROXY_HOST/PROXY_PORT 使用单个端点），或 PROXY_STRATEGY=backconnect（适用于 Decodo/Bright Data/Oxylabs 的轮换粘性会话）。Camoufox 的 GeoIP 会根据代理出口 IP 自动设置区域设置、时区和地理位置。
• 通过 VNC 交互式登录：设置 ENABLE_VNC=1 + VNC_PASSWORD。noVNC Web UI 位于 NOVNC_PORT（默认值为 6080）。通过 GET /sessions/:userId/storage_state 导出生成的认证状态。

详细信息（Cookie 格式、backconnect 会话轮换、存储状态复用、VNC 工作流）：references/sessions-cookies-proxy.md。

环境变量

包含默认值的完整表格：references/deployment.md。最常设置的变量：

变量	默认值
CAMOFOX_PORT / PORT	9377
CAMOFOX_API_KEY	未设置（禁用 Cookie 导入）
MAX_SESSIONS	50
MAX_TABS_PER_SESSION	10
SESSION_TIMEOUT_MS	1800000（30 分钟）
BROWSER_IDLE_TIMEOUT_MS	300000（5 分钟）
HANDLER_TIMEOUT_MS	30000
MAX_CONCURRENT_PER_USER	3
MAX_OLD_SPACE_SIZE	128（MB，Node V8 堆）
PROXY_STRATEGY	未设置（simple 模式）
PROMETHEUS_ENABLED	未设置（关闭指标）

插件系统

插件位于 plugins/<name>/index.js 下，并导出 register(app, ctx)。根据 camofox.config.json 加载（{"plugins": ["youtube", …]}）。如果文件或 plugins 键缺失，则加载 plugins/ 下的所有插件（向后兼容）。

通过 CLI 安装第三方插件：

npm run plugin install https://github.com/user/camofox-screenshot-plugin
npm run plugin install git:github.com/user/my-plugin
npm run plugin install ./path/to/my-plugin
npm run plugin list
npm run plugin remove my-plugin

随附的默认插件：

插件	已启用	用途
youtube	是	通过 yt-dlp（快速）或浏览器回退获取 /youtube/transcript
persistence	是	在磁盘上保存每位用户的存储状态
vnc	否（需要 ENABLE_VNC=1）	通过 noVNC 进行浏览器交互式登录

OpenClaw 扫描器隔离（关键约束）

OpenClaw 技能扫描器会标记任何同时包含规则两部分的单个 .js 文件。违规会导致无法发布。规则：

• env-harvesting（严重）：同一文件中包含 /process\.env/ 和 /\bfetch\b|\bpost\b|http\.request/i。正则表达式不区分大小写——字符串字面量（如 'POST'）以及提及 process.env 的注释都会触发该规则。
• dangerous-exec（严重）：同一文件中包含 child_process 导入和 exec/spawn 调用。
• potential-exfiltration（警告）：同一文件中包含 readFile 和 fetch/post/http.request。

强制执行的布局：

• process.env 读取只能位于 lib/config.js 中。
• child_process / execFile / spawn 只能位于 plugins/youtube/youtube.js、plugins/vnc/vnc-launcher.js 和 lib/launcher.js 中。
• server.js 包含路由，但不包含 process.env 和 child_process。
• lib/metrics.js 不包含 process.env 和 HTTP 方法字符串字面量；仅当 PROMETHEUS_ENABLED=1 时才会延迟加载 prom-client。
• lib/request-utils.js 包含 HTTP 方法字符串，但不包含 process.env。

添加需要环境变量或子进程的功能时，请将相关代码放入 lib/ 模块，并将结果导入 server.js 或插件的路由文件。

插件 register(app, ctx) API、29 事件总线、ctx.createMetric、可修改钩子（browser:launching、session:creating，等等）、apt.txt + post-install.sh 依赖文件，以及 youtube 参考实现：references/plugin-development.md。

测试

npm test               # unit + e2e + plugin
npm run test:e2e       # e2e only
npm run test:live      # hits real sites (Google, macros)
npm run test:debug     # with server stdout
npm run test:plugins   # all plugin tests
npx jest plugins/youtube

关键文件

• server.js — Express 路由 + 浏览器逻辑（不含 process.env 和 child_process）
• lib/config.js — 所有环境变量读取
• lib/launcher.js — Camoufox 子进程启动
• lib/cookies.js — Cookie 文件 I/O
• lib/metrics.js — Prometheus 指标（延迟加载）
• lib/request-utils.js — actionFromReq、classifyError
• lib/snapshot.js — 无障碍树
• lib/macros.js — 搜索宏 URL 展开
• lib/plugins.js — 插件加载器 + 事件总线
• lib/auth.js — API 密钥 / 本地回环中间件
• lib/persistence.js — 原子存储状态
• lib/inflight.js — 合并处理中请求
• lib/tmp-cleanup.js — 孤立临时文件清理
• camofox.config.json — 插件加载列表
• openclaw.plugin.json — OpenClaw 网关集成清单（与 camofox 自身配置分开）
• plugins/youtube/、plugins/persistence/、plugins/vnc/ — 内置插件
• scripts/install-plugin-deps.sh — 用于 apt.txt + post-install.sh 的 Docker 构建钩子

参考资料

文件	阅读时机
api-reference.md	确切的端点架构、查询参数、请求/响应正文
deployment.md	Docker/Fly/Railway/Make 目标、环境变量表、日志记录、yt-dlp 安装
agent-usage.md	快照 → ref → 点击流程、分页、截图、宏的使用方法
sessions-cookies-proxy.md	Cookie 导入、会话持久化、代理/GeoIP、VNC 登录、存储状态复用
plugin-development.md	register(app, ctx) API、事件、扫描器隔离、指标、依赖文件