redf0x1/camofox-browser

CamoFox Browser Server

是什么 – 一个基于 TypeScript 的服务器，封装了 Camoufox 隐蔽式 Firefox 引擎（一个带有 C++ 级指纹伪装功能的 Firefox 分支）。它提供语言无关的 REST API 和强大的 CLI，使 AI 代理或任何程序能够控制一个比 Puppeteer 或 Playwright 等常规自动化工具更难被反机器人系统检测到的浏览器。

对 AI 代理的重要性 – 现代的机器人检测服务会寻找无头 Chromium 浏览器留下的典型指纹。CamoFox 将伪装技术下放到浏览器引擎本身，使得生成的会话看起来像普通用户的 Firefox。服务器返回的是 结构化可访问性快照（带有稳定 eN 元素引用的小型 JSON 树），而不是原始 HTML 或截图，这使得 LLM 驱动的代理解析和响应成本更低。

核心功能

• 引擎级反检测 – C++ 级指纹伪装（地区、时区、画布、WebGL 等）
• REST API – HTTP 端点，用于打开页面、点击、输入、截图、提取结构化数据等；可从任何语言调用。
• CLI – 50 多个命令（camofox open、snapshot、click e5、type e3 "text"、trace start 等），需要时会自动启动服务器。
• 多会话与配置文件 – 支持最多 50 个并发用户会话，每个会话拥有独立的持久化 Firefox 配置文件（Cookie、localStorage、IndexedDB 在重启后仍保留）。
• 地理与代理预设 – 内置 8 个区域预设和会话级代理配置，支持混合“显式优先”或“代理锁定”模式。
• 搜索宏 – 在 Google、YouTube、Amazon、Reddit、Wikipedia、Twitter 等平台的一行搜索。
• 认证保险库 – AES-256-GCM 加密的凭证存储（基于 Argon2id 的密钥），可直接将凭证注入浏览器，而无需向调用的 LLM 暴露。
• Playwright 跟踪 – 记录并导出用于调试复杂交互的跟踪数据。
• 结构化提取 – 基于用户提供的模式生成确定性 JSON 输出，避免任意 JavaScript 执行。
• Docker 与便携式 Windows 构建 – 官方 Docker 镜像（ghcr.io/redf0x1/camofox-browser）和一个捆绑了 Node.js 与 Camoufox 二进制文件的头无优先 Windows-x64 ZIP 包。

LLM 驱动代理的典型工作流

1. 启动服务器（camofox 或通过 Docker）。
2. 打开页面 – camofox open https://example.com。
3. 快照 – camofox snapshot --format json → 带有稳定 eN 引用的 JSON 树。
4. 交互 – camofox click e5，camofox type e3 "hello"。
5. 提取数据 – camofox extract-structured @schema.json 或使用 /extract API 端点。
6. 持久化状态 – camofox session save login-flow 以供后续重用。
7. 安全登录 – 将凭证存入保险库（camofox auth save gmail）并注入（camofox auth load gmail --inject --username-ref e5 --password-ref e12）。

成熟度 – 目前处于 预览（阶段 1）。API 可用，但端点签名在小版本间仍可能变更，不兼容升级时需手动重置本地状态。

快速入门

# 从源码
git clone https://github.com/redf0x1/camofox-browser.git
cd camofox-browser
npm install && npm run build && npm start

# 或全局安装 CLI
npm install -g camofox-browser
camofox open https://example.com
camofox snapshot --format json

适用场景 – 为需要可靠、低曝光度网页交互（网页搜索、表单填写、数据提取、测试）的 AI 代理提供前端，避免传统无头浏览器的检测陷阱。