ghostfox

---

AI Agent 会遭到拦截。无头 Chrome 会在约 20% 的网络上触发 Cloudflare 403 错误，而托管的“隐匿浏览器”会让 Agent 的 Cookie、身份和会话经由他人的云服务传输。

Ghostfox 是另一种选择：一套由你自行运行的完整浏览器栈——由指纹一致的隐匿引擎和 Rust MCP 运行时组成，全部集成在同一个代码库中。

Firefox (MPL-2.0)
  └─ Camoufox (anti-detect patches, by daijro)
       └─ Ghostfox engine          engine/   — spoofing at the C++ level
            └─ Ghostfox runtime     runtime/  — Rust: sessions, identities, MCP

	Ghostfox	托管隐匿服务（如 Browserbase）	playwright-mcp	反检测套件（如 Multilogin）
可自托管	✓	✗	✓	部分支持
开源	✓	✗	✓	✗
原生支持 MCP	✓	✓	✓	✗
引擎级反检测	✓（C++/Firefox）	供应商合作	✗	✓（闭源）
一致的身份 + 审计工具	✓	✗	✗	部分支持
运行时语言	Rust	—	Node	—

护城河——这为何不只是又一个封装器。

1. 我们拥有引擎。 反检测功能通过 C++ 补丁实现，直接集成在我们自己的 Firefox 分支中，而不是通过检测器可以读取的注入式 JS 实现。上游 Camoufox 已表明补丁将部分闭源；封装器会继承这一风险，而拥有自有引擎的分支不会。
2. 持续积累的实证语料。 这里的每项声明都有凭据：bilibili 图标点选 ×6、生产环境注册中的 hCaptcha、TikTok OAuth+OTP 实测、500/500 身份审计、Docker E2E。功能一周内就会被复制，但经过验证的历史无法复制。
3. 为 Agent 原生打造的易用性。 43 个协调一致的 MCP 工具、执行后验证的凭据、证据记录，以及从真实运行中提炼的操作手册（AGENTS.md）。Agent（及其提示词）会在这个界面上养成习惯，迁移成本确实存在。
4. 规范化分发。 以同一名称发布到 PyPI、npm、GHCR 和官方 MCP Registry，并提供文档、基准测试和变更日志作为支撑。分支会一直存在，但经过验证的主干就在这里。

验证码套件——8 类验证码，设备端求解（v0.6.7+）。 运行时内置了采用本地模型的 MCP 原生求解器——无需付费验证码农场、云服务或浏览器租赁：

类别	原生工具	方式
GeeTest 滑块 / v4 雷达	page_geetest_slide	背景图与完整背景图差异比较 + 最大连通块间隙检测
GeeTest 图标点选（文字点选）	page_geetest_click	自定义训练的 YOLOv8s + 孪生网络相似度（rten，CPU）
旋转	page_captcha_rotate	24 角度扫描 + 程序化判定
普通 OCR	page_captcha_ocr	移植版 ddddocr（CRNN+LSTM，onnxruntime）
hCaptcha	page_hcaptcha	布局路由器 + 553 模型的 QIN2DIM 模型库 + 可选的视觉模型集成
Cloudflare Turnstile / TikTok	captcha_solve + 行为配方	AGENTS.md §6b–6e 中经过验证的操作手册

已针对生产网站完成 E2E 验证（非供应商演示）：bilibili 图标点选 ×6，显示“Verification Succeeded”；真实注册流程中的 hCaptcha（dashboard.hcaptcha.com、dosya.co）；TikTok OAuth+OTP 实时会话。

调试中枢——能说明原因的页面工具（v0.7）。 页面行为异常时，Agent 不再需要猜测：

• page_console — 页面加载以来的所有 console.log/warn/error
• page_errors — 带堆栈跟踪的未捕获 JS 异常
• page_network_start/read/body — 请求/响应捕获及正文获取

这就是通过 MCP 提供的 DevTools 三件套。

多模型视觉（可选）。 page_vision + page_ocr + page_match_image + page_pixels + page_contrast — 可接入任意具备视觉能力的模型（Cloudflare Workers AI、GLM、Qwen 等），用于交叉验证网格谜题和布局问题。密钥为可选项；上述原生求解器完全在本地运行。

从原生来源观察——page_a11y {"native": true} 读取引擎自身的无障碍树（Gecko 的 DocAccessible 遍历，即 ariaSnapshot 机制），因此页面脚本无法篡改你看到的内容：影子 DOM、iframe 和 ARIA 语义均由 Gecko 自行处理，并提供更丰富的状态（焦点、必填、已选中、已展开、已禁用、层级）。原生引用是观察句柄；执行操作时需通过角色+名称锚点或 JS 遍历来源。

Agent 的眼睛——page_a11y。 一次调用即可返回所有可见的交互元素，包括稳定引用、语义角色、可访问名称和实时值——可穿透影子 DOM 和同源 iframe，因此可完整查看 Web 组件 UI（Reddit、现代框架）。快照还会报告**login_state**（已登录 / 未登录 / 未知）、页面 URL 和标题，Agent 可在操作前检查会话状态，而不是等失败后再检查。

Agent 按引用执行操作：page_click_ref e38、page_type_ref e21 "text"——无需 CSS 选择器。富文本编辑器（Lexical、Draft、ProseMirror）通过编辑器原生输入路径处理，并提供执行后验证的凭据。page_wait_for 可取代手动休眠。page_read_ref 可返回完整且未经截断的值。page_upload_file 可绕过原生文件选择器。 也支持 Android 配置——session_create {"platform": "android"} 会提供竖屏屏幕、Adreno/Mali GPU、Android 字体栈和 Android 版 Firefox 的 UA，所有配置都像桌面设备身份一样经过审计（500/500 项一致，参见 运行时文档）。

身份统一，杜绝矛盾。 身份根据一致的设备预设（平台、屏幕、能实际搭配使用的 GPU 和字体）生成，在引擎层注入，并在使用前经过审计——被伪装的浏览器最怕的，就是自己声称“MacBook 上有 4 个核心”。

快速开始

选择一个发行版本：

# Python (Linux x86_64)
pip install ghostfox
python -c "import ghostfox; ghostfox.install_engine(); ghostfox.install_runtime()"

# npm / any MCP host
npm install -g ghostfox        # or: npx ghostfox install
{
  "mcpServers": {
    "ghostfox": { "command": "npx", "args": ["-y", "ghostfox", "mcp"] }
  }
}

# Docker (engine + MCP runtime, ubuntu:24.04 base)
docker run -i --rm ghcr.io/autokeren/ghostfox:v0.7.2
# or one-line install of the binary stack:
curl -fsSL https://raw.githubusercontent.com/autokeren/ghostfox/main/install.sh | bash
# Windows (PowerShell):
powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/autokeren/ghostfox/main/install.ps1 | iex"

也已列入官方 MCP 注册表 （io.github.autokeren/ghostfox）——在支持注册表的客户端中一键添加。

从源代码开始：

# 1) Get the engine (prebuilt) and unpack it somewhere, e.g. /opt
unzip ghostfox-<ver>-lin.x86_64.zip -d /opt/ghostfox

# 2) Build the runtime
git clone https://github.com/autokeren/ghostfox.git
cd ghostfox/runtime
cargo build --release

{
  "mcpServers": {
    "ghostfox": {
      "command": "/path/to/ghostfox/runtime/target/release/ghostfox-mcp",
      "env": { "GHOSTFOX_HOME": "/opt/ghostfox" }
    }
  }
}

然后，Agent 可以：session_create → page_open → page_a11y → 按 ref 执行操作。

可移植的会话。 session_create 支持使用 profile_dir 来保存配置文件：Cookie、存储数据和身份 TOML 文件集中存放在一处，让登录状态在重启后仍然有效。要从其他 Camoufox 系浏览器迁移会话？复制 Cookie，并让身份与来源设备匹配（平台、时区、地区、屏幕）——会话身份突然改变，看起来就像一次不可能的登录，反欺诈系统会撤销该会话。经验证的流程，参见 AGENTS.md §8。

完整工具集（71 个工具）——两个层级，一个二进制文件：

• core（默认）：26 个精选工具——黄金循环（读取 → 操作 → 验证）以及调试必备工具，没有重复变体。这是 Agent 和注册表检查器开箱即见的工具集：高效、清晰，每个工具的描述都会说明何时优先使用该工具。
• full：全部 71 个工具——验证码系列、像素/视觉层级、网络拦截、WebSocket 捕获/注入/阻止、身份变更、chrome 模式、Android、page_download（基于浏览器身份的媒体采集）。使用 GHOSTFOX_TOOLSET=full 运行服务。

该服务还会发布使用说明（Agent 在选择工具前读取的决策树）——为这两个层级提供消歧说明。

类别	工具
会话	session_create · session_pages · session_me
查看	page_a11y（语义信息 + 登录状态 + shadow DOM/iframe） · page_extract（带类型、节省令牌的 a11y 筛选器） · page_snapshot · page_screenshot · page_read_ref（完整值） · page_diff（observeDiff：自上次快照以来的变化） · page_mutations（M3：无法钩取的 DOM 变更提示） · page_a11y_events（M3：以流的形式呈现 a11y 树——焦点/文本/状态/实时区域事件，以及增量差异）
等待	page_wait_for（轮询直到可见） · page_dismiss_modal · page_wait_stable（渲染稳定后） · page_wait_visual（M3.5：基于刷新驱动器的视觉稳定性——告别 sleep）
操作	page_click_ref · page_click_native（可信的 a11y 边界点击：先滚动，坐标经 DOM 验证） · page_click_at（原始可信坐标——不进行 a11y 解析） · page_type_ref · page_click · page_type · page_fill · page_press · page_drag · page_move_to · page_upload_file · page_init_script · page_a11y_set_text（AT 原生文本输入——Flutter 路径）
验证码	captcha_solve · page_geetest_slide · page_geetest_click · page_captcha_rotate · page_captcha_ocr · page_hcaptcha · page_captcha_vision（用于读取扭曲文本验证码的主机端 VLM）
网络代理	page_network_intercept（拦截每个请求） · page_network_resume（修改 url/method/headers/postData） · page_network_abort（阻止） · page_network_fulfill（模拟响应）
调试	page_console · page_errors · page_network_start · page_network_read（每个请求的 DNS/TLS/TTFB 耗时） · page_network_body · page_frame_stats（M3.5：卡顿检测器——帧间隔统计） · page_timing_report（M3.5：导航计时 + 绘制） · page_ws_frames（M3：WebSocket 流——双向套接字和帧） · page_ws_send（M3：WS 注入——客户端→服务端消息） · page_ws_block（M3：WS 阻止——丢弃双向帧） · page_ui_audit（M5：对渲染后 UI 进行视觉 QA）
视觉	page_vision · page_ocr · page_match_image · page_pixels（合成器像素——区域/语义/ref，不使用 toDataURL） · page_contrast
检查	page_eval · page_open · page_comment
采集	page_download（通过浏览器身份获取媒体——cookies、TLS 指纹、referer；流式传输到 <session>/downloads/）
身份	identity_generate · identity_audit · identity_morph（停止→重新启动→更换身份，同时保留会话）
身体感知	page_proprio（M4：真实身体状态——焦点、选区/插入符、滚动器） · page_cookie_events（M4：cookie/会话心跳——身份验证 cookie 被删除是会话失效的最早信号） · session_vitals（M4.5：每个进程的 CPU/内存）
配方	recipe_record · recipe_save · recipe_list · recipe_replay（确定性重放、语义锚点、严格/宽松升级）
证据与安全	session_evidence · confirm_action

每次修改都会返回一份回执——page_fill 会报告 landed_chars，而 type_ref 会先触发再验证异步编辑器，因此页面静默切换不会悄然吞掉 编辑内容。会话也可以以有头模式运行（{"headful": true}），以便 人类观察 Agent 的工作。

每次运行都会记录证据。 每个会话都会在 ~/.ghostfox/recordings/ 下写入仅追加的事件日志 （events.jsonl）、完整页面快照和所用身份——随时可通过 session_evidence 获取。

引擎诊断。 ghostfox-mcp --self-test 会遍历引擎 管线（检测 → 启动 → juggler 握手 → Browser.enable），并在失败时 打印逐步报告以及引擎的 stderr 尾部内容——平台行为异常时，将输出 粘贴到 issue 中。

无需模拟器的 E2E：Flutter Web + 任意 Web 应用

Android E2E 通常意味着要用模拟器、Appium 和一整组设备。 Ghostfox 选择了 Web 路线：将 Flutter 应用构建为 Web 应用 （flutter build web——使用同一套 Dart 代码），再用针对恶意网站的 同一套感知能力来操控：

• 原生读取语义树——启用语义后，Flutter 的无障碍节点（角色、 标签、边界）会出现在 page_a11y(native=true) 中（只需在应用中添加一行：SemanticsBinding.instance.ensureSemantics()）。
• 原生点击——page_click_native 会在 Flutter 按钮可信的无障碍坐标处触发点击（已验证：提交会触发，状态会渲染）。
• 回执 + page_diff + page_mutations + page_wait_stable — 使用同一套执行→观察→对比的证据闭环，无需靠轮询猜测。
• 视觉 QA——page_ui_audit 会评估渲染后的 UI。

范围说明：逻辑／流程／UI 均可完整覆盖；要让最终视觉效果与真实设备（Impeller 渲染）一致，以及测试平台通道（传感器、 摄像头），仍需在设备或模拟器上运行一次。

赞助

Ghostfox 独立开发，由自有资金支持。如果它帮你的团队绕过了验证码墙， 或避免了氛围编程造成的 UI 错误，请支持我们继续运营：

• GitHub Sponsors — 按月 赞助，金额不限
• Buy Me a Coffee — 一次性赞助

企业：现已开放赞助，并可提前使用托管的 Visual QA 服务 —— sponsor the repo， 或提交标题为 sponsorship 的 issue。

或者用一条命令安装（Linux x86_64）：

curl -fsSL https://raw.githubusercontent.com/autokeren/ghostfox/main/install.sh | bash

从源码端到端构建（自行构建引擎）： 参见 engine/README.md — make dir && make build。

仓库结构

runtime/   Rust: ghostfox-{core,fingerprint,mcp,eval}     (MIT OR Apache-2.0)
engine/    Browser fork: patches, branding, build system    (MPL-2.0)
AGENTS.md  The agent playbook — how AI agents drive Ghostfox like a human
SKILL.md   The compact agent skill — the golden loop + tool map at a glance
docs/JOURNEY.md  The dev-log, todo list and the road ahead (the five senses)

两个目录，两种许可证，一个产品。运行时原生使用 Juggler——运行时无需 Node 或 Python。

要将 Ghostfox 与 AI Agent（opencode、Codex、Cursor、Claude Code、 ……）搭配使用？ 请先阅读 AGENTS.md——其中汇总了 实际 Agent 运行中的实用指南：READ → REASON → DECIDE → ACT 循环、自我健康管理 （速率限制、草稿、通知）、富文本编辑器输入，以及所有已知的拦截及其经验证的解决方案。

为什么要自己掌控引擎？

• 反检测能力经得起检查。 欺骗行为在引擎内部实现（navigator、screen、WebGL、字体、WebRTC、时区、音频），而不是放在检测器可以读取的注入式 JS 中。
• 不依赖云服务。 Agent 的身份信息和 Cookie 绝不会流经第三方主机。
• 上游保障。 engine/ 跟踪 daijro/camoufox 作为 upstream；Ghostfox 使用自己的品牌，可随时变基——即使上游补丁改为闭源也不例外。

状态

v0.7 — alpha。已验证：身份一致性（500/500）、完整 MCP 往返 E2E（创建 → 打开 → 填写 → 提交）、在生产网站上的 8 类验证码 E2E （bilibili、受 hCaptcha 保护的注册页面、TikTok）、调试 cortex （控制台／错误／网络）、Docker 镜像 E2E（在容器内完成会话 → 打开 → 快照）、 Camoufox 衍生浏览器之间的可移植会话。通过 PyPI、npm、Docker (GHCR) 和官方 MCP Registry 分发。 已知限制记录在 runtime/ 和 engine/ 下的变更日志中。

请勿用于测试未经授权的目标。 这是一个测试／研究工具。

致谢

Ghostfox 脚踏巨人的肩膀而立—— Camoufox（daijro）提供反检测补丁栈， Mozilla Firefox 提供引擎， LibreWolf 提供补丁工具链传承， Playwright 提供 Juggler 协议。

许可证

• engine/ — MPL-2.0（继承自 Firefox / Camoufox）。参见 engine/LICENSE。
• runtime/ — MIT OR Apache-2.0。参见 runtime/LICENSE-MIT。