CamoFox Browser Server
面向 AI Agent 的反检测浏览器服务器：用 C++ 引擎级指纹伪装的 Camoufox 引擎，通过 REST API、CLI、MCP 与 OpenClaw 插件供任意语言或智能体调用。
证据显示较好的最小权限默认(默认绑定127.0.0.1、非回环强制API key、默认阻止私网/元数据地址)，凭据处理突出(AES-256-GCM、Argon2id、0600权限、不回显到stdout)。扣分点：没有用户确认机制，工具用途本身是绕过反爬检测(规避第三方服务条款)，无来源代码可静态核实这些默认的实际实现。回滚有文档化但需手动清状态。
发布流程强制tag/插件版本/CHANGELOG一致，CI矩阵覆盖双OS双Node版本，测试断言具体错误消息(400/403/404/408/429/409)且有可操作恢复路径文档。扣分点：postinstall使用`|| true`吞掉Camoufox引擎下载失败，首次运行可能隐式降级。
目标受众(风险意识Agent)和使用场景描述充分，环境适配全面(Docker、Windows便携包、Linux Xvfb)。扣分点：遗留别名(listItemId、OpenClaw /act路由)降低了端点触发的精确性，Agent可能命中非预期路径；边界声明虽好但均为声明而非可静态核实的代码。
信息架构、安装说明、已知限制(Preview非目标)、许可证(MIT,含版权字体排除说明)、版本化与CHANGELOG(发布强制校验)均达到充分水平。扣分点：维护责任模糊——单一未经验证的作者'Jo, Inc'/'redf0x1'，无治理或响应承诺；无FAQ；命名稳定性仅靠口头兼容承诺。
输出可用性强(多格式、可访问性快照、eN元素引用、token效率设计)。扣分点：边际价值依赖于Camoufox上游核心能力，本项目的增量主要是REST/CLI封装；成本收益在Preview阶段未量化，API表面可能在小版本间变动。
多数声明可在仓库内追溯(配置项、CI、测试文件)。扣分点：核心反检测能力声明('通过Google/Cloudflare检测')依赖上游且无独立佐证；发布者身份未经核验，单一信息源；README中事实与营销性表述(robust/full)未明确分离。
- 本工具设计用途是绕过网站反机器人检测，部署前请评估法律与目标网站服务条款合规风险。
- postinstall 中 `|| true` 会掩盖 Camoufox 引擎下载失败，首次运行请通过 /health 显式验证引擎就绪。
- Preview 阶段 API 可能在小版本间变动，升级/回滚可能需手动清除本地状态文件。
- 发布者身份未经核验，生产环境引入前建议审计源码并锁定修订版本。
- 非回环绑定配合代理时，私有网络目标校验不足，需显式知情配置 CAMOFOX_ALLOW_PRIVATE_NETWORK。
这个 Agent 能做什么，适合哪些场景？
CamoFox Browser Server（redf0x1/camofox-browser）是一个用严格模式 TypeScript 编写的 Express 服务器，将 Camoufox——一个在 C++ 引擎层做指纹伪装的 Firefox 分支——封装为 HTTP 服务，默认监听 9377 端口。它提供约 42 个核心 REST 端点和约 7 个 OpenClaw 兼容端点，覆盖标签页创建、导航、可访问性快照（带 eN 元素引用）、点击/输入/滚动交互、截图、Cookie 导入导出、下载管理和 Playwright 追踪。每个 userId 获得独立的持久化 Firefox 配置目录，Cookie、localStorage 和 IndexedDB 跨会话保留，闲置上下文通过 LRU 淘汰。内置 14 个搜索宏（Google、YouTube、Reddit 等）、8 个地区预设以及基于命名配置文件的会话级代理与地理覆盖。它还附带 50 多条命令的 CLI、AES-256-GCM 加密的凭据保险库（凭据绝不输出到 stdout，对 LLM 安全）、结构化 schema 提取、控制台捕获，以及 Docker、Docker Compose、Fly.io、Railway、Render 等多种部署方式。项目目前处于 Preview 阶段，采用仅增量的弃用模型。
启动一个 Express/TypeScript 服务器（camofox-browser 命令或 npm start），包装 Camoufox 反检测 Firefox 引擎。客户端通过 REST 调用（如 POST /tabs 创建标签页、POST /tabs/:tabId/navigate 导航或展开 @google_search 等宏、GET /tabs/:tabId/snapshot 获取带 eN 引用的可访问性快照、POST /tabs/:tabId/click|type|press|scroll 交互、GET /tabs/:tabId/screenshot 截图）驱动浏览器，也可使用 OpenClaw 兼容端点 /start、/tabs/open、/act。POST /tabs/:tabId/extract-structured 按 schema 输出确定性 JSON，无需任意 JavaScript。CLI 提供 camofox open/snapshot/click/type/session/cookie/auth/trace 等命令并可用 camofox run 执行流水线脚本；auth save/load 使用 AES-256-GCM + Argon2id 保险库，--inject 将凭据直接注入页面而不暴露给 LLM。服务器按 userId 管理持久化浏览器上下文（默认最多 50 个会话、每会话 10 个标签页），支持 8 个内置 geo 预设、自定义预设文件（CAMOFOX_PRESETS_FILE）、命名代理配置文件（CAMOFOX_PROXY_PROFILES_FILE）和 explicit-wins / proxy-locked 两种 geo 模式；显示模式可在 headless、headed 和 Linux 专属的 virtual（Xvfb + noVNC，默认 2 分钟自动结束）之间切换。Docker 镜像为 ghcr.io/redf0x1/camofox-browser，通过 CAMOFOX_HOST、CAMOFOX_AUTH_MODE、CAMOFOX_API_KEY 等环境变量控制绑定与鉴权。
- 需要抓取或自动化受 Cloudflare、Google 等反爬系统保护的站点的 AI Agent 开发者，希望用引擎级指纹伪装而非脆弱的 JS 注入补丁。
- 构建 LLM 自动化流水线的工程师，需要语言无关的 HTTP 端点驱动浏览器：创建标签页、按 eN 引用点击、截取快照并以 JSON 形式回传。
- 需要在多个账号/身份间保持登录态的团队：每个 userId 的持久化 Firefox 配置保留 Cookie、localStorage 和 IndexedDB。
- 需要按地区模拟访问（如 japan、uk 预设）或将出口 IP 与时区/语言锁定的采集任务，可用 geo 预设与 proxy-locked 模式。
- 希望让 Claude Code、Cursor 等编程助手直接操作浏览器的用户，可通过 npx skills add redf0x1/camofox-browser 安装技能，或用 CamoFox MCP 做协议级集成。
- 需要安全注入登录凭据而不把密码暴露给 LLM 的自动化场景：auth vault 以 AES-256-GCM 存储凭据并用 --inject 直接填入页面。
这个 Agent 有哪些优点和局限？
- 反检测发生在 Camoufox 的 C++ 引擎层而非 JS 注入，README 称可通过 Google、Cloudflare 等反爬检测，比 Puppeteer/Playwright 的 JS 补丁更稳健。
- 面向 Agent 的接口齐全：REST API + OpenClaw 兼容端点 + 外部 CamoFox MCP + 可安装到 Claude Code/Cursor 等的 skills，且有 --format 的 CLI 输出。
- eN 元素引用的可访问性快照比原始 HTML/截图更省 token，结构化提取（extract-structured）提供确定性 JSON 且无需执行任意 JavaScript。
- 运维细节完善：持久化配置、LRU 上下文淘汰、两段式闲置清理、健康探测、Playwright 追踪、AES-256-GCM 凭据保险库、版本化本地状态与 fail-closed 完整性检查。
- 项目处于 Preview（Phase 1）：API 表面未冻结，端点行为和响应格式可能在次版本间变化，且本地状态升级不兼容时需手动删除 profile/registry 文件。
- 运行成本高：浏览器加上下文需要 2GB+ 内存，每个 userId 一个持久 Firefox 进程（默认上限 50 会话、每会话 10 标签页）；建议 Linux 生产环境。
- 平台限制：Windows x64 仅支持 headless=true，Xvfb/VNC 虚拟显示仅限 Linux，VNC 会话默认 2 分钟自动结束。
- 与上游绑定较深：依赖 Camoufox 引擎（Windows 便携包还因字体版权排除其 fonts 目录），YouTube 字幕提取额外依赖 yt-dlp。
如何安装或部署这个 Agent？
三种方式任选其一。
1) 从源码：git clone https://github.com/redf0x1/camofox-browser.git && cd camofox-browser && npm install && npm run build && npm start（需 Node.js 20+，建议 2GB+ 内存）。
2) npm 全局安装：npm install -g camofox-browser，然后运行 camofox-browser 启动服务器或直接用 camofox 命令（CLI 会按需自动启动服务器）。
3) Docker：docker run -d --name camofox-browser -p 9377:9377 -p 6080:6080 -e CAMOFOX_HOST=0.0.0.0 -e CAMOFOX_AUTH_MODE=auto -e CAMOFOX_API_KEY=change-me -v ~/.camofox:/home/node/.camofox ghcr.io/redf0x1/camofox-browser。也提供 Windows x64 便携 ZIP（免装 Node.js，仅支持 headless=true）以及 Fly.io/Railway/Render 部署配置。
如何使用这个 Agent？
启动后先用 curl http://localhost:9377/health 验证（返回 {"ok":true,"engine":"camoufox","browserConnected":true}）。REST 用法：POST /tabs 带 {"userId":"agent1","sessionKey":"task1","url":"https://example.com","preset":"japan"} 创建标签页；POST /tabs/:tabId/navigate 可用 {"macro":"@google_search","query":"..."} 执行搜索宏；GET /tabs/:tabId/snapshot?userId=agent1 获取带 eN 引用的可访问性树；POST /tabs/:tabId/click 带 {"userId":"agent1","ref":"e12"} 交互。CLI 用法：camofox open https://example.com → camofox snapshot → camofox click e5 → camofox screenshot --output page.png → camofox close；用 --format 获得结构化输出供 Agent 解析。凭据注入：camofox auth save gmail 保存后，用 camofox auth load gmail --inject --username-ref e5 --password-ref e12。多步流程可写入脚本文件后 camofox run flow.txt 执行。安全注意：默认 CAMOFOX_HOST=127.0.0.1；绑定到非回环地址时 auto 模式要求设置 CAMOFOX_API_KEY，且默认禁止导航到回环/私有/元数据地址。
这个 Agent 与同类方案有什么区别？
README 将其与 Puppeteer/Playwright 对比：后者的反检测依赖脆弱的 JavaScript 补丁且指纹伪装有限，而 CamoFox 使用 Camoufox 的 C++ 引擎级伪装，并通过 REST API + 可访问性快照为任意语言和 AI Agent 提供语言无关、更省 token 的集成方式。底层引擎是 daijro 的 Camoufox，另有配套的 CamoFox MCP 服务器用于 Claude、Cursor、VS Code 等 MCP 客户端。