Camofox Browser

在构建 AI 代理（Agent）时，最大的障碍往往不是逻辑推理，而是网络访问。传统的无头浏览器（如 Headless Chrome）或自动化工具（Playwright/Puppeteer）极易被 Cloudflare、Google 等平台的机器人检测机制识别并拦截。即使使用隐身插件，其本身也会成为新的指纹特征。

Camofox Browser 是一个专为 AI Agent 设计的隐形无头浏览器服务器，由强大的 Camoufox 引擎驱动。它通过在 C++ 层面修补 Firefox，从底层伪装 navigator、WebGL、AudioContext 等关键指纹，没有任何 JS 层面的 shim 或包装器痕迹，从而实现真正的“隐形”。

核心亮点：隐形、高效、智能

1. C++ 级底层反检测

• 深度伪装：在 JavaScript 执行前，直接在 C++ 层修改硬件并发数、渲染器信息、屏幕几何、WebRTC 等指纹数据。
• 零痕迹：没有可被检测的 JS 注入痕迹，完美绕过 Google、Cloudflare 及大多数主流机器人检测系统。
• 真实体验：提供接近真实用户浏览器的行为特征，大幅降低被封禁风险。

2. Token 高效与稳定交互

• 可访问性快照：返回精简的 Accessibility Snapshot，比原始 HTML 小约 90%，显著降低 LLM 的 Token 消耗。
• 稳定元素引用：为页面元素分配稳定的 e1, e2, e3 标识符，即使 DOM 结构微调，Agent 也能可靠地点击和操作目标。
• REST API 封装：将复杂的浏览器操作简化为标准的 HTTP 接口，易于集成到任何技术栈中。

3. 智能会话管理与地理伪装

• Cookie 导入与持久化：支持 Netscape 格式 Cookie 文件导入，实现 LinkedIn、Amazon 等网站的认证浏览；会话状态自动持久化，无需重复登录。
• 代理 + GeoIP 自动匹配：通过住宅代理路由流量，Camoufox 自动根据出口 IP 调整浏览器的语言、时区和地理位置，确保指纹一致性。
• 会话隔离：每个用户拥有独立的 Cookie/Storage 空间，互不干扰。

4. 丰富的内置宏与工具

• 搜索宏：内置 @google_search, @youtube_search, @amazon_search 等 10+ 种常用搜索模板，简化 Agent 指令。
• YouTube 字幕提取：集成 yt-dlp，无需 API Key 即可快速提取任何 YouTube 视频的隐藏字幕。
• 结构化提取：支持通过 JSON Schema 定义提取规则，结合 x-ref 映射，精准获取页面数据。
• VNC 交互式登录：通过 noVNC 可视化界面手动完成复杂登录或验证码，随后导出状态供 Agent 复用。

快速开始

1. 独立运行（推荐开发测试）

git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
npm install
npm start  # 首次运行会自动下载 Camoufox 二进制文件（约 300MB）

服务默认启动在 http://localhost:9377。

2. Docker 部署（推荐生产环境）

使用提供的 Makefile 自动检测架构并预下载二进制文件，加速构建：

make up  # 自动检测 M1/M2 (aarch64) 或 Intel (x86_64)

3. OpenClaw 插件集成

如果你使用 OpenClaw 框架，可直接安装插件：

openclaw plugins install @askjo/camofox-browser

可用工具包括：camofox_create_tab, camofox_snapshot, camofox_click, camofox_type 等。

典型应用场景

高级配置：Cookie 导入与认证

为了跳过复杂登录，Camofox 支持导入浏览器导出的 Cookie 文件：

1. 生成 API Key：

   openssl rand -hex 32
   export CAMOFOX_API_KEY="your-generated-key"
   

2. 导出 Cookie：使用浏览器扩展（如 “cookies.txt”）导出 Netscape 格式的 Cookie 文件（如 linkedin.txt）。
3. 放置文件：

   mkdir -p ~/.camofox/cookies
   cp linkedin.txt ~/.camofox/cookies/
   

4. Agent 调用：
   Agent 执行 camofox_import_cookies 工具，后续访问该域名时将自动携带认证状态。

隐私与遥测

• 匿名遥测：默认开启匿名崩溃/卡顿报告（通过 GitHub Issues），帮助改进稳定性。可通过 CAMOFOX_CRASH_REPORT_ENABLED=false 关闭。
• 数据本地化：所有会话数据、Cookie、Trace 文件均存储在本地（~/.camofox/），无云端上传风险。