jo-inc/camofox-browser

camofox‑browser – 面向 AI 代理人的反检测浏览器服务器

是什么 – 一个极小的 Node.js 服务器，运行经过特殊修补的 Firefox 构建版本（Camoufox），并为 AI 代理人提供 REST API，使其能够浏览真实网络而不会被标记为机器人。浏览器的指纹在 C++ 层级被伪造，因此网站看到的是一个正常的 Firefox，而非无头或被监控的浏览器。

对代理人的意义 – 现代网络爬取工具（Playwright、无头 Chrome）正越来越多地被 Cloudflare、Google 等机器人检测服务屏蔽。camofox-browser 通过以下方式解决此问题：

• 在任何 JavaScript 执行前，伪造低层级属性（CPU 核心数、WebGL、AudioContext、屏幕尺寸、WebRTC 等）。
• 提供 可访问性快照（页面的紧凑、屏幕阅读器友好表示），其大小比原始 HTML 小约 90%，为 LLM 驱动的代理人节省 token 预算。
• 提供稳定的元素引用（e1, e2, …），使代理人能可靠地点击或输入，而无需脆弱的 CSS/XPath 选择器。

主要功能（如 README 所述）

功能	作用
C++ 反检测	通过在二进制级别修补 Firefox，绕过 Google、Cloudflare 及大多数机器人检测器。
元素引用	返回交互元素的稳定短 ID，使代理人的命令具有确定性。
高效 token 快照	发送可访问性树而非完整 HTML，大幅减少数据包大小。
低资源占用	延迟启动和空闲关闭使内存保持在约 40 MiB；可在廉价 VPS 或 Raspberry Pi 上运行。
会话隔离与持久化	每个用户独立的 cookie/存储；可选持久化至 ~/.camofox/profiles/。
Cookie 导入	接受 Netscape 格式 cookie 文件，使代理人可复用现有登录（如 LinkedIn、Amazon）。
文件上传	允许代理人从配置目录上传文件，无需原生操作系统对话框。
代理 + GeoIP	通过住宅代理路由流量；自动将区域、时区和地理位置与代理 IP 对齐。
YouTube 字幕	通过 yt‑dlp 提取字幕（无需 API 密钥）。
搜索宏	内置快捷方式如 @google_search、@youtube_search、@amazon_search 等。
快照截图	与可访问性快照一同返回 base64 编码的 PNG。
大页面处理	通过基于偏移的分页截断快照，保持响应可管理。
下载捕获	捕获浏览器下载的文件，并通过 API 提供（可选内联 base64）。
DOM 图像提取	列出 <img> 的源/alt 文本，并可返回 data-URL 版本。
随处部署	支持 Docker、Fly.io、Railway 或直接 npm start。
VNC 交互式登录	NoVNC UI 允许人类视觉登录；生成的存储状态可被代理人重用。
OpenAPI 文档	在 /openapi.json 自动生成规范，在 /docs 提供交互式 Swagger UI。
结构化提取	向 /tabs/:tabId/extract 发送 JSON 模式，将字段映射到快照引用（x‑ref）。
会话追踪	可选的 Playwright 跟踪（截图、DOM、网络）每会话提供，可下载为 zip。
遥测	匿名崩溃/挂起报告发送至 Cloudflare Worker 并创建 GitHub 问题；可禁用。

如何运行

1. 克隆并安装

   git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
   npm install   # 首次运行时下载 Camoufox 二进制文件（约 300 MiB）
   npm start     # 服务器监听 http://localhost:9377
   

2. 可选 – Docker（生产环境推荐）

   make up            # 构建镜像，下载二进制文件，启动容器
   # 停止/移除
   make down
   

   Makefile 会自动检测 CPU 架构（x86_64 或 aarch64），并预先下载 Camoufox + yt‑dlp，使构建快速。
3. 配置 – 多数行为由环境变量控制，例如：
   • CAMOFOX_API_KEY – 用于特权端点（Cookie 导入、VNC 登录）的密钥。
   • PROXY_HOST, PROXY_PORT, PROXY_USERNAME, PROXY_PASSWORD – 启用代理路由。
   • CAMOFOX_CRASH_REPORT_ENABLED=false – 禁用遥测。
   • CAMOFOX_EXECUTABLE – 若自行管理，可指向预下载的 Camoufox 二进制文件。

典型代理工作流

1. 创建标签页 – POST /tabs 传入 {userId, sessionKey, url}，返回 tabId。
2. 获取快照 – GET /tabs/:tabId/snapshot 返回可访问性树和 base64 PNG。
3. 交互 – 使用 POST /tabs/:tabId/click、.../type、.../scroll 等，通过稳定 ID（e1, e2）引用元素。
4. 提取结构化数据 – 定义 JSON 模式，将所需字段映射到 x‑ref ID，POST 至 /tabs/:tabId/extract。
5. 关闭 – DELETE /tabs/:tabId（或关闭整个会话）释放资源，并可选择性保存追踪。

集成点

• OpenClaw 插件 – README 提到 openclaw 插件（@askjo/camofox-browser）将 HTTP 调用封装为便捷的 CLI 命令（camofox_create_tab, camofox_click 等）。对已使用 OpenClaw 代理框架的开发者非常有用。
• 独立 CLI – npx @askjo/camofox-browser 可在不克隆仓库的情况下运行服务器。
• OpenAPI – 生成的规范可用于生成任意语言的客户端库，便于嵌入自定义 LLM 协调器。

谁开发了它 – 该项目由 Jo 团队维护，Jo 是一个部分运行在用户 Mac 上、部分运行在云机器上的个人 AI 助手。同一团队创建了 Camoufox，即底层的指纹伪造 Firefox 分支。

---

TL;DR

• camofox‑browser = 一个轻量级 REST 包装器，用于指纹伪造的 Firefox（Camoufox）。
• 专为需要在不被阻止的情况下浏览开放网络的 AI 代理人设计。
• 提供小型结构化快照、稳定元素 ID、Cookie 导入、代理支持和可选追踪。
• 使用 npm install && npm start 或通过 Docker/Make 安装；通过环境变量配置。