From ed0e42edfaea9d73620b396edb395537f3f46eb9 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 14 Apr 2026 08:34:23 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/tools/browser.md | 555 ++++++++++++++++++++---------------- 1 file changed, 308 insertions(+), 247 deletions(-) diff --git a/docs/zh-CN/tools/browser.md b/docs/zh-CN/tools/browser.md index 923d4d0e3..476d84061 100644 --- a/docs/zh-CN/tools/browser.md +++ b/docs/zh-CN/tools/browser.md @@ -3,13 +3,13 @@ read_when: - 添加由智能体控制的浏览器自动化 - 调试为什么 openclaw 会干扰你自己的 Chrome - 在 macOS 应用中实现浏览器设置 + 生命周期管理 -summary: 集成浏览器控制服务 + 操作命令 +summary: 集成的浏览器控制服务 + 操作命令 title: 浏览器（由 OpenClaw 管理） x-i18n: - generated_at: "2026-04-10T18:36:58Z" + generated_at: "2026-04-14T08:32:15Z" model: gpt-5.4 provider: openai - source_hash: da6fed36a6f40a50e825f90e5616778954545bd7e52397f7e088b85251ee024f + source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2 source_path: tools/browser.md workflow: 15 --- @@ -18,24 +18,24 @@ x-i18n: OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。 它与你的个人浏览器隔离，并通过 Gateway 网关 内部一个小型本地控制服务进行管理 -（仅限 loopback）。 +（仅 loopback）。 初学者视角： -- 可以把它理解为一个**独立的、仅供智能体使用的浏览器**。 -- `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。 -- 智能体可以在一条安全通道中**打开标签页、读取页面、点击和输入**。 -- 内置的 `user` 配置文件会通过 Chrome MCP 附加到你真实、已登录的 Chrome 会话。 +- 可以把它看作一个**独立的、仅供智能体使用的浏览器**。 +- `openclaw` 配置文件**不会**接触你的个人浏览器配置文件。 +- 智能体可以在一个安全通道中**打开标签页、读取页面、点击和输入**。 +- 内置的 `user` 配置文件会通过 Chrome MCP 附加到你真实的已登录 Chrome 会话。 ## 你将获得什么 -- 一个名为 **openclaw** 的独立浏览器配置文件（默认带橙色强调色）。 +- 一个名为 **openclaw** 的独立浏览器配置文件（默认使用橙色强调色）。 - 可预测的标签页控制（列出/打开/聚焦/关闭）。 -- 智能体操作（点击/输入/拖拽/选择）、快照、截图、PDF。 -- 可选的多配置文件支持（`openclaw`、`work`、`remote`、……）。 +- 智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。 +- 可选的多配置文件支持（`openclaw`、`work`、`remote` 等）。 -这个浏览器**不是**你的日常主力浏览器。它是一个安全、隔离的界面， -用于智能体自动化和验证。 +这个浏览器**不是**你的日常主力浏览器。它是一个安全、隔离的表面，用于 +智能体自动化和验证。 ## 快速开始 @@ -49,13 +49,13 @@ openclaw browser --browser-profile openclaw snapshot 如果你看到“浏览器已禁用”，请在配置中启用它（见下文），然后重启 Gateway 网关。 -如果 `openclaw browser` 完全不存在，或者智能体提示浏览器工具 -不可用，请跳转到[缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 +如果 `openclaw browser` 整个命令都不存在，或者智能体提示浏览器工具 +不可用，请跳转到 [缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 ## 插件控制 -默认的 `browser` 工具现在是一个内置插件，默认启用。 -这意味着你可以在不移除 OpenClaw 其余插件系统的情况下禁用或替换它： +默认的 `browser` 工具现在是一个默认启用的内置插件。 +这意味着你可以禁用或替换它，而无需移除 OpenClaw 的其余插件系统： ```json5 { @@ -69,29 +69,27 @@ Gateway 网关。 } ``` -在安装另一个提供相同 `browser` 工具名称的插件之前，请先禁用该内置插件。 -默认浏览器体验需要同时满足以下两项： +在安装另一个提供相同 `browser` 工具名称的插件之前，请先禁用内置插件。 +默认浏览器体验同时需要： - `plugins.entries.browser.enabled` 未被禁用 - `browser.enabled=true` -如果你只关闭插件，那么内置浏览器 CLI（`openclaw browser`）、 -Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览器控制服务 -都会一起消失。你的 `browser.*` 配置会保持不变，以便替代插件复用。 +如果你只关闭插件，内置的浏览器 CLI（`openclaw browser`）、 +Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览器控制 +服务都会一起消失。你的 `browser.*` 配置会保持不变，以便替换插件复用。 -这个内置浏览器插件现在也负责浏览器运行时实现。 -核心部分现在只保留共享的插件 SDK 辅助工具，以及对旧内部导入路径的兼容性重导出。 -实际效果是，移除或替换浏览器插件包会直接移除浏览器功能集， -而不会留下第二套由核心拥有的运行时实现。 +内置浏览器插件现在也负责浏览器运行时实现。 +核心仅保留共享的插件 SDK 辅助工具，以及对旧内部导入路径的兼容性重新导出。 +在实际效果上，移除或替换浏览器插件包会移除浏览器功能集，而不会留下第二套由核心拥有的运行时实现。 -浏览器配置更改仍然需要重启 Gateway 网关， -这样内置插件才能使用新设置重新注册其浏览器服务。 +浏览器配置更改仍然需要重启 Gateway 网关，这样内置插件才能使用新设置重新注册其浏览器服务。 ## 缺少浏览器命令或工具 -如果升级后 `openclaw browser` 突然变成未知命令， -或者智能体报告浏览器工具缺失，最常见的原因是 -过于严格的 `plugins.allow` 列表中不包含 `browser`。 +如果升级后 `openclaw browser` 突然变成未知命令，或者 +智能体报告缺少浏览器工具，最常见的原因是限制性的 `plugins.allow` +列表中不包含 `browser`。 错误配置示例： @@ -103,7 +101,7 @@ Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览 } ``` -修复方法是将 `browser` 添加到插件允许列表中： +解决方法是在插件允许列表中添加 `browser`： ```json5 { @@ -115,10 +113,10 @@ Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览 重要说明： -- 当设置了 `plugins.allow` 时，仅有 `browser.enabled=true` 本身并不够。 -- 当设置了 `plugins.allow` 时，仅有 `plugins.entries.browser.enabled=true` 本身也不够。 +- 当设置了 `plugins.allow` 时，仅有 `browser.enabled=true` 本身还不够。 +- 当设置了 `plugins.allow` 时，仅有 `plugins.entries.browser.enabled=true` 本身也还不够。 - `tools.alsoAllow: ["browser"]` **不会**加载内置浏览器插件。它只会在插件已加载后调整工具策略。 -- 如果你不需要严格的插件允许列表，删除 `plugins.allow` 也能恢复默认的内置浏览器行为。 +- 如果你不需要限制性的插件允许列表，删除 `plugins.allow` 也可以恢复默认的内置浏览器行为。 典型症状： @@ -128,15 +126,15 @@ Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览 ## 配置文件：`openclaw` 与 `user` -- `openclaw`：受管理、隔离的浏览器（无需扩展）。 -- `user`：内置 Chrome MCP 附加配置文件，用于连接你**真实且已登录的 Chrome** +- `openclaw`：受管理的隔离浏览器（无需扩展）。 +- `user`：内置的 Chrome MCP 附加配置文件，用于连接你**真实已登录的 Chrome** 会话。 对于智能体浏览器工具调用： - 默认：使用隔离的 `openclaw` 浏览器。 -- 当现有登录会话很重要，并且用户就在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。 -- 当你想要指定某种浏览器模式时，`profile` 是显式覆盖项。 +- 当现有登录会话很重要，并且用户在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。 +- 当你想使用特定浏览器模式时，`profile` 是显式覆盖项。 如果你希望默认使用受管理模式，请设置 `browser.defaultProfile: "openclaw"`。 @@ -147,16 +145,16 @@ Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览 ```json5 { browser: { - enabled: true, // default: true + enabled: true, // 默认：true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // 仅在信任私有网络访问时选择启用 + // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override - remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms) - remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms) + // cdpUrl: "http://127.0.0.1:18792", // 旧版单配置文件覆盖 + remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时（毫秒） + remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒） defaultProfile: "openclaw", color: "#FF4500", headless: false, @@ -185,28 +183,28 @@ Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览 说明： -- 浏览器控制服务会绑定到一个 loopback 端口，该端口从 `gateway.port` - 派生而来（默认是 `18791`，即 gateway + 2）。 +- 浏览器控制服务会绑定到一个基于 `gateway.port` + 派生的 loopback 端口（默认：`18791`，即 gateway + 2）。 - 如果你覆盖了 Gateway 网关 端口（`gateway.port` 或 `OPENCLAW_GATEWAY_PORT`）， - 派生出的浏览器端口也会随之偏移，以保持在同一个“端口族”中。 -- 当未设置时，`cdpUrl` 默认指向受管理的本地 CDP 端口。 + 派生的浏览器端口也会一起移动，以保持在同一个“家族”中。 +- 未设置时，`cdpUrl` 默认使用受管理的本地 CDP 端口。 - `remoteCdpTimeoutMs` 适用于远程（非 loopback）CDP 可达性检查。 -- `remoteCdpHandshakeTimeoutMs` 适用于远程 CDP WebSocket 可达性握手检查。 -- 浏览器导航/打开标签页在导航前会进行 SSRF 防护，并会在导航完成后对最终 `http(s)` URL 尽力再次检查。 -- 在严格 SSRF 模式下，远程 CDP 端点发现/探测（`cdpUrl`，包括 `/json/version` 查找）也会被检查。 -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认禁用。仅当你明确可信任私有网络浏览器访问时，才将其设为 `true`。 -- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为兼容性的旧别名受到支持。 -- `attachOnly: true` 表示“绝不启动本地浏览器；仅在浏览器已运行时附加”。 -- `color` 和各配置文件的 `color` 会为浏览器 UI 着色，让你能看出当前激活的是哪个配置文件。 +- `remoteCdpHandshakeTimeoutMs` 适用于远程 CDP WebSocket 可达性检查。 +- 浏览器导航/打开标签页在导航前会进行 SSRF 防护，并在导航后针对最终 `http(s)` URL 进行尽力的再次检查。 +- 在严格 SSRF 模式下，远程 CDP 端点发现/探测（`cdpUrl`，包括 `/json/version` 查询）也会被检查。 +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认禁用。仅在你明确信任私有网络浏览器访问时将其设为 `true`。 +- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为兼容性的旧版别名受支持。 +- `attachOnly: true` 表示“绝不启动本地浏览器；如果它已经运行，则只进行附加。” +- `color` 加上各配置文件的 `color` 会为浏览器 UI 着色，以便你看出当前哪个配置文件处于活动状态。 - 默认配置文件是 `openclaw`（由 OpenClaw 管理的独立浏览器）。使用 `defaultProfile: "user"` 可改为默认使用已登录的用户浏览器。 -- 自动检测顺序：若系统默认浏览器是基于 Chromium 的浏览器则优先使用；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。 -- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl` —— 只有远程 CDP 才需要设置这些项。 -- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。请勿为该驱动设置 `cdpUrl`。 -- 当某个 existing-session 配置文件需要附加到非默认的 Chromium 用户配置文件（如 Brave 或 Edge）时，请设置 `browser.profiles..userDataDir`。 +- 自动检测顺序：若系统默认浏览器是基于 Chromium，则使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。 +- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl` —— 仅在远程 CDP 场景下设置这些值。 +- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。此驱动下请勿设置 `cdpUrl`。 +- 当 existing-session 配置文件需要附加到非默认的 Chromium 用户配置文件（例如 Brave 或 Edge）时，请设置 `browser.profiles..userDataDir`。 ## 使用 Brave（或其他基于 Chromium 的浏览器） -如果你的**系统默认**浏览器是基于 Chromium 的浏览器（Chrome/Brave/Edge 等）， +如果你的**系统默认**浏览器是基于 Chromium 的（Chrome/Brave/Edge 等）， OpenClaw 会自动使用它。设置 `browser.executablePath` 可以覆盖 自动检测： @@ -241,49 +239,49 @@ 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 可以包含身份验证信息： +远程 CDP URL 可以包含认证信息： -- 查询参数令牌（例如 `https://provider.example?token=`） -- HTTP Basic auth（例如 `https://user:pass@provider.example`） +- 查询令牌（例如 `https://provider.example?token=`） +- HTTP Basic 认证（例如 `https://user:pass@provider.example`） OpenClaw 在调用 `/json/*` 端点以及连接 -CDP WebSocket 时会保留这些认证信息。对于令牌，优先使用环境变量或密钥管理器， -而不是将其提交到配置文件中。 +CDP WebSocket 时会保留这些认证信息。与其将令牌提交到配置文件，不如优先使用环境变量或密钥管理器。 ## 节点浏览器代理（默认零配置） -如果你在拥有浏览器的那台机器上运行了一个**节点主机**，OpenClaw 可以 -在无需额外浏览器配置的情况下，自动将浏览器工具调用路由到该节点。 +如果你在拥有浏览器的机器上运行**节点主机**，OpenClaw 可以 +在无需任何额外浏览器配置的情况下，自动将浏览器工具调用路由到该节点。 这是远程 Gateway 网关 的默认路径。 说明： -- 节点主机会通过一个**代理命令**公开它的本地浏览器控制服务器。 -- 配置文件来自节点自身的 `browser.profiles` 配置（与本地相同）。 -- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空即可保持旧版/默认行为：所有已配置的配置文件都可以通过代理访问，包括配置文件创建/删除路由。 -- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有允许列表中的配置文件可以成为目标，并且持久化配置文件的创建/删除路由会在代理界面上被阻止。 -- 如果你不想启用它，可以禁用： +- 节点主机会通过**代理命令**公开其本地浏览器控制服务器。 +- 配置文件来自节点自己的 `browser.profiles` 配置（与本地相同）。 +- `nodeHost.browserProxy.allowProfiles` 是可选项。将其留空即可使用旧版/默认行为：所有已配置的配置文件都可通过代理访问，包括配置文件创建/删除路由。 +- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有允许列表中的配置文件可以作为目标，而且持久化配置文件的创建/删除路由会在代理表面上被阻止。 +- 如果你不想使用它，可以禁用： - 在节点上：`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。 示例： @@ -307,28 +305,28 @@ CDP 连接 URL。OpenClaw 两种形式都支持，但对于远程浏览器配置 说明： - 将 `` 替换为你真实的 Browserless 令牌。 -- 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。 +- 选择与你的 Browserless 账户匹配的区域端点（见其文档）。 - 如果 Browserless 提供给你的是 HTTPS 基础 URL，你可以将其转换为 `wss://` 以建立直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw - 去发现 `/json/version`。 + 自动发现 `/json/version`。 ## 直接 WebSocket CDP 提供商 -某些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是 -标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 两种方式都支持： +一些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是 +标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 同时支持这两种： -- **HTTP(S) 端点** — OpenClaw 会调用 `/json/version` 来发现 +- **HTTP(S) 端点** —— OpenClaw 调用 `/json/version` 发现 WebSocket 调试器 URL，然后再连接。 -- **WebSocket 端点**（`ws://` / `wss://`）— OpenClaw 直接连接， - 跳过 `/json/version`。这适用于 +- **WebSocket 端点**（`ws://` / `wss://`）—— OpenClaw 直接连接， + 跳过 `/json/version`。这适用于像 [Browserless](https://browserless.io)、 - [Browserbase](https://www.browserbase.com) 或任何直接提供 - WebSocket URL 的服务商。 + [Browserbase](https://www.browserbase.com) 这样的服务，或任何直接提供 + WebSocket URL 的提供商。 ### Browserbase -[Browserbase](https://www.browserbase.com) 是一个用于运行无头浏览器的云平台， -内置 CAPTCHA 求解、隐身模式和住宅代理。 +[Browserbase](https://www.browserbase.com) 是一个云平台，用于运行 +无头浏览器，并内置 CAPTCHA 解决、隐身模式和住宅代理。 ```json5 { @@ -349,61 +347,61 @@ CDP 连接 URL。OpenClaw 两种形式都支持，但对于远程浏览器配置 说明： -- 前往 [Sign up](https://www.browserbase.com/sign-up) 注册，并从 [Overview dashboard](https://www.browserbase.com/overview) 复制你的 **API Key**。 +- 前往 [注册](https://www.browserbase.com/sign-up)，并从 [Overview 仪表板](https://www.browserbase.com/overview) 复制你的 **API Key**。 - 将 `` 替换为你真实的 Browserbase API 密钥。 - 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 auth、`x-openclaw-password`，或使用 - 已配置 gateway 密码的 HTTP Basic auth。 + gateway token Bearer 认证、`x-openclaw-password`，或使用 + 已配置 gateway 密码的 HTTP Basic 认证。 - Tailscale Serve 身份标头和 `gateway.auth.mode: "trusted-proxy"` - **不能**用于认证这个独立的 loopback 浏览器 API。 -- 如果启用了浏览器控制，但未配置共享密钥认证，OpenClaw + **不会**为这个独立的 loopback 浏览器 API 提供身份验证。 +- 如果启用了浏览器控制但未配置共享密钥认证，OpenClaw 会在启动时自动生成 `gateway.auth.token` 并将其持久化到配置中。 - 当 `gateway.auth.mode` 已经是 - `password`、`none` 或 `trusted-proxy` 时，OpenClaw **不会**自动生成该令牌。 + `password`、`none` 或 `trusted-proxy` 时，OpenClaw **不会**自动生成该 token。 - 请将 Gateway 网关 和任何节点主机保持在私有网络中（Tailscale）；避免公开暴露。 -- 将远程 CDP URL/令牌视为密钥；优先使用环境变量或密钥管理器。 +- 将远程 CDP URL/token 视为机密；优先使用环境变量或密钥管理器。 远程 CDP 提示： -- 尽可能优先使用加密端点（HTTPS 或 WSS）和短期令牌。 -- 避免将长期令牌直接写入配置文件。 +- 尽量优先使用加密端点（HTTPS 或 WSS）以及短期 token。 +- 避免将长期 token 直接嵌入配置文件。 ## 配置文件（多浏览器） OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是： -- **由 openclaw 管理**：一个专用的、基于 Chromium 的浏览器实例，拥有自己的用户数据目录和 CDP 端口 -- **远程**：一个显式的 CDP URL（基于 Chromium 的浏览器在其他地方运行） -- **现有会话**：通过 Chrome DevTools MCP 自动连接你现有的 Chrome 配置文件 +- **由 openclaw 管理**：一个专用的基于 Chromium 的浏览器实例，拥有独立的用户数据目录 + CDP 端口 +- **远程**：显式的 CDP URL（运行在其他位置的基于 Chromium 的浏览器） +- **现有会话**：通过 Chrome DevTools MCP 自动连接到你当前已有的 Chrome 配置文件 默认值： -- 如果缺少 `openclaw` 配置文件，会自动创建它。 -- `user` 配置文件是内置的，用于通过 Chrome MCP 附加现有会话。 -- 除 `user` 之外，existing-session 配置文件需要显式启用；请使用 `--driver existing-session` 创建。 -- 本地 CDP 端口默认从 **18800–18899** 范围分配。 -- 删除配置文件时，其本地数据目录会被移到废纸篓。 +- 如果缺失，会自动创建 `openclaw` 配置文件。 +- `user` 配置文件是内置的，用于通过 Chrome MCP 附加到现有会话。 +- 除 `user` 外，现有会话配置文件需要显式启用；请使用 `--driver existing-session` 创建它们。 +- 本地 CDP 端口默认从 **18800–18899** 分配。 +- 删除配置文件会将其本地数据目录移到废纸篓。 所有控制端点都接受 `?profile=`；CLI 使用 `--browser-profile`。 -## 通过 Chrome DevTools MCP 连接现有会话 +## 通过 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) @@ -412,15 +410,14 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到一个正 - `user` -可选：如果你想使用不同的名称、颜色或浏览器数据目录，可以创建你自己的 -自定义 existing-session 配置文件。 +可选：如果你想使用不同的名称、颜色或浏览器数据目录，也可以创建你自己的自定义现有会话配置文件。 默认行为： -- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，它会连接到 - 默认的本地 Google Chrome 配置文件。 +- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，目标是 + 默认本地 Google Chrome 配置文件。 -对于 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`： +对于 Brave、Edge、Chromium 或非默认的 Chrome 配置文件，请使用 `userDataDir`： ```json5 { @@ -437,13 +434,13 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到一个正 } ``` -然后在对应的浏览器中： +然后在对应浏览器中： -1. 打开该浏览器用于远程调试的 inspect 页面。 +1. 打开该浏览器用于远程调试的检查页面。 2. 启用远程调试。 3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。 -常见的 inspect 页面： +常见检查页面： - Chrome：`chrome://inspect/#remote-debugging` - Brave：`brave://inspect/#remote-debugging` @@ -458,44 +455,45 @@ 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` 返回所选实时标签页中的 refs +- `snapshot` 返回所选实时标签页的 refs -如果附加不起作用，请检查： +如果附加不成功，请检查： -- 目标的基于 Chromium 的浏览器版本为 `144+` -- 已在该浏览器的 inspect 页面中启用远程调试 -- 浏览器已经显示附加同意提示，并且你已接受 +- 目标的基于 Chromium 的浏览器版本是否为 `144+` +- 是否已在该浏览器的检查页面中启用远程调试 +- 浏览器是否显示了附加同意提示，并且你已接受 - `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查 - 默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法 - 替你启用浏览器侧的远程调试 + 默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法替你启用浏览器端远程调试 智能体使用： -- 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。 -- 如果你使用自定义 existing-session 配置文件，请传入那个显式的配置文件名。 +- 当你需要用户已登录浏览器状态时，使用 `profile="user"`。 +- 如果你使用自定义现有会话配置文件，请传入该显式配置文件名称。 - 只有当用户就在电脑前可以批准附加提示时，才选择此模式。 - Gateway 网关 或节点主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect` 说明： - 与隔离的 `openclaw` 配置文件相比，这条路径风险更高，因为它可以 - 在你的已登录浏览器会话中执行操作。 -- 对于这个驱动，OpenClaw 不会启动浏览器；它只会附加到现有会话。 -- OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果 - 设置了 `userDataDir`，OpenClaw 会将其传递下去，以定位那个显式的 + 在你已登录的浏览器会话中执行操作。 +- 对于这个驱动，OpenClaw 不会启动浏览器；它只会附加到一个 + 现有会话。 +- OpenClaw 在这里使用官方 Chrome DevTools MCP 的 `--autoConnect` 流程。如果 + 设置了 `userDataDir`，OpenClaw 会将其一并传递，以显式定位该 Chromium 用户数据目录。 -- existing-session 截图支持页面截图，以及来自快照的 `--ref` 元素 +- 现有会话截图支持整页截图以及来自快照的 `--ref` 元素 截图，但不支持 CSS `--element` 选择器。 -- existing-session 页面截图无需通过 Playwright，即可通过 Chrome MCP 工作。 - 基于 ref 的元素截图（`--ref`）在那里也可用，但 `--full-page` +- 现有会话页面截图无需 Playwright 即可通过 Chrome MCP 工作。 + 基于 ref 的元素截图（`--ref`）在该模式下也可用，但 `--full-page` 不能与 `--ref` 或 `--element` 组合使用。 -- 与受管浏览器路径相比，existing-session 操作仍然更受限制： +- 与受管理浏览器 + 路径相比，现有会话操作仍然更受限制： - `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要 使用快照 refs，而不是 CSS 选择器 - `click` 仅支持左键（不支持按钮覆盖或修饰键） @@ -504,25 +502,25 @@ openclaw browser --browser-profile user snapshot --format ai - `hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不 支持每次调用的超时覆盖 - `select` 当前仅支持单个值 -- existing-session `wait --url` 与其他浏览器驱动一样，支持精确、子串和 glob 模式。 - 目前还不支持 `wait --load networkidle`。 -- existing-session 上传钩子要求提供 `ref` 或 `inputRef`，每次只支持一个文件， - 并且不支持 CSS `element` 定位。 -- existing-session 对话框钩子不支持超时覆盖。 -- 某些功能仍然需要受管浏览器路径，包括批量操作、 - PDF 导出、下载拦截和 `responsebody`。 -- existing-session 是主机本地的。如果 Chrome 位于另一台机器上，或位于 +- 现有会话 `wait --url` 与其他浏览器驱动一样，支持精确、子串和 glob 模式。 + 但尚不支持 `wait --load networkidle`。 +- 现有会话上传钩子需要 `ref` 或 `inputRef`，一次只支持一个文件， + 且不支持 CSS `element` 定位。 +- 现有会话对话框钩子不支持超时覆盖。 +- 某些功能仍然需要受管理浏览器路径，包括批量 + 操作、PDF 导出、下载拦截以及 `responsebody`。 +- 现有会话是主机本地的。如果 Chrome 位于另一台机器上，或者在 不同的网络命名空间中，请改用远程 CDP 或节点主机。 ## 隔离保证 -- **专用用户数据目录**：绝不会触碰你的个人浏览器配置文件。 -- **专用端口**：避免使用 `9222`，以防与开发工作流冲突。 -- **可预测的标签页控制**：通过 `targetId` 定位标签页，而不是“最后一个标签页”。 +- **专用用户数据目录**：绝不会接触你的个人浏览器配置文件。 +- **专用端口**：避开 `9222`，防止与开发工作流发生冲突。 +- **确定性的标签页控制**：通过 `targetId` 选定标签页，而不是“最后一个标签页”。 ## 浏览器选择 -在本地启动时，OpenClaw 会按以下顺序选择第一个可用的浏览器： +在本地启动时，OpenClaw 会选择第一个可用的浏览器： 1. Chrome 2. Brave @@ -530,7 +528,7 @@ openclaw browser --browser-profile user snapshot --format ai 4. Chromium 5. Chrome Canary -你可以通过 `browser.executablePath` 覆盖它。 +你可以通过 `browser.executablePath` 覆盖此行为。 平台： @@ -540,7 +538,7 @@ openclaw browser --browser-profile user snapshot --format ai ## 控制 API（可选） -仅用于本地集成时，Gateway 网关 会暴露一个小型的 loopback HTTP API： +仅用于本地集成时，Gateway 网关 会暴露一个小型 loopback HTTP API： - 状态/启动/停止：`GET /`、`POST /start`、`POST /stop` - 标签页：`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId` @@ -557,37 +555,38 @@ openclaw browser --browser-profile user snapshot --format ai 所有端点都接受 `?profile=`。 -如果配置了共享密钥 gateway 认证，浏览器 HTTP 路由也需要认证： +如果配置了共享密钥 gateway 身份验证，浏览器 HTTP 路由也需要身份验证： - `Authorization: Bearer ` -- `x-openclaw-password: `，或使用该密码的 HTTP Basic auth +- `x-openclaw-password: ` 或使用该密码的 HTTP Basic 身份验证 说明： - 这个独立的 loopback 浏览器 API **不会**使用 trusted-proxy 或 Tailscale Serve 身份标头。 - 如果 `gateway.auth.mode` 是 `none` 或 `trusted-proxy`，这些 loopback 浏览器 - 路由不会继承那些带身份信息的模式；请将它们保持为仅限 loopback。 + 路由不会继承这些携带身份的模式；请将它们保持为仅限 loopback。 -### `/act` 错误契约 +### `/act` 错误约定 -`POST /act` 对路由级验证和策略失败使用结构化错误响应： +`POST /act` 对路由级验证和 +策略失败使用结构化错误响应： ```json { "error": "", "code": "ACT_*" } ``` -当前的 `code` 值： +当前 `code` 值： - `ACT_KIND_REQUIRED`（HTTP 400）：缺少 `kind` 或其值无法识别。 -- `ACT_INVALID_REQUEST`（HTTP 400）：操作负载在规范化或验证时失败。 -- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）：在不支持的操作类型中使用了 `selector`。 -- `ACT_EVALUATE_DISABLED`（HTTP 403）：配置中禁用了 `evaluate`（或 `wait --fn`）。 +- `ACT_INVALID_REQUEST`（HTTP 400）：操作负载未通过规范化或验证。 +- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）：在不受支持的操作类型中使用了 `selector`。 +- `ACT_EVALUATE_DISABLED`（HTTP 403）：配置中已禁用 `evaluate`（或 `wait --fn`）。 - `ACT_TARGET_ID_MISMATCH`（HTTP 403）：顶层或批量 `targetId` 与请求目标冲突。 -- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：existing-session 配置文件不支持该操作。 +- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：现有会话配置文件不支持该操作。 -其他运行时失败仍可能返回 `{ "error": "" }`，而没有 -`code` 字段。 +其他运行时失败仍可能返回不带 +`code` 字段的 `{ "error": "" }`。 ### Playwright 要求 @@ -595,12 +594,13 @@ openclaw browser --browser-profile user snapshot --format ai PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回 明确的 501 错误。 -未安装 Playwright 时仍可使用的功能： +在没有 Playwright 的情况下，仍然可用的功能： - ARIA 快照 -- 当每个标签页的 CDP WebSocket 可用时，受管 `openclaw` 浏览器的页面截图 -- `existing-session` / Chrome MCP 配置文件的页面截图 -- 来自快照输出的 `existing-session` 基于 `--ref` 的截图 +- 当每个标签页的 CDP + WebSocket 可用时，为受管理的 `openclaw` 浏览器截取页面截图 +- 为 `existing-session` / Chrome MCP 配置文件截取页面截图 +- 基于快照输出的 `existing-session` ref 截图（`--ref`） 仍然需要 Playwright 的功能： @@ -615,11 +615,12 @@ not supported for element screenshots`。 如果你看到 `Playwright is not available in this gateway build`，请安装完整的 Playwright 包（不是 `playwright-core`）并重启 gateway，或者重新安装 -带浏览器支持的 OpenClaw。 +带有浏览器支持的 OpenClaw。 #### Docker Playwright 安装 -如果你的 Gateway 网关 运行在 Docker 中，请避免使用 `npx playwright`（会与 npm override 冲突）。 +如果你的 Gateway 网关 在 Docker 中运行，请避免使用 `npx playwright` +（会与 npm override 冲突）。 请改用内置 CLI： ```bash @@ -627,9 +628,9 @@ docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` -要持久化浏览器下载内容，请设置 `PLAYWRIGHT_BROWSERS_PATH`（例如 -`/home/node/.cache/ms-playwright`），并确保 `/home/node` 通过 -`OPENCLAW_HOME_VOLUME` 或 bind mount 持久化。参见 [Docker](/zh-CN/install/docker)。 +要持久化浏览器下载，请设置 `PLAYWRIGHT_BROWSERS_PATH`（例如 +`/home/node/.cache/ms-playwright`），并确保通过 +`OPENCLAW_HOME_VOLUME` 或 bind mount 持久化 `/home/node`。参见 [Docker](/zh-CN/install/docker)。 ## 工作原理（内部） @@ -637,7 +638,8 @@ docker compose run --rm openclaw-cli \ - 一个小型**控制服务器**接收 HTTP 请求。 - 它通过 **CDP** 连接到基于 Chromium 的浏览器（Chrome/Brave/Edge/Chromium）。 -- 对于高级操作（点击/输入/快照/PDF），它在 CDP 之上使用 **Playwright**。 +- 对于高级操作（点击/输入/快照/PDF），它会在 + CDP 之上使用 **Playwright**。 - 当缺少 Playwright 时，只有非 Playwright 操作可用。 这种设计让智能体始终使用稳定、可预测的接口，同时允许 @@ -645,8 +647,8 @@ docker compose run --rm openclaw-cli \ ## CLI 快速参考 -所有命令都接受 `--browser-profile ` 以指定目标配置文件。 -所有命令也都接受 `--json` 以获得机器可读输出（稳定负载）。 +所有命令都接受 `--browser-profile ` 以定位特定配置文件。 +所有命令也都接受 `--json` 以输出机器可读格式（稳定负载）。 基础命令： @@ -679,9 +681,10 @@ docker compose run --rm openclaw-cli \ 生命周期说明： -- 对于 attach-only 和远程 CDP 配置文件，测试完成后 `openclaw browser stop` - 仍然是正确的清理命令。它会关闭当前控制会话并清除临时仿真覆盖， - 而不是杀掉底层浏览器。 +- 对于仅附加和远程 CDP 配置文件，测试结束后 `openclaw browser stop` 仍然是 + 正确的清理命令。它会关闭当前活动的控制会话，并 + 清除临时仿真覆盖，而不是杀掉底层 + 浏览器。 - `openclaw browser errors --clear` - `openclaw browser requests --filter api --clear` - `openclaw browser pdf` @@ -732,59 +735,60 @@ docker compose run --rm openclaw-cli \ 说明： -- `upload` 和 `dialog` 是**预置**调用；请在触发文件选择器/对话框的点击或按键操作之前运行它们。 -- 下载和 trace 输出路径被限制在 OpenClaw 临时根目录下： +- `upload` 和 `dialog` 是**预置**调用；请在触发文件选择器/对话框的点击或按键 + 之前运行它们。 +- 下载和 trace 输出路径限制在 OpenClaw 临时根目录下： - traces：`/tmp/openclaw`（回退：`${os.tmpdir()}/openclaw`） - downloads：`/tmp/openclaw/downloads`（回退：`${os.tmpdir()}/openclaw/downloads`） -- 上传路径被限制在 OpenClaw 临时上传根目录下： +- 上传路径限制在 OpenClaw 临时 uploads 根目录下： - uploads：`/tmp/openclaw/uploads`（回退：`${os.tmpdir()}/openclaw/uploads`） -- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入框。 +- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入。 - `snapshot`： - - `--format ai`（安装了 Playwright 时的默认值）：返回带数字 refs 的 AI 快照（`aria-ref=""`）。 - - `--format aria`：返回无障碍树（没有 refs；仅用于检查）。 + - `--format ai`（安装 Playwright 时的默认值）：返回带有数字 refs 的 AI 快照（`aria-ref=""`）。 + - `--format aria`：返回无障碍树（无 refs；仅供检查）。 - `--efficient`（或 `--mode efficient`）：紧凑的 role 快照预设（interactive + compact + depth + 更低的 maxChars）。 - - 配置默认值（仅工具/CLI）：设置 `browser.snapshotDefaults.mode: "efficient"`，即可在调用方未传入模式时使用高效快照（参见 [Gateway 配置](/zh-CN/gateway/configuration-reference#browser)）。 - - Role 快照选项（`--interactive`、`--compact`、`--depth`、`--selector`）会强制使用基于 role 的快照，并生成如 `ref=e12` 这样的 refs。 - - `--frame "