chore(i18n): refresh zh-CN translations

docs/zh-CN/cli/browser.md

@@ -1,22 +1,22 @@
 ---
 read_when:
     - 你使用 `openclaw browser`，并且想要查看常见任务的示例
-    - 你想通过节点主机控制在另一台机器上运行的浏览器
+    - 你想通过一个节点主机来控制另一台机器上运行的浏览器
     - 你想通过 Chrome MCP 连接到你本地已登录的 Chrome
 summary: '`openclaw browser` 的 CLI 参考（生命周期、配置文件、标签页、操作、状态和调试）'
 title: 浏览器
 x-i18n:
-    generated_at: "2026-04-25T00:40:14Z"
+    generated_at: "2026-04-25T06:35:01Z"
     model: gpt-5.4
     provider: openai
-    source_hash: d9da317f18128075203febae3b4c0e416d3a797cb92d473d35488098814a005d
+    source_hash: 03994a04839214fca41a8b53f21ddfb71560455039ff2e14b309b887eb86f5f9
     source_path: cli/browser.md
     workflow: 15
 ---
 
 # `openclaw browser`
 
-管理 OpenClaw 的浏览器控制界面，并运行浏览器操作（生命周期、配置文件、标签页、快照、截图、导航、输入、状态模拟和调试）。
+管理 OpenClaw 的浏览器控制界面并运行浏览器操作（生命周期、配置文件、标签页、快照、截图、导航、输入、状态模拟和调试）。
 
 相关内容：
 
@@ -24,12 +24,12 @@ x-i18n:
 
 ## 常用标志
 
-- `--url <gatewayWsUrl>`：Gateway 网关 WebSocket URL（默认来自配置）。
+- `--url <gatewayWsUrl>`：Gateway 网关 WebSocket URL（默认使用配置中的值）。
 - `--token <token>`：Gateway 网关令牌（如果需要）。
-- `--timeout <ms>`：请求超时（毫秒）。
+- `--timeout <ms>`：请求超时时间（毫秒）。
 - `--expect-final`：等待最终的 Gateway 网关响应。
-- `--browser-profile <name>`：选择浏览器配置文件（默认来自配置）。
-- `--json`：机器可读输出（在支持的情况下）。
+- `--browser-profile <name>`：选择一个浏览器配置文件（默认使用配置中的默认值）。
+- `--json`：机器可读输出（在支持时）。
 
 ## 快速开始（本地）
 
@@ -44,9 +44,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 doctor
@@ -55,7 +55,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)
+详细指南：[浏览器故障排除](/zh-CN/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block)
 
 ## 生命周期
 
@@ -69,10 +69,10 @@ 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`。
 
@@ -86,15 +86,15 @@ 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)
 
 ## 配置文件
 
-配置文件是具名的浏览器路由配置。实际使用中：
+配置文件是命名的浏览器路由配置。实际使用中：
 
-- `openclaw`：启动或连接到一个专用的、由 OpenClaw 管理的 Chrome 实例（隔离的用户数据目录）。
+- `openclaw`：启动或连接到专用的 OpenClaw 托管 Chrome 实例（隔离的用户数据目录）。
 - `user`：通过 Chrome DevTools MCP 控制你现有的已登录 Chrome 会话。
 - 自定义 CDP 配置文件：指向本地或远程 CDP 端点。
 
@@ -106,7 +106,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 +125,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、原始 target ID，以及唯一的 target-id 前缀都可接受。
+`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId`（如 `t1`）、可选标签以及原始 `targetId`。智能体应将 `suggestedTargetId` 传回 `focus`、`close`、快照和操作中使用。你可以使用 `open --label`、`tab new --label` 或 `tab label` 分配标签；标签、标签页 id、原始 target id 以及唯一的 target-id 前缀都可被接受。
 
 ## 快照 / 截图 / 操作
 
@@ -148,15 +148,16 @@ openclaw browser screenshot --labels
 说明：
 
 - `--full-page` 仅用于页面截图；不能与 `--ref` 或 `--element` 组合使用。
-- `existing-session` / `user` 配置文件支持页面截图和基于快照输出的 `--ref` 截图，但不支持 CSS `--element` 截图。
+- `existing-session` / `user` 配置文件支持页面截图和基于快照输出中 `--ref` 的截图，但不支持基于 CSS `--element` 的截图。
 - `--labels` 会在截图上叠加当前快照引用标签。
-- `snapshot --urls` 会将发现的链接目标追加到 AI 快照中，以便智能体选择直接导航目标，而不是仅凭链接文本猜测。
+- `snapshot --urls` 会将发现的链接目标追加到 AI 快照中，这样智能体可以选择直接的导航目标，而不是仅根据链接文本猜测。
 
 导航 / 点击 / 输入（基于 ref 的 UI 自动化）：
 
 ```bash
 openclaw browser navigate https://example.com
 openclaw browser click <ref>
+openclaw browser click-coords 120 340
 openclaw browser type <ref> "hello"
 openclaw browser press Enter
 openclaw browser hover <ref>
@@ -168,7 +169,7 @@ openclaw browser wait --text "Done"
 openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>
 ```
 
-文件 + 对话框辅助：
+文件 + 对话框辅助功能：
 
 ```bash
 openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
@@ -220,7 +221,7 @@ openclaw browser trace stop --out trace.zip
 
 ## 通过 MCP 使用现有 Chrome
 
-使用内置的 `user` 配置文件，或者创建你自己的 `existing-session` 配置文件：
+使用内置的 `user` 配置文件，或创建你自己的 `existing-session` 配置文件：
 
 ```bash
 openclaw browser --browser-profile user tabs
@@ -229,27 +230,27 @@ 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 的限制：
 
-- 基于快照的操作使用 ref，不使用 CSS 选择器
-- `click` 仅支持左键单击
+- 基于快照的操作使用 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 配置文件
+- `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)
 

docs/zh-CN/tools/browser-control.md

@@ -1,32 +1,32 @@
 ---
 read_when:
-    - 通过本地控制 API 为智能体浏览器编写脚本或进行调试
+    - 通过本地控制 API 对智能体浏览器进行脚本操作或调试
     - 正在查找 `openclaw browser` CLI 参考
-    - 使用快照和 refs 添加自定义浏览器自动化
+    - 添加带有快照和 refs 的自定义浏览器自动化
 summary: OpenClaw 浏览器控制 API、CLI 参考和脚本操作
 title: 浏览器控制 API
 x-i18n:
-    generated_at: "2026-04-25T00:43:59Z"
+    generated_at: "2026-04-25T06:34:57Z"
     model: gpt-5.4
     provider: openai
-    source_hash: ec7b6e83b231fefc9c4a63fabde9bdaeb2ea2b2a8ab64943e179a7af5ed4badc
+    source_hash: e9d18da48dfb6cf127fabbaa056411162640ab62e15690617138af3c23ee19c9
     source_path: tools/browser-control.md
     workflow: 15
 ---
 
-有关设置、配置和故障排除，请参见 [Browser](/zh-CN/tools/browser)。
+有关设置、配置和故障排除，请参阅 [Browser](/zh-CN/tools/browser)。
 本页是本地控制 HTTP API、`openclaw browser`
-CLI 以及脚本模式（快照、refs、等待、调试流程）的参考文档。
+CLI，以及脚本模式（快照、refs、等待、调试流程）的参考文档。
 
 ## 控制 API（可选）
 
-仅用于本地集成时，Gateway 网关会公开一个小型 loopback HTTP API：
+仅用于本地集成时，Gateway 网关会暴露一个小型的 loopback HTTP API：
 
-- 状态 / 启动 / 停止：`GET /`、`POST /start`、`POST /stop`
+- 状态/启动/停止：`GET /`、`POST /start`、`POST /stop`
 - 标签页：`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId`
-- 快照 / 截图：`GET /snapshot`、`POST /screenshot`
+- 快照/截图：`GET /snapshot`、`POST /screenshot`
 - 操作：`POST /navigate`、`POST /act`
-- Hooks：`POST /hooks/file-chooser`、`POST /hooks/dialog`
+- 钩子：`POST /hooks/file-chooser`、`POST /hooks/dialog`
 - 下载：`POST /download`、`POST /wait/download`
 - 调试：`GET /console`、`POST /pdf`
 - 调试：`GET /errors`、`GET /requests`、`POST /trace/start`、`POST /trace/stop`、`POST /highlight`
@@ -37,17 +37,17 @@ CLI 以及脚本模式（快照、refs、等待、调试流程）的参考文档
 
 所有端点都接受 `?profile=<name>`。
 
-如果已配置共享密钥 Gateway 网关鉴权，则浏览器 HTTP 路由也需要鉴权：
+如果配置了共享密钥 Gateway 网关认证，浏览器 HTTP 路由也需要认证：
 
 - `Authorization: Bearer <gateway token>`
-- `x-openclaw-password: <gateway password>`，或使用该密码的 HTTP Basic 鉴权
+- `x-openclaw-password: <gateway password>` 或使用该密码的 HTTP Basic auth
 
-说明：
+注意：
 
-- 这个独立的 loopback 浏览器 API **不会**消费 trusted-proxy 或
+- 这个独立的 loopback 浏览器 API **不会** 使用受信任代理或
   Tailscale Serve 身份标头。
 - 如果 `gateway.auth.mode` 是 `none` 或 `trusted-proxy`，这些 loopback 浏览器
-  路由不会继承这些携带身份信息的模式；请将它们保持为仅 loopback。
+  路由不会继承这些携带身份信息的模式；请将它们仅保留在 loopback 中使用。
 
 ### `/act` 错误契约
 
@@ -58,51 +58,51 @@ CLI 以及脚本模式（快照、refs、等待、调试流程）的参考文档
 { "error": "<message>", "code": "ACT_*" }
 ```
 
-当前 `code` 值：
+当前的 `code` 值：
 
-- `ACT_KIND_REQUIRED`（HTTP 400）：缺少 `kind`，或其无法识别。
+- `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_TARGET_ID_MISMATCH`（HTTP 403）：顶层或批处理的 `targetId` 与请求目标冲突。
-- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：现有会话 profile 不支持该操作。
+- `ACT_EVALUATE_DISABLED`（HTTP 403）：配置中禁用了 `evaluate`（或 `wait --fn`）。
+- `ACT_TARGET_ID_MISMATCH`（HTTP 403）：顶层或批量 `targetId` 与请求目标冲突。
+- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：现有会话配置文件不支持此操作。
 
-其他运行时失败仍可能返回 `{ "error": "<message>" }`，而不包含
+其他运行时故障仍可能返回 `{ "error": "<message>" }`，而没有
 `code` 字段。
 
 ### Playwright 要求
 
-某些功能（navigate / act / AI 快照 / 角色快照、元素截图、
+某些功能（navigate/act/AI snapshot/role snapshot、元素截图、
 PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回
 明确的 501 错误。
 
-未安装 Playwright 时仍可使用的功能：
+在没有 Playwright 时仍可使用的功能：
 
 - ARIA 快照
-- 当存在每标签页 CDP
-  WebSocket 时，对受管 `openclaw` 浏览器进行页面截图
-- 对 `existing-session` / Chrome MCP profiles 进行页面截图
-- 从快照输出中基于 ref 的 `existing-session` 截图（`--ref`）
+- 当托管的 `openclaw` 浏览器具有每标签页 CDP
+  WebSocket 可用时的页面截图
+- `existing-session` / Chrome MCP 配置文件的页面截图
+- 从快照输出生成的 `existing-session` 基于 ref 的截图（`--ref`）
 
 仍然需要 Playwright 的功能：
 
 - `navigate`
 - `act`
-- AI 快照 / 角色快照
+- AI 快照 / role 快照
 - 基于 CSS 选择器的元素截图（`--element`）
 - 完整浏览器 PDF 导出
 
-元素截图也会拒绝 `--full-page`；路由会返回 `fullPage is
+元素截图也会拒绝 `--full-page`；该路由会返回 `fullPage is
 not supported for element screenshots`。
 
 如果你看到 `Playwright is not available in this gateway build`，请修复
-内置浏览器插件运行时依赖，以确保已安装 `playwright-core`，
+内置浏览器插件运行时依赖，确保已安装 `playwright-core`，
 然后重启 Gateway 网关。对于打包安装，请运行 `openclaw doctor --fix`。
-对于 Docker，还需要按如下所示安装 Chromium 浏览器二进制文件。
+对于 Docker，还需按下文所示安装 Chromium 浏览器二进制文件。
 
 #### Docker Playwright 安装
 
-如果你的 Gateway 网关在 Docker 中运行，请避免使用 `npx playwright`（npm 覆盖冲突）。
+如果你的 Gateway 网关运行在 Docker 中，请避免使用 `npx playwright`（会有 npm 覆盖冲突）。
 请改用内置 CLI：
 
 ```bash
@@ -110,26 +110,26 @@ 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)。
 
 ## 工作原理（内部）
 
-一个小型 loopback 控制服务器接收 HTTP 请求，并通过 CDP 连接到基于 Chromium 的浏览器。高级操作（点击 / 输入 / 快照 / PDF）通过 CDP 之上的 Playwright 执行；当缺少 Playwright 时，只能使用非 Playwright 操作。智能体看到的是一个稳定接口，而底层的本地 / 远程浏览器和 profiles 可以自由切换。
+一个小型 loopback 控制服务器接受 HTTP 请求，并通过 CDP 连接到基于 Chromium 的浏览器。高级操作（点击/输入/快照/PDF）通过 CDP 之上的 Playwright 完成；当缺少 Playwright 时，仅提供非 Playwright 操作。智能体看到的是一个稳定接口，而底层的本地/远程浏览器和配置文件可以自由切换。
 
 ## CLI 快速参考
 
-所有命令都接受 `--browser-profile <name>` 以指定某个 profile，接受 `--json` 以输出机器可读结果。
+所有命令都接受 `--browser-profile <name>` 以定位到特定配置文件，并接受 `--json` 以输出机器可读格式。
 
 <AccordionGroup>
 
-<Accordion title="基础：状态、标签页、打开 / 聚焦 / 关闭">
+<Accordion title="基础：状态、标签页、打开/聚焦/关闭">
 
 ```bash
 openclaw browser status
 openclaw browser start
-openclaw browser stop            # 对仅附加 / 远程 CDP 也会清除仿真
+openclaw browser stop            # 也会清除仅附加/远程 CDP 上的模拟状态
 openclaw browser tabs
 openclaw browser tab             # 当前标签页的快捷方式
 openclaw browser tab new
@@ -147,7 +147,7 @@ openclaw browser close abcd1234
 ```bash
 openclaw browser screenshot
 openclaw browser screenshot --full-page
-openclaw browser screenshot --ref 12        # 或 --ref e12，用于角色 refs
+openclaw browser screenshot --ref 12        # 或 --ref e12
 openclaw browser screenshot --labels
 openclaw browser snapshot
 openclaw browser snapshot --format aria --limit 200
@@ -166,12 +166,13 @@ openclaw browser responsebody "**/api" --max-chars 5000
 
 </Accordion>
 
-<Accordion title="操作：导航、点击、输入、拖拽、等待、evaluate">
+<Accordion title="操作：navigate、click、type、drag、wait、evaluate">
 
 ```bash
 openclaw browser navigate https://example.com
 openclaw browser resize 1280 720
-openclaw browser click 12 --double           # 或 e12，用于角色 refs
+openclaw browser click 12 --double           # 或 e12 用于 role refs
+openclaw browser click-coords 120 340        # 视口坐标
 openclaw browser type 23 "hello" --submit
 openclaw browser press Enter
 openclaw browser hover 44
@@ -193,7 +194,7 @@ openclaw browser trace stop
 
 </Accordion>
 
-<Accordion title="状态：cookies、storage、离线、headers、geo、device">
+<Accordion title="状态：cookies、storage、offline、headers、geo、device">
 
 ```bash
 openclaw browser cookies
@@ -204,7 +205,7 @@ openclaw browser storage local set theme dark
 openclaw browser storage session clear
 openclaw browser set offline on
 openclaw browser set headers --headers-json '{"X-Debug":"1"}'
-openclaw browser set credentials user pass            # --clear 可移除
+openclaw browser set credentials user pass            # 使用 --clear 删除
 openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
 openclaw browser set media dark
 openclaw browser set timezone America/New_York
@@ -216,21 +217,21 @@ openclaw browser set device "iPhone 14"
 
 </AccordionGroup>
 
-说明：
+注意：
 
-- `upload` 和 `dialog` 是**预置**调用；请在触发文件选择器 / 对话框的点击或按键之前运行它们。
-- `click` / `type` / 等操作需要来自 `snapshot` 的 `ref`（数字 `12` 或角色 ref `e12`）。操作有意不支持 CSS 选择器。
-- 下载、trace 和 upload 路径受限于 OpenClaw 临时根目录：`/tmp/openclaw{,/downloads,/uploads}`（回退为 `${os.tmpdir()}/openclaw/...`）。
-- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入。
+- `upload` 和 `dialog` 是**预设**调用；请在触发文件选择器/对话框的点击或按键之前运行它们。
+- `click` / `type` / 等操作需要来自 `snapshot` 的 `ref`（数字 `12` 或 role ref `e12`）。操作有意不支持 CSS 选择器。当可见视口位置是唯一可靠目标时，请使用 `click-coords`。
+- 下载、trace 和 upload 路径被限制在 OpenClaw 临时根目录中：`/tmp/openclaw{,/downloads,/uploads}`（回退为：`${os.tmpdir()}/openclaw/...`）。
+- `upload` 还可以通过 `--input-ref` 或 `--element` 直接设置文件输入。
 
-快照标志速览：
+快照标志一览：
 
-- `--format ai`（安装了 Playwright 时为默认）：AI 快照，带数字 refs（`aria-ref="<n>"`）。
+- `--format ai`（安装 Playwright 时的默认值）：带数字 refs 的 AI 快照（`aria-ref="<n>"`）。
 - `--format aria`：无障碍树，无 refs；仅用于检查。
-- `--efficient`（或 `--mode efficient`）：紧凑角色快照预设。设置 `browser.snapshotDefaults.mode: "efficient"` 可将其设为默认值（参见 [Gateway 配置](/zh-CN/gateway/configuration-reference#browser)）。
-- `--interactive`、`--compact`、`--depth`、`--selector` 会强制使用带 `ref=e12` refs 的角色快照。`--frame "<iframe>"` 会将角色快照限定到某个 iframe。
-- `--labels` 会附加带有叠加 ref 标签的仅视口截图（输出 `MEDIA:<path>`）。
-- `--urls` 会将发现的链接目标追加到 AI 快照中。
+- `--efficient`（或 `--mode efficient`）：紧凑的 role 快照预设。设置 `browser.snapshotDefaults.mode: "efficient"` 可将其设为默认值（参见 [Gateway configuration](/zh-CN/gateway/configuration-reference#browser)）。
+- `--interactive`、`--compact`、`--depth`、`--selector` 会强制生成 role 快照，并使用 `ref=e12` refs。`--frame "<iframe>"` 将 role 快照范围限定到某个 iframe。
+- `--labels` 会添加带叠加 ref 标签的仅视口截图（输出 `MEDIA:<path>`）。
+- `--urls` 会将已发现的链接目标附加到 AI 快照中。
 
 ## 快照和 refs
 
@@ -241,22 +242,22 @@ OpenClaw 支持两种“快照”样式：
   - 操作：`openclaw browser click 12`、`openclaw browser type 23 "hello"`。
   - 在内部，ref 通过 Playwright 的 `aria-ref` 解析。
 
-- **角色快照（如 `e12` 这样的角色 refs）**：`openclaw browser snapshot --interactive`（或 `--compact`、`--depth`、`--selector`、`--frame`）
-  - 输出：基于角色的列表 / 树，带有 `[ref=e12]`（以及可选的 `[nth=1]`）。
+- **Role 快照（类似 `e12` 的 role refs）**：`openclaw browser snapshot --interactive`（或 `--compact`、`--depth`、`--selector`、`--frame`）
+  - 输出：带有 `[ref=e12]`（以及可选的 `[nth=1]`）的基于 role 的列表/树。
   - 操作：`openclaw browser click e12`、`openclaw browser highlight e12`。
-  - 在内部，ref 通过 `getByRole(...)` 解析（重复项时再配合 `nth()`）。
-  - 添加 `--labels` 可附加带有叠加 `e12` 标签的视口截图。
-  - 当链接文本存在歧义且智能体需要具体
+  - 在内部，ref 通过 `getByRole(...)` 解析（重复项则结合 `nth()`）。
+  - 添加 `--labels` 可包含带叠加 `e12` 标签的视口截图。
+  - 当链接文本有歧义且智能体需要明确的
     导航目标时，添加 `--urls`。
 
 ref 行为：
 
-- refs **不会在导航之间保持稳定**；如果某项操作失败，请重新运行 `snapshot` 并使用新的 ref。
-- 如果角色快照是通过 `--frame` 获取的，则角色 refs 会限定在该 iframe 中，直到下一次角色快照。
+- refs **不会在导航后保持稳定**；如果操作失败，请重新运行 `snapshot` 并使用新的 ref。
+- 如果 role 快照是通过 `--frame` 获取的，那么 role refs 会限定在该 iframe 中，直到下一次 role 快照。
 
-## 等待增强功能
+## Wait 增强功能
 
-你可以等待的对象不止是时间 / 文本：
+你可以等待的不仅仅是时间/文本：
 
 - 等待 URL（支持 Playwright glob）：
   - `openclaw browser wait --url "**/dash"`
@@ -264,10 +265,10 @@ ref 行为：
   - `openclaw browser wait --load networkidle`
 - 等待 JS 谓词：
   - `openclaw browser wait --fn "window.ready===true"`
-- 等待某个选择器变为可见：
+- 等待选择器变为可见：
   - `openclaw browser wait "#main"`
 
-这些条件可以组合使用：
+这些可以组合使用：
 
 ```bash
 openclaw browser wait "#main" \
@@ -279,22 +280,22 @@ openclaw browser wait "#main" \
 
 ## 调试工作流
 
-当某个操作失败时（例如“不可见”“严格模式冲突”“被遮挡”）：
+当某个操作失败时（例如 “not visible”、“strict mode violation”、“covered”）：
 
 1. `openclaw browser snapshot --interactive`
-2. 使用 `click <ref>` / `type <ref>`（在交互模式下优先使用角色 refs）
-3. 如果仍然失败：运行 `openclaw browser highlight <ref>` 查看 Playwright 实际定位的目标
-4. 如果页面行为异常：
+2. 使用 `click <ref>` / `type <ref>`（在交互模式下优先使用 role refs）
+3. 如果仍然失败：使用 `openclaw browser highlight <ref>` 查看 Playwright 实际定位的目标
+4. 如果页面表现异常：
    - `openclaw browser errors --clear`
    - `openclaw browser requests --filter api --clear`
-5. 若需深入调试：记录一个 trace：
+5. 若需深入调试：记录 trace：
    - `openclaw browser trace start`
-   - 复现问题
+   - 重现问题
    - `openclaw browser trace stop`（输出 `TRACE:<path>`）
 
 ## JSON 输出
 
-`--json` 用于脚本编写和结构化工具。
+`--json` 用于脚本编写和结构化工具处理。
 
 示例：
 
@@ -305,35 +306,35 @@ openclaw browser requests --filter api --json
 openclaw browser cookies --json
 ```
 
-JSON 格式的角色快照包含 `refs` 和一个小型 `stats` 块（lines / chars / refs / interactive），以便工具推断负载大小和密度。
+JSON 格式的 role 快照包含 `refs` 以及一个小型 `stats` 块（lines/chars/refs/interactive），以便工具推断负载大小和密度。
 
-## 状态和环境旋钮
+## 状态和环境调节项
 
-这些选项对于“让站点表现得像 X 一样”的工作流很有用：
+这些对“让网站表现得像 X 一样”的工作流很有用：
 
 - Cookies：`cookies`、`cookies set`、`cookies clear`
 - Storage：`storage local|session get|set|clear`
-- 离线：`set offline on|off`
-- Headers：`set headers --headers-json '{"X-Debug":"1"}'`（旧版 `set headers --json '{"X-Debug":"1"}'` 仍受支持）
-- HTTP Basic 鉴权：`set credentials user pass`（或 `--clear`）
-- 地理位置：`set geo <lat> <lon> --origin "https://example.com"`（或 `--clear`）
-- 媒体：`set media dark|light|no-preference|none`
-- 时区 / locale：`set timezone ...`、`set locale ...`
-- 设备 / 视口：
+- Offline：`set offline on|off`
+- Headers：`set headers --headers-json '{"X-Debug":"1"}'`（旧版 `set headers --json '{"X-Debug":"1"}'` 仍然受支持）
+- HTTP Basic auth：`set credentials user pass`（或使用 `--clear`）
+- Geolocation：`set geo <lat> <lon> --origin "https://example.com"`（或使用 `--clear`）
+- Media：`set media dark|light|no-preference|none`
+- Timezone / locale：`set timezone ...`、`set locale ...`
+- Device / viewport：
   - `set device "iPhone 14"`（Playwright 设备预设）
   - `set viewport 1280 720`
 
-## 安全和隐私
+## 安全与隐私
 
-- openclaw 浏览器 profile 可能包含已登录会话；请将其视为敏感内容。
+- `openclaw` 浏览器配置文件可能包含已登录会话；请将其视为敏感内容。
 - `browser act kind=evaluate` / `openclaw browser evaluate` 和 `wait --fn`
   会在页面上下文中执行任意 JavaScript。提示注入可能会引导
-  这一行为。如果你不需要它，请通过 `browser.evaluateEnabled=false` 禁用。
-- 有关登录和反机器人说明（X/Twitter 等），请参见 [Browser login + X/Twitter posting](/zh-CN/tools/browser-login)。
-- 保持 Gateway 网关 / 节点宿主为私有（仅 loopback 或仅 tailnet）。
-- 远程 CDP 端点能力很强；请对其进行隧道保护和访问防护。
+  执行这些操作。如果你不需要它，请使用 `browser.evaluateEnabled=false` 禁用。
+- 关于登录和反机器人说明（X/Twitter 等），请参阅 [Browser login + X/Twitter posting](/zh-CN/tools/browser-login)。
+- 请将 Gateway 网关/节点主机保持为私有（仅 loopback 或仅 tailnet）。
+- 远程 CDP 端点权限很高；请通过隧道接入并加以保护。
 
-严格模式示例（默认阻止私有 / 内部目标）：
+严格模式示例（默认阻止私有/内部目标）：
 
 ```json5
 {
@@ -349,7 +350,7 @@ JSON 格式的角色快照包含 `refs` 和一个小型 `stats` 块（lines / ch
 
 ## 相关内容
 
-- [Browser](/zh-CN/tools/browser) — 概览、配置、profiles、安全
+- [Browser](/zh-CN/tools/browser) — 概述、配置、配置文件、安全
 - [Browser login](/zh-CN/tools/browser-login) — 登录网站
 - [Browser Linux troubleshooting](/zh-CN/tools/browser-linux-troubleshooting)
 - [Browser WSL2 troubleshooting](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)

docs/zh-CN/tools/browser.md

@@ -1,39 +1,39 @@
 ---
 read_when:
     - 添加由智能体控制的浏览器自动化
-    - 调试为什么 OpenClaw 会干扰你自己的 Chrome
-    - 在 macOS 应用中实现浏览器设置和生命周期
-summary: 集成浏览器控制服务 + 操作命令
-title: 浏览器（OpenClaw 托管）
+    - 调试为什么 openclaw 会干扰你自己的 Chrome
+    - 在 macOS 应用中实现浏览器设置 + 生命周期
+summary: 集成式浏览器控制服务 + 操作命令
+title: 浏览器（由 OpenClaw 管理）
 x-i18n:
-    generated_at: "2026-04-25T05:56:56Z"
+    generated_at: "2026-04-25T06:35:03Z"
     model: gpt-5.4
     provider: openai
-    source_hash: e150084059ae485cfb83ef70fd9d5d3ca46c5bd42431df3667857192009ec14c
+    source_hash: f529cbcc4e818a89274fd9fc25e46b3cc5b30913278d62652ee1100e8ae6dcef
     source_path: tools/browser.md
     workflow: 15
 ---
 
-OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium profile**，由智能体进行控制。
-它与你的个人浏览器隔离，并通过 Gateway 网关内部一个小型本地控制服务进行管理
-（仅 loopback）。
+OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。  
+它与你的个人浏览器隔离，并通过 Gateway 网关内部的一个小型本地控制服务进行管理（仅限 loopback）。
 
-面向初学者的理解方式：
+初学者视角：
 
-- 你可以把它看作一个**独立的、仅供智能体使用的浏览器**。
-- `openclaw` profile **不会**触碰你的个人浏览器 profile。
+- 可以把它理解为一个**独立的、仅供智能体使用的浏览器**。
+- `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。
 - 智能体可以在一条安全通道中**打开标签页、读取页面、点击和输入**。
-- 内置的 `user` profile 会通过 Chrome MCP 附加到你真实的、已登录的 Chrome 会话。
+- 内置的 `user` 配置文件会通过 Chrome MCP 附加到你真实的已登录 Chrome 会话。
 
-## 你将获得什么
+## 你将获得的内容
 
-- 一个名为 **openclaw** 的独立浏览器 profile（默认使用橙色强调色）。
-- 确定性的标签页控制（列出/打开/聚焦/关闭）。
-- 智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。
-- 一个内置的 `browser-automation` Skill，在启用 browser 插件时，它会教智能体使用 snapshot、stable-tab、stale-ref 和 manual-blocker 恢复循环。
-- 可选的多 profile 支持（`openclaw`、`work`、`remote`，等等）。
+- 一个名为 **openclaw** 的独立浏览器配置文件（默认使用橙色强调色）。
+- 可预测的标签页控制（列出/打开/聚焦/关闭）。
+- 智能体操作（点击/输入/拖拽/选择）、快照、截图、PDF。
+- 一个内置的 `browser-automation` Skills，它会在启用浏览器插件时教会智能体使用 snapshot、stable-tab、stale-ref 和 manual-blocker 恢复循环。
+- 可选的多配置文件支持（`openclaw`、`work`、`remote`，等等）。
 
-这个浏览器**不是**你的日常主力浏览器。它是一个安全、隔离的表面，用于智能体自动化和验证。
+这个浏览器**不是**你日常使用的主浏览器。  
+它是一个安全、隔离的界面，用于智能体自动化和验证。
 
 ## 快速开始
 
@@ -45,14 +45,13 @@ openclaw browser --browser-profile openclaw open https://example.com
 openclaw browser --browser-profile openclaw snapshot
 ```
 
-如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启
-Gateway 网关。
+如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启 Gateway 网关。
 
-如果 `openclaw browser` 完全不存在，或者智能体提示 browser 工具不可用，请跳转到 [缺少 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
 {
@@ -66,22 +65,23 @@ Gateway 网关。
 }
 ```
 
-默认情况下，需要同时满足 `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 插件提供两个层级的智能体指引：
+浏览器插件附带两级智能体指引：
 
-- `browser` 工具说明承载了紧凑、始终启用的约定：选择正确的 profile，在同一标签页上保持 refs，使用 `tabId`/labels 进行标签页定向，并在多步骤任务中加载 browser Skill。
-- 内置的 `browser-automation` Skill 承载了更长的操作循环：先检查状态/标签页，为任务标签页打标签，在操作前创建快照，在 UI 变化后重新创建快照，恢复一次 stale refs，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为需要手动操作，而不是猜测。
+- `browser` 工具描述承载了始终启用的精简契约：选择正确的配置文件、在同一标签页上保持 refs、使用 `tabId`/labels 进行标签页定位，并在进行多步骤工作时加载浏览器 skill。
+- 内置的 `browser-automation` Skills 承载更长的操作循环：先检查状态/标签页，为任务标签页打标签，在操作前先做 snapshot，在 UI 变化后重新 snapshot，遇到 stale refs 时恢复一次，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为需要手动操作，而不是猜测处理。
 
-当插件启用时，插件内置的 Skills 会列在智能体可用 Skills 中。完整的 Skill 指令会按需加载，因此常规轮次不会支付完整的 token 成本。
+启用插件后，插件内置的 Skills 会显示在智能体的可用技能列表中。  
+完整的技能说明按需加载，因此常规轮次不会承担完整的 token 成本。
 
-## 缺少 browser 命令或工具
+## 缺少浏览器命令或工具
 
-如果升级后 `openclaw browser` 变成未知命令、`browser.request` 丢失，或者智能体报告 browser 工具不可用，通常原因是 `plugins.allow` 列表中遗漏了 `browser`。把它加上：
+如果升级后 `openclaw browser` 无法识别、缺少 `browser.request`，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中遗漏了 `browser`。请将它加上：
 
 ```json5
 {
@@ -91,20 +91,20 @@ browser 插件提供两个层级的智能体指引：
 }
 ```
 
-`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` 也会恢复默认行为。
 
-## Profiles：`openclaw` 与 `user`
+## 配置文件：`openclaw` 与 `user`
 
-- `openclaw`：受管、隔离的浏览器（不需要扩展）。
-- `user`：内置的 Chrome MCP 附加 profile，用于你的**真实已登录 Chrome** 会话。
+- `openclaw`：受管理、隔离的浏览器（不需要扩展）。
+- `user`：内置的 Chrome MCP 附加配置文件，用于你的**真实已登录 Chrome** 会话。
 
-对于智能体 browser 工具调用：
+对于智能体浏览器工具调用：
 
 - 默认：使用隔离的 `openclaw` 浏览器。
 - 当现有登录会话很重要，并且用户就在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。
-- `profile` 是你希望指定某种特定浏览器模式时的显式覆盖项。
+- 当你想指定特定浏览器模式时，使用 `profile` 作为显式覆盖。
 
-如果你希望默认使用受管模式，请设置 `browser.defaultProfile: "openclaw"`。
+如果你想默认使用受管模式，请设置 `browser.defaultProfile: "openclaw"`。
 
 ## 配置
 
@@ -115,18 +115,18 @@ browser 插件提供两个层级的智能体指引：
   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", // 旧的单 profile 覆盖项
+    // cdpUrl: "http://127.0.0.1:18792", // 旧的单配置文件覆盖项
     remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时（毫秒）
     remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒）
     tabCleanup: {
       enabled: true, // 默认：true
-      idleMinutes: 120, // 设为 0 可禁用空闲清理
-      maxTabsPerSession: 8, // 设为 0 可禁用每会话上限
+      idleMinutes: 120, // 设为 0 以禁用空闲清理
+      maxTabsPerSession: 8, // 设为 0 以禁用每个会话的上限
       sweepMinutes: 5,
     },
     defaultProfile: "openclaw",
@@ -162,46 +162,44 @@ browser 插件提供两个层级的智能体指引：
 
 <AccordionGroup>
 
-<Accordion title="端口和可达性">
+<Accordion title="端口与可达性">
 
-- 控制服务会绑定到 loopback，端口由 `gateway.port` 推导而来（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会让同一族中的派生端口一起变化。
-- 本地 `openclaw` profiles 会自动分配 `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 握手。
-- `tabCleanup` 是对由主智能体 browser 会话打开的标签页进行尽力而为的清理。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭它们显式跟踪的标签页；主会话会让活动标签页保持可复用，然后在后台关闭空闲或超出上限的已跟踪标签页。
+- `tabCleanup` 是对主智能体浏览器会话所打开标签页的尽力清理机制。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭它们显式跟踪的标签页；主会话会保留活动标签页以便重复使用，然后在后台关闭空闲或超出数量的已跟踪标签页。
 
 </Accordion>
 
 <Accordion title="SSRF 策略">
 
-- browser navigation 和 open-tab 会在导航前经过 SSRF 防护，并在之后对最终的 `http(s)` URL 进行尽力而为的复检。
+- 浏览器导航和打开标签页会在导航前经过 SSRF 防护，并在事后对最终 `http(s)` URL 进行尽力复查。
 - 在严格 SSRF 模式下，远程 CDP 端点发现和 `/json/version` 探测（`cdpUrl`）也会被检查。
-- Gateway 网关/提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动代理 OpenClaw 托管的浏览器。受管 Chrome 默认直接启动，因此提供商代理设置不会削弱 browser SSRF 检查。
-- 如果要代理受管浏览器本身，请通过 `browser.extraArgs` 传入显式 Chrome 代理标志，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。严格 SSRF 模式会阻止显式 browser 代理路由，除非你明确启用了私有网络 browser 访问。
-- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅在你明确受信任私有网络 browser 访问时启用。
-- `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` 作为旧别名仍然受支持。
 
 </Accordion>
 
-<Accordion title="Profile 行为">
+<Accordion title="配置文件行为">
 
-- `attachOnly: true` 表示绝不启动本地浏览器；只有在浏览器已经运行时才附加。
-- `headless` 可以在全局或按本地受管 profile 设置。按 profile 的值会覆盖 `browser.headless`，因此一个本地启动的 profile 可以保持 headless，而另一个仍然可见。
-- `executablePath` 也可以在全局或按本地受管 profile 设置。按 profile 的值会覆盖 `browser.executablePath`，因此不同的受管 profiles 可以启动不同的 Chromium 系浏览器。
-- `color`（顶层和按 profile）会给浏览器 UI 加上色调，这样你可以看出当前活动的是哪个 profile。
-- 默认 profile 是 `openclaw`（受管独立模式）。使用 `defaultProfile: "user"` 可切换为已登录用户浏览器。
-- 自动检测顺序：系统默认浏览器（如果它是 Chromium 系）；否则 Chrome → Brave → Edge → Chromium → Chrome Canary。
-- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。不要为该驱动设置 `cdpUrl`。
-- 当一个 existing-session profile 应附加到非默认 Chromium 用户 profile（Brave、Edge 等）时，请设置 `browser.profiles.<name>.userDataDir`。
+- `attachOnly: true` 表示绝不启动本地浏览器；仅在浏览器已经运行时才进行附加。
+- `headless` 可以在全局或每个本地受管配置文件上设置。每个配置文件的值会覆盖 `browser.headless`，因此一个本地启动的配置文件可以保持无头模式，而另一个仍然可见。
+- `executablePath` 可以在全局或每个本地受管配置文件上设置。每个配置文件的值会覆盖 `browser.executablePath`，因此不同的受管配置文件可以启动不同的 Chromium 内核浏览器。
+- `color`（顶层和每个配置文件）会为浏览器 UI 着色，这样你可以看出当前活动的是哪个配置文件。
+- 默认配置文件是 `openclaw`（受管独立模式）。使用 `defaultProfile: "user"` 可切换为已登录用户浏览器。
+- 自动检测顺序：如果系统默认浏览器是 Chromium 内核，则优先使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。
+- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。不要为这种 driver 设置 `cdpUrl`。
+- 当一个 existing-session 配置文件需要附加到非默认的 Chromium 用户配置文件（Brave、Edge 等）时，请设置 `browser.profiles.<name>.userDataDir`。
 
 </Accordion>
 
 </AccordionGroup>
 
-## 使用 Brave（或其他 Chromium 系浏览器）
+## 使用 Brave（或其他 Chromium 内核浏览器）
 
-如果你的**系统默认**浏览器是 Chromium 系（Chrome/Brave/Edge 等），
-OpenClaw 会自动使用它。设置 `browser.executablePath` 可覆盖
-自动检测。`~` 会展开为你的操作系统主目录：
+如果你的**系统默认**浏览器是 Chromium 内核（Chrome/Brave/Edge 等），OpenClaw 会自动使用它。设置 `browser.executablePath` 可以覆盖自动检测。`~` 会展开为你的操作系统主目录：
 
 ```bash
 openclaw config set browser.executablePath "/usr/bin/google-chrome"
@@ -240,50 +238,47 @@ openclaw config set browser.profiles.work.executablePath "/Applications/Google C
   </Tab>
 </Tabs>
 
-按 profile 设置的 `executablePath` 只影响 OpenClaw 启动的本地受管 profiles。`existing-session` profiles 会附加到一个已经运行的浏览器，而远程 CDP profiles 会使用 `cdpUrl` 背后的浏览器。
+每个配置文件的 `executablePath` 只会影响由 OpenClaw 启动的本地受管配置文件。`existing-session` 配置文件会改为附加到已在运行的浏览器，而远程 CDP 配置文件则使用 `cdpUrl` 背后的浏览器。
 
 ## 本地控制与远程控制
 
 - **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并且可以启动本地浏览器。
-- **远程控制（节点主机）：** 在拥有浏览器的机器上运行一个节点主机；Gateway 网关会把 browser 操作代理给它。
-- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`）以附加到远程 Chromium 系浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
-- `headless` 只影响 OpenClaw 启动的本地受管 profiles。它不会重启或更改 existing-session 或远程 CDP 浏览器。
-- `executablePath` 也遵循同样的本地受管 profile 规则。在正在运行的本地受管 profile 上修改它，会将该 profile 标记为需要重启/对齐，以便下次启动时使用新的二进制文件。
+- **远程控制（节点主机）：** 在拥有浏览器的机器上运行一个节点主机；Gateway 网关会将浏览器操作代理到它。
+- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`）以附加到远程 Chromium 内核浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
+- `headless` 只影响由 OpenClaw 启动的本地受管配置文件。它不会重启或改变 existing-session 或远程 CDP 浏览器。
+- `executablePath` 也遵循同样的本地受管配置文件规则。在正在运行的本地受管配置文件上更改它，会将该配置文件标记为需要重启/协调，以便下一次启动时使用新的二进制文件。
 
-停止行为会因 profile 模式而不同：
+停止行为会因配置文件模式不同而有所区别：
 
-- 本地受管 profiles：`openclaw browser stop` 会停止由 OpenClaw 启动的浏览器进程
-- attach-only 和远程 CDP profiles：`openclaw browser stop` 会关闭当前控制会话，并释放 Playwright/CDP 模拟覆盖状态（viewport、color scheme、locale、timezone、offline mode 以及类似状态），即使 OpenClaw 实际上并未启动任何浏览器进程
+- 本地受管配置文件：`openclaw browser stop` 会停止由 OpenClaw 启动的浏览器进程
+- 仅附加和远程 CDP 配置文件：`openclaw browser stop` 会关闭当前控制会话，并释放 Playwright/CDP 模拟覆盖项（视口、配色方案、区域设置、时区、离线模式以及类似状态），即使 OpenClaw 并未启动任何浏览器进程
 
 远程 CDP URL 可以包含认证信息：
 
-- 查询参数 token（例如 `https://provider.example?token=<token>`）
-- HTTP Basic 认证（例如 `https://user:pass@provider.example`）
+- 查询 token（例如 `https://provider.example?token=<token>`）
+- HTTP Basic auth（例如 `https://user:pass@provider.example`）
 
-OpenClaw 在调用 `/json/*` 端点和连接到 CDP WebSocket 时会保留这些认证信息。
-对于 token，优先使用环境变量或密钥管理器，而不是把它们提交到配置文件中。
+OpenClaw 在调用 `/json/*` 端点以及连接 CDP WebSocket 时都会保留这些认证信息。  
+对于 token，优先使用环境变量或密钥管理器，而不是将它们提交到配置文件中。
 
-## 节点 browser 代理（默认零配置）
+## 节点浏览器代理（默认零配置）
 
-如果你在拥有浏览器的那台机器上运行了一个**节点主机**，OpenClaw 就可以
-自动将 browser 工具调用路由到该节点，而无需额外的 browser 配置。
+如果你在拥有浏览器的那台机器上运行一个**节点主机**，OpenClaw 可以自动将浏览器工具调用路由到该节点，而无需任何额外的浏览器配置。  
 这是远程 Gateway 网关的默认路径。
 
-说明：
+注意事项：
 
-- 节点主机会通过一个**代理命令**暴露其本地 browser 控制服务器。
-- Profiles 来自该节点自己的 `browser.profiles` 配置（与本地相同）。
-- `nodeHost.browserProxy.allowProfiles` 是可选项。保持为空即可沿用旧版/默认行为：所有已配置的 profiles 都仍然可以通过代理访问，包括 profile 创建/删除路由。
-- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有 allowlist 中的 profiles 才能被定向，而且持久化的 profile 创建/删除路由会在代理表面上被阻止。
+- 节点主机会通过一个**代理命令**暴露其本地浏览器控制服务器。
+- 配置文件来自节点自身的 `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 两种形式都可以使用，但对于远程浏览器 profile，
-最简单的选项是使用 Browserless 连接文档中的直接 WebSocket URL。
+[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，通过 HTTPS 和 WebSocket 暴露 CDP 连接 URL。OpenClaw 两种形式都支持，但对于远程浏览器配置文件，最简单的选项是使用 Browserless 连接文档中的直接 WebSocket URL。
 
 示例：
 
@@ -304,40 +299,27 @@ CDP 连接 URL。OpenClaw 两种形式都可以使用，但对于远程浏览器
 }
 ```
 
-说明：
+注意事项：
 
-- 将 `<BROWSERLESS_API_KEY>` 替换为你真实的 Browserless token。
+- 请将 `<BROWSERLESS_API_KEY>` 替换为你真实的 Browserless token。
 - 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。
-- 如果 Browserless 提供给你的是一个 HTTPS 基础 URL，你可以将其转换为
-  `wss://` 以建立直接 CDP 连接，也可以保留 HTTPS URL，让 OpenClaw
-  去发现 `/json/version`。
+- 如果 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 debugger URL，
-  然后建立连接。不会回退到 WebSocket。
-- **直接 WebSocket 端点** — `ws://host[:port]/devtools/<kind>/<id>` 或
-  `wss://...`，并带有 `/devtools/browser|page|worker|shared_worker|service_worker/<id>`
-  路径。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` 发现（将协议规范化为 `http`/`https`）；
-  如果发现结果返回了 `webSocketDebuggerUrl`，就使用它，否则 OpenClaw
-  会回退为对裸根路径进行直接 WebSocket 握手。这让指向本地 Chrome 的裸 `ws://`
-  仍然可以连接，因为 Chrome 只接受位于
-  `/json/version` 返回的特定按目标路径上的 WebSocket 升级。
+- **HTTP(S) 发现** — `http://host[:port]` 或 `https://host[:port]`。  
+  OpenClaw 会调用 `/json/version` 来发现 WebSocket 调试器 URL，然后连接。没有 WebSocket 回退。
+- **直接 WebSocket 端点** — `ws://host[:port]/devtools/<kind>/<id>` 或  
+  `wss://...` 且路径为 `/devtools/browser|page|worker|shared_worker|service_worker/<id>`。  
+  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` 发现（将协议规范化为 `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
 {
@@ -356,80 +338,70 @@ CDP URL 形态，并自动选择正确的连接策略：
 }
 ```
 
-说明：
+注意事项：
 
-- [注册](https://www.browserbase.com/sign-up)，然后从 [概览仪表板](https://www.browserbase.com/overview) 复制你的 **API Key**。
-- 将 `<BROWSERBASE_API_KEY>` 替换为你真实的 Browserbase API key。
-- Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此
-  不需要手动创建会话。
-- 免费层允许一个并发会话以及每月一个浏览器小时。
-  付费计划限制请参见 [定价](https://www.browserbase.com/pricing)。
-- 完整 API 参考、SDK 指南和集成示例请参见 [Browserbase 文档](https://docs.browserbase.com)。
+- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview dashboard](https://www.browserbase.com/overview) 复制你的 **API Key**。
+- 请将 `<BROWSERBASE_API_KEY>` 替换为你真实的 Browserbase API key。
+- Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此不需要手动创建会话步骤。
+- 免费套餐每月允许一个并发会话和一个浏览器小时。  
+  付费套餐限制请参见 [pricing](https://www.browserbase.com/pricing)。
+- 完整 API 参考、SDK 指南和集成示例请参见 [Browserbase docs](https://docs.browserbase.com)。
 
-## 安全
+## 安全性
 
-关键点：
+关键概念：
 
-- 浏览器控制仅限 loopback；访问通过 Gateway 网关认证或节点配对进行。
-- 独立的 loopback 浏览器 HTTP API **只**使用共享密钥认证：
-  gateway token bearer auth、`x-openclaw-password`，或者使用已配置
-  gateway password 的 HTTP Basic auth。
-- 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；访问通过 Gateway 网关认证或节点配对完成。
+- 独立的 loopback 浏览器 HTTP API **仅使用共享密钥认证**：gateway token bearer auth、`x-openclaw-password`，或使用已配置 gateway 密码的 HTTP Basic auth。
+- 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 提示：
 
-- 尽可能优先使用加密端点（HTTPS 或 WSS）和短期 token。
-- 避免将长期 token 直接写入配置文件。
+- 尽可能优先使用加密端点（HTTPS 或 WSS）以及短期 token。
+- 避免将长期 token 直接嵌入配置文件。
 
-## Profiles（多浏览器）
+## 配置文件（多浏览器）
 
-OpenClaw 支持多个命名 profiles（路由配置）。Profiles 可以是：
+OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是：
 
-- **OpenClaw 托管**：一个专用的 Chromium 系浏览器实例，带有自己的用户数据目录 + CDP 端口
-- **远程**：一个显式的 CDP URL（在其他地方运行的 Chromium 系浏览器）
-- **现有会话**：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome profile
+- **由 OpenClaw 管理**：一个专用的 Chromium 内核浏览器实例，拥有自己的用户数据目录 + CDP 端口
+- **远程**：显式 CDP URL（运行在其他位置的 Chromium 内核浏览器）
+- **现有会话**：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome 配置文件
 
 默认值：
 
-- 如果缺失，会自动创建 `openclaw` profile。
-- `user` profile 是内置的，用于 Chrome MCP existing-session 附加。
-- 除 `user` 外，existing-session profiles 需要显式启用；使用 `--driver existing-session` 创建它们。
+- 如果缺少，`openclaw` 配置文件会自动创建。
+- `user` 配置文件是内置的，用于 Chrome MCP 现有会话附加。
+- 除 `user` 外，existing-session 配置文件需要显式启用；使用 `--driver existing-session` 创建它们。
 - 本地 CDP 端口默认从 **18800–18899** 分配。
-- 删除 profile 会将其本地数据目录移到回收站。
+- 删除配置文件会将其本地数据目录移到废纸篓。
 
 所有控制端点都接受 `?profile=<name>`；CLI 使用 `--browser-profile`。
 
-## 通过 Chrome DevTools MCP 使用现有会话
+## 通过 Chrome DevTools MCP 连接现有会话
 
-OpenClaw 还可以通过
-官方 Chrome DevTools MCP 服务器附加到一个正在运行的 Chromium 系浏览器 profile。
-这会复用该浏览器 profile 中已经打开的标签页和登录状态。
+OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运行的 Chromium 内核浏览器配置文件。这样可以复用该浏览器配置文件中已经打开的标签页和登录状态。
 
-官方背景和设置参考：
+官方背景与设置参考：
 
-- [Chrome for Developers：使用 Chrome DevTools MCP 调试你的浏览器会话](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
+- [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)
 
-内置 profile：
+内置配置文件：
 
 - `user`
 
-可选：如果你想使用不同的名称、颜色或浏览器数据目录，
-可以创建你自己的自定义 existing-session profile。
+可选：如果你想使用不同的名称、颜色或浏览器数据目录，也可以创建自己的自定义 existing-session 配置文件。
 
 默认行为：
 
-- 内置的 `user` profile 使用 Chrome MCP 自动连接，目标是
-  默认的本地 Google Chrome profile。
+- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，目标是默认的本地 Google Chrome 配置文件。
 
-对于 Brave、Edge、Chromium 或非默认 Chrome profile，请使用 `userDataDir`：
+如果要用于 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`：
 
 ```json5
 {
@@ -452,13 +424,13 @@ OpenClaw 还可以通过
 2. 启用远程调试。
 3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。
 
-常见 inspect 页面：
+常见的 inspect 页面：
 
 - Chrome：`chrome://inspect/#remote-debugging`
 - Brave：`brave://inspect/#remote-debugging`
 - Edge：`edge://inspect/#remote-debugging`
 
-实时附加 smoke 测试：
+实时附加冒烟测试：
 
 ```bash
 openclaw browser --browser-profile user start
@@ -472,55 +444,46 @@ openclaw browser --browser-profile user snapshot --format ai
 - `status` 显示 `driver: existing-session`
 - `status` 显示 `transport: chrome-mcp`
 - `status` 显示 `running: true`
-- `tabs` 列出你已经打开的浏览器标签页
-- `snapshot` 返回来自所选活动标签页的 refs
+- `tabs` 会列出你已经打开的浏览器标签页
+- `snapshot` 会返回所选实时标签页中的 refs
 
-如果附加不起作用，需要检查：
+如果附加不起作用，请检查：
 
-- 目标 Chromium 系浏览器版本为 `144+`
-- 该浏览器的 inspect 页面中已启用远程调试
-- 浏览器显示了附加同意提示，并且你已接受
-- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查
-  对于默认自动连接 profiles，Chrome 是否已在本地安装，但它不能替你
-  启用浏览器侧的远程调试
+- 目标 Chromium 内核浏览器版本是否为 `144+`
+- 该浏览器的 inspect 页面中是否启用了远程调试
+- 浏览器是否显示了附加同意提示，并且你已经接受
+- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法替你启用浏览器侧的远程调试
 
 智能体使用：
 
 - 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。
-- 如果你使用的是自定义 existing-session profile，请传入那个显式 profile 名称。
-- 只有当用户就在电脑前可以批准附加提示时，才应选择这种模式。
+- 如果你使用自定义 existing-session 配置文件，请传入该显式配置文件名。
+- 仅当用户就在电脑前可以批准附加提示时才选择此模式。
 - Gateway 网关或节点主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect`
 
-说明：
+注意事项：
 
-- 这条路径比隔离的 `openclaw` profile 风险更高，因为它可以
-  在你已登录的浏览器会话内执行操作。
-- 对于这个驱动，OpenClaw 不会启动浏览器；它只会附加。
-- OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果
-  设置了 `userDataDir`，它会被透传，以定位到该用户数据目录。
-- Existing-session 可以附加到选定主机上，或通过已连接的
-  browser 节点附加。如果 Chrome 位于别处且没有连接 browser 节点，请改用
-  远程 CDP 或节点主机。
+- 与隔离的 `openclaw` 配置文件相比，这条路径风险更高，因为它可以在你的已登录浏览器会话中操作。
+- 对于这个 driver，OpenClaw 不会启动浏览器；它只会进行附加。
+- OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果设置了 `userDataDir`，它会一并传入以定位该用户数据目录。
+- existing-session 可以附加到所选主机上，或者通过已连接的浏览器节点附加。如果 Chrome 位于其他地方且没有连接任何浏览器节点，请改用远程 CDP 或节点主机。
 
-<Accordion title="Existing-session 功能限制">
+<Accordion title="existing-session 功能限制">
 
-与受管的 `openclaw` profile 相比，existing-session 驱动受到更多限制：
+与受管的 `openclaw` 配置文件相比，existing-session driver 的限制更多：
 
-- **截图** —— 页面捕获和 `--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` 需要 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` 仍然需要受管浏览器路径。
 
 </Accordion>
 
 ## 隔离保证
 
-- **专用用户数据目录**：绝不会触碰你的个人浏览器 profile。
-- **专用端口**：避开 `9222`，以防与开发工作流冲突。
-- **确定性的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后是
-  稳定的 `tabId` 句柄（如 `t1`）、可选标签以及原始 `targetId`。
-  智能体应复用 `suggestedTargetId`；原始 id 仍然保留，用于
-  调试和兼容性。
+- **专用用户数据目录**：绝不会接触你的个人浏览器配置文件。
+- **专用端口**：避免使用 `9222`，以防与开发工作流冲突。
+- **可预测的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId` 句柄，例如 `t1`、可选 labels，以及原始 `targetId`。智能体应复用 `suggestedTargetId`；原始 id 仍然保留，以便调试和兼容。
 
 ## 浏览器选择
 
@@ -532,9 +495,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` 等。
@@ -542,24 +505,21 @@ openclaw browser --browser-profile user snapshot --format ai
 
 ## 控制 API（可选）
 
-为了便于脚本编写和调试，Gateway 网关暴露了一个小型的**仅 loopback 的 HTTP
-控制 API**，以及与之对应的 `openclaw browser` CLI（快照、refs、wait
-增强、JSON 输出、调试工作流）。完整参考请参见
-[Browser 控制 API](/zh-CN/tools/browser-control)。
+为了便于脚本编写和调试，Gateway 网关暴露了一个小型的**仅限 loopback 的 HTTP 控制 API**，并提供与之匹配的 `openclaw browser` CLI（快照、refs、wait 增强功能、JSON 输出、调试工作流）。完整参考请参见 [Browser control API](/zh-CN/tools/browser-control)。
 
 ## 故障排除
 
-对于 Linux 特有问题（尤其是 snap Chromium），请参见
-[浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)。
+有关 Linux 特定问题（尤其是 snap Chromium），请参见  
+[Browser 故障排除](/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 启动失败 vs 导航 SSRF 阻止
 
-这是两类不同的故障，它们指向不同的代码路径。
+这是两类不同的失败，它们指向不同的代码路径。
 
-- **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面是健康的。
+- **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。
 - **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但页面导航目标因策略被拒绝。
 
 常见示例：
@@ -570,7 +530,7 @@ openclaw browser --browser-profile user snapshot --format ai
 - 导航 SSRF 阻止：
   - 当 `start` 和 `tabs` 仍然可用时，`open`、`navigate`、snapshot 或打开标签页流程因浏览器/网络策略错误而失败
 
-使用下面这组最小命令来区分这两类问题：
+使用以下最小序列来区分两者：
 
 ```bash
 openclaw browser --browser-profile openclaw start
@@ -578,26 +538,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`，浏览器配置默认也会采用 fail-closed 的 SSRF 策略对象。
-- 对于本地 loopback 的 `openclaw` 受管 profile，CDP 健康检查会有意跳过对 OpenClaw 自身本地控制平面的 browser SSRF 可达性强制检查。
-- 导航保护是独立的。`start` 或 `tabs` 成功，并不意味着后续的 `open` 或 `navigate` 目标一定被允许。
+- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会使用一个失败即关闭的 SSRF 策略对象。
+- 对于本地 loopback 的 `openclaw` 受管配置文件，CDP 健康检查会有意跳过对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制执行。
+- 导航保护是独立的。`start` 或 `tabs` 成功，并不意味着之后的 `open` 或 `navigate` 目标一定被允许。
 
 安全建议：
 
-- **不要**默认放宽 browser SSRF 策略。
-- 优先使用像 `hostnameAllowlist` 或 `allowedHostnames` 这样的窄范围主机例外，而不是广泛开放私有网络访问。
-- 仅在明确受信任、确实需要并已审查私有网络 browser 访问的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。
+- **不要**默认放宽浏览器 SSRF 策略。
+- 相比广泛开放私有网络访问，优先使用更窄范围的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`。
+- 仅在明确受信任、确实需要并且已审查私有网络浏览器访问的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。
 
-## 智能体工具 + 控制如何工作
+## 智能体工具 + 控制工作方式
 
 智能体会获得**一个工具**用于浏览器自动化：
 
@@ -605,21 +565,21 @@ openclaw browser --browser-profile openclaw open https://example.com
 
 映射关系如下：
 
-- `browser snapshot` 返回一个稳定的 UI 树（AI 或 ARIA）。
-- `browser act` 使用 snapshot 的 `ref` ID 来执行 click/type/drag/select。
-- `browser screenshot` 捕获像素（整页、元素或带标签的 refs）。
-- `browser doctor` 检查 Gateway 网关、插件、profile、浏览器和标签页就绪状态。
+- `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。
+- `browser act` 使用 snapshot `ref` ID 来执行点击/输入/拖拽/选择。
+- `browser screenshot` 捕获像素截图（整页、元素或带标签的 refs）。
+- `browser doctor` 检查 Gateway 网关、插件、配置文件、浏览器和标签页就绪情况。
 - `browser` 接受：
-  - `profile`，用于选择命名浏览器 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: "host"` 需要 `agents.defaults.sandbox.browser.allowHostControl=true`。
+  - 如果省略 `target`：沙箱隔离会话默认使用 `sandbox`，非沙箱隔离会话默认使用 `host`。
+  - 如果已连接支持浏览器的节点，工具可能会自动路由到该节点，除非你固定指定 `target="host"` 或 `target="node"`。
 
 这样可以让智能体保持确定性，并避免脆弱的选择器。
 
 ## 相关内容
 
-- [工具概览](/zh-CN/tools) — 所有可用的智能体工具
-- [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱环境中的浏览器控制
-- [安全](/zh-CN/gateway/security) — 浏览器控制的风险与加固
+- [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具
+- [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的浏览器控制
+- [安全性](/zh-CN/gateway/security) — 浏览器控制的风险与加固