From 312d6121cce1799f8873b1d73fe286121fda67f8 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 10:20:01 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/browser.md | 63 ++-- .../tools/browser-linux-troubleshooting.md | 76 ++-- docs/zh-CN/tools/browser.md | 334 +++++++++--------- 3 files changed, 233 insertions(+), 240 deletions(-) diff --git a/docs/zh-CN/cli/browser.md b/docs/zh-CN/cli/browser.md index 937179d84..16933a1c7 100644 --- a/docs/zh-CN/cli/browser.md +++ b/docs/zh-CN/cli/browser.md @@ -1,15 +1,15 @@ --- read_when: - 你使用 `openclaw browser`，并且想要查看常见任务的示例 - - 你想通过节点主机来控制另一台机器上运行的浏览器 + - 你想通过节点主机控制另一台机器上运行的浏览器 - 你想通过 Chrome MCP 连接到你本地已登录的 Chrome summary: '`openclaw browser` 的 CLI 参考（生命周期、配置文件、标签页、操作、状态和调试）' title: 浏览器 x-i18n: - generated_at: "2026-04-25T09:15:38Z" + generated_at: "2026-04-25T10:18:24Z" model: gpt-5.4 provider: openai - source_hash: 8516a139ad04c20df6fadb261b4fd7175a145cee7edd3cec51d8acdbfe40de26 + source_hash: d97ba217f59832f57105d988c731a84e0259ffabad844b167f12a82ee315fff9 source_path: cli/browser.md workflow: 15 --- @@ -28,8 +28,8 @@ x-i18n: - `--token `：Gateway 网关令牌（如果需要）。 - `--timeout `：请求超时时间（毫秒）。 - `--expect-final`：等待最终的 Gateway 网关响应。 -- `--browser-profile `：选择浏览器配置文件（默认来自配置）。 -- `--json`：机器可读输出（在支持的情况下）。 +- `--browser-profile `：选择一个浏览器配置文件（默认值来自配置）。 +- `--json`：机器可读输出（在支持的地方）。 ## 快速开始（本地） @@ -46,7 +46,7 @@ openclaw browser --browser-profile openclaw snapshot 如果 `start` 因 `not reachable after start` 失败，请先排查 CDP 就绪状态。如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则浏览器控制平面是健康的，失败通常是导航 SSRF 策略导致的。 -最小排查步骤： +最小操作序列： ```bash openclaw browser --browser-profile openclaw doctor @@ -67,16 +67,17 @@ openclaw browser stop openclaw browser --browser-profile openclaw reset-profile ``` -说明： +注意： - 对于 `attachOnly` 和远程 CDP 配置文件，即使 OpenClaw 本身没有启动浏览器进程，`openclaw browser stop` 也会关闭当前控制会话并清除临时模拟覆盖。 -- 对于本地受管配置文件，`openclaw browser stop` 会停止已启动的浏览器进程。 +- 对于本地托管配置文件，`openclaw browser stop` 会停止已启动的浏览器进程。 +- 在没有 `DISPLAY` 或 `WAYLAND_DISPLAY` 的 Linux 主机上，本地托管配置文件会自动以无头模式运行，除非 `OPENCLAW_BROWSER_HEADLESS=0`、`browser.headless=false` 或 `browser.profiles..headless=false` 明确要求显示浏览器界面。 -## 如果命令不存在 +## 如果命令缺失 如果 `openclaw browser` 是未知命令，请检查 `~/.openclaw/openclaw.json` 中的 `plugins.allow`。 -当存在 `plugins.allow` 时，内置的浏览器插件必须被显式列出： +当存在 `plugins.allow` 时，内置的 browser 插件必须被显式列出： ```json5 { @@ -86,7 +87,7 @@ openclaw browser --browser-profile openclaw reset-profile } ``` -当插件允许列表排除了 `browser` 时，`browser.enabled=true` 不会恢复这个 CLI 子命令。 +当插件允许列表排除了 `browser` 时，`browser.enabled=true` 不会恢复该 CLI 子命令。 相关内容：[浏览器工具](/zh-CN/tools/browser#missing-browser-command-or-tool) @@ -94,7 +95,7 @@ openclaw browser --browser-profile openclaw reset-profile 配置文件是命名的浏览器路由配置。实际使用中： -- `openclaw`：启动或连接到专用的 OpenClaw 托管 Chrome 实例（隔离的用户数据目录）。 +- `openclaw`：启动或连接到一个专用的、由 OpenClaw 托管的 Chrome 实例（隔离的用户数据目录）。 - `user`：通过 Chrome DevTools MCP 控制你现有的已登录 Chrome 会话。 - 自定义 CDP 配置文件：指向本地或远程 CDP 端点。 @@ -106,7 +107,7 @@ openclaw browser create-profile --name remote --cdp-url https://browser-host.exa openclaw browser delete-profile --name work ``` -使用指定配置文件： +使用特定配置文件： ```bash openclaw browser --browser-profile work tabs @@ -125,7 +126,7 @@ openclaw browser focus docs openclaw browser close t1 ``` -`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId`（例如 `t1`）、可选标签以及原始 `targetId`。智能体应将 `suggestedTargetId` 传回给 `focus`、`close`、快照和操作。你可以使用 `open --label`、`tab new --label` 或 `tab label` 分配标签；标签、标签页 ID、原始目标 ID，以及唯一的目标 ID 前缀都可以被接受。 +`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId`（例如 `t1`）、可选标签以及原始 `targetId`。智能体应将 `suggestedTargetId` 传回 `focus`、`close`、快照和操作中。你可以使用 `open --label`、`tab new --label` 或 `tab label` 分配标签；标签、标签页 ID、原始 target ID 以及唯一的 target-id 前缀都可以接受。 ## 快照 / 截图 / 操作 @@ -145,12 +146,12 @@ openclaw browser screenshot --ref e12 openclaw browser screenshot --labels ``` -说明： +注意： -- `--full-page` 仅用于页面截图；不能与 `--ref` 或 `--element` 一起使用。 -- `existing-session` / `user` 配置文件支持页面截图，以及基于快照输出中 `--ref` 的截图，但不支持基于 CSS `--element` 的截图。 -- `--labels` 会在截图上叠加当前快照引用标签。 -- `snapshot --urls` 会将发现的链接目标追加到 AI 快照中，以便智能体可以直接选择导航目标，而不是仅凭链接文本猜测。 +- `--full-page` 仅用于整页截图；不能与 `--ref` 或 `--element` 组合使用。 +- `existing-session` / `user` 配置文件支持页面截图和基于快照输出中 `--ref` 的截图，但不支持基于 CSS `--element` 的截图。 +- `--labels` 会在截图上叠加当前快照的 ref 标记。 +- `snapshot --urls` 会把发现的链接目标追加到 AI 快照中，这样智能体就可以选择直接导航目标，而不是仅根据链接文本猜测。 导航 / 点击 / 输入（基于 ref 的 UI 自动化）： @@ -169,7 +170,7 @@ openclaw browser wait --text "Done" openclaw browser evaluate --fn '(el) => el.textContent' --ref ``` -文件与对话框辅助： +文件 + 对话框辅助： ```bash openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref @@ -178,7 +179,7 @@ openclaw browser download report.pdf openclaw browser dialog --accept ``` -受管的 Chrome 配置文件会将普通点击触发的下载保存到 OpenClaw 下载目录（默认为 `/tmp/openclaw/downloads`，或已配置的临时根目录）。当智能体需要等待特定文件并返回其路径时，请使用 `waitfordownload` 或 `download`；这些显式等待器会接管下一次下载。 +托管的 Chrome 配置文件会将普通的点击触发下载保存到 OpenClaw 下载目录（默认是 `/tmp/openclaw/downloads`，或配置的临时根目录）。当智能体需要等待某个特定文件并返回其路径时，请使用 `waitfordownload` 或 `download`；这些显式等待器会接管下一次下载。 ## 状态和存储 @@ -223,7 +224,7 @@ openclaw browser trace stop --out trace.zip ## 通过 MCP 使用现有 Chrome -使用内置的 `user` 配置文件，或者创建你自己的 `existing-session` 配置文件： +使用内置的 `user` 配置文件，或创建你自己的 `existing-session` 配置文件： ```bash openclaw browser --browser-profile user tabs @@ -232,30 +233,30 @@ openclaw browser create-profile --name brave-live --driver existing-session --us openclaw browser --browser-profile chrome-live tabs ``` -这条路径仅适用于宿主机。对于 Docker、无头服务器、Browserless 或其他远程设置，请改用 CDP 配置文件。 +这条路径仅适用于主机本机。对于 Docker、无头服务器、Browserless 或其他远程设置，请改用 CDP 配置文件。 当前 `existing-session` 的限制： -- 基于快照的操作使用 refs，而不是 CSS 选择器 -- 当调用方省略 `timeoutMs` 时，`browser.actionTimeoutMs` 会将受支持的 `act` 请求默认设置为 60000 ms；但每次调用的 `timeoutMs` 仍然优先 +- 基于快照驱动的操作使用 ref，而不是 CSS 选择器 +- 当调用方省略 `timeoutMs` 时，`browser.actionTimeoutMs` 会将受支持的默认 `act` 请求设置为 60000 ms；但每次调用的 `timeoutMs` 仍然优先生效。 - `click` 仅支持左键点击 - `type` 不支持 `slowly=true` - `press` 不支持 `delayMs` - `hover`、`scrollintoview`、`drag`、`select`、`fill` 和 `evaluate` 会拒绝每次调用的超时覆盖 - `select` 仅支持一个值 - 不支持 `wait --load networkidle` -- 文件上传需要 `--ref` / `--input-ref`，不支持 CSS `--element`，并且当前一次仅支持一个文件 +- 文件上传需要 `--ref` / `--input-ref`，不支持 CSS `--element`，并且当前一次只支持一个文件 - 对话框钩子不支持 `--timeout` -- 截图支持页面捕获和 `--ref`，但不支持 CSS `--element` -- `responsebody`、下载拦截、PDF 导出和批量操作仍然需要受管浏览器或原始 CDP 配置文件 +- 截图支持页面截图和 `--ref`，但不支持 CSS `--element` +- `responsebody`、下载拦截、PDF 导出和批量操作仍然需要托管浏览器或原始 CDP 配置文件 ## 远程浏览器控制（节点主机代理） -如果 Gateway 网关运行在与浏览器不同的机器上，请在安装有 Chrome/Brave/Edge/Chromium 的机器上运行一个**节点主机**。Gateway 网关会将浏览器操作代理到该节点（不需要单独的浏览器控制服务器）。 +如果 Gateway 网关运行在与浏览器不同的机器上，请在安装了 Chrome/Brave/Edge/Chromium 的机器上运行一个**节点主机**。Gateway 网关会将浏览器操作代理到该节点（不需要单独的浏览器控制服务器）。 -使用 `gateway.nodes.browser.mode` 来控制自动路由，并使用 `gateway.nodes.browser.node` 在连接了多个节点时固定到特定节点。 +使用 `gateway.nodes.browser.mode` 控制自动路由，使用 `gateway.nodes.browser.node` 在连接了多个节点时固定到某个特定节点。 -安全与远程设置：[浏览器工具](/zh-CN/tools/browser)、[远程访问](/zh-CN/gateway/remote)、[Tailscale](/zh-CN/gateway/tailscale)、[安全](/zh-CN/gateway/security) +安全性 + 远程设置：[浏览器工具](/zh-CN/tools/browser)、[远程访问](/zh-CN/gateway/remote)、[Tailscale](/zh-CN/gateway/tailscale)、[安全性](/zh-CN/gateway/security) ## 相关内容 diff --git a/docs/zh-CN/tools/browser-linux-troubleshooting.md b/docs/zh-CN/tools/browser-linux-troubleshooting.md index 739dbd68e..8a9426671 100644 --- a/docs/zh-CN/tools/browser-linux-troubleshooting.md +++ b/docs/zh-CN/tools/browser-linux-troubleshooting.md @@ -1,50 +1,50 @@ --- read_when: Browser control fails on Linux, especially with snap Chromium -summary: 修复 Linux 上 OpenClaw 浏览器控制中 Chrome / Brave / Edge / Chromium 的 CDP 启动问题 +summary: 修复 OpenClaw 在 Linux 上进行浏览器控制时 Chrome/Brave/Edge/Chromium 的 CDP 启动问题 title: 浏览器故障排除 x-i18n: - generated_at: "2026-04-25T05:56:47Z" + generated_at: "2026-04-25T10:18:21Z" model: gpt-5.4 provider: openai - source_hash: 4b972e9f611962b60c76088487a8db628bc1cbf8447f73f75d33606f177c701a + source_hash: 7756634001798bf4d14546b1bb679e9f4530adf33adc1aa323e9c594b0a7abbd source_path: tools/browser-linux-troubleshooting.md workflow: 15 --- ## 问题：“在端口 18800 上启动 Chrome CDP 失败” -OpenClaw 的浏览器控制服务器在启动 Chrome / Brave / Edge / Chromium 时失败，并报出如下错误： +OpenClaw 的浏览器控制服务器在启动 Chrome/Brave/Edge/Chromium 时失败，并报错： -``` +```` {"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"openclaw\"."} -``` +```` ### 根本原因 -在 Ubuntu（以及许多 Linux 发行版）上，默认的 Chromium 安装是 **snap 包**。Snap 的 AppArmor 限制会干扰 OpenClaw 启动和监控浏览器进程的方式。 +在 Ubuntu（以及许多 Linux 发行版）上，默认的 Chromium 安装是一个 **snap 软件包**。Snap 的 AppArmor 限制会干扰 OpenClaw 启动和监控浏览器进程的方式。 -`apt install chromium` 命令安装的是一个会重定向到 snap 的存根包： +`apt install chromium` 命令安装的是一个会重定向到 snap 的占位软件包： -``` +```` Note, selecting 'chromium-browser' instead of 'chromium' chromium-browser is already the newest version (2:1snap1-0ubuntu2). -``` +```` -这**不是**真正的浏览器——它只是一个包装器。 +这**不是真正的浏览器**——它只是一个包装器。 -其他常见的 Linux 启动失败： +其他常见的 Linux 启动失败情况： -- `The profile appears to be in use by another Chromium process` 表示 Chrome 在托管配置文件目录中发现了陈旧的 `Singleton*` 锁文件。当锁指向已退出的进程或不同主机上的进程时，OpenClaw 会移除这些锁并重试一次。 -- `Missing X server or $DISPLAY` 表示 OpenClaw 正在尝试在没有桌面会话的主机上启动一个可见浏览器。请使用 `browser.headless: true`、启动 `Xvfb`，或在真实桌面会话中运行 OpenClaw。 +- `The profile appears to be in use by another Chromium process` 表示 Chrome 在受管配置文件目录中发现了过期的 `Singleton*` 锁文件。当锁指向一个已退出的进程或另一台主机上的进程时，OpenClaw 会移除这些锁并重试一次。 +- `Missing X server or $DISPLAY` 表示你在没有桌面会话的主机上明确请求了可见浏览器。默认情况下，当 `DISPLAY` 和 `WAYLAND_DISPLAY` 都未设置时，本地受管配置文件现在会在 Linux 上回退到无头模式。如果你设置了 `OPENCLAW_BROWSER_HEADLESS=0`、`browser.headless: false` 或 `browser.profiles..headless: false`，请移除该有头模式覆盖，设置 `OPENCLAW_BROWSER_HEADLESS=1`，启动 `Xvfb`，或在真实桌面会话中运行 OpenClaw。 ### 解决方案 1：安装 Google Chrome（推荐） -安装官方 Google Chrome `.deb` 包，它不会受到 snap 的沙箱限制： +安装官方的 Google Chrome `.deb` 软件包，它不会受到 snap 沙箱限制： ```bash wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb sudo dpkg -i google-chrome-stable_current_amd64.deb -sudo apt --fix-broken install -y # if there are dependency errors +sudo apt --fix-broken install -y # 如果有依赖错误 ``` 然后更新你的 OpenClaw 配置（`~/.openclaw/openclaw.json`）： @@ -60,9 +60,9 @@ sudo apt --fix-broken install -y # if there are dependency errors } ``` -### 解决方案 2：以仅附加模式使用 Snap Chromium +### 解决方案 2：使用 snap Chromium 的仅附加模式 -如果你必须使用 snap Chromium，请将 OpenClaw 配置为附加到一个手动启动的浏览器： +如果你必须使用 snap Chromium，请将 OpenClaw 配置为附加到手动启动的浏览器： 1. 更新配置： @@ -86,7 +86,7 @@ chromium-browser --headless --no-sandbox --disable-gpu \ about:blank & ``` -3. 可选：创建一个 systemd 用户服务以自动启动 Chrome： +3. 可选：创建一个 systemd 用户服务来自动启动 Chrome： ```ini # ~/.config/systemd/user/openclaw-browser.service @@ -103,7 +103,7 @@ RestartSec=5 WantedBy=default.target ``` -启用方式：`systemctl --user enable --now openclaw-browser.service` +启用命令：`systemctl --user enable --now openclaw-browser.service` ### 验证浏览器是否正常工作 @@ -123,39 +123,35 @@ curl -s http://127.0.0.1:18791/tabs ### 配置参考 | 选项 | 描述 | 默认值 | -| ------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------- | +| --------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- | | `browser.enabled` | 启用浏览器控制 | `true` | -| `browser.executablePath` | 基于 Chromium 的浏览器二进制路径（Chrome / Brave / Edge / Chromium） | 自动检测（优先选择默认浏览器，如果它基于 Chromium） | -| `browser.headless` | 无 GUI 运行 | `false` | -| `browser.noSandbox` | 添加 `--no-sandbox` 标志（某些 Linux 设置需要） | `false` | +| `browser.executablePath` | Chromium 内核浏览器二进制文件的路径（Chrome/Brave/Edge/Chromium） | 自动检测（如果默认浏览器是 Chromium 内核，则优先使用默认浏览器） | +| `browser.headless` | 在无 GUI 模式下运行 | `false` | +| `OPENCLAW_BROWSER_HEADLESS` | 针对本地受管浏览器无头模式的按进程覆盖 | 未设置 | +| `browser.noSandbox` | 添加 `--no-sandbox` 标志（某些 Linux 环境需要） | `false` | | `browser.attachOnly` | 不启动浏览器，只附加到现有浏览器 | `false` | | `browser.cdpPort` | Chrome DevTools Protocol 端口 | `18800` | -### 问题：“未找到 profile=\"user\" 的 Chrome 标签页” +### 问题：“未找到 profile="user" 的 Chrome 标签页” -你正在使用 `existing-session` / Chrome MCP profile。OpenClaw 可以看到本地 Chrome， -但没有可供附加的打开标签页。 +你正在使用 `existing-session` / Chrome MCP 配置文件。OpenClaw 可以看到本地 Chrome，但没有可用于附加的已打开标签页。 修复选项： -1. **使用托管浏览器：** `openclaw browser start --browser-profile openclaw` +1. **使用受管浏览器：** `openclaw browser start --browser-profile openclaw` （或设置 `browser.defaultProfile: "openclaw"`）。 -2. **使用 Chrome MCP：** 确保本地 Chrome 正在运行且至少打开了一个标签页，然后使用 `--browser-profile user` 重试。 +2. **使用 Chrome MCP：** 确保本地 Chrome 正在运行且至少有一个打开的标签页，然后使用 `--browser-profile user` 重试。 说明： -- `user` 仅限主机本地。对于 Linux 服务器、容器或远程主机，请优先使用 CDP profiles。 -- `user` / 其他 `existing-session` profiles 保留当前的 Chrome MCP 限制： - 基于 ref 的操作、单文件上传钩子、不支持对话框超时覆盖、不支持 - `wait --load networkidle`，也不支持 `responsebody`、PDF 导出、下载拦截 - 或批量操作。 -- 本地 `openclaw` profiles 会自动分配 `cdpPort` / `cdpUrl`；仅在远程 CDP 场景中才设置这些值。 -- 远程 CDP profiles 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 对 `/json/version` 发现请使用 HTTP(S)，或者当你的浏览器 - 服务提供直接的 DevTools socket URL 时使用 WS(S)。 +- `user` 仅适用于主机本地。对于 Linux 服务器、容器或远程主机，优先使用 CDP 配置文件。 +- `user` / 其他 `existing-session` 配置文件会保留当前的 Chrome MCP 限制：基于 ref 的操作、单文件上传钩子、不支持对话框超时覆盖、不支持 `wait --load networkidle`，以及不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 +- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；只有远程 CDP 才需要手动设置这些值。 +- 远程 CDP 配置文件接受 `http://`、`https://`、`ws://` 和 `wss://`。 + 当使用 `/json/version` 发现时请使用 HTTP(S)，或者当你的浏览器服务直接提供 DevTools socket URL 时使用 WS(S)。 ## 相关内容 - [浏览器](/zh-CN/tools/browser) -- [Browser 登录](/zh-CN/tools/browser-login) -- [Browser WSL2 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting) +- [浏览器登录](/zh-CN/tools/browser-login) +- [浏览器 WSL2 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting) diff --git a/docs/zh-CN/tools/browser.md b/docs/zh-CN/tools/browser.md index 4cf6174c2..459b3b606 100644 --- a/docs/zh-CN/tools/browser.md +++ b/docs/zh-CN/tools/browser.md @@ -1,36 +1,37 @@ --- read_when: - 添加由智能体控制的浏览器自动化 - - 调试为什么 openclaw 会干扰你自己的 Chrome - - 在 macOS 应用中实现浏览器设置 + 生命周期 -summary: 集成的浏览器控制服务 + 操作命令 -title: 浏览器（OpenClaw 管理） + - 调试 openclaw 为什么会干扰你自己的 Chrome + - 在 macOS 应用中实现浏览器设置 + 生命周期管理 +summary: 集成式浏览器控制服务 + 操作命令 +title: 浏览器（由 OpenClaw 管理） x-i18n: - generated_at: "2026-04-25T08:15:42Z" + generated_at: "2026-04-25T10:18:23Z" model: gpt-5.4 provider: openai - source_hash: b8277b012479cad5f02dade2f0dd2ea77dffe1b1535934a0401f67e756065c3c + source_hash: 64c8b99911a4cf7d109c2e1eecb6beac9ce5c08115faccbeaf962819c98f2915 source_path: tools/browser.md workflow: 15 --- OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。 -它与你的个人浏览器隔离，并通过 Gateway 网关内部的一个小型本地控制服务进行管理（仅限 loopback）。 +它与你的个人浏览器隔离，并通过 Gateway 网关内部的一个小型本地控制服务进行管理 +（仅限 loopback）。 初学者视角： - 可以把它看作一个**独立的、仅供智能体使用的浏览器**。 -- `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。 -- 智能体可以在一条安全通道中**打开标签页、读取页面、点击和输入**。 -- 内置的 `user` 配置文件会通过 Chrome MCP 连接到你真实的、已登录的 Chrome 会话。 +- `openclaw` 配置文件**不会**接触你的个人浏览器配置文件。 +- 智能体可以在安全隔离的通道中**打开标签页、读取页面、点击和输入**。 +- 内置的 `user` 配置文件会通过 Chrome MCP 附加到你真实的已登录 Chrome 会话。 ## 你将获得什么 - 一个名为 **openclaw** 的独立浏览器配置文件（默认使用橙色强调色）。 - 可预测的标签页控制（列出/打开/聚焦/关闭）。 -- 智能体操作（点击/输入/拖拽/选择）、快照、截图、PDF。 -- 一个内置的 `browser-automation` Skills，用于在启用浏览器插件时教会智能体使用快照、稳定标签页、陈旧引用和手动阻塞恢复循环。 -- 可选的多配置文件支持（`openclaw`、`work`、`remote` 等）。 +- 智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。 +- 一个内置的 `browser-automation` Skills，用于在启用浏览器插件时教会智能体使用 snapshot、stable-tab、stale-ref 和 manual-blocker 恢复循环。 +- 可选的多配置文件支持（`openclaw`、`work`、`remote`，等等）。 这个浏览器**不是**你的日常主力浏览器。 它是一个安全、隔离的界面，用于智能体自动化和验证。 @@ -45,13 +46,13 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启 Gateway 网关。 +如果你看到“Browser 已禁用”，请在配置中启用它（见下文），然后重启 Gateway 网关。 -如果完全没有 `openclaw browser`，或者智能体提示浏览器工具不可用，请跳转到 [缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 +如果根本没有 `openclaw browser`，或者智能体提示浏览器工具不可用，请跳转到[缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 ## 插件控制 -默认的 `browser` 工具是一个内置插件。若要用另一个注册同名 `browser` 工具的插件替换它，请将其禁用： +默认的 `browser` 工具是一个内置插件。如果你想用另一个注册相同 `browser` 工具名称的插件来替换它，请禁用该插件： ```json5 { @@ -65,22 +66,22 @@ openclaw browser --browser-profile openclaw snapshot } ``` -默认行为需要同时满足 `plugins.entries.browser.enabled` **和** `browser.enabled=true`。仅禁用插件会一次性移除 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具和控制服务；你的 `browser.*` 配置会保留，以供替代插件使用。 +默认行为要求同时设置 `plugins.entries.browser.enabled` **和** `browser.enabled=true`。如果只禁用插件，会把 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具以及控制服务作为一个整体一并移除；你的 `browser.*` 配置会保留，以供替代插件使用。 -浏览器配置变更需要重启 Gateway 网关，以便插件重新注册其服务。 +浏览器配置变更需要重启 Gateway 网关，这样插件才能重新注册其服务。 ## 智能体指引 -浏览器插件提供两个层级的智能体指引： +浏览器插件提供两层智能体指引： -- `browser` 工具说明包含简洁的常驻约定：选择正确的配置文件、在同一标签页内保持引用一致、使用 `tabId`/标签来定位标签页，以及在执行多步骤任务时加载浏览器 Skills。 -- 内置的 `browser-automation` Skills 包含更完整的操作循环：先检查状态/标签页，给任务标签页打标签，在操作前创建快照，在 UI 变更后重新创建快照，遇到陈旧引用时重试一次恢复，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为需要手动处理，而不是猜测。 +- `browser` 工具描述携带精简的始终启用契约：选择正确的配置文件，在同一标签页内保持 refs，使用 `tabId`/标签来定位标签页，并在处理多步骤任务时加载浏览器 Skills。 +- 内置的 `browser-automation` Skills 携带更长的操作循环：先检查状态/标签页，为任务标签页打标签，操作前先做 snapshot，在 UI 变更后重新 snapshot，遇到 stale refs 时恢复一次，并在遇到登录/2FA/captcha 或摄像头/麦克风阻塞时，将其报告为需要手动操作，而不是猜测处理。 -启用插件后，插件内置的 Skills 会列在智能体可用的 Skills 中。完整的 Skills 指令按需加载，因此常规轮次无需承担全部 token 成本。 +启用插件后，插件内置的 Skills 会列在智能体的可用 Skills 中。完整的 Skills 指令按需加载，因此日常轮次不会承担全部 token 成本。 ## 缺少浏览器命令或工具 -如果升级后 `openclaw browser` 无法识别、缺少 `browser.request`，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中遗漏了 `browser`。把它加上： +如果升级后 `openclaw browser` 无法识别、缺少 `browser.request`，或者智能体报告浏览器工具不可用，常见原因是 `plugins.allow` 列表中遗漏了 `browser`。请将其添加进去： ```json5 { @@ -90,20 +91,20 @@ openclaw browser --browser-profile openclaw snapshot } ``` -`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 都不能替代出现在 allowlist 中——allowlist 决定插件是否加载，而工具策略只会在加载之后运行。完全移除 `plugins.allow` 也会恢复默认行为。 +`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 都不能替代 allowlist 成员资格——allowlist 控制插件是否加载，而工具策略只会在加载之后运行。完全移除 `plugins.allow` 也会恢复默认行为。 ## 配置文件：`openclaw` 与 `user` -- `openclaw`：托管的隔离浏览器（无需扩展）。 -- `user`：内置的 Chrome MCP 连接配置文件，用于连接你**真实的、已登录的 Chrome** 会话。 +- `openclaw`：受管理、隔离的浏览器（无需扩展）。 +- `user`：内置的 Chrome MCP 附加配置文件，用于连接你**真实的已登录 Chrome** 会话。 对于智能体浏览器工具调用： - 默认：使用隔离的 `openclaw` 浏览器。 -- 当现有的已登录会话很重要，且用户正坐在电脑前可以点击/批准任何连接提示时，优先使用 `profile="user"`。 -- 当你想指定某种浏览器模式时，`profile` 是显式覆盖项。 +- 当现有登录会话很重要，并且用户就在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。 +- 当你想明确指定某种浏览器模式时，使用 `profile` 作为显式覆盖。 -如果你希望默认使用托管模式，请设置 `browser.defaultProfile: "openclaw"`。 +如果你希望默认使用受管理模式，请设置 `browser.defaultProfile: "openclaw"`。 ## 配置 @@ -114,15 +115,15 @@ openclaw browser --browser-profile openclaw snapshot browser: { enabled: true, // 默认值：true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 仅在信任私有网络访问时启用 + // dangerouslyAllowPrivateNetwork: true, // 仅在信任私有网络访问时选择启用 // allowPrivateNetwork: true, // 旧别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // 旧的单配置文件覆盖项 - remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时（毫秒） - remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒） - actionTimeoutMs: 60000, // 默认浏览器 act 超时（毫秒） + // cdpUrl: "http://127.0.0.1:18792", // 旧的单配置文件覆盖方式 + remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时时间（毫秒） + remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时时间（毫秒） + actionTimeoutMs: 60000, // 默认浏览器 act 超时时间（毫秒） tabCleanup: { enabled: true, // 默认值：true idleMinutes: 120, // 设为 0 可禁用空闲清理 @@ -164,35 +165,37 @@ openclaw browser --browser-profile openclaw snapshot -- 控制服务绑定到 loopback，使用一个基于 `gateway.port` 派生出的端口（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会让同一组派生端口整体移动。 -- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；仅在远程 CDP 时才需要设置这些值。未设置时，`cdpUrl` 默认使用托管的本地 CDP 端口。 -- `remoteCdpTimeoutMs` 适用于远程（非 loopback）CDP HTTP 可达性检查；`remoteCdpHandshakeTimeoutMs` 适用于远程 CDP WebSocket 握手。 -- `actionTimeoutMs` 是浏览器 `act` 请求的默认时限，当调用方没有传入 `timeoutMs` 时使用。客户端传输层会额外增加一个小的缓冲窗口，这样长时间等待可以完成，而不是在 HTTP 边界超时。 -- `tabCleanup` 是针对主智能体浏览器会话所打开标签页的尽力清理机制。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭其显式跟踪的标签页；主会话会保留活跃标签页以供复用，然后在后台关闭空闲或超额的已跟踪标签页。 +- 控制服务绑定到 loopback 上，端口基于 `gateway.port` 推导而来（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会让这些派生端口按同一族整体偏移。 +- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；只有远程 CDP 才需要设置这些值。未设置时，`cdpUrl` 默认指向受管理的本地 CDP 端口。 +- `remoteCdpTimeoutMs` 用于远程（非 loopback）CDP HTTP 可达性检查；`remoteCdpHandshakeTimeoutMs` 用于远程 CDP WebSocket 握手。 +- 当调用方没有传入 `timeoutMs` 时，`actionTimeoutMs` 是浏览器 `act` 请求的默认时间预算。客户端传输层会额外增加一个小的宽限窗口，这样长时间等待可以完成，而不会在 HTTP 边界超时。 +- `tabCleanup` 是针对主智能体浏览器会话所打开标签页的尽力清理机制。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭它们明确跟踪的标签页；主会话会保留活动标签页以供复用，然后在后台关闭空闲或超额的已跟踪标签页。 -- 浏览器导航和打开标签页在导航前会进行 SSRF 防护，并在之后对最终的 `http(s)` URL 做尽力复检。 +- 浏览器导航和打开标签页会在导航前受到 SSRF 保护，并在导航后对最终 `http(s)` URL 进行尽力复查。 - 在严格 SSRF 模式下，远程 CDP 端点发现和 `/json/version` 探测（`cdpUrl`）也会被检查。 -- Gateway 网关/提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动代理 OpenClaw 托管的浏览器。托管的 Chrome 默认直接启动，因此提供商代理设置不会削弱浏览器的 SSRF 检查。 -- 若要代理托管浏览器本身，请通过 `browser.extraArgs` 传入显式的 Chrome 代理参数，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。严格 SSRF 模式会阻止显式的浏览器代理路由，除非你明确启用了私有网络浏览器访问。 -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅在你有意信任私有网络浏览器访问时启用。 -- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为旧别名受支持。 +- Gateway 网关/提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动代理由 OpenClaw 管理的浏览器。受管理的 Chrome 默认直接启动，因此提供商代理设置不会削弱浏览器的 SSRF 检查。 +- 若要代理受管理浏览器本身，请通过 `browser.extraArgs` 传入明确的 Chrome 代理参数，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。在严格 SSRF 模式下，除非你明确启用了私有网络浏览器访问，否则显式浏览器代理路由会被阻止。 +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；只有在你明确信任私有网络浏览器访问时才应启用。 +- `browser.ssrfPolicy.allowPrivateNetwork` 仍然作为旧别名受支持。 -- `attachOnly: true` 表示绝不启动本地浏览器；仅在浏览器已经运行时进行连接。 -- `headless` 可以在全局或每个本地托管配置文件中设置。每个配置文件的值会覆盖 `browser.headless`，因此一个本地启动的配置文件可以保持无头模式，而另一个保持可见。 -- `executablePath` 可以在全局或每个本地托管配置文件中设置。每个配置文件的值会覆盖 `browser.executablePath`，因此不同的托管配置文件可以启动不同的 Chromium 系浏览器。 -- `color`（顶层和每个配置文件）会为浏览器 UI 着色，以便你看出当前激活的是哪个配置文件。 -- 默认配置文件是 `openclaw`（托管的独立模式）。使用 `defaultProfile: "user"` 可改为默认使用已登录的用户浏览器。 -- 自动检测顺序：系统默认浏览器（如果它是 Chromium 系）；否则依次为 Chrome → Brave → Edge → Chromium → Chrome Canary。 +- `attachOnly: true` 表示绝不启动本地浏览器；只有在浏览器已经运行时才进行附加。 +- `headless` 可以在全局或每个本地受管理配置文件上设置。每个配置文件的值会覆盖 `browser.headless`，因此一个本地启动的配置文件可以保持 headless，而另一个仍保持可见。 +- 在没有 `DISPLAY` 或 `WAYLAND_DISPLAY` 的 Linux 主机上，如果环境和配置文件/全局配置都没有明确选择有头模式，那么本地受管理配置文件会默认自动使用 headless 模式。`openclaw browser status --json` 会将 `headlessSource` 报告为 `env`、`profile`、`config`、`linux-display-fallback` 或 `default`。 +- `OPENCLAW_BROWSER_HEADLESS=1` 会强制当前进程中的本地受管理启动使用 headless。`OPENCLAW_BROWSER_HEADLESS=0` 会强制使用有头模式，并在没有显示服务器的 Linux 主机上返回可操作的错误。 +- `executablePath` 可以在全局或每个本地受管理配置文件上设置。每个配置文件的值会覆盖 `browser.executablePath`，因此不同的受管理配置文件可以启动不同的 Chromium 系浏览器。 +- `color`（顶层和每个配置文件级别）会给浏览器 UI 着色，以便你看到当前哪个配置文件处于活动状态。 +- 默认配置文件是 `openclaw`（受管理的独立浏览器）。使用 `defaultProfile: "user"` 可以改为默认使用已登录的用户浏览器。 +- 自动检测顺序：如果系统默认浏览器是 Chromium 系，则优先使用系统默认浏览器；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。 - `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。不要为该驱动设置 `cdpUrl`。 -- 当某个 existing-session 配置文件需要连接到非默认的 Chromium 用户配置文件（Brave、Edge 等）时，请设置 `browser.profiles..userDataDir`。 +- 当 existing-session 配置文件需要附加到非默认的 Chromium 用户配置文件（Brave、Edge 等）时，请设置 `browser.profiles..userDataDir`。 @@ -201,7 +204,7 @@ openclaw browser --browser-profile openclaw snapshot ## 使用 Brave（或其他 Chromium 系浏览器） 如果你的**系统默认**浏览器是 Chromium 系（Chrome/Brave/Edge 等）， -OpenClaw 会自动使用它。设置 `browser.executablePath` 可以覆盖自动检测。 +OpenClaw 会自动使用它。设置 `browser.executablePath` 可覆盖自动检测。 `~` 会展开为你的操作系统主目录： ```bash @@ -209,7 +212,7 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" ``` -或者按平台在配置中设置： +或者在配置中按平台设置： @@ -241,47 +244,46 @@ openclaw config set browser.profiles.work.executablePath "/Applications/Google C -每个配置文件的 `executablePath` 仅影响由 OpenClaw 启动的本地托管配置文件。`existing-session` 配置文件会连接到一个已在运行的浏览器，而远程 CDP 配置文件则使用 `cdpUrl` 背后的浏览器。 +每个配置文件级别的 `executablePath` 只会影响由 OpenClaw 启动的本地受管理配置文件。`existing-session` 配置文件会改为附加到一个已经运行的浏览器，而远程 CDP 配置文件会使用 `cdpUrl` 背后的浏览器。 ## 本地控制与远程控制 -- **本地控制（默认）：** Gateway 网关会启动 loopback 控制服务，并且可以启动本地浏览器。 -- **远程控制（节点主机）：** 在拥有浏览器的机器上运行一个节点主机；Gateway 网关会将浏览器操作代理过去。 -- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）以连接到远程 Chromium 系浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 -- `headless` 仅影响由 OpenClaw 启动的本地托管配置文件。它不会重启或更改 existing-session 或远程 CDP 浏览器。 -- `executablePath` 也遵循相同的本地托管配置文件规则。在运行中的本地托管配置文件上更改它，会将该配置文件标记为需要重启/协调，以便下次启动时使用新的二进制文件。 +- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并且可以启动本地浏览器。 +- **远程控制（节点主机）：** 在拥有浏览器的机器上运行一个节点主机；Gateway 网关会将浏览器操作代理给它。 +- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）以附加到远程 Chromium 系浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 +- `headless` 只影响由 OpenClaw 启动的本地受管理配置文件。它不会重启或更改 existing-session 或远程 CDP 浏览器。 +- `executablePath` 也遵循同样的本地受管理配置文件规则。在正在运行的本地受管理配置文件上更改它时，该配置文件会被标记为需要重启/重新协调，以便下一次启动时使用新的二进制文件。 -不同配置文件模式下，停止行为有所不同： +不同配置文件模式下，停止行为也不同： -- 本地托管配置文件：`openclaw browser stop` 会停止由 OpenClaw 启动的浏览器进程 -- 仅连接和远程 CDP 配置文件：`openclaw browser stop` 会关闭当前控制会话，并释放 Playwright/CDP 仿真覆盖项（视口、配色方案、区域设置、时区、离线模式及类似状态），即使 OpenClaw 没有启动任何浏览器进程 +- 本地受管理配置文件：`openclaw browser stop` 会停止由 OpenClaw 启动的浏览器进程 +- 仅附加和远程 CDP 配置文件：`openclaw browser stop` 会关闭当前控制会话，并释放 Playwright/CDP 仿真覆盖项（视口、配色方案、区域设置、时区、离线模式及类似状态），即使 OpenClaw 并未启动任何浏览器进程也是如此 远程 CDP URL 可以包含认证信息： -- 查询参数 token（例如，`https://provider.example?token=`） -- HTTP Basic 认证（例如，`https://user:pass@provider.example`） +- 查询参数令牌（例如：`https://provider.example?token=`） +- HTTP Basic 认证（例如：`https://user:pass@provider.example`） -OpenClaw 在调用 `/json/*` 端点以及连接到 CDP WebSocket 时会保留认证信息。 -对于 token，优先使用环境变量或密钥管理器，而不是将其提交到配置文件中。 +OpenClaw 在调用 `/json/*` 端点以及连接到 CDP WebSocket 时都会保留这些认证信息。对于令牌，优先使用环境变量或 secrets manager，而不是将它们提交到配置文件中。 -## 节点浏览器代理（默认零配置） +## Node 浏览器代理（默认零配置） 如果你在拥有浏览器的那台机器上运行了一个**节点主机**，OpenClaw 可以自动将浏览器工具调用路由到该节点，而无需任何额外的浏览器配置。 这是远程 Gateway 网关的默认路径。 说明： -- 节点主机会通过一个**代理命令**暴露其本地浏览器控制服务器。 +- 节点主机会通过一个**代理命令**暴露它的本地浏览器控制服务器。 - 配置文件来自节点自身的 `browser.profiles` 配置（与本地相同）。 -- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空即可保留旧版/默认行为：所有已配置的配置文件都可通过代理访问，包括配置文件创建/删除路由。 -- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有 allowlist 中的配置文件可以作为目标，并且持久化配置文件的创建/删除路由会在代理界面上被阻止。 -- 如果你不想启用它，可以关闭： +- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空可保留旧版/默认行为：所有已配置的配置文件都可以通过代理访问，包括配置文件创建/删除路由。 +- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有 allowlist 中的配置文件可以作为目标，并且持久化配置文件创建/删除路由会在代理界面上被阻止。 +- 如果你不想启用它，可以禁用： - 在节点上：`nodeHost.browserProxy.enabled=false` - - 在 gateway 上：`gateway.nodes.browser.mode="off"` + - 在 Gateway 网关上：`gateway.nodes.browser.mode="off"` ## Browserless（托管远程 CDP） -[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，通过 HTTPS 和 WebSocket 暴露 CDP 连接 URL。OpenClaw 可以使用任一形式，但对于远程浏览器配置文件，最简单的选项是使用 Browserless 连接文档中的直接 WebSocket URL。 +[Browserless](https://browserless.io) 是一项托管的 Chromium 服务，它通过 HTTPS 和 WebSocket 暴露 CDP 连接 URL。OpenClaw 两种形式都可以使用，但对于远程浏览器配置文件，最简单的选项是使用 Browserless 连接文档中提供的直接 WebSocket URL。 示例： @@ -304,25 +306,22 @@ OpenClaw 在调用 `/json/*` 端点以及连接到 CDP WebSocket 时会保留认 说明： -- 将 `` 替换为你真实的 Browserless token。 -- 选择与你的 Browserless 账户匹配的区域端点（见其文档）。 -- 如果 Browserless 提供给你的是 HTTPS 基础 URL，你可以将其转换为 `wss://` 用于直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw 去发现 `/json/version`。 +- 将 `` 替换为你真实的 Browserless 令牌。 +- 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。 +- 如果 Browserless 提供给你的是 HTTPS 基础 URL，你可以将其转换为 `wss://` 以进行直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw 自动发现 `/json/version`。 ## 直接 WebSocket CDP 提供商 -有些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种 CDP URL 形式，并会自动选择正确的连接策略： +某些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种 CDP URL 形式，并会自动选择正确的连接策略： - **HTTP(S) 发现** — `http://host[:port]` 或 `https://host[:port]`。 OpenClaw 会调用 `/json/version` 来发现 WebSocket 调试器 URL，然后进行连接。没有 WebSocket 回退。 -- **直接 WebSocket 端点** — `ws://host[:port]/devtools//` 或 - `wss://...` 且路径为 `/devtools/browser|page|worker|shared_worker|service_worker/`。 - OpenClaw 会直接通过 WebSocket 握手连接，并完全跳过 `/json/version`。 -- **裸 WebSocket 根路径** — `ws://host[:port]` 或 `wss://host[:port]`，且没有 - `/devtools/...` 路径（例如 [Browserless](https://browserless.io)、[Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试 HTTP `/json/version` 发现（将 scheme 规范化为 `http`/`https`）；如果发现返回了 `webSocketDebuggerUrl`，就使用它，否则 OpenClaw 会回退为在裸根路径上直接进行 WebSocket 握手。这使得指向本地 Chrome 的裸 `ws://` 仍可连接，因为 Chrome 只接受来自 `/json/version` 中特定目标路径的 WebSocket 升级。 +- **直接 WebSocket 端点** — `ws://host[:port]/devtools//` 或带有 `/devtools/browser|page|worker|shared_worker|service_worker/` 路径的 `wss://...`。OpenClaw 会直接通过 WebSocket 握手连接，并完全跳过 `/json/version`。 +- **裸 WebSocket 根路径** — `ws://host[:port]` 或 `wss://host[:port]`，且没有 `/devtools/...` 路径（例如 [Browserless](https://browserless.io)、[Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试 HTTP `/json/version` 发现（将 scheme 规范化为 `http`/`https`）；如果发现返回了 `webSocketDebuggerUrl`，就使用它，否则 OpenClaw 会回退到裸根路径上的直接 WebSocket 握手。这使得指向本地 Chrome 的裸 `ws://` 仍可连接，因为 Chrome 只接受来自 `/json/version` 返回的特定 target 路径上的 WebSocket 升级。 ### Browserbase -[Browserbase](https://www.browserbase.com) 是一个云平台，用于运行无头浏览器，内置 CAPTCHA 解决、隐身模式和住宅代理。 +[Browserbase](https://www.browserbase.com) 是一个云平台，用于运行 headless 浏览器，内置 CAPTCHA 求解、隐身模式和住宅代理。 ```json5 { @@ -343,53 +342,52 @@ OpenClaw 在调用 `/json/*` 端点以及连接到 CDP WebSocket 时会保留认 说明： -- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview dashboard](https://www.browserbase.com/overview) 复制你的 **API Key**。 +- [注册](https://www.browserbase.com/sign-up)，并从 [Overview dashboard](https://www.browserbase.com/overview) 复制你的**API Key**。 - 将 `` 替换为你真实的 Browserbase API key。 -- Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此无需手动创建会话。 -- 免费套餐每月允许一个并发会话和一个浏览器小时。 - 付费方案限制请参见 [pricing](https://www.browserbase.com/pricing)。 -- 完整的 API 参考、SDK 指南和集成示例，请参见 [Browserbase docs](https://docs.browserbase.com)。 +- Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此不需要手动创建会话步骤。 +- 免费套餐每月允许一个并发会话和一个浏览器小时。付费套餐限制请参阅 [pricing](https://www.browserbase.com/pricing)。 +- 完整 API 参考、SDK 指南和集成示例请参阅 [Browserbase docs](https://docs.browserbase.com)。 -## 安全 +## 安全性 关键概念： - 浏览器控制仅限 loopback；访问通过 Gateway 网关的认证或节点配对进行。 -- 独立的 loopback 浏览器 HTTP API **仅使用共享密钥认证**：gateway token bearer 认证、`x-openclaw-password`，或使用已配置 gateway 密码的 HTTP Basic 认证。 -- Tailscale Serve 身份头和 `gateway.auth.mode: "trusted-proxy"` **不会**为这个独立的 loopback 浏览器 API 提供认证。 -- 如果启用了浏览器控制且未配置共享密钥认证，OpenClaw 会在启动时自动生成 `gateway.auth.token`，并将其持久化到配置中。 -- 如果 `gateway.auth.mode` 已经是 `password`、`none` 或 `trusted-proxy`，OpenClaw **不会**自动生成该 token。 -- 请将 Gateway 网关和所有节点主机放在私有网络（Tailscale）中；避免公开暴露。 -- 将远程 CDP URL/token 视为机密；优先使用环境变量或密钥管理器。 +- 独立的 loopback 浏览器 HTTP API **仅**使用共享密钥认证：gateway token bearer 认证、`x-openclaw-password`，或使用已配置 gateway 密码的 HTTP Basic 认证。 +- Tailscale Serve 身份头和 `gateway.auth.mode: "trusted-proxy"` **不能**为这个独立的 loopback 浏览器 API 提供认证。 +- 如果启用了浏览器控制，但没有配置共享密钥认证，OpenClaw 会在启动时自动生成 `gateway.auth.token` 并将其持久化到配置中。 +- 如果 `gateway.auth.mode` 已经是 `password`、`none` 或 `trusted-proxy`，OpenClaw **不会**自动生成该令牌。 +- 将 Gateway 网关和任何节点主机保持在私有网络（Tailscale）中；避免公开暴露。 +- 将远程 CDP URL/令牌视为机密；优先使用环境变量或 secrets manager。 远程 CDP 提示： -- 尽可能优先使用加密端点（HTTPS 或 WSS）和短期 token。 -- 避免将长期 token 直接嵌入配置文件中。 +- 尽可能优先使用加密端点（HTTPS 或 WSS）和短期令牌。 +- 避免将长期令牌直接嵌入配置文件。 ## 配置文件（多浏览器） OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是： -- **openclaw-managed**：一个专用的 Chromium 系浏览器实例，拥有自己的用户数据目录 + CDP 端口 -- **remote**：一个显式的 CDP URL（运行在其他地方的 Chromium 系浏览器） -- **existing session**：通过 Chrome DevTools MCP 自动连接你的现有 Chrome 配置文件 +- **由 OpenClaw 管理**：一个专用的 Chromium 系浏览器实例，具有自己的用户数据目录 + CDP 端口 +- **远程**：一个显式的 CDP URL（运行在其他地方的 Chromium 系浏览器） +- **existing session**：通过 Chrome DevTools MCP 自动连接你现有的 Chrome 配置文件 默认值： -- 如果缺失，会自动创建 `openclaw` 配置文件。 -- `user` 配置文件内置用于 Chrome MCP existing-session 连接。 -- 除 `user` 之外，existing-session 配置文件需要显式启用；请使用 `--driver existing-session` 创建它们。 +- 如果缺少，`openclaw` 配置文件会自动创建。 +- `user` 配置文件是内置的，用于 Chrome MCP existing-session 附加。 +- 除 `user` 之外，existing-session 配置文件需要显式启用；使用 `--driver existing-session` 创建它们。 - 本地 CDP 端口默认从 **18800–18899** 分配。 -- 删除某个配置文件时，其本地数据目录会被移到废纸篓。 +- 删除配置文件会将其本地数据目录移动到回收站。 所有控制端点都接受 `?profile=`；CLI 使用 `--browser-profile`。 ## 通过 Chrome DevTools MCP 使用现有会话 -OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器连接到一个正在运行的 Chromium 系浏览器配置文件。这样可以复用该浏览器配置文件中已经打开的标签页和登录状态。 +OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到一个正在运行的 Chromium 系浏览器配置文件。这会复用该浏览器配置文件中已经打开的标签页和登录状态。 -官方背景和设置参考： +官方背景与设置参考： - [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) @@ -402,9 +400,9 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器连接到一个正 默认行为： -- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，目标是默认的本地 Google Chrome 配置文件。 +- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，其目标是默认的本地 Google Chrome 配置文件。 -对于 Brave、Edge、Chromium 或非默认的 Chrome 配置文件，请使用 `userDataDir`： +对于 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`： ```json5 { @@ -425,15 +423,15 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器连接到一个正 1. 打开该浏览器用于远程调试的 inspect 页面。 2. 启用远程调试。 -3. 保持浏览器运行，并在 OpenClaw 连接时批准连接提示。 +3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。 -常见的 inspect 页面： +常见 inspect 页面： - Chrome：`chrome://inspect/#remote-debugging` - Brave：`brave://inspect/#remote-debugging` - Edge：`edge://inspect/#remote-debugging` -实时连接冒烟测试： +实时附加冒烟测试： ```bash openclaw browser --browser-profile user start @@ -442,51 +440,51 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -成功时的表现： +成功时应表现为： - `status` 显示 `driver: existing-session` - `status` 显示 `transport: chrome-mcp` - `status` 显示 `running: true` -- `tabs` 会列出你已经打开的浏览器标签页 -- `snapshot` 会从所选中的实时标签页返回引用 +- `tabs` 列出你已经打开的浏览器标签页 +- `snapshot` 返回来自所选实时标签页的 refs -如果连接不起作用，请检查： +如果附加无法工作，请检查： -- 目标 Chromium 系浏览器的版本为 `144+` +- 目标 Chromium 系浏览器版本为 `144+` - 该浏览器的 inspect 页面中已启用远程调试 -- 浏览器已显示连接授权提示，并且你已接受 -- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法替你在浏览器端启用远程调试 +- 浏览器已经显示附加同意提示，并且你已接受 +- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已本地安装，但它不能替你在浏览器端启用远程调试 智能体使用： -- 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。 -- 如果你使用的是自定义 existing-session 配置文件，请传入那个明确的配置文件名称。 -- 仅当用户正坐在电脑前，可以批准连接提示时，才选择这种模式。 +- 当你需要用户已登录浏览器状态时，使用 `profile="user"`。 +- 如果你使用自定义 existing-session 配置文件，请传入该明确的配置文件名。 +- 仅当用户就在电脑前可以批准附加提示时，才选择此模式。 - Gateway 网关或节点主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect` 说明： -- 这一路径比隔离的 `openclaw` 配置文件风险更高，因为它可以在你已登录的浏览器会话中执行操作。 -- 对于这个驱动，OpenClaw 不会启动浏览器；它只会进行连接。 -- OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果设置了 `userDataDir`，它会一并传递，以便定位该用户数据目录。 -- Existing-session 可以连接到所选主机上，或通过已连接的浏览器节点连接。如果 Chrome 位于别处且没有连接浏览器节点，请改用远程 CDP 或节点主机。 +- 与隔离的 `openclaw` 配置文件相比，这条路径风险更高，因为它可以在你已登录的浏览器会话中执行操作。 +- 对于此驱动，OpenClaw 不会启动浏览器；它只会进行附加。 +- OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果设置了 `userDataDir`，则会将其一并传入，以定位该用户数据目录。 +- Existing-session 可以附加到选定主机上，或通过已连接的浏览器节点进行附加。如果 Chrome 位于其他地方且没有连接浏览器节点，请改用远程 CDP 或节点主机。 -与托管的 `openclaw` 配置文件相比，existing-session 驱动限制更多： +与受管理的 `openclaw` 配置文件相比，existing-session 驱动的限制更多： -- **截图** —— 支持页面截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面截图或基于 ref 的元素截图不需要 Playwright。 -- **操作** —— `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要快照 ref（不支持 CSS 选择器）。`click-coords` 点击可见视口坐标，不需要快照 ref。`click` 仅支持鼠标左键。`type` 不支持 `slowly=true`；请改用 `fill` 或 `press`。`press` 不支持 `delayMs`。`type`、`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持逐调用超时。`select` 接受单个值。 -- **等待 / 上传 / 对话框** —— `wait --url` 支持精确、子串和 glob 模式；不支持 `wait --load networkidle`。上传钩子需要 `ref` 或 `inputRef`，一次一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。 -- **仅托管模式功能** —— 批量操作、PDF 导出、下载拦截和 `responsebody` 仍然需要托管浏览器路径。 +- **截图** — 支持页面截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面截图或基于 ref 的元素截图不需要 Playwright。 +- **操作** — `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要 snapshot refs（不支持 CSS 选择器）。`click-coords` 点击可见视口坐标，不需要 snapshot ref。`click` 仅支持左键。`type` 不支持 `slowly=true`；请使用 `fill` 或 `press`。`press` 不支持 `delayMs`。`type`、`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用设置超时。`select` 接受单个值。 +- **等待 / 上传 / 对话框** — `wait --url` 支持精确、子串和 glob 模式；不支持 `wait --load networkidle`。上传钩子要求 `ref` 或 `inputRef`，一次一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。 +- **仅受管理模式支持的功能** — 批量操作、PDF 导出、下载拦截和 `responsebody` 仍然需要使用受管理浏览器路径。 ## 隔离保证 -- **专用用户数据目录**：绝不会触碰你的个人浏览器配置文件。 -- **专用端口**：避免使用 `9222`，以防与开发工作流冲突。 -- **可预测的标签页控制**：`tabs` 会优先返回 `suggestedTargetId`，然后是稳定的 `tabId` 句柄（例如 `t1`）、可选标签以及原始 `targetId`。智能体应复用 `suggestedTargetId`；原始 id 仍保留用于调试和兼容性。 +- **专用用户数据目录**：绝不会接触你的个人浏览器配置文件。 +- **专用端口**：避免使用 `9222`，以防与开发工作流发生冲突。 +- **可预测的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId` 句柄，例如 `t1`、可选标签以及原始 `targetId`。智能体应复用 `suggestedTargetId`；原始 id 仍可用于调试和兼容性场景。 ## 浏览器选择 @@ -498,32 +496,30 @@ openclaw browser --browser-profile user snapshot --format ai 4. Chromium 5. Chrome Canary -你可以使用 `browser.executablePath` 进行覆盖。 +你可以通过 `browser.executablePath` 覆盖此行为。 -平台： +平台说明： - macOS：检查 `/Applications` 和 `~/Applications`。 -- Linux：检查 `/usr/bin`、`/snap/bin`、`/opt/google`、`/opt/brave.com`、`/usr/lib/chromium` 和 `/usr/lib/chromium-browser` 下常见的 Chrome/Brave/Edge/Chromium 位置。 -- Windows：检查常见的安装位置。 +- Linux：检查 `/usr/bin`、`/snap/bin`、`/opt/google`、`/opt/brave.com`、`/usr/lib/chromium` 和 `/usr/lib/chromium-browser` 下常见的 Chrome/Brave/Edge/Chromium 路径。 +- Windows：检查常见安装位置。 ## 控制 API（可选） -对于脚本编写和调试，Gateway 网关会暴露一个小型的**仅限 loopback 的 HTTP 控制 API**，以及与之对应的 `openclaw browser` CLI（快照、ref、等待增强功能、JSON 输出、调试工作流）。完整参考请参见 [浏览器控制 API](/zh-CN/tools/browser-control)。 +对于脚本编写和调试，Gateway 网关提供了一个小型的**仅限 loopback 的 HTTP 控制 API**，以及与之匹配的 `openclaw browser` CLI（快照、refs、wait 增强功能、JSON 输出、调试工作流）。完整参考请参见[浏览器控制 API](/zh-CN/tools/browser-control)。 ## 故障排除 -对于 Linux 特有问题（尤其是 snap Chromium），请参见 -[浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)。 +对于 Linux 特有问题（尤其是 snap Chromium），请参见[浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)。 -对于 WSL2 Gateway 网关 + Windows Chrome 分离主机设置，请参见 -[WSL2 + Windows + 远程 Chrome CDP 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)。 +对于 WSL2 Gateway 网关 + Windows Chrome 分离主机设置，请参见[WSL2 + Windows + 远程 Chrome CDP 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)。 ### CDP 启动失败与导航 SSRF 阻止 -这两者是不同的失败类型，并且指向不同的代码路径。 +这两者属于不同的失败类型，并指向不同的代码路径。 -- **CDP 启动或就绪失败**表示 OpenClaw 无法确认浏览器控制平面处于健康状态。 -- **导航 SSRF 阻止**表示浏览器控制平面是健康的，但页面导航目标被策略拒绝了。 +- **CDP 启动或就绪失败**意味着 OpenClaw 无法确认浏览器控制平面处于健康状态。 +- **导航 SSRF 阻止**意味着浏览器控制平面是健康的，但某个页面导航目标因策略而被拒绝。 常见示例： @@ -531,9 +527,9 @@ openclaw browser --browser-profile user snapshot --format ai - `Chrome CDP websocket for profile "openclaw" is not reachable after start` - `Remote CDP for profile "" is not reachable at ` - 导航 SSRF 阻止： - - 当 `start` 和 `tabs` 仍然可用时，`open`、`navigate`、快照或打开标签页流程因浏览器/网络策略错误而失败 + - 当 `start` 和 `tabs` 仍然可用时，`open`、`navigate`、snapshot 或打开标签页流程因浏览器/网络策略错误而失败 -使用下面这组最小命令来区分两者： +使用下面这个最小化序列来区分两者： ```bash openclaw browser --browser-profile openclaw start @@ -541,26 +537,26 @@ openclaw browser --browser-profile openclaw tabs openclaw browser --browser-profile openclaw open https://example.com ``` -如何理解结果： +结果解读方式： -- 如果 `start` 因 `not reachable after start` 失败，先排查 CDP 就绪性。 -- 如果 `start` 成功但 `tabs` 失败，则控制平面仍然不健康。应将其视为 CDP 可达性问题，而不是页面导航问题。 -- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则浏览器控制平面已启动，失败点在导航策略或目标页面。 -- 如果 `start`、`tabs` 和 `open` 全部成功，则基础的托管浏览器控制路径是健康的。 +- 如果 `start` 因 `not reachable after start` 失败，先排查 CDP 就绪问题。 +- 如果 `start` 成功但 `tabs` 失败，说明控制平面仍不健康。应将其视为 CDP 可达性问题，而不是页面导航问题。 +- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面已正常运行，失败点在导航策略或目标页面上。 +- 如果 `start`、`tabs` 和 `open` 全部成功，则说明基础的受管理浏览器控制路径是健康的。 重要行为细节： -- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会使用一个故障关闭的 SSRF 策略对象。 -- 对于本地 loopback 的 `openclaw` 托管配置文件，CDP 健康检查会有意跳过浏览器 SSRF 可达性强制，以便 OpenClaw 自身的本地控制平面正常工作。 -- 导航保护是独立的。`start` 或 `tabs` 成功，并不意味着后续的 `open` 或 `navigate` 目标一定被允许。 +- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会使用一个默认拒绝的 SSRF 策略对象。 +- 对于本地 loopback 的 `openclaw` 受管理配置文件，CDP 健康检查会有意跳过针对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制校验。 +- 导航保护是独立的。`start` 或 `tabs` 成功，并不意味着之后的 `open` 或 `navigate` 目标一定被允许。 安全建议： -- 默认情况下**不要**放宽浏览器 SSRF 策略。 -- 优先使用精确的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`，而不是宽泛地允许私有网络访问。 -- 仅在明确受信任、确实需要并已审核私有网络浏览器访问的环境中使用 `dangerouslyAllowPrivateNetwork: true`。 +- **不要**默认放宽浏览器 SSRF 策略。 +- 优先使用精细的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`，而不是广泛开放私有网络访问。 +- 仅在明确受信任、且私有网络浏览器访问确有需要并已审核的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。 -## 智能体工具 + 控制方式 +## 智能体工具 + 控制工作方式 智能体获得**一个工具**用于浏览器自动化： @@ -568,21 +564,21 @@ openclaw browser --browser-profile openclaw open https://example.com 它的映射方式如下： -- `browser snapshot` 返回一个稳定的 UI 树（AI 或 ARIA）。 -- `browser act` 使用快照中的 `ref` ID 来执行点击/输入/拖拽/选择。 -- `browser screenshot` 捕获像素内容（整页、元素或带标签的 ref）。 +- `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。 +- `browser act` 使用 snapshot 的 `ref` ID 来执行点击/输入/拖动/选择。 +- `browser screenshot` 捕获像素截图（整页、元素或带标签的 refs）。 - `browser doctor` 检查 Gateway 网关、插件、配置文件、浏览器和标签页就绪状态。 - `browser` 接受： - - `profile`：选择一个命名的浏览器配置文件（openclaw、chrome 或远程 CDP）。 + - `profile`：选择命名浏览器配置文件（openclaw、chrome 或远程 CDP）。 - `target`（`sandbox` | `host` | `node`）：选择浏览器所在位置。 - 在沙箱隔离会话中，`target: "host"` 需要 `agents.defaults.sandbox.browser.allowHostControl=true`。 - - 如果省略 `target`：沙箱隔离会话默认使用 `sandbox`，非沙箱会话默认使用 `host`。 - - 如果已连接具备浏览器能力的节点，工具可能会自动路由到该节点，除非你固定指定 `target="host"` 或 `target="node"`。 + - 如果省略 `target`：沙箱隔离会话默认使用 `sandbox`，非沙箱隔离会话默认使用 `host`。 + - 如果连接了具备浏览器能力的节点，除非你固定指定 `target="host"` 或 `target="node"`，否则该工具可能会自动路由到该节点。 -这样可以让智能体保持确定性，并避免脆弱的选择器。 +这能让智能体保持确定性，并避免脆弱的选择器。 ## 相关内容 -- [工具概览](/zh-CN/tools) —— 所有可用的智能体工具 -- [沙箱隔离](/zh-CN/gateway/sandboxing) —— 沙箱隔离环境中的浏览器控制 -- [安全](/zh-CN/gateway/security) —— 浏览器控制风险与加固 +- [工具概览](/zh-CN/tools) — 所有可用的智能体工具 +- [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的浏览器控制 +- [安全性](/zh-CN/gateway/security) — 浏览器控制的风险与加固