名称： stealthy-auto-browse
描述： 通过 Docker 运行的隐身浏览器。能通过 CreepJS、BrowserScan、Pixelscan 和 Cloudflare 检测——零 CDP 暴露，操作系统级输入，持久化指纹。当标准浏览器技能遇到 403 或验证码时使用。
主页： https://github.com/psyb0t/docker-stealthy-auto-browse
user-invocable: true
元数据：
{ "openclaw": { "emoji": "🕵️", "primaryEnv": "STEALTHY_AUTO_BROWSE_URL", "requires": { "bins": ["docker", "curl"] } } }

stealthy-auto-browse

一个在 Docker 中运行的隐身浏览器。它使用 Camoufox（一个自定义的 Firefox 分支）而非 Chromium，因此机器人检测器无法发现任何 Chrome 开发者工具协议（CDP）信号。鼠标和键盘输入通过 PyAutoGUI 在操作系统级别进行——浏览器本身并不知道正在被自动化操作，这意味着行为分析也无法检测到它。

为什么需要它

标准的浏览器自动化工具（Playwright + Chromium、Puppeteer、Selenium）会暴露 CDP 信号，这些信号会被机器人检测服务（Cloudflare、DataDome、PerimeterX、Akamai）瞬间捕获。即使使用隐身插件，CDP 协议仍然存在且可被检测。本技能通过使用 Firefox（完全没有 CDP）并在操作系统级别生成输入事件（而非通过浏览器的自动化 API），彻底消除了这个问题。

何时使用此技能

• 网站启用了机器人检测（Cloudflare 挑战页面、DataDome、PerimeterX、Akamai）
• 网站屏蔽无头浏览器或提供验证码
• 你需要一个不会被封禁的已登录会话
• 其他浏览器技能遇到 403 或空/被屏蔽的响应
• 你正在抓取一个积极对抗自动化的网站

何时不应使用此技能

• 没有机器人防护的简单抓取——使用 curl 或 WebFetch
• 不关心自动化的网站——使用常规的浏览器技能，设置更快
• 你只需要静态 HTML——使用 curl

设置

1. 启动容器：

docker run -d -p 8080:8080 -p 5900:5900 psyb0t/stealthy-auto-browse

端口 8080 是 HTTP API。端口 5900 是 noVNC 网页查看器，你可以实时观看浏览器。

2. 设置环境变量：

export STEALTHY_AUTO_BROWSE_URL=http://localhost:8080

或通过 OpenClaw 配置 (~/.openclaw/openclaw.json)：

{
  "skills": {
    "entries": {
      "stealthy-auto-browse": {
        "env": {
          "STEALTHY_AUTO_BROWSE_URL": "http://localhost:8080"
        }
      }
    }
  }
}

3. 验证： 当浏览器就绪时，curl $STEALTHY_AUTO_BROWSE_URL/health 应返回 ok。

工作原理

容器运行一个虚拟 X 显示服务器（Xvfb，分辨率 1920x1080）、Camoufox 浏览器和一个 HTTP API 服务器。你向 API 发送 JSON 命令并获取 JSON 响应。所有命令都发送到 POST $STEALTHY_AUTO_BROWSE_URL/，格式为 {"action": "<name>", ...params}。

每个响应都具有以下结构：

{
  "success": true,
  "timestamp": 1234567890.123,
  "data": { ... },
  "error": "仅在 success 为 false 时出现"
}

data 字段的内容因操作而异——下文将对每个操作进行说明。

理解两种输入模式

这是最重要的概念。有两种与页面交互的方式：

系统输入（不可检测）

操作：system_click、mouse_move、mouse_click、system_type、send_key、scroll

这些操作使用 PyAutoGUI 生成真实的操作系统级鼠标移动和按键。浏览器将这些视为真实的用户输入——任何网站 JavaScript 都无法将其与真实人类区分开来。为保持隐身性，请使用这些操作。

系统输入使用视口坐标（浏览器内容区域内的 x, y 像素位置）。从 get_interactive_elements 获取这些坐标。

Playwright 输入（可检测）

操作：click、fill、type

这些操作使用 Playwright 的 DOM 自动化，通过 CSS 选择器或 XPath 与元素交互。它们更快、更可靠（无需坐标计算），但它们通过浏览器的自动化层注入事件。复杂的行为分析可能检测到其时间模式。当速度比隐身性更重要，或者你只有选择器而没有坐标时，请使用这些操作。

何时使用哪种模式

• 对隐身性要求高的网站（Cloudflare、登录表单、任何有机器人检测的网站）：始终使用系统输入。
• 简单的抓取，且网站没有积极对抗你：Playwright 输入即可，且更容易。
• 表单填写：使用 system_click 聚焦字段，然后使用 system_type 输入文本。这是不可检测的。使用 fill 更快但可被检测。
• 点击按钮：如果你有来自 get_interactive_elements 的坐标，使用 system_click。如果只有 CSS 选择器，使用 click。

工作流程

这是与页面交互的典型步骤：

1. 导航：使用 goto 加载 URL
2. 读取页面：get_text 返回所有可见文本——通常足以理解页面内容
3. 如果文本不清晰：get_html 提供完整的 DOM 结构
4. 如果仍然困惑：截取屏幕截图 (GET /screenshot/browser?whLargest=512)
5. 查找交互元素：get_interactive_elements 返回所有按钮、链接、输入框及其 x, y 坐标
6. 交互：使用 system_click 点击，system_type 输入，send_key 发送 Enter/Tab/Escape
7. 等待结果：使用 wait_for_element 或 wait_for_text 代替休眠
8. 验证：再次调用 get_text 确认页面按预期变化

操作参考

导航

goto

导航到 URL。这是加载页面的方式。

{"action": "goto", "url": "https://example.com"}
{"action": "goto", "url": "https://example.com", "wait_until": "networkidle"}

参数：
- url（必需）：要导航到的 URL。
- wait_until（可选，默认 "domcontentloaded"）：何时认为页面已加载。选项："domcontentloaded"（DOM 已解析，最快）、"load"（所有资源已加载）、"networkidle"（500 毫秒内无网络活动，最慢但最完整）。

响应数据： {"url": "https://example.com/", "title": "Example Domain"}

注意： 如果页面加载器匹配 URL（参见页面加载器部分），则执行加载器的步骤而非默认导航。发生这种情况时，响应将包含 "loader": "loader name"。

refresh

重新加载当前页面。

{"action": "refresh"}
{"action": "refresh", "wait_until": "networkidle"}

参数：
- wait_until（可选，默认 "domcontentloaded"）：与 goto 相同的选项。

响应数据： {"url": "https://example.com/current-page", "title": "Current Page"}

系统输入（不可检测）

system_click

将鼠标以类人曲线（随机抖动，缓动加速）移动到视口坐标，然后点击。这是隐身点击的主要方式。

{"action": "system_click", "x": 500, "y": 300}
{"action": "system_click", "x": 500, "y": 300, "duration": 0.5}

参数：
- x, y（必需）：视口坐标——从 get_interactive_elements 获取。
- duration（可选）：鼠标移动的持续时间（秒）。如果省略，则使用 0.2-0.6 秒之间的随机持续时间以增加真实感。

响应数据： {"system_clicked": {"x": 500, "y": 300}}

与 mouse_click 的区别： system_click 总是先移动鼠标（平滑的类人路径），然后点击。mouse_click 可以在位置瞬间点击而无需平滑移动，或者点击鼠标当前位置。

mouse_move

将鼠标以类人移动（抖动，缓动曲线）移动到视口坐标，但不点击。用于悬停在元素上（触发悬停菜单、工具提示）或在操作之间模拟自然的鼠标行为。

{"action": "mouse_move", "x": 500, "y": 300}
{"action": "mouse_move", "x": 500, "y": 300, "duration": 0.4}

参数：
- x, y（必需）：视口坐标。
- duration（可选）：移动时间（秒）。如果省略，则为 0.2-0.6 秒的随机值。

响应数据： {"moved_to": {"x": 500, "y": 300}}

mouse_click

在指定位置或鼠标当前位置点击。与 system_click 不同，此操作不先进行平滑鼠标移动——它是通过 PyAutoGUI 的直接点击。

{"action": "mouse_click"}
{"action": "mouse_click", "x": 500, "y": 300}

参数：
- x, y（可选）：如果提供，则直接在该视口位置点击。如果省略，则点击鼠标当前位置。

响应数据： {"clicked_at": {"x": 500, "y": 300}} 或 {"clicked_at": "current"}

何时使用： 在 mouse_move 之后，当你想将移动和点击分成两步时。或者当鼠标已经定位好，你只需要点击时。

system_type

通过真实的操作系统按键逐字符输入文本。每次按键都有随机延迟（在间隔时间附近抖动），以模拟人类打字速度。完全不可检测。

{"action": "system_type", "text": "hello world"}
{"action": "system_type", "text": "hello world", "interval": 0.12}

参数：
- text（必需）：要输入的文本。必须先点击/聚焦输入字段。
- interval（可选，默认 0.08）：按键之间的基本延迟（秒）。实际延迟在此值附近随机化 ±30 毫秒。

响应数据： {"typed_len": 11}

重要： 在调用 system_type 之前，必须先点击输入字段（使用 system_click 或 click）。此操作将文本输入到当前聚焦的任何内容中。

send_key

通过操作系统级输入发送单个键盘按键或组合键。用于按 Enter 提交表单、Tab 在字段间移动、Escape 关闭对话框，或任何组合键如 Ctrl+A、Ctrl+C 等。

{"action": "send_key", "key": "enter"}
{"action": "send_key", "key": "tab"}
{"action": "send_key", "key": "escape"}
{"action": "send_key", "key": "ctrl+a"}
{"action": "send_key", "key": "ctrl+shift+t"}

参数：
- key（必需）：按键名称或组合键，用 + 分隔。按键名称遵循 PyAutoGUI 命名：enter、tab、escape、backspace、delete、up、down、left、right、home、end、pageup、pagedown、f1-f12、ctrl、alt、shift、space 等。

响应数据： {"send_key": "enter"}

scroll

使用鼠标滚轮滚动页面。生成真实的操作系统级滚动事件。

{"action": "scroll", "amount": -3}
{"action": "scroll", "amount": 5, "x": 500, "y": 300}

参数：
- amount（可选，默认 -3）：滚动量。负值 = 向下滚动，正值 = 向上滚动。每个单位大致相当于鼠标滚轮的一次“点击”。
- x, y（可选）：如果提供，先将鼠标移动到这些视口坐标，然后滚动。用于在特定可滚动元素内滚动，而非整个页面。

响应数据： {"scrolled": -3}

Playwright 输入（可检测）

这些操作更快、更方便，但使用 Playwright 的 DOM 事件注入，可能被复杂的行为分析检测到。

click

通过 CSS 选择器或 XPath 点击元素。Playwright 在 DOM 中查找元素，如果需要则将其滚动到视图中，并分发点击事件。

{"action": "click", "selector": "#submit-btn"}
{"action": "click", "selector": "button.primary"}
{"action": "click", "selector": "xpath=//button[@id='submit-btn']"}

参数：
- selector（必需）：CSS 选择器或 XPath（前缀为 xpath=）。

响应数据： {"clicked": "#submit-btn"}

何时使用而非 system_click： 当你有选择器但不想费力获取坐标时。当元素可能移动且坐标不可靠时。当隐身性不关键时。

fill

通过选择器填充输入字段。先清除任何现有内容，然后设置值。这是填充表单最快的方式，但可被检测，因为它不生成单独的按键事件。

{"action": "fill", "selector": "input[name='email']", "value": "user@example.com"}

参数：
- selector（必需）：输入元素的 CSS 选择器或 XPath。
- value（必需）：要填充的文本。

响应数据： {"filled": "input[name='email']"}

type

通过 Playwright（非操作系统）逐字符将文本输入到元素中。每次按键都有可配置的延迟。这是介于 fill（即时但明显自动化）和 system_type（操作系统级，不可检测）之间的折中方案。打字模式比 fill 更真实，但仍通过 Playwright 的事件系统。

{"action": "type", "selector": "#search", "text": "query", "delay": 0.05}

参数：
- selector（必需）：元素的 CSS 选择器或 XPath。
- text（必需）：要输入的文本。
- delay（可选，默认 0.05）：按键之间的延迟（秒）。

响应数据： {"typed": "#search"}

屏幕截图

屏幕截图是 GET 请求（非 POST 操作）。

GET /screenshot/browser

将浏览器视口捕获为 PNG 图像。这是用户看到的页面样子。

curl -s "$STEALTHY_AUTO_BROWSE_URL/screenshot/browser?whLargest=512" -o screenshot.png

始终调整屏幕截图大小以避免图像过大。调整大小查询参数（全部可选）：

GET /screenshot/desktop

使用 scrot 捕获整个虚拟桌面（包括窗口边框、任务栏等）。调整大小参数同上。当需要查看浏览器视口之外的内容时很有用。

curl -s "$STEALTHY_AUTO_BROWSE_URL/screenshot/desktop?whLargest=512" -o desktop.png

页面检查

get_interactive_elements

扫描页面并返回每个交互元素（按钮、链接、输入框、选择框、文本区域等）及其视口坐标。这是你查找要点击的内容和位置的方式。

{"action": "get_interactive_elements"}
{"action": "get_interactive_elements", "visible_only": true}

参数：
- visible_only（可选，默认 true）：仅返回当前屏幕上可见的元素。

响应数据：

{
  "count": 5,
  "elements": [
    {
      "i": 0,
      "tag": "button",
      "id": "submit-btn",
      "text": "Submit",
      "selector": "#submit-btn",
      "x": 400,
      "y": 250,
      "w": 120,
      "h": 40,
      "visible": true
    },
    {
      "i": 1,
      "tag": "input",
      "id": null,
      "text": "",
      "selector": "input[name='email']",
      "x": 300,
      "y": 180,
      "w": 250,
      "h": 35,
      "visible": true
    }
  ]
}

x, y 是元素的中心——直接传递给 system_click。selector 可用于 Playwright 操作如 click 或 fill。w, h 提供元素的尺寸。

这是你理解页面上可以交互内容的主要工具。 在点击任何内容之前调用此操作。

get_text

返回页面正文的所有可见文本内容。文本被截断为 10,000 个字符。

{"action": "get_text"}

响应数据： `{"text": "Page title