介绍
# Stealth Browser Skill 🥷
反机器人浏览器自动化，可绕过 Cloudflare Turnstile、Datadome 和激进的指纹识别。
## 适用场景
- 标准的 Playwright/Selenium 被拦截 - 网站显示 Cloudflare 验证码或“正在检查您的浏览器” - 需要抓取 Airbnb、Yelp 或类似的受保护网站 - `playwright-stealth` 不再起作用
## 工具选择
| 目标难度 | 工具 | 适用场景 | |------------------|------|-------------| | **浏览器** | Camoufox | 所有受保护网站 - Cloudflare, Datadome, Yelp, Airbnb | | **仅 API** | curl_cffi | 无需浏览器，仅需 TLS 欺骗 |
## 快速开始
所有脚本均在 `pybox` distrobox 中隔离运行。
⚠️ **明确使用 `python3.14`** - pybox 可能安装了多个 Python 版本，且包含不同的软件包。
### 1. 设置（首次）
```bash # Install tools in pybox (use python3.14) distrobox-enter pybox -- python3.14 -m pip install camoufox curl_cffi
# Camoufox browser downloads automatically on first run (~700MB Firefox fork) ```
### 2. 获取受保护页面
**浏览器：** ```bash distrobox-enter pybox -- python3.14 scripts/camoufox-fetch.py "https://example.com" --headless ```
**仅 API：** ```bash distrobox-enter pybox -- python3.14 scripts/curl-api.py "https://api.example.com/endpoint" ```
## 架构
``` ┌─────────────────────────────────────────────────────────┐ │ OpenClaw Agent │ ├─────────────────────────────────────────────────────────┤ │ distrobox-enter pybox -- python3.14 scripts/xxx.py │ ├─────────────────────────────────────────────────────────┤ │ pybox Container │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ Camoufox │ │ curl_cffi │ │ │ │ (Firefox) │ │ (TLS spoof)│ │ │ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────┘ ```
## 工具详情
### Camoufox - **是什么：** 带有 C++ 级隐身补丁的自定义 Firefox 构建 - **优点：** 最佳的指纹规避，自动通过 Turnstile - **缺点：** 约 700MB 下载量，基于 Firefox - **最适用于：** 所有受保护网站 - Cloudflare, Datadome, Yelp, Airbnb
### curl_cffi - **是什么：** 带有浏览器 TLS 指纹欺骗功能的 Python HTTP 客户端 - **优点：** 无浏览器开销，速度非常快 - **缺点：** 无 JS 执行，仅限 API 端点 - **最适用于：** 已知的 API 端点，移动应用逆向工程
## 关键：代理要求
**数据中心 IP (AWS, DigitalOcean) = 在 Airbnb/Yelp 上会被立即拦截**
您必须使用住宅或移动代理：
```python # Example proxy config proxy = "http://user:[email protected]:8080" ```
代理配置请参阅 **[references/proxy-setup.md](references/proxy-setup.md)**。
## 行为技巧
像 Airbnb/Yelp 这样的网站会使用行为分析。为避免被检测到：
1. **预热：** 不要直接访问目标 URL。先访问主页，滚动，四处点击。 2. **鼠标移动：** 注入随机的鼠标移动（Camoufox 会处理此问题）。 3. **时机：** 添加随机延迟（操作之间 2-5 秒），不要使用固定间隔。 4. **会话粘性：** 在 10-30 分钟的会话中使用相同的代理 IP，不要在每个请求时轮换。
## 无头模式警告
⚠️ 旧的 `--headless` 标志会被检测到。选项：
1. **新版无头模式：** 使用 `headless="new"` (Chrome 109+) 2. **Xvfb：** 在虚拟显示器中运行有头浏览器 3. **有头模式：** 如果可以，直接运行有头模式（最可靠）
```bash # Xvfb approach (Linux) Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 python scripts/camoufox-fetch.py "https://example.com" ```
## 故障排除
| 问题 | 解决方案 | |---------|----------| | 立即出现“Access Denied” | 使用住宅代理 | | Cloudflare 验证死循环 | 尝试使用 Camoufox 代替 Nodriver | | 浏览器在 pybox 中崩溃 | 安装缺失的依赖：`sudo dnf install gtk3 libXt` | | TLS 指纹被拦截 | 使用 curl_cffi 并设置 `impersonate="chrome120"` | | 出现 Turnstile 复选框 | 添加鼠标移动，增加等待时间 | | `ModuleNotFoundError: camoufox` | 使用 `python3.14` 而非 `python` 或 `python3` | | `greenlet` 段错误 (退出码 139) | Python 版本不匹配 - 明确使用 `python3.14` | | `libstdc++.so.6` 错误 | NixOS lib 路径问题 - 在 pybox 中使用 `python3.14` |
### Python 版本问题 (NixOS/pybox)
`pybox` 容器可能拥有多个 Python 版本，且具有独立的 site-packages：
```bash # Check which Python has camoufox distrobox-enter pybox -- python3.14 -c "import camoufox; print('OK')"
# Wrong (may use different Python) distrobox-enter pybox -- python3.14 scripts/camoufox-session.py ...
# Correct (explicit version) distrobox-enter pybox -- python3.14 scripts/camoufox-session.py ... ```
如果遇到段错误或导入错误，请务必明确使用 `python3.14`。
## 示例
### 抓取 Airbnb 列表
```bash distrobox-enter pybox -- python3.14 scripts/camoufox-fetch.py \ "https://www.airbnb.com/rooms/12345" \ --headless --wait 10 \ --screenshot airbnb.png ```
### 抓取 Yelp 商家信息
```bash distrobox-enter pybox -- python3.14 scripts/camoufox-fetch.py \ "https://www.yelp.com/biz/some-restaurant" \ --headless --wait 8 \ --output yelp.html ```
### 使用 TLS 欺骗进行 API 抓取
```bash distrobox-enter pybox -- python3.14 scripts/curl-api.py \ "https://api.yelp.com/v3/businesses/search?term=coffee&location=SF" \ --headers '{"Authorization": "Bearer xxx"}' ```
## 会话管理
持久化会话允许跨运行重用已认证状态，无需重新登录。
### 快速开始
```bash # 1. Login interactively (headed browser opens) distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \ --profile airbnb --login "https://www.airbnb.com/account-settings"
# Complete login in browser, then press Enter to save session
# 2. Reuse session in headless mode distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \ --profile airbnb --headless "https://www.airbnb.com/trips"
# 3. Check session status distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \ --profile airbnb --status "https://www.airbnb.com" ```
### 标志
| 标志 | 描述 | |------|-------------| | `--profile NAME` | 用于会话存储的命名配置文件（必需） | | `--login` | 交互式登录模式 - 打开有头浏览器 | | `--headless` | 在无头模式下使用已保存的会话 | | `--status` | 检查会话是否有效 | | `--export-cookies FILE` | 将 Cookie 导出为 JSON 以进行备份 | | `--import-cookies FILE` | 从 JSON 文件导入 Cookie |
### 存储
- **位置：** `~/.stealth-browser/profiles/<name>/` - **权限：** 目录 `700`，文件 `600` - **配置文件名称：** 仅限字母、数字、`_`、`-`（1-63 个字符）
### Cookie 处理
- **保存：** 来自所有域的所有 Cookie 均存储在浏览器配置文件中 - **恢复：** 仅使用与目标 URL 域匹配的 Cookie - **SSO：** 如果重定向到 Google/auth 域，重新认证一次，配置文件即会更新
### 登录墙检测
脚本使用多个信号检测会话过期：
1. **HTTP 状态：** 401, 403 2. **URL 模式：** `/login`, `/signin`, `/auth` 3. **标题模式：** "login", "sign in" 等 4. **内容关键词：** "captcha", "verify", "authenticate" 5. **表单检测：** 密码输入字段
如果在 `--headless` 模式下检测到上述情况，您将看到： ``` 🔒 Login wall signals: url-path, password-form ```
使用 `--login` 重新运行以刷新会话。
### 远程登录 (SSH)
由于 `--login` 需要可见的浏览器，您需要进行显示转发：
**X11 转发（推荐）：** ```bash # Connect with X11 forwarding ssh -X user@server
# Run login (opens browser on your local machine) distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \ --profile mysite --login "https://example.com" ```
**VNC 替代方案：** ```bash # On server: start VNC session vncserver :1
# On client: connect to VNC vncviewer server:1
# In VNC session: run login distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \ --profile mysite --login "https://example.com" ```
### 安全说明
⚠️ **Cookie 即凭证。** 请像对待密码一样对待配置文件目录： - 配置文件目录具有 `chmod 700`（仅所有者） - Cookie 导出文件具有 `chmod 600` - 不要通过不安全渠道共享配置文件或导出的 Cookie - 考虑对备份进行加密
### 限制
| 限制 | 原因 | |------------|--------| | 不导出 localStorage/sessionStorage | 改用浏览器配置文件（自动处理） | | IndexedDB 不可移植 | 存储在浏览器配置文件中，而非 Cookie 导出中 | | 不支持并行配置文件访问 | v1 中无文件锁定；每个配置文件使用一个进程 |
## 参考资料
- [references/proxy-setup.md](references/proxy-setup.md) — 代理配置指南 - [references/fingerprint-checks.md](references/fingerprint-checks.md) — 反机器人系统检查的内容