---
name: browser-chromium
version: 1.1.0
description: 基于 patchright + CloakBrowser 双引擎的反检测 Chromium 浏览器自动化
---

# browser-chromium (v1.1.0)

基于 patchright + CloakBrowser 双引擎的反检测浏览器，适合需要绕过检测的网站。

**新增 v1.1.0**: CloakBrowser C++级源码补丁引擎，可通过 `--engine cloak` 切换

## 双引擎架构

| 引擎 | 命令 | 原理 | 适用场景 |
|------|------|------|---------|
| **patchright** (默认) | `--engine patchright` | JS注入反检测，兼容Playwright API | 普通反爬站(Twitter/X等) |
| **CloakBrowser** | `--engine cloak` | C++源码级Chromium补丁，最强反检测 | Cloudflare/Turnstile/高防护站 |
| **auto** | `--engine auto` | 自动选择(检测到防护站自动切CloakBrowser) | 通用 |

## 与 browser-desktop 的区别

| 维度 | browser-desktop | browser-chromium |
|------|----------------|-----------------|
| 浏览器 | Firefox (Playwright) | Chromium (patchright + CloakBrowser) |
| 反检测 | 无 | 多层指纹伪装 |
| 适用场景 | 普通网站 | 反爬/反机器人检测/高防护站 |
| 速度 | 正常 | 正常 |

## 安装

```bash
pip install patchright --break-system-packages
patchright install chromium
pip install cloakbrowser --break-system-packages
pip install crawlee --break-system-packages  # 指纹套件
```

## 使用

```bash
# 标准浏览 (patchright 引擎)
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py "https://x.com"

# 截图
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py "https://example.com" --screenshot

# 高防护站 (CloakBrowser 引擎)
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py "https://cloudflare.com" --engine cloak

# 自动选择引擎
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py "https://x.com" --engine auto

# 带代理
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py "https://example.com" --proxy "http://192.168.0.66:7890"

# 检测指纹强度
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py --check-fingerprint --engine patchright
```

## API（Python 脚本中引用）

```python
from patchright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto("https://x.com")
    page.screenshot()
    browser.close()
```

## CloakBrowser 用法

```python
from cloakbrowser import CloakBrowser

cb = CloakBrowser(headless=True, proxy="http://192.168.0.66:7890")
page = cb.page
page.goto("https://cloudflare.com")
print(page.content())
```

## 引擎选择建议

```
简单站/登录站 → patchright (默认，Cookie持久化)
Cloudflare/Turnstile → cloak
未知站 → auto
```

## 持久化会话

Cookie 自动保存到 `~/.openclaw/browser-chromium-cookies.json`，下次打开自动复用登录状态。（CloakBrowser模式除外）

## 依赖生态

| 库 | 用途 | 状态 |
|----|------|------|
| patchright | 主引擎 | ✅ |
| playwright | patchright 依赖 | ✅ |
| cloakbrowser | C++级反检测 | ✅ |
| crawlee | fingerprint_suite | ✅ |
| parsel | crawlee 依赖 | ✅ |
| jaro-winkler | crawlee 依赖 | ✅ |

## 注意事项

- patchright 只支持 Chromium，Firefox/WebKit 不支持
- 如遇检测，优先尝试 `--engine cloak` 或加代理
- CloakBrowser 会话不持久化（每次新建）