jo-inc/camofox-browser

camofox-browser – 专为 AI 代理设计的反检测浏览器服务器

它是什么 – 一个 Node-JS 服务，运行修补过的 Firefox 二进制文件 (Camoufox) 并公开 REST API，让自主 AI 代理能够在不被指纹识别或封锁的情况下浏览网页。浏览器在 C++ 层级进行修改，在任何 JavaScript 执行之前伪装硬件、WebGL、WebRTC、屏幕尺寸等。服务器返回轻量级的 无障碍快照 (页面 UI 树的精简表示) 以及可选的屏幕截图，并提供稳定的元素引用 (e1, e2 …) 以实现可靠的点击、输入、滚动等操作。

对 AI 的重要性 – 大型语言模型代理通常需要从网站获取真实世界的信息。传统的无头浏览器 (Playwright, Chrome) 很容易被反机器人服务 (Google, Cloudflare) 检测并封锁。camofox-browser 通过以下方式解决此问题：

• 使用 Camoufox 的底层指纹伪装，使会话看起来像正常的桌面版 Firefox。
• 提供 Token 高效的 API (快照比原始 HTML 小约 90 %)，减少 LLM 的 Token 使用量。
• 支持会话隔离、Cookie 导入、代理/GeoIP 处理以及基于 VNC 的手动登录，使代理能够在任务间维护已验证的会话。

主要功能

• C++ 反检测 – 在 JS 检测到之前伪装硬件并发性、WebGL、AudioContext、屏幕几何结构、WebRTC 等。
• 元素引用 – 用于确定性操作的稳定标识码 (e1, e2)。
• 无障碍快照 – 精简的 JSON UI 树；可选的 base64 PNG 屏幕截图。
• 会话管理 – 用户专属存储、Cookie 导入 (Netscape 格式)、持久化配置文件、可选的 IndexedDB 持久化。
• 代理与 GeoIP – 支持住宅代理，并具有自动地区/时区匹配功能。
• 搜索宏 – 内置 Google、YouTube、Amazon、Reddit 等的快捷方式。
• YouTube 字幕 – 通过 yt-dlp (无需 API 密钥)。
• 大型页面处理 – 快照分页、下载截取、图片提取。
• 追踪 – 每个会话可选的 Playwright 追踪 (屏幕截图、DOM、网络)，可下载为 zip 包。
• 部署性 – Docker、Fly.io、Railway、Raspberry Pi；低闲置内存占用 (~40 MiB)。
• 遥测 – 发送匿名崩溃/健康报告至 Cloudflare Worker 以创建 GitHub issues；可选择退出。

如何开始

1. 克隆并安装：

   git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
   npm install   # 首次执行时下载 Camoufox (~300 MiB)
   npm start     # 服务器监听 9377 端口
   

2. 调用 API (示例创建一个标签页)：

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

   响应包含 tabId 和无障碍快照。
3. 使用提供的 OpenClaw 插件指令 (camofox_click, camofox_type, …) 或直接调用 HTTP 端点与页面交互。
4. 对于需要验证的网站，导入 Cookie：

   export CAMOFOX_API_KEY=$(openssl rand -hex 32)
   # 将 Netscape 格式的 Cookie 文件放入 ~/.camofox/cookies/
   camofox_import_cookies linkedin.txt
   

5. 使用提供的 Makefile/build.ps1 通过 Docker (或 Fly.io/Railway) 部署 – 脚本会预先下载二进制文件以加快构建速度。

典型使用案例 – 基于 LLM 的个人助理 (例如 jo) 收到请求，例如 “在 Reddit 上寻找 2024 Tesla Model Y 的最新评论并进行总结。” 代理调用 camofox_browser 打开 Reddit，运行搜索宏，通过无障碍快照提取 UI 树，解析相关元素，然后撰写响应——所有这些过程，底层浏览器对 Reddit 的反机器人措施来说都是无法检测的。

限制 / 考量

• 需要 Camoufox 二进制文件 (≈300 MiB)，YouTube 字幕可配选 yt-dlp。
• 遥测默认启用；若有隐私顾虑，请使用 CAMOFOX_CRASH_REPORT_ENABLED=false 禁用。
• 追踪功能只能在创建会话时启用；之后无法切换。
• 本服务是 Playwright 控制的 Firefox 的封装，因此任何在网络层级封锁浏览器的网站 (例如 IP 封锁) 仍需要可靠的代理。

授权 – MIT。