Camofox Browser

这个 Agent 能做什么，适合哪些场景？

Camofox Browser 是一个运行在 Node.js 上的自托管浏览器服务器，以 Camoufox 的 Firefox 引擎为基础，并通过 REST API 供自动化客户端调用。它把页面转为带 e1、e2 等稳定元素引用的无障碍快照，而非直接返回大量 HTML，并提供点击、输入、导航、滚动、截图与下载读取等接口。每位用户使用独立 BrowserContext，项目可持久化 cookies 和 localStorage，并可按 sessionKey 组织标签页。服务按需启动浏览器、在空闲时关闭，支持 Docker、Railway 和 Fly.io 等部署路径。它还包含代理与 GeoIP 配置、Netscape 格式 Cookie 导入、可选 VNC 登录、会话 Trace、YouTube 字幕提取及匿名化故障遥测。

客户端通过 POST /tabs 创建带 userId、sessionKey 和 URL 的标签页；服务启动 Camoufox，并在该用户的 BrowserContext 中打开页面。随后可调用 GET /tabs/:id/snapshot 获取带元素 ref 的无障碍快照，可选 includeScreenshot=true 返回 base64 PNG；POST /tabs/:id/click、/type、/press、/scroll、/navigate 分别执行交互，navigate 可使用 @google_search、@reddit_search 等宏。GET /tabs/:id/links、/images、/downloads 和 /screenshot 分别提取链接、img 信息、已捕获下载和截图；POST /tabs/:tabId/extract 支持以 JSON Schema 和 x-ref 做结构化提取。它可通过 POST /sessions/:userId/cookies 注入 Playwright cookie 对象，使用 GET /sessions/:userId/storage_state 导出存储状态，并在首个标签创建时传入 trace:true 来生成 Playwright trace zip。POST /youtube/transcript 优先调用 yt-dlp 提取字幕，缺少 yt-dlp 时回退到浏览器拦截方式。

1. 正在构建网页研究助手的开发者，需要让后端服务创建标签页、读取无障碍快照，并按 e1 这类引用完成点击和输入。
2. 运行多用户自动化任务的团队，需要让不同 userId 的 cookies、localStorage 和标签页互相隔离，并在重启后恢复会话。
3. 需要通过住宅代理访问地区相关网页的采集系统，可配置 PROXY_HOST 或 backconnect 代理，并让 Camoufox 根据出口 IP 设置语言、时区和地理位置。
4. 需要复用人工登录状态的运营人员，可先通过 VNC 完成站点登录，或导入 Netscape 格式 cookie 文件供后续会话使用。
5. 需要排查浏览器任务失败的工程团队，可对指定会话开启 Playwright trace，并通过 trace zip 查看截图、DOM 快照、网络请求和控制台输出。
6. 需要获得 YouTube 视频字幕的自动化流程，可向 /youtube/transcript 提交视频 URL，并在本机安装 yt-dlp 以走更快的提取路径。

这个 Agent 有哪些优点和局限？

如何安装或部署这个 Agent？

独立运行：

git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
npm install
npm start

服务默认监听 http://localhost:9377；首次运行会下载约 300MB 的 Camoufox。也可直接运行：

npx @askjo/camofox-browser

Docker 部署请使用项目提供的流程：

make up

如需导入 Cookie，先生成并设置密钥：

export CAMOFOX_API_KEY="your-generated-key"
npm start

如需更快的 YouTube 字幕提取，在本地额外安装：

pip install yt-dlp

如何使用这个 Agent？

创建第一个标签页：

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

使用响应中的 TAB_ID 获取快照：

curl "http://localhost:9377/tabs/TAB_ID/snapshot?userId=agent1"

按快照中的元素引用点击：

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

若将服务暴露到非本地网络，可设置 CAMOFOX_ACCESS_KEY，并在请求中发送 Authorization: Bearer <key>。

这个 Agent 与同类方案有什么区别？

常见问题