camofox-browser

专为 AI Agent 设计的反检测浏览器服务器，由 Camoufox 强力驱动。

基于强大的 Camoufox —— 一个在 C++ 层面进行指纹伪装的 Firefox 分支。

由 jo 团队开发。jo 是一个个人 AI Agent，一半运行在你的 Mac 上，另一半运行在专属云端，无需任何维护。支持 macOS、Telegram、WhatsApp 和 Email。立即免费体验 Beta 版 ->

git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
npm install && npm start
# -> http://localhost:9377

---

为什么选择它

AI Agent 需要浏览真实的网页。Playwright 容易被封锁，Headless Chrome 会被记录指纹，而各种“防检测”插件本身就成了显眼的指纹标识。

Camoufox 在 C++ 实现层面对 Firefox 进行了修补——包括 navigator.hardwareConcurrency、WebGL 渲染器、AudioContext、屏幕几何形状、WebRTC 等——这些信息在被 JavaScript 获取之前就已经完成了伪装。没有补丁（shims），没有封装（wrappers），没有泄露。

本项目将该引擎封装为专为 Agent 设计的 REST API：提供可访问性快照（而非臃肿的 HTML）、用于点击的稳定元素引用（Element Refs），以及针对常用网站的搜索宏。

功能特性

• C++ 反检测 - 绕过 Google、Cloudflare 和大多数机器人检测机制。
• 元素引用 (Element Refs) - 稳定的 e1, e2, e3 标识符，实现可靠的交互。
• Token 高效 - 可访问性快照比原始 HTML 小约 90%。
• 运行资源占用极低 - 延迟加载浏览器 + 空闲自动关闭，空闲时内存占用仅约 40MB。旨在与你的其他技术栈共存 —— 树莓派、5 美元 VPS、共享基础设施均可运行。
• 会话隔离 - 每个用户拥有独立的 Cookie/存储空间。
• Cookie 导入 - 支持导入 Netscape 格式的 Cookie 文件，实现已认证的浏览。
• 代理 + GeoIP - 通过住宅代理路由流量，并自动匹配地区/时区。
• 结构化日志 - 带有请求 ID 的 JSON 日志行，便于生产环境观察。
• YouTube 字幕提取 - 通过 yt-dlp 从任何 YouTube 视频提取字幕，无需 API Key。
• 搜索宏 - 内置 @google_search, @youtube_search, @amazon_search, @reddit_subreddit 等 10 多个快捷指令。
• 快照截图 - 在可访问性快照中包含 base64 PNG 格式截图。
• 大页面处理 - 自动进行快照截断，支持基于偏移量的分页。
• 下载捕获 - 捕获浏览器下载的文件，并通过 API 获取（可选内联 base64）。
• DOM 图片提取 - 列出 <img> 的 src/alt，并可选择返回内联数据 URL。
• 轻松部署 - 支持 Docker、Fly.io、Railway。
• VNC 交互登录 - 通过 noVNC 可视化登录网站，导出存储状态供 Agent 重用。
• OpenAPI 文档 - 在 /openapi.json 自动生成规范，并可在 /docs 查看交互式文档。
• 结构化提取 - 支持 POST /tabs/:tabId/extract，通过 x-ref 使用 JSON Schema 将属性映射到快照引用。
• 会话追踪 - 可选的每会话 Playwright 追踪捕获（截图 + DOM 快照 + 网络），并提供获取、查询及删除追踪 zip 包的 API。
• 遥测数据 - 通过 GitHub Issues 进行自动匿名崩溃/挂起遥测。用于识别哪些网站导致失败及常见的失败模式。私有域名会经过 HMAC 哈希处理，路径/参数会被剥离，Token/IP 会被遮盖。可通过 CAMOFOX_CRASH_REPORT_ENABLED=false 关闭。

可选依赖

依赖	用途	安装
yt-dlp	YouTube 字幕提取（快速路径）	pip install yt-dlp 或 brew install yt-dlp

Docker 镜像已包含 yt-dlp。对于本地开发，请安装它以支持 /youtube/transcript 接口。若未安装，该接口将回退到较慢的浏览器抓取方法。

快速开始

OpenClaw 插件

openclaw plugins install @askjo/camofox-browser

工具： camofox_create_tab | camofox_snapshot | camofox_click | camofox_type | camofox_navigate | camofox_scroll | camofox_screenshot | camofox_close_tab | camofox_list_tabs | camofox_import_cookies

独立运行

从 npm 运行：

npx @askjo/camofox-browser

或从源码运行：

git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
npm install
npm start  # 首次运行会自动下载 Camoufox (~300MB)

默认端口为 9377。查看 环境变量 获取完整配置选项。

注意： postinstall 脚本在获取 Camoufox 二进制文件前会自动取消设置 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD。如果不进行此覆盖，当环境变量 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 存在时（在配置 Playwright 使用系统 Chrome 时很常见），会导致程序静默跳过二进制文件下载，从而在运行时崩溃。

外部 Camoufox 可执行文件： 在 npm install 之前以及启动服务器时，设置 CAMOFOX_EXECUTABLE=/path/to/camoufox-bin 即可跳过捆绑下载。