cloakbrowser

CloakBrowser

经过修补的 Chromium 源码，加上一个 Playwright 风格的 Python 封装。指纹在 C++ 层面经过修改（canvas、WebGL、音频、字体、WebRTC、TLS、CDP 输入、navigator.webdriver、插件列表、window.chrome，等等），因此检测服务看到的是真实浏览器，因为它确实是真实浏览器——没有会在下次 Chrome 升级后失效的 JS 补丁。

此 VPS 上的安装状态

已安装：

• cloakbrowser CLI 位于稳定版 OpenClaw 容器镜像中的 /home/node/.local/bin/cloakbrowser。
• 隐身 Chromium 二进制文件位于 /home/node/.cloakbrowser/chromium-<version>/chrome。
• Python 封装可通过 /usr/local/bin/cloakbrowser-python 使用；随附脚本会使用这个稳定的封装，因此即使 Codex 将 HOME 设为隔离的会话目录，也能正常运行。

如果需要在全新检出环境或新机器上进行设置：

uv tool install cloakbrowser
cloakbrowser install        # downloads the ~206 MB Chromium binary

cloakbrowser CLI 只管理二进制文件（install、info、update、clear-cache）。它不是爬虫工具——要进行爬取，请使用此技能中的脚本或编写内联 Python 代码。

决策树——选择合适的工具

任务	使用
获取网页的 HTML 或可见文本	scripts/fetch.py
保存网页或元素的 PNG	scripts/screenshot.py
将网页渲染为 PDF	scripts/pdf.py
对网页运行 JS 表达式并获取 JSON 返回值	scripts/eval-js.py
确认隐身功能正常运行	scripts/check-stealth.py
在多次工具调用／技能间共享长期运行的浏览器	scripts/serve.sh + CDP
多步骤交互流程（登录、点击、输入、有条件地等待）	内联 Python——见下文

请优先使用随附脚本。它们使用 argparse，并支持 --humanize、--proxy、--geoip、--wait 等选项——大多数需求都能满足。

随附脚本

所有脚本都可执行（#! 已指向正确的 Python）。请使用绝对路径调用：

SK=/root/.openclaw/skills/cloakbrowser/scripts

$SK/fetch.py https://example.com                       # full HTML on stdout
$SK/fetch.py https://example.com --text                # visible text only
$SK/fetch.py https://example.com --selector "h1"       # scoped to a selector
$SK/fetch.py https://protected.example --humanize      # behavioural stealth
$SK/fetch.py https://geo.example --proxy socks5://u:p@host:1080 --geoip

$SK/screenshot.py https://example.com /tmp/out.png --full
$SK/screenshot.py https://example.com /tmp/hero.png --selector ".hero"
$SK/screenshot.py https://example.com /tmp/m.png --viewport 390x844

$SK/pdf.py https://example.com /tmp/page.pdf --format A4
$SK/pdf.py https://example.com /tmp/wide.pdf --landscape

$SK/eval-js.py https://news.example "Array.from(document.querySelectorAll('h2')).map(h=>h.innerText)"
$SK/eval-js.py https://example.com  "({ua: navigator.userAgent, w: innerWidth})"

$SK/check-stealth.py        # JSON report + exit 0 if all 4 stealth tells pass

$SK/serve.sh --port 9222    # starts cloakserve in background; logs /tmp/cloakserve.log

用法一致：位置参数为 URL（以及相关情况下的 OUTPUT），之后可添加可选标志 --humanize、--proxy、--geoip、--wait、--timeout。

内联 Python——用于脚本无法涵盖的所有情况

对于多步骤流程（登录、填写表单、逐步点击、条件等待），请编写一次性脚本。使用 uv 工具虚拟环境的解释器：

CB_PY=/usr/local/bin/cloakbrowser-python

"$CB_PY" - <<'PY'
from cloakbrowser import launch
b = launch(headless=True, humanize=True)
p = b.new_page()
p.goto("https://example.com/login", wait_until="domcontentloaded")
p.fill("#email", "[email protected]")
p.fill("#password", "…")
p.click("button[type=submit]")
p.wait_for_url("**/dashboard**")
print(p.title())
b.close()
PY

API 与 Playwright 的同步 API 完全相同——Playwright 文档中的所有内容都适用于此处。仅有以下差异：

• 使用 from cloakbrowser import launch（而不是 from playwright.sync_api）
• 跳过 sync_playwright().start()——launch() 是顶层函数
• 所有隐身标志（humanize、proxy、geoip、auto_update）都传给 launch()，而不是页面

对于持久会话，请使用 launch_persistent_context(user_data_dir)。

何时加载 references/stealth-knobs.md

以下情况请阅读：

• 即使启用了隐身功能，目标站点仍会拦截请求（文档涵盖 humanize／代理／持久配置文件的升级顺序）。
• 用户询问代理、住宅代理与数据中心代理的区别，或地理位置匹配问题。
• 需要在多次工具调用之间共享一个浏览器（CDP 服务模式）。

对于常规的“获取此 URL”／“截取此页面”操作，上面的表格和脚本示例已经足够——无需加载参考文档。

反模式

• 不要在系统范围内运行 pip install cloakbrowser。PEP 668 会在此 VPS 上阻止此操作。 请使用 uv tool install cloakbrowser（已完成）。
• 不要运行 playwright install——CloakBrowser 自带 Chromium，不使用 Playwright 捆绑的二进制文件。
• 不要从系统 Python 导入 cloakbrowser——它只存在于 uv 工具的虚拟环境中。请使用该虚拟环境中的 Python，或使用捆绑的脚本。
• 对未受保护的网站进行常规抓取时，不要启用 humanize=True——它只会增加延迟，没有任何好处。
• 对于一次性抓取，不要让 serve.sh 持续运行。CDP 服务适用于共享的长期会话；抓取单个 URL 时，fetch.py 更快。

故障排除

• Binary not found / 首次运行卡住 → 运行 cloakbrowser install。
• ModuleNotFoundError: cloakbrowser → 使用的 Python 不正确。请使用 /usr/local/bin/cloakbrowser-python 或捆绑的脚本（它们的 shebang 已指向该路径）。
• 启动缓慢 → 二进制文件会在启动时检查更新。向 launch() 传入 auto_update=False（或设置 CLOAKBROWSER_AUTO_UPDATE=0）即可跳过检查。
• 仍然被拦截 → 请参阅 references/stealth-knobs.md，了解逐步升级的顺序（humanize → 住宅代理 + geoip → 持久配置文件）。