名称： camoufox-stealth-browser
主页： https://github.com/kesslerio/camoufox-stealth-browser-clawhub-skill
描述： 使用 Camoufox（经过补丁的 Firefox）在隔离容器中进行 C++ 级别的反机器人浏览器自动化。可绕过 Cloudflare Turnstile、Datadome、Airbnb、Yelp。优于仅进行 JS 级别修补的基于 Chrome 的解决方案（如 undetected-chromedriver、puppeteer-stealth）。当标准 Playwright/Selenium 被屏蔽时使用。
元数据：
openclaw:
emoji: "🦊"
requires:
bins: ["distrobox"]
env: []

Camoufox 隐身浏览器 🦊

C++ 级别的反机器人规避方案，使用 Camoufox —— 一个定制的 Firefox 分支，其隐身补丁直接编译到浏览器本身，而非通过 JavaScript 附加。

为何 Camoufox 优于基于 Chrome 的解决方案

Camoufox 在源代码级别修补 Firefox —— WebGL、Canvas、AudioContext 指纹是真实地被伪造，而非通过反机器人系统可以检测到的 JavaScript 覆盖来掩盖。

主要优势

1. C++ 级别隐身 —— 指纹伪造直接编译进浏览器，而非 JS 技巧
2. 容器隔离 —— 在 distrobox 中运行，保持主机系统清洁
3. 双工具策略 —— Camoufox 用于浏览器，curl_cffi 用于纯 API（无浏览器开销）
4. 基于 Firefox —— 比 Chrome 的指纹特征更少（所有机器人都用 Chrome）

使用场景

• 标准 Playwright/Selenium 被屏蔽时
• 网站显示 Cloudflare 验证或"正在检查您的浏览器"时
• 需要抓取 Airbnb、Yelp 或类似受保护站点时
• puppeteer-stealth 或 undetected-chromedriver 失效时
• 需要真正的隐身，而非 JS 临时补救措施时

工具选择

快速开始

所有脚本均在 pybox distrobox 容器中运行以实现隔离。

⚠️ 请明确使用 python3.14 - pybox 容器可能安装了多个 Python 版本，且包环境不同。

1. 首次设置

# 在 pybox 容器中安装工具（使用 python3.14）
distrobox-enter pybox -- python3.14 -m pip install camoufox curl_cffi

# Camoufox 浏览器将在首次运行时自动下载（约 700MB 的 Firefox 分支）

2. 抓取受保护页面

浏览器模式 (Camoufox):

distrobox-enter pybox -- python3.14 scripts/camoufox-fetch.py "https://example.com" --headless

纯 API 模式 (curl_cffi):

distrobox-enter pybox -- python3.14 scripts/curl-api.py "https://api.example.com/endpoint"

架构概览

┌─────────────────────────────────────────────────────────┐
│                     OpenClaw 代理                       │
├─────────────────────────────────────────────────────────┤
│  distrobox-enter pybox -- python3.14 scripts/xxx.py     │
├─────────────────────────────────────────────────────────┤
│                      pybox 容器                         │
│         ┌─────────────┐  ┌─────────────┐               │
│         │  Camoufox   │  │  curl_cffi  │               │
│         │  (Firefox)  │  │  (TLS伪造)  │               │
│         └─────────────┘  └─────────────┘               │
└─────────────────────────────────────────────────────────┘

工具详情

Camoufox

• 是什么： 具有 C++ 级别隐身补丁的定制版 Firefox
• 优点： 最佳的指纹规避能力，可自动通过 Turnstile 验证
• 缺点： 约 700MB 下载量，基于 Firefox
• 最佳适用： 所有受保护站点 - Cloudflare、Datadome、Yelp、Airbnb

curl_cffi

• 是什么： 具有浏览器 TLS 指纹伪造功能的 Python HTTP 客户端
• 优点： 无浏览器开销，速度极快
• 缺点： 无法执行 JS，仅适用于 API 端点
• 最佳适用： 已知的 API 端点，移动应用逆向工程

关键：代理要求

数据中心 IP (AWS, DigitalOcean) = 在 Airbnb/Yelp 上会立即被屏蔽

必须使用住宅或移动代理：

# 代理配置示例
proxy = "http://user:pass@residential-proxy.example.com:8080"

有关代理配置，请参阅 references/proxy-setup.md。

行为规避技巧

像 Airbnb/Yelp 这样的网站会进行行为分析。为避免检测：

1. 预热： 不要直接访问目标 URL。先访问主页，滚动，点击浏览。
2. 鼠标移动： 注入随机鼠标移动（Camoufox 已处理此问题）。
3. 时机： 添加随机延迟（操作间隔 2-5 秒），而非固定间隔。
4. 会话粘性： 使用相同的代理 IP 维持 10-30 分钟的会话，不要每次请求都更换。

无头模式警告

⚠️ 旧的 --headless 标志可被检测。可选方案：

1. 新无头模式： 使用 headless="new" (Chrome 109+)
2. Xvfb： 在虚拟显示中运行有头浏览器
3. 有头模式： 如果可以，直接运行有头模式（最可靠）

# Xvfb 方案 (Linux)
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
python scripts/camoufox-fetch.py "https://example.com"

故障排除

Python 版本问题 (NixOS/pybox)

pybox 容器可能包含多个 Python 版本，且各自拥有独立的 site-packages：

# 检查哪个 Python 安装了 camoufox
distrobox-enter pybox -- python3.14 -c "import camoufox; print('OK')"

# 错误用法 (可能使用了不同的 Python)
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py ...

# 正确用法 (明确指定版本)
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py ...

如果遇到段错误或导入错误，请始终明确使用 python3.14。

示例

抓取 Airbnb 房源信息

distrobox-enter pybox -- python3.14 scripts/camoufox-fetch.py \
  "https://www.airbnb.com/rooms/12345" \
  --headless --wait 10 \
  --screenshot airbnb.png

抓取 Yelp 商家信息

distrobox-enter pybox -- python3.14 scripts/camoufox-fetch.py \
  "https://www.yelp.com/biz/some-restaurant" \
  --headless --wait 8 \
  --output yelp.html

使用 TLS 伪造进行 API 抓取

distrobox-enter pybox -- python3.14 scripts/curl-api.py \
  "https://api.yelp.com/v3/businesses/search?term=coffee&location=SF" \
  --headers '{"Authorization": "Bearer xxx"}'

会话管理

持久会话允许跨运行重用认证状态，无需重新登录。

快速开始

# 1. 交互式登录（打开有头浏览器）
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \
  --profile airbnb --login "https://www.airbnb.com/account-settings"

# 在浏览器中完成登录，然后按 Enter 保存会话

# 2. 在无头模式下重用会话
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \
  --profile airbnb --headless "https://www.airbnb.com/trips"

# 3. 检查会话状态
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \
  --profile airbnb --status "https://www.airbnb.com"

标志说明

存储

• 位置： ~/.stealth-browser/profiles/<name>/
• 权限： 目录 700，文件 600
• 配置文件命名： 仅限字母、数字、_、-（1-63 个字符）

Cookie 处理

• 保存： 来自所有域的所有 Cookie 都存储在浏览器配置文件中
• 恢复： 仅使用与目标 URL 域匹配的 Cookie
• SSO： 如果被重定向到 Google/认证域，重新认证一次后配置文件会更新

登录墙检测

脚本使用多种信号检测会话是否过期：

1. HTTP 状态码： 401, 403
2. URL 模式： /login, /signin, /auth
3. 标题模式： "login", "sign in" 等
4. 内容关键词： "captcha", "verify", "authenticate"
5. 表单检测： 密码输入字段

如果在 --headless 模式下检测到，您将看到：

🔒 登录墙信号：url-path, password-form

请使用 --login 重新运行以刷新会话。

远程登录 (SSH)

由于 --login 需要可见的浏览器，您需要进行显示转发：

X11 转发 (推荐)：

# 使用 X11 转发连接
ssh -X user@server

# 运行登录（在您的本地机器上打开浏览器）
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \
  --profile mysite --login "https://example.com"

VNC 替代方案：

# 在服务器上：启动 VNC 会话
vncserver :1

# 在客户端：连接到 VNC
vncviewer server:1

# 在 VNC 会话中：运行登录
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \
  --profile mysite --login "https://example.com"

安全注意事项

⚠️ Cookie 是凭证。 请像对待密码一样对待配置文件目录：
- 配置文件目录权限为 chmod 700（仅所有者）
- Cookie 导出文件权限为 chmod 600
- 不要通过不安全渠道共享配置文件或导出的 Cookie
- 考虑对备份进行加密

限制

参考文档

• references/proxy-setup.md — 代理配置指南
• references/fingerprint-checks.md — 反机器人系统检查的内容