From cfff918bbdcb9831126af513dacf604b4dcb683f Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 23:40:03 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/browser.md | 86 ++++----- docs/zh-CN/tools/browser.md | 347 +++++++++++++++++++----------------- 2 files changed, 231 insertions(+), 202 deletions(-) diff --git a/docs/zh-CN/cli/browser.md b/docs/zh-CN/cli/browser.md index db05194b0..68ab7493c 100644 --- a/docs/zh-CN/cli/browser.md +++ b/docs/zh-CN/cli/browser.md @@ -1,34 +1,34 @@ --- read_when: - - 你使用 `openclaw browser`，并且想要常见任务的示例 - - 你想通过节点主机控制另一台机器上运行的浏览器 + - 你正在使用 `openclaw browser`，并希望查看常见任务的示例 + - 你想通过节点主机控制在另一台机器上运行的浏览器 - 你想通过 Chrome MCP 连接到你本地已登录的 Chrome -summary: '`openclaw browser` 的 CLI 参考（生命周期、配置文件、标签页、操作、状态和调试）' +summary: '`openclaw browser` 的 CLI 参考（生命周期、配置档案、标签页、操作、状态和调试）' title: 浏览器 x-i18n: - generated_at: "2026-04-24T23:30:21Z" + generated_at: "2026-04-24T23:38:43Z" model: gpt-5.4 provider: openai - source_hash: 07d8aad1aa28f9504d201d156178e9d7d6aa59a684aa26cde84d7946480364f6 + source_hash: c6e9201d028d94c92dec9ee87fd6097a9cfa039c777a543ca424d8b9981618e7 source_path: cli/browser.md workflow: 15 --- # `openclaw browser` -管理 OpenClaw 的浏览器控制界面，并运行浏览器操作（生命周期、配置文件、标签页、快照、截图、导航、输入、状态模拟和调试）。 +管理 OpenClaw 的浏览器控制界面，并运行浏览器操作（生命周期、配置档案、标签页、快照、截图、导航、输入、状态模拟和调试）。 相关内容： -- 浏览器工具 + API：[浏览器工具](/zh-CN/tools/browser) +- Browser 工具 + API：[Browser 工具](/zh-CN/tools/browser) ## 常用标志 -- `--url `：Gateway 网关 WebSocket URL（默认使用配置中的值）。 -- `--token `：Gateway 网关令牌（如果需要）。 -- `--timeout `：请求超时时间（毫秒）。 -- `--expect-final`：等待最终的 Gateway 网关响应。 -- `--browser-profile `：选择浏览器配置文件（默认值来自配置）。 +- `--url `：Gateway 网关 WebSocket URL（默认来自配置）。 +- `--token `：Gateway 网关令牌（如需要）。 +- `--timeout `：请求超时（毫秒）。 +- `--expect-final`：等待 Gateway 网关返回最终响应。 +- `--browser-profile `：选择浏览器配置档案（默认来自配置）。 - `--json`：机器可读输出（在支持的情况下）。 ## 快速开始（本地） @@ -42,9 +42,9 @@ openclaw browser --browser-profile openclaw snapshot ## 快速故障排除 -如果 `start` 因 `not reachable after start` 失败，请先排查 CDP 就绪状态。如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面是健康的，失败原因通常是导航 SSRF 策略。 +如果 `start` 失败并提示 `not reachable after start`，请先排查 CDP 就绪状态。如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面是正常的，而失败通常是导航 SSRF 策略导致的。 -最小操作序列： +最小排查序列： ```bash openclaw browser --browser-profile openclaw start @@ -52,7 +52,7 @@ openclaw browser --browser-profile openclaw tabs openclaw browser --browser-profile openclaw open https://example.com ``` -详细指南：[浏览器故障排除](/zh-CN/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block) +详细指南：[Browser 故障排除](/zh-CN/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block) ## 生命周期 @@ -65,14 +65,14 @@ openclaw browser --browser-profile openclaw reset-profile 说明： -- 对于 `attachOnly` 和远程 CDP 配置文件，即使 OpenClaw 本身没有启动浏览器进程，`openclaw browser stop` 也会关闭当前活动的控制会话并清除临时模拟覆盖项。 -- 对于本地托管配置文件，`openclaw browser stop` 会停止已启动的浏览器进程。 +- 对于 `attachOnly` 和远程 CDP 配置档案，即使 OpenClaw 本身没有启动浏览器进程，`openclaw browser stop` 也会关闭当前控制会话并清除临时模拟覆盖项。 +- 对于本地托管配置档案，`openclaw browser stop` 会停止已启动的浏览器进程。 -## 如果命令缺失 +## 如果命令不存在 如果 `openclaw browser` 是未知命令，请检查 `~/.openclaw/openclaw.json` 中的 `plugins.allow`。 -当存在 `plugins.allow` 时，内置的浏览器插件必须被显式列出： +当存在 `plugins.allow` 时，内置的 browser 插件必须被显式列出： ```json5 { @@ -84,15 +84,15 @@ openclaw browser --browser-profile openclaw reset-profile 当插件允许列表排除了 `browser` 时，`browser.enabled=true` 不会恢复该 CLI 子命令。 -相关内容：[浏览器工具](/zh-CN/tools/browser#missing-browser-command-or-tool) +相关内容：[Browser 工具](/zh-CN/tools/browser#missing-browser-command-or-tool) -## 配置文件 +## 配置档案 -配置文件是具名的浏览器路由配置。实际使用中： +配置档案是具名的浏览器路由配置。实际使用中： - `openclaw`：启动或连接到专用的 OpenClaw 托管 Chrome 实例（隔离的用户数据目录）。 - `user`：通过 Chrome DevTools MCP 控制你现有的已登录 Chrome 会话。 -- 自定义 CDP 配置文件：指向本地或远程 CDP 端点。 +- 自定义 CDP 配置档案：指向本地或远程的 CDP 端点。 ```bash openclaw browser profiles @@ -102,7 +102,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 @@ -121,7 +121,7 @@ openclaw browser focus docs openclaw browser close t1 ``` -`tabs` 返回原始 `targetId` 以及稳定的 `tabId`，例如 `t1`。你也可以使用 `open --label`、`tab new --label` 或 `tab label` 分配标签。`focus`、`close`、快照和操作都接受原始 `targetId`、`tabId`、标签或唯一的 target-id 前缀。 +`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId`（如 `t1`）、可选标签以及原始 `targetId`。智能体应将 `suggestedTargetId` 传回给 `focus`、`close`、快照和操作命令。你可以使用 `open --label`、`tab new --label` 或 `tab label` 分配标签；标签、标签页 ID、原始目标 ID 以及唯一的目标 ID 前缀都可以被接受。 ## 快照 / 截图 / 操作 @@ -141,8 +141,8 @@ openclaw browser screenshot --ref e12 说明： -- `--full-page` 仅用于页面截图；不能与 `--ref` 或 `--element` 组合使用。 -- `existing-session` / `user` 配置文件支持页面截图，以及基于快照输出中的 `--ref` 截图，但不支持基于 CSS `--element` 的截图。 +- `--full-page` 仅用于整页截图；不能与 `--ref` 或 `--element` 组合使用。 +- `existing-session` / `user` 配置档案支持整页截图以及基于快照输出中 `--ref` 的截图，但不支持基于 CSS `--element` 的截图。 导航 / 点击 / 输入（基于 ref 的 UI 自动化）： @@ -160,7 +160,7 @@ openclaw browser wait --text "Done" openclaw browser evaluate --fn '(el) => el.textContent' --ref ``` -文件和对话框辅助功能： +文件和对话框辅助命令： ```bash openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref @@ -171,7 +171,7 @@ openclaw browser dialog --accept ## 状态和存储 -视口 + 模拟： +视口和模拟： ```bash openclaw browser resize 1280 720 @@ -186,7 +186,7 @@ openclaw browser set headers '{"x-test":"1"}' openclaw browser set credentials myuser mypass ``` -Cookies + 存储： +Cookies 和存储： ```bash openclaw browser cookies @@ -212,7 +212,7 @@ openclaw browser trace stop --out trace.zip ## 通过 MCP 使用现有 Chrome -使用内置的 `user` 配置文件，或创建你自己的 `existing-session` 配置文件： +使用内置的 `user` 配置档案，或者创建你自己的 `existing-session` 配置档案： ```bash openclaw browser --browser-profile user tabs @@ -221,31 +221,31 @@ 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` 的限制： +当前 existing-session 的限制： -- 基于快照的操作使用 refs，而不是 CSS 选择器 +- 基于快照的操作使用 ref，而不是 CSS 选择器 - `click` 仅支持左键点击 - `type` 不支持 `slowly=true` - `press` 不支持 `delayMs` -- `hover`、`scrollintoview`、`drag`、`select`、`fill` 和 `evaluate` 会拒绝每次调用的超时覆盖 +- `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) +安全性和远程设置：[Browser 工具](/zh-CN/tools/browser)、[远程访问](/zh-CN/gateway/remote)、[Tailscale](/zh-CN/gateway/tailscale)、[安全性](/zh-CN/gateway/security) -## 相关 +## 相关内容 - [CLI 参考](/zh-CN/cli) -- [浏览器](/zh-CN/tools/browser) +- [Browser](/zh-CN/tools/browser) diff --git a/docs/zh-CN/tools/browser.md b/docs/zh-CN/tools/browser.md index 7a3e235be..036bfcff0 100644 --- a/docs/zh-CN/tools/browser.md +++ b/docs/zh-CN/tools/browser.md @@ -2,38 +2,40 @@ read_when: - 添加由智能体控制的浏览器自动化 - 调试为什么 openclaw 会干扰你自己的 Chrome - - 在 macOS 应用中实现浏览器设置 + 生命周期管理 + - 在 macOS 应用中实现浏览器设置 + 生命周期 summary: 集成的浏览器控制服务 + 操作命令 title: 浏览器（由 OpenClaw 管理） x-i18n: - generated_at: "2026-04-24T23:30:18Z" + generated_at: "2026-04-24T23:38:43Z" model: gpt-5.4 provider: openai - source_hash: 58806d9728345ca32f0341a060bd53f8447f7614a1a5fdcad822d94f9bd48d40 + source_hash: d804015e89f68541c0bf3149a91d4f38618bfc3b9e13ca8cffc8b9ca4d5025c6 source_path: tools/browser.md workflow: 15 --- -OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。 -它与你的个人浏览器隔离，并通过 Gateway 网关内部的一个小型本地控制服务进行管理 -（仅限 loopback）。 +OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。 +它与你的个人浏览器隔离，并通过 Gateway 网关内置的一个小型本地 +控制服务进行管理（仅限 loopback）。 -新手视角： +面向初学者的理解方式： -- 可以把它看作一个**单独的、仅供智能体使用的浏览器**。 +- 可以把它看作一个**独立的、仅供智能体使用的浏览器**。 - `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。 - 智能体可以在一条安全通道中**打开标签页、读取页面、点击和输入**。 -- 内置的 `user` 配置文件会通过 Chrome MCP 连接到你真实的已登录 Chrome 会话。 +- 内置的 `user` 配置文件会通过 Chrome MCP 连接到你真实已登录的 Chrome 会话。 ## 你将获得什么 -- 一个名为 **openclaw** 的独立浏览器配置文件（默认带橙色强调色）。 +- 一个名为 **openclaw** 的独立浏览器配置文件（默认使用橙色强调色）。 - 可预测的标签页控制（列出/打开/聚焦/关闭）。 -- 智能体操作（点击/输入/拖拽/选择）、快照、截图、PDF。 -- 一个内置的 `browser-automation` Skills，会在启用浏览器插件时教会智能体如何使用 snapshot、stable-tab、stale-ref，以及手动阻塞恢复循环。 -- 可选的多配置文件支持（`openclaw`、`work`、`remote`，等等）。 +- 智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。 +- 一个内置的 `browser-automation` Skills，用于在启用浏览器 + 插件时，教会智能体处理快照、稳定标签页、过期引用和手动阻塞恢复循环。 +- 可选的多配置文件支持（`openclaw`、`work`、`remote` 等）。 -这个浏览器**不是**你的日常主力浏览器。它是一个安全、隔离的界面，用于智能体自动化和验证。 +这个浏览器**不是**你日常使用的主浏览器。它是一个安全、隔离的界面， +用于智能体自动化和验证。 ## 快速开始 @@ -44,13 +46,15 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启 Gateway 网关。 +如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启 +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 { @@ -64,22 +68,28 @@ 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` 工具描述包含紧凑的常驻契约：选择正确的配置文件，在同一个标签页内保持 refs 一致，使用 `tabId`/标签进行标签页定位，并在执行多步骤任务时加载浏览器 Skills。 -- 内置的 `browser-automation` Skills 包含更长的操作循环：先检查状态/标签页，给任务标签页打标签，操作前先做快照，在 UI 变化后重新快照，遇到 stale refs 时重试恢复一次，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为需要手动操作，而不是猜测处理。 +- `browser` 工具描述包含简明且始终启用的契约：选择 + 正确的配置文件，在同一个标签页中保持引用，使用 `tabId`/标签进行标签页 + 定位，并在多步骤任务中加载浏览器 skill。 +- 内置的 `browser-automation` Skills 包含更长的操作循环： + 先检查状态/标签页，为任务标签页打标签，在执行操作前创建快照， + 在 UI 变化后重新快照，过期引用恢复一次，并将登录/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 { @@ -89,20 +99,22 @@ 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** 会话。 +- `user`：内置 Chrome MCP 连接配置文件，用于连接你**真实已登录的 Chrome** + 会话。 对于智能体浏览器工具调用： - 默认：使用隔离的 `openclaw` 浏览器。 -- 当现有登录会话很重要，并且用户就在电脑前可以点击/批准任何连接提示时，优先使用 `profile="user"`。 -- 当你想要特定浏览器模式时，`profile` 是显式覆盖项。 +- 当现有登录会话很重要，且用户 + 正在电脑前可以点击/批准任何连接提示时，优先使用 `profile="user"`。 +- 当你想使用特定浏览器模式时，`profile` 是显式覆盖项。 -如果你希望默认使用受管理模式，请设置 `browser.defaultProfile: "openclaw"`。 +如果你希望默认使用受管模式，请设置 `browser.defaultProfile: "openclaw"`。 ## 配置 @@ -149,10 +161,10 @@ openclaw browser --browser-profile openclaw snapshot - + -- 控制服务绑定到 loopback 上，端口从 `gateway.port` 派生而来（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会同步移动这一组派生端口。 -- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；只有远程 CDP 才需要设置这些值。未设置时，`cdpUrl` 默认使用受管理的本地 CDP 端口。 +- 控制服务绑定到 loopback，其端口派生自 `gateway.port`（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会让派生端口在同一组中一起变化。 +- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；仅在远程 CDP 场景下设置它们。未设置时，`cdpUrl` 默认使用受管本地 CDP 端口。 - `remoteCdpTimeoutMs` 适用于远程（非 loopback）CDP HTTP 可达性检查；`remoteCdpHandshakeTimeoutMs` 适用于远程 CDP WebSocket 握手。 @@ -161,19 +173,19 @@ openclaw browser --browser-profile openclaw snapshot - 浏览器导航和打开标签页在导航前会受到 SSRF 保护，并会在之后尽力对最终的 `http(s)` URL 再次检查。 - 在严格 SSRF 模式下，远程 CDP 端点发现和 `/json/version` 探测（`cdpUrl`）也会被检查。 -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；只有在你有意信任私有网络浏览器访问时才启用。 -- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为遗留别名受到支持。 +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅当你明确可信任私有网络浏览器访问时才启用。 +- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- `attachOnly: true` 表示绝不启动本地浏览器；如果浏览器已经在运行，则只进行连接。 -- `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`。 +- `attachOnly: true` 表示永不启动本地浏览器；仅在浏览器已运行时附加。 +- `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`。 @@ -182,7 +194,8 @@ openclaw browser --browser-profile openclaw snapshot ## 使用 Brave（或其他基于 Chromium 的浏览器） 如果你的**系统默认**浏览器是基于 Chromium 的（Chrome/Brave/Edge 等）， -OpenClaw 会自动使用它。设置 `browser.executablePath` 可覆盖自动检测： +OpenClaw 会自动使用它。设置 `browser.executablePath` 可覆盖 +自动检测： ```bash openclaw config set browser.executablePath "/usr/bin/google-chrome" @@ -222,43 +235,51 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## 本地控制与远程控制 -- **本地控制（默认）：** Gateway 网关会启动 loopback 控制服务，并可启动本地浏览器。 -- **远程控制（节点主机）：** 在安装浏览器的机器上运行节点主机；Gateway 网关会将浏览器操作代理到该主机。 -- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）即可连接远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 +- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并且可以启动本地浏览器。 +- **远程控制（节点主机）：** 在拥有浏览器的机器上运行一个节点主机；Gateway 网关会将浏览器操作代理到该节点主机。 +- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）以 + 附加到远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 -停止行为会因配置文件模式而异： +停止行为因配置文件模式而异： -- 本地受管理配置文件：`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`） -OpenClaw 在调用 `/json/*` 端点以及连接到 CDP WebSocket 时会保留这些认证信息。对于 token，优先使用环境变量或密钥管理器，而不是将它们提交到配置文件中。 +OpenClaw 在调用 `/json/*` 端点以及连接 +CDP WebSocket 时会保留这些认证信息。对于 token，优先使用 +环境变量或密钥管理器，而不是将其提交到配置文件中。 ## 节点浏览器代理（默认零配置） -如果你在拥有浏览器的机器上运行了一个**节点主机**，OpenClaw 可以 -自动将浏览器工具调用路由到该节点，而无需额外的浏览器配置。 +如果你在拥有浏览器的机器上运行一个**节点主机**，OpenClaw 可以 +自动将浏览器工具调用路由到该节点，而无需任何额外的浏览器配置。 这是远程 Gateway 网关的默认路径。 说明： -- 节点主机会通过一个**代理命令**暴露其本地浏览器控制服务器。 -- 配置文件来自节点自己的 `browser.profiles` 配置（与本地相同）。 -- `nodeHost.browserProxy.allowProfiles` 是可选项。留空即可保留旧版/默认行为：所有已配置的配置文件都可通过代理访问，包括配置文件创建/删除路由。 -- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有列入 allowlist 的配置文件可以被定位，且持久化配置文件的创建/删除路由会在代理界面上被阻止。 +- 节点主机会通过一个**代理命令**公开它的本地浏览器控制服务器。 +- 配置文件来自节点自身的 `browser.profiles` 配置（与本地相同）。 +- `nodeHost.browserProxy.allowProfiles` 是可选项。留空即可保持旧版/默认行为：所有已配置的配置文件都可通过代理访问，包括配置文件创建/删除路由。 +- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有 allowlist 中的配置文件可以成为目标，同时持久化配置文件创建/删除路由会在代理暴露面上被阻止。 - 如果你不想使用它，可以禁用： - 在节点上：`nodeHost.browserProxy.enabled=false` - 在 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。 示例： @@ -281,38 +302,39 @@ CDP 连接 URL。OpenClaw 两种形式都支持，但对于远程浏览器配置 说明： -- 请将 `` 替换为你真实的 Browserless token。 +- 将 `` 替换为你真实的 Browserless token。 - 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。 -- 如果 Browserless 提供给你的是一个 HTTPS 基础 URL，你可以将它转换为 - `wss://` 以建立直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw +- 如果 Browserless 提供给你的是 HTTPS 基础 URL，你可以将它转换为 + `wss://` 以进行直接 CDP 连接，或者保留该 HTTPS URL，让 OpenClaw 自动发现 `/json/version`。 ## 直接 WebSocket CDP 提供商 -某些托管浏览器服务提供的是**直接 WebSocket** 端点，而不是 +有些托管浏览器服务暴露的是**直接 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 握手进行连接，并完全跳过 +- **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 握手。这样一来，即使一个裸 `ws://` - 指向本地 Chrome，也仍然可以连接，因为 Chrome 只接受针对 - `/json/version` 返回的特定逐目标路径上的 WebSocket 升级。 +- **裸 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 升级。 ### Browserbase -[Browserbase](https://www.browserbase.com) 是一个云平台，用于运行 -无头浏览器，内置 CAPTCHA 求解、隐身模式和住宅代理。 +[Browserbase](https://www.browserbase.com) 是一个用于运行 +无头浏览器的云平台，内置 CAPTCHA 求解、隐身模式和住宅代理。 ```json5 { @@ -333,76 +355,80 @@ CDP URL 形式，并会自动选择正确的连接策略： 说明： -- [注册](https://www.browserbase.com/sign-up)，并从 [Overview dashboard](https://www.browserbase.com/overview) 复制你的 **API Key**。 -- 请将 `` 替换为你真实的 Browserbase API 密钥。 +- [注册](https://www.browserbase.com/sign-up)，并从 [概览仪表板](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)。 + 付费套餐限制请参阅 [定价](https://www.browserbase.com/pricing)。 +- 完整 API + 参考、SDK 指南和集成示例请参阅 [Browserbase 文档](https://docs.browserbase.com)。 ## 安全性 -核心概念： +关键概念： -- 浏览器控制仅限 loopback；访问通过 Gateway 网关的认证或节点配对进行。 +- 浏览器控制仅限 loopback；访问通过 Gateway 网关的认证或节点配对进行流转。 - 独立的 loopback 浏览器 HTTP API **仅使用共享密钥认证**： - gateway token bearer 认证、`x-openclaw-password`，或者使用 + gateway bearer token 认证、`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）中；避免公开暴露。 +- 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 视为密钥；优先使用环境变量或密钥管理器。 -远程 CDP 建议： +远程 CDP 提示： -- 尽量优先使用加密端点（HTTPS 或 WSS）以及短期 token。 -- 避免将长期有效的 token 直接嵌入配置文件中。 +- 尽可能优先使用加密端点（HTTPS 或 WSS）和短生命周期 token。 +- 避免将长期有效的 token 直接嵌入配置文件。 ## 配置文件（多浏览器） OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是： - **openclaw-managed**：一个专用的基于 Chromium 的浏览器实例，拥有自己的用户数据目录和 CDP 端口 -- **remote**：一个显式的 CDP URL（在其他地方运行的基于 Chromium 的浏览器） -- **existing session**：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome 配置文件 +- **remote**：显式的 CDP URL（运行在其他位置的基于 Chromium 的浏览器） +- **existing session**：通过 Chrome DevTools MCP 自动连接你的现有 Chrome 配置文件 默认值： -- 如果缺少 `openclaw` 配置文件，会自动创建。 +- 如果缺失，会自动创建 `openclaw` 配置文件。 - `user` 配置文件内置用于 Chrome MCP existing-session 连接。 -- 除 `user` 外，existing-session 配置文件需要显式启用；使用 `--driver existing-session` 创建它们。 -- 本地 CDP 端口默认从 **18800–18899** 分配。 -- 删除配置文件时，其本地数据目录会被移至废纸篓。 +- 除 `user` 之外，existing-session 配置文件需要显式启用；使用 `--driver existing-session` 创建它们。 +- 默认情况下，本地 CDP 端口从 **18800–18899** 分配。 +- 删除配置文件会将其本地数据目录移到废纸篓。 所有控制端点都接受 `?profile=`；CLI 使用 `--browser-profile`。 -## 通过 Chrome DevTools MCP 使用 Existing-session +## 通过 Chrome DevTools MCP 使用 existing-session -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 for Developers：将 Chrome DevTools MCP 与你的浏览器会话一起使用](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) 内置配置文件： - `user` -可选：如果你想使用不同的名称、颜色或浏览器数据目录，可以创建你自己的自定义 existing-session 配置文件。 +可选：如果你想使用不同的名称、颜色或浏览器数据目录， +也可以创建你自己的自定义 existing-session 配置文件。 默认行为： - 内置的 `user` 配置文件使用 Chrome MCP 自动连接，其目标是 默认的本地 Google Chrome 配置文件。 -对于 Brave、Edge、Chromium 或非默认的 Chrome 配置文件，请使用 `userDataDir`： +对于 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`： ```json5 { @@ -423,7 +449,7 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器连接到一个正 1. 打开该浏览器用于远程调试的 inspect 页面。 2. 启用远程调试。 -3. 保持浏览器运行，并在 OpenClaw 连接时批准连接提示。 +3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。 常见的 inspect 页面： @@ -431,7 +457,7 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器连接到一个正 - Brave：`brave://inspect/#remote-debugging` - Edge：`edge://inspect/#remote-debugging` -实时连接冒烟测试： +实时附加冒烟测试： ```bash openclaw browser --browser-profile user start @@ -448,41 +474,42 @@ openclaw browser --browser-profile user snapshot --format ai - `tabs` 列出你已经打开的浏览器标签页 - `snapshot` 返回所选实时标签页中的 refs -如果连接不起作用，请检查： +如果附加无法工作，请检查： -- 目标的基于 Chromium 的浏览器版本是否为 `144+` -- 是否已在该浏览器的 inspect 页面启用远程调试 -- 浏览器是否显示了连接同意提示，并且你已接受 +- 目标的基于 Chromium 的浏览器版本为 `144+` +- 已在该浏览器的 inspect 页面中启用远程调试 +- 浏览器显示了附加同意提示，且你已接受 - `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查 - 默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法替你 - 启用浏览器侧的远程调试 + 默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它不能 + 替你启用浏览器端的远程调试 -智能体使用方式： +智能体用法： - 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。 -- 如果你使用的是自定义 existing-session 配置文件，请传入明确的配置文件名称。 -- 只有当用户就在电脑前可以批准连接提示时，才应选择此模式。 +- 如果你使用自定义 existing-session 配置文件，请传入该显式配置文件名。 +- 仅当用户在电脑前可以批准附加 + 提示时才选择此模式。 - Gateway 网关或节点主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect` 说明： -- 与隔离的 `openclaw` 配置文件相比，这一路径风险更高，因为它可以 +- 与隔离的 `openclaw` 配置文件相比，这条路径风险更高，因为它可以 在你已登录的浏览器会话中执行操作。 -- 对于这个驱动，OpenClaw 不会启动浏览器；它只会进行连接。 -- OpenClaw 在这里使用官方 Chrome DevTools MCP 的 `--autoConnect` 流程。如果设置了 - `userDataDir`，它会一并传递过去，以定位该用户数据目录。 -- Existing-session 可以在选定主机上连接，也可以通过已连接的 - 浏览器节点连接。如果 Chrome 位于其他地方且没有浏览器节点已连接，请改用 +- 对于这个驱动，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` 需要使用 snapshot refs（不支持 CSS 选择器）。`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` 需要快照 refs（不支持 CSS 选择器）。`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` 仍然需要受管浏览器路径。 @@ -490,8 +517,10 @@ openclaw browser --browser-profile user snapshot --format ai - **专用用户数据目录**：绝不会触碰你的个人浏览器配置文件。 - **专用端口**：避免使用 `9222`，以防与开发工作流冲突。 -- **可预测的标签页控制**：通过原始 `targetId`、稳定的 `tabId` - 句柄（如 `t1`），或你使用 `open --label` / `tab label` 分配的标签来定位标签页。 +- **可预测的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后是 + 稳定的 `tabId` 句柄（如 `t1`）、可选标签和原始 `targetId`。 + 智能体应复用 `suggestedTargetId`；原始 id 仍保留用于 + 调试和兼容性。 ## 浏览器选择 @@ -503,9 +532,9 @@ openclaw browser --browser-profile user snapshot --format ai 4. Chromium 5. Chrome Canary -你可以通过 `browser.executablePath` 覆盖它。 +你可以用 `browser.executablePath` 覆盖。 -平台行为： +平台： - macOS：检查 `/Applications` 和 `~/Applications`。 - Linux：查找 `google-chrome`、`brave`、`microsoft-edge`、`chromium` 等。 @@ -513,25 +542,25 @@ openclaw browser --browser-profile user snapshot --format ai ## 控制 API（可选） -对于脚本编写和调试，Gateway 网关会暴露一个小型的**仅限 loopback 的 HTTP -控制 API**，以及与之对应的 `openclaw browser` CLI（快照、refs、wait -增强功能、JSON 输出、调试工作流）。完整参考请参见 +用于脚本编写和调试时，Gateway 网关会暴露一个小型的**仅 loopback 的 HTTP +控制 API**，以及与之匹配的 `openclaw browser` CLI（快照、refs、wait +增强功能、JSON 输出、调试工作流）。完整参考请参阅 [浏览器控制 API](/zh-CN/tools/browser-control)。 ## 故障排除 -有关 Linux 特有问题（尤其是 snap Chromium），请参见 +对于 Linux 特有问题（尤其是 snap Chromium），请参阅 [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)。 -有关 WSL2 Gateway 网关 + Windows Chrome 分离主机场景，请参见 +对于 WSL2 Gateway 网关 + Windows Chrome 分离主机设置，请参阅 [WSL2 + Windows + 远程 Chrome CDP 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)。 ### CDP 启动失败与导航 SSRF 阻止 -这是两类不同的故障，它们对应不同的代码路径。 +这两类故障不同，并且分别对应不同的代码路径。 - **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。 -- **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但页面导航目标因策略而被拒绝。 +- **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但页面导航目标被策略拒绝。 常见示例： @@ -539,7 +568,7 @@ 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 阻止： - - `open`、`navigate`、snapshot 或标签页打开流程因浏览器/网络策略错误而失败，而 `start` 和 `tabs` 仍然可用 + - `open`、`navigate`、快照或标签页打开流程因浏览器/网络策略错误而失败，而 `start` 和 `tabs` 仍然可用 使用下面的最小命令序列来区分两者： @@ -551,45 +580,45 @@ 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 健康检查会有意跳过针对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制检查。 -- 导航保护是独立的。`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`。 -## 智能体工具 + 控制如何工作 +## 智能体工具 + 控制工作原理 -智能体会获得**一个工具**用于浏览器自动化： +智能体获得**一个工具**用于浏览器自动化： - `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act -其映射方式如下： +它的映射方式如下： - `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。 -- `browser act` 使用 snapshot 的 `ref` ID 来执行 click/type/drag/select。 -- `browser screenshot` 捕获像素内容（整页或元素）。 +- `browser act` 使用快照中的 `ref` ID 执行点击/输入/拖动/选择。 +- `browser screenshot` 捕获像素（整页或元素）。 - `browser` 接受： - `profile`，用于选择命名浏览器配置文件（openclaw、chrome 或远程 CDP）。 - `target`（`sandbox` | `host` | `node`），用于选择浏览器所在位置。 - 在沙箱隔离会话中，`target: "host"` 需要 `agents.defaults.sandbox.browser.allowHostControl=true`。 - 如果省略 `target`：沙箱隔离会话默认使用 `sandbox`，非沙箱会话默认使用 `host`。 - - 如果已连接支持浏览器的节点，该工具可能会自动路由到该节点，除非你固定指定 `target="host"` 或 `target="node"`。 + - 如果连接了具备浏览器能力的节点，工具可能会自动路由到该节点，除非你固定为 `target="host"` 或 `target="node"`。 -这样可以让智能体保持确定性，并避免脆弱的选择器。 +这样可以让智能体保持可预测，并避免脆弱的选择器。 ## 相关内容 - [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具 - [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的浏览器控制 -- [安全性](/zh-CN/gateway/security) — 浏览器控制的风险与加固措施 +- [安全性](/zh-CN/gateway/security) — 浏览器控制的风险与加固