chore(i18n): refresh zh-CN translations

2026-04-25 07:25:06 +00:00 · 2026-04-25 07:25:06 +00:00 · 3758fc282e
commit 3758fc282e
parent 63b06557af
7 changed files with 603 additions and 542 deletions
--- a/docs/zh-CN/cli/browser.md
+++ b/docs/zh-CN/cli/browser.md
@ -1,22 +1,22 @@
 ---
 read_when:
-    - 你使用 `openclaw browser`，并且想要查看常见任务的示例
+    - 你会使用 `openclaw browser`，并且想查看常见任务的示例
    - 你想通过一个节点主机来控制另一台机器上运行的浏览器
    - 你想通过 Chrome MCP 连接到你本地已登录的 Chrome
 summary: '`openclaw browser` 的 CLI 参考（生命周期、配置文件、标签页、操作、状态和调试）'
 title: 浏览器
 x-i18n:
-    generated_at: "2026-04-25T06:35:01Z"
+    generated_at: "2026-04-25T07:22:23Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 03994a04839214fca41a8b53f21ddfb71560455039ff2e14b309b887eb86f5f9
+    source_hash: 292fc15c72de0aea069b1b87de471e645dbaa3e568e2c7fa493cbcd7c6791a9e
    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`：机器可读输出（在支持的地方）。

 ## 快速开始（本地）

@ -46,7 +46,7 @@ openclaw browser --browser-profile openclaw snapshot

 如果 `start` 因 `not reachable after start` 失败，请先排查 CDP 就绪状态。如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面是健康的，失败通常是导航 SSRF 策略导致的。

-最小操作序列：
+最小排查步骤：

 ```bash
 openclaw browser --browser-profile openclaw doctor
@ -69,7 +69,7 @@ openclaw browser --browser-profile openclaw reset-profile

 说明：

- 对于 `attachOnly` 和远程 CDP 配置文件，即使 OpenClaw 本身并未启动浏览器进程，`openclaw browser stop` 也会关闭当前控制会话并清除临时模拟覆盖项。
+- 对于 `attachOnly` 和远程 CDP 配置文件，即使 OpenClaw 本身没有启动浏览器进程，`openclaw browser stop` 也会关闭当前控制会话并清除临时模拟覆盖。
 - 对于本地受管配置文件，`openclaw browser stop` 会停止已启动的浏览器进程。

 ## 如果命令缺失
@ -92,9 +92,9 @@ openclaw browser --browser-profile openclaw reset-profile

 ## 配置文件

-配置文件是命名的浏览器路由配置。实际使用中：
+配置文件是具名的浏览器路由配置。实际使用中：

- `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、原始目标 ID 以及唯一的目标 ID 前缀都可被接受。

 ## 快照 / 截图 / 操作

@ -147,10 +147,10 @@ openclaw browser screenshot --labels

 说明：

- `--full-page` 仅用于页面截图；不能与 `--ref` 或 `--element` 组合使用。
- `existing-session` / `user` 配置文件支持页面截图和基于快照输出中 `--ref` 的截图，但不支持基于 CSS `--element` 的截图。
+- `--full-page` 仅用于整页截图；不能与 `--ref` 或 `--element` 组合使用。
+- `existing-session` / `user` 配置文件支持整页截图和基于快照输出的 `--ref` 截图，但不支持 CSS `--element` 截图。
 - `--labels` 会在截图上叠加当前快照引用标签。
- `snapshot --urls` 会将发现的链接目标追加到 AI 快照中，这样智能体可以选择直接的导航目标，而不是仅根据链接文本猜测。
+- `snapshot --urls` 会将已发现的链接目标追加到 AI 快照中，这样智能体就可以选择直接的导航目标，而不必仅根据链接文本猜测。

 导航 / 点击 / 输入（基于 ref 的 UI 自动化）：

@ -169,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>
@ -195,7 +195,7 @@ openclaw browser set headers '{"x-test":"1"}'
 openclaw browser set credentials myuser mypass
 ```

-Cookie + 存储：
+Cookies + 存储：

 ```bash
 openclaw browser cookies
@ -230,29 +230,30 @@ openclaw browser create-profile --name brave-live --driver existing-session --us
 openclaw browser --browser-profile chrome-live tabs
 ```

-这一路径仅适用于主机本机。对于 Docker、无头服务器、Browserless 或其他远程设置，请改用 CDP 配置文件。
+此路径仅适用于宿主机。对于 Docker、无头服务器、Browserless 或其他远程设置，请改用 CDP 配置文件。

 当前 existing-session 的限制：

 - 基于快照的操作使用 ref，而不是 CSS 选择器
+- 当调用方省略 `timeoutMs` 时，`browser.actionTimeoutMs` 会将受支持的 `act` 请求默认设置为 60000 毫秒；但单次调用的 `timeoutMs` 仍然优先生效。
 - `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`
+- 截图支持整页截图和 `--ref`，但不支持 CSS `--element`
 - `responsebody`、下载拦截、PDF 导出和批量操作仍然需要受管浏览器或原始 CDP 配置文件

 ## 远程浏览器控制（节点主机代理）

-如果 Gateway 网关运行在与浏览器不同的机器上，请在安装了 Chrome / Brave / Edge / Chromium 的机器上运行一个**节点主机**。Gateway 网关会将浏览器操作代理到该节点（不需要单独的浏览器控制服务器）。
+如果 Gateway 网关运行在与浏览器不同的机器上，请在安装了 Chrome / Brave / Edge / Chromium 的机器上运行一个**节点主机**。Gateway 网关会将浏览器操作代理到该节点（无需单独的浏览器控制服务器）。

-使用 `gateway.nodes.browser.mode` 控制自动路由，并使用 `gateway.nodes.browser.node` 在连接了多个节点时固定到特定节点。
+使用 `gateway.nodes.browser.mode` 控制自动路由，并在连接了多个节点时使用 `gateway.nodes.browser.node` 固定到特定节点。

-安全性 + 远程设置：[浏览器工具](/zh-CN/tools/browser)、[远程访问](/zh-CN/gateway/remote)、[Tailscale](/zh-CN/gateway/tailscale)、[安全性](/zh-CN/gateway/security)
+安全性和远程设置：[浏览器工具](/zh-CN/tools/browser)、[远程访问](/zh-CN/gateway/remote)、[Tailscale](/zh-CN/gateway/tailscale)、[安全](/zh-CN/gateway/security)

 ## 相关内容

--- a/docs/zh-CN/concepts/memory-builtin.md
+++ b/docs/zh-CN/concepts/memory-builtin.md
@ -1,21 +1,21 @@
 ---
 read_when:
-    - 你想了解默认记忆后端
+    - 你想了解默认的 Memory 后端
    - 你想配置嵌入提供商或混合搜索
-summary: 默认基于 SQLite 的记忆后端，支持关键词、向量和混合搜索
-title: 内置记忆引擎
+summary: 默认基于 SQLite 的 Memory 后端，支持关键词、向量和混合搜索
+title: 内置 Memory 引擎
 x-i18n:
-    generated_at: "2026-04-24T02:14:46Z"
+    generated_at: "2026-04-25T07:22:18Z"
    model: gpt-5.4
    provider: openai
-    source_hash: f82c1f4dc37b4fc6c075a7fcd2ec78bfcbfbebbcba7e48d366a1da3afcaff508
+    source_hash: 9ccf0b70bd3ed4e2138ae1d811573f6920c95eb3f8117693b242732012779dc6
    source_path: concepts/memory-builtin.md
    workflow: 15
 ---

-内置引擎是默认的记忆后端。它会将你的记忆索引存储在每个智能体专属的 SQLite 数据库中，入门时无需额外依赖。
+内置引擎是默认的 Memory 后端。它将你的内存索引存储在每个智能体各自的 SQLite 数据库中，入门时无需任何额外依赖。

-## 它提供的功能
+## 它提供的能力

 - **关键词搜索**：通过 FTS5 全文索引（BM25 评分）实现。
 - **向量搜索**：通过任意受支持提供商提供的嵌入实现。
@ -25,7 +25,7 @@ x-i18n:

 ## 入门指南

-如果你拥有 OpenAI、Gemini、Voyage 或 Mistral 的 API 密钥，内置引擎会自动检测并启用向量搜索。无需配置。
+如果你有 OpenAI、Gemini、Voyage 或 Mistral 的 API 密钥，内置引擎会自动检测并启用向量搜索。无需配置。

 如需显式设置提供商：

@ -43,7 +43,7 @@ x-i18n:

 如果没有嵌入提供商，则只能使用关键词搜索。

-如需强制使用内置本地嵌入提供商，请将 `local.modelPath` 指向一个 GGUF 文件：
+如果你想强制使用内置的本地嵌入提供商，请在 OpenClaw 旁边安装可选的 `node-llama-cpp` 运行时包，然后将 `local.modelPath` 指向一个 GGUF 文件：

 ```json5
 {
@ -63,29 +63,28 @@ x-i18n:

 ## 支持的嵌入提供商

-| 提供商 | ID        | 自动检测 | 说明 |
-| -------- | --------- | ------------- | ----------------------------------- |
-| OpenAI   | `openai`  | 是           | 默认：`text-embedding-3-small`   |
-| Gemini   | `gemini`  | 是           | 支持多模态（图像 + 音频） |
-| Voyage   | `voyage`  | 是           |                                     |
-| Mistral  | `mistral` | 是           |                                     |
-| Ollama   | `ollama`  | 否            | 本地，需显式设置               |
-| Local    | `local`   | 是（优先）   | GGUF 模型，下载大小约 0.6 GB        |
+| 提供商 | ID        | 自动检测 | 说明                                |
+| ------ | --------- | -------- | ----------------------------------- |
+| OpenAI | `openai`  | 是       | 默认：`text-embedding-3-small`      |
+| Gemini | `gemini`  | 是       | 支持多模态（图像 + 音频）           |
+| Voyage | `voyage`  | 是       |                                     |
+| Mistral | `mistral` | 是      |                                     |
+| Ollama | `ollama`  | 否       | 本地，需显式设置                    |
+| Local  | `local`   | 是（优先） | 可选的 `node-llama-cpp` 运行时    |

-自动检测会按照上表顺序，选择第一个可解析出 API 密钥的提供商。设置 `memorySearch.provider` 可覆盖此行为。
+自动检测会按表中所示顺序，选择第一个能够解析出 API 密钥的提供商。设置 `memorySearch.provider` 可覆盖此行为。

 ## 索引的工作方式

-OpenClaw 会将 `MEMORY.md` 和 `memory/*.md` 索引为若干块（约 400 个 token，重叠 80 个 token），并将它们存储在每个智能体专属的 SQLite 数据库中。
+OpenClaw 会将 `MEMORY.md` 和 `memory/*.md` 索引为分块（约 400 个 token，带 80 个 token 重叠），并将其存储在每个智能体各自的 SQLite 数据库中。

 - **索引位置：** `~/.openclaw/memory/<agentId>.sqlite`
- **文件监视：** 记忆文件发生变化时，会触发带防抖的重新索引（1.5 秒）。
+- **文件监听：** 对内存文件的更改会触发防抖后的重新索引（1.5 秒）。
 - **自动重新索引：** 当嵌入提供商、模型或分块配置发生变化时，整个索引会自动重建。
 - **按需重新索引：** `openclaw memory index --force`

 <Info>
-你还可以使用 `memorySearch.extraPaths` 为工作区外的 Markdown 文件建立索引。参见
-[配置参考](/zh-CN/reference/memory-config#additional-memory-paths)。
+你也可以使用 `memorySearch.extraPaths` 为工作区外部的 Markdown 文件建立索引。参见[配置参考](/zh-CN/reference/memory-config#additional-memory-paths)。
 </Info>

 ## 何时使用
@ -97,35 +96,33 @@ OpenClaw 会将 `MEMORY.md` 和 `memory/*.md` 索引为若干块（约 400 个 t
 - 支持所有嵌入提供商。
 - 混合搜索结合了两种检索方式的优势。

-如果你需要重排序、查询扩展，或者希望为工作区外的目录建立索引，可以考虑切换到 [QMD](/zh-CN/concepts/memory-qmd)。
+如果你需要重排、查询扩展，或者想为工作区外的目录建立索引，可以考虑切换到 [QMD](/zh-CN/concepts/memory-qmd)。

-如果你希望获得跨会话记忆以及自动用户建模，可以考虑 [Honcho](/zh-CN/concepts/memory-honcho)。
+如果你想要带有自动用户建模的跨会话记忆，可以考虑 [Honcho](/zh-CN/concepts/memory-honcho)。

 ## 故障排除

-**记忆搜索被禁用？** 检查 `openclaw memory status`。如果未检测到提供商，请显式设置一个，或添加 API 密钥。
+**Memory 搜索已禁用？** 检查 `openclaw memory status`。如果未检测到提供商，请显式设置一个提供商或添加 API 密钥。

-**未检测到本地提供商？** 确认本地路径存在，并运行：
+**未检测到本地提供商？** 确认本地路径存在，然后运行：

 ```bash
 openclaw memory status --deep --agent main
 openclaw memory index --force --agent main
 ```

-独立 CLI 命令和 Gateway 网关使用相同的 `local` 提供商 ID。
-当提供商设置为 `auto` 时，只有在 `memorySearch.local.modelPath` 指向一个现有本地文件的情况下，才会优先考虑本地嵌入。
+独立的 CLI 命令和 Gateway 网关 都使用相同的 `local` 提供商 ID。如果提供商设置为 `auto`，只有当 `memorySearch.local.modelPath` 指向一个存在的本地文件时，才会优先考虑本地嵌入。

-**结果过时？** 运行 `openclaw memory index --force` 以重建索引。监视器在极少数边缘情况下可能会漏掉变更。
+**结果过时？** 运行 `openclaw memory index --force` 进行重建。监听器在极少数边界情况下可能会漏掉更改。

-**sqlite-vec 无法加载？** OpenClaw 会自动回退到进程内余弦相似度计算。请检查日志以查看具体加载错误。
+**sqlite-vec 无法加载？** OpenClaw 会自动回退到进程内余弦相似度计算。请检查日志以获取具体的加载错误。

 ## 配置

-有关嵌入提供商设置、混合搜索调优（权重、MMR、时间衰减）、批量索引、多模态记忆、sqlite-vec、额外路径以及所有其他配置项，请参见
-[记忆配置参考](/zh-CN/reference/memory-config)。
+有关嵌入提供商设置、混合搜索调优（权重、MMR、时间衰减）、批量索引、多模态 Memory、sqlite-vec、额外路径以及所有其他配置项，请参见 [Memory 配置参考](/zh-CN/reference/memory-config)。

 ## 相关内容

- [记忆概览](/zh-CN/concepts/memory)
- [记忆搜索](/zh-CN/concepts/memory-search)
- [活跃记忆](/zh-CN/concepts/active-memory)
+- [Memory 概览](/zh-CN/concepts/memory)
+- [Memory 搜索](/zh-CN/concepts/memory-search)
+- [Active memory](/zh-CN/concepts/active-memory)
--- a/docs/zh-CN/concepts/memory-qmd.md
+++ b/docs/zh-CN/concepts/memory-qmd.md
@ -1,27 +1,27 @@
 ---
 read_when:
-    - 你想将 QMD 设置为你的记忆后端
-    - 你想要高级记忆功能，例如重排或额外的索引路径
-summary: 本地优先的搜索 sidecar，具备 BM25、向量、重排和查询扩展功能
-title: QMD 记忆引擎
+    - 你想将 QMD 设置为你的 memory 后端
+    - 你想要高级 memory 功能，例如重排序或额外的索引路径
+summary: 本地优先的搜索 sidecar，具备 BM25、向量、重排序和查询扩展功能
+title: QMD memory 引擎
 x-i18n:
-    generated_at: "2026-04-23T22:56:50Z"
+    generated_at: "2026-04-25T07:22:21Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 7d7af326291e194a04a17aa425901bf7e2517c23bae8282cd504802d24e9e522
+    source_hash: 89e6a5e0c8f5fb8507dffd08975fec0ca6fda03883079a27c2a28a1d09e95368
    source_path: concepts/memory-qmd.md
    workflow: 15
 ---

-[QMD](https://github.com/tobi/qmd) 是一个本地优先的搜索 sidecar，与 OpenClaw 一同运行。它将 BM25、向量搜索和重排组合进同一个二进制文件中，并且可以索引超出你的工作区记忆文件范围的内容。
+[QMD](https://github.com/tobi/qmd) 是一个本地优先的搜索 sidecar，与 OpenClaw 一起运行。它将 BM25、向量搜索和重排序整合到同一个二进制中，并且可以为超出你的工作区 memory 文件范围的内容建立索引。

-## 相比内置功能增加了什么
+## 相比 builtin 增加了什么

- **重排和查询扩展**，以获得更好的召回效果。
- **索引额外目录** —— 项目文档、团队笔记、磁盘上的任何内容。
- **索引会话转录** —— 回忆更早的对话。
- **完全本地** —— 通过 Bun + node-llama-cpp 运行，并自动下载 GGUF 模型。
- **自动回退** —— 如果 QMD 不可用，OpenClaw 会无缝回退到内置引擎。
+- **重排序和查询扩展**，以获得更好的召回效果。
+- **为额外目录建立索引** —— 项目文档、团队笔记、磁盘上的任何内容。
+- **为会话转录建立索引** —— 回忆更早的对话。
+- **完全本地** —— 使用可选的 `node-llama-cpp` 运行时包，并自动下载 GGUF 模型。
+- **自动回退** —— 如果 QMD 不可用，OpenClaw 会无缝回退到 builtin 引擎。

 ## 入门指南

@ -29,8 +29,8 @@ x-i18n:

 - 安装 QMD：`npm install -g @tobilu/qmd` 或 `bun install -g @tobilu/qmd`
 - 支持扩展的 SQLite 构建版本（在 macOS 上使用 `brew install sqlite`）。
- QMD 必须位于 Gateway 网关的 `PATH` 中。
- macOS 和 Linux 可开箱即用。Windows 最佳支持方式是通过 WSL2。
+- QMD 必须存在于 Gateway 网关的 `PATH` 中。
+- macOS 和 Linux 开箱即用。Windows 最适合通过 WSL2 使用。

 ### 启用

@ -42,25 +42,23 @@ x-i18n:
 }
 ```

-OpenClaw 会在 `~/.openclaw/agents/<agentId>/qmd/` 下创建一个自包含的 QMD 主目录，并自动管理 sidecar 生命周期 —— 集合、更新和嵌入运行都会由它为你处理。
-它会优先使用当前的 QMD collection 和 MCP 查询结构，但在需要时仍会回退到旧版 `--mask` collection 标志和较早的 MCP 工具名称。
-启动时的协调还会在检测到存在同名旧 QMD collection 时，将过时的受管集合重新创建为其规范模式。
+OpenClaw 会在 `~/.openclaw/agents/<agentId>/qmd/` 下创建一个自包含的 QMD 主目录，并自动管理 sidecar 生命周期 —— 集合、更新和嵌入运行都会由它处理。它会优先使用当前的 QMD 集合和 MCP 查询形态，但在需要时仍会回退到旧版的 `--mask` 集合标志和更旧的 MCP 工具名称。启动时的协调流程还会在检测到存在同名旧版 QMD 集合时，将过期的托管集合重新创建为其规范模式。

 ## sidecar 的工作方式

- OpenClaw 会根据你的工作区记忆文件以及任何已配置的 `memory.qmd.paths` 创建集合，然后在启动时和周期性地（默认为每 5 分钟）运行 `qmd update` + `qmd embed`。
- 默认工作区集合会跟踪 `MEMORY.md` 以及 `memory/` 目录树。小写的 `memory.md` 不会被索引为根记忆文件。
- 启动刷新会在后台运行，因此不会阻塞聊天启动。
- 搜索会使用已配置的 `searchMode`（默认：`search`；也支持 `vsearch` 和 `query`）。如果某个模式失败，OpenClaw 会使用 `qmd query` 重试。
- 如果 QMD 完全失败，OpenClaw 会回退到内置 SQLite 引擎。
+- OpenClaw 会根据你的工作区 memory 文件以及所有已配置的 `memory.qmd.paths` 创建集合，然后在启动时和周期性地（默认每 5 分钟）运行 `qmd update` + `qmd embed`。
+- 默认工作区集合会跟踪 `MEMORY.md` 以及 `memory/` 目录树。小写的 `memory.md` 不会作为根 memory 文件建立索引。
+- 启动时刷新会在后台运行，因此不会阻塞聊天启动。
+- 搜索会使用已配置的 `searchMode`（默认：`search`；也支持 `vsearch` 和 `query`）。如果某种模式失败，OpenClaw 会使用 `qmd query` 重试。
+- 如果 QMD 完全失败，OpenClaw 会回退到 builtin SQLite 引擎。

 <Info>
-首次搜索可能会很慢 —— QMD 会在首次运行 `qmd query` 时自动下载用于重排和查询扩展的 GGUF 模型（约 2 GB）。
+第一次搜索可能会很慢 —— QMD 会在首次运行 `qmd query` 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。
 </Info>

 ## 模型覆盖

-QMD 模型环境变量会原样从 Gateway 网关进程透传，因此你可以在不添加新的 OpenClaw 配置的情况下全局调优 QMD：
+QMD 模型环境变量会从 Gateway 网关进程原样透传，因此你可以在不新增 OpenClaw 配置的情况下全局调优 QMD：

 ```bash
 export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
@ -68,11 +66,11 @@ export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"
 export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
 ```

-更改嵌入模型后，请重新运行嵌入，使索引与新的向量空间匹配。
+更改嵌入模型后，请重新运行嵌入，以确保索引与新的向量空间匹配。

-## 索引额外路径
+## 为额外路径建立索引

-将 QMD 指向其他目录，以便让它们也可搜索：
+将 QMD 指向其他目录，使其可被搜索：

 ```json5
 {
@ -85,9 +83,9 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
 }
 ```

-来自额外路径的片段会在搜索结果中显示为 `qmd/<collection>/<relative-path>`。`memory_get` 能识别这个前缀，并从正确的 collection 根目录读取。
+来自额外路径的片段会在搜索结果中显示为 `qmd/<collection>/<relative-path>`。`memory_get` 能理解这个前缀，并从正确的集合根目录读取内容。

-## 索引会话转录
+## 为会话转录建立索引

 启用会话索引以回忆更早的对话：

@ -102,11 +100,11 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
 }
 ```

-转录会作为经过清理的用户/助手轮次导出到专用的 QMD collection 中，位置为 `~/.openclaw/agents/<id>/qmd/sessions/`。
+转录内容会作为经过净化的用户 / 助手轮次导出到位于 `~/.openclaw/agents/<id>/qmd/sessions/` 下的专用 QMD 集合中。

 ## 搜索范围

-默认情况下，QMD 搜索结果会显示在私聊和渠道会话中（不包括群组）。可配置 `memory.qmd.scope` 来更改这一点：
+默认情况下，QMD 搜索结果会显示在直接会话和渠道会话中（不包括群组）。通过配置 `memory.qmd.scope` 来更改此行为：

 ```json5
 {
@ -121,46 +119,45 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
 }
 ```

-当范围规则拒绝某次搜索时，OpenClaw 会记录一条警告，其中包含推导出的渠道和聊天类型，以便更容易调试空结果。
+当范围规则拒绝某次搜索时，OpenClaw 会记录一条警告日志，其中包含推导出的渠道和聊天类型，以便更容易调试空结果问题。

 ## 引用

-当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含 `Source: <path#line>` 页脚。将 `memory.citations = "off"` 可省略该页脚，同时仍在内部将路径传递给智能体。
+当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含一个 `Source: <path#line>` 页脚。将 `memory.citations = "off"` 可省略该页脚，同时仍在内部将路径传递给智能体。

 ## 何时使用

 当你需要以下能力时，请选择 QMD：

- 通过重排获得更高质量的结果。
- 搜索工作区之外的项目文档或笔记。
+- 使用重排序获得更高质量的结果。
+- 搜索工作区外的项目文档或笔记。
 - 回忆过去的会话对话。
- 完全本地搜索，无需 API 密钥。
+- 完全本地的搜索，无需 API 密钥。

-对于更简单的设置，[内置引擎](/zh-CN/concepts/memory-builtin) 在没有额外依赖的情况下也能很好地工作。
+对于更简单的设置，[builtin 引擎](/zh-CN/concepts/memory-builtin) 在无需额外依赖的情况下也能很好地工作。

 ## 故障排除

-**找不到 QMD？** 请确保该二进制文件位于 Gateway 网关的 `PATH` 中。如果 OpenClaw 作为服务运行，请创建一个符号链接：
+**找不到 QMD？** 确保该二进制位于 Gateway 网关的 `PATH` 中。如果 OpenClaw 作为服务运行，请创建一个符号链接：
 `sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`。

-**首次搜索很慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录运行 `qmd query "test"` 进行预热。
+**第一次搜索很慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录运行 `qmd query "test"` 进行预热。

 **搜索超时？** 增加 `memory.qmd.limits.timeoutMs`（默认：4000ms）。对于较慢的硬件，可设置为 `120000`。

-**群聊中结果为空？** 检查 `memory.qmd.scope` —— 默认只允许私聊和渠道会话。
+**群聊中结果为空？** 检查 `memory.qmd.scope` —— 默认只允许直接会话和渠道会话。

-**根记忆搜索突然变得过宽？** 重启 Gateway 网关，或等待下一次启动协调。OpenClaw 在检测到同名冲突时，会将过时的受管集合重新创建回规范的 `MEMORY.md` 和 `memory/` 模式。
+**根 memory 搜索突然变得过于宽泛？** 重启 Gateway 网关，或等待下一次启动协调。OpenClaw 会在检测到同名冲突时，将过期的托管集合重新创建为规范的 `MEMORY.md` 和 `memory/` 模式。

-**工作区中可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？**
-QMD 当前的遍历遵循底层 QMD 扫描器行为，而不是 OpenClaw 内置的符号链接规则。在 QMD 暴露出防循环遍历或显式排除控制之前，请将临时 monorepo 检出保存在 `.tmp/` 之类的隐藏目录下，或放在已索引 QMD 根目录之外。
+**工作区可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？** QMD 当前的遍历行为遵循底层 QMD 扫描器的行为，而不是 OpenClaw builtin 的符号链接规则。在 QMD 提供具备循环安全的遍历或显式排除控制之前，请将临时 monorepo 检出保存在 `.tmp/` 这样的隐藏目录下，或放在已建立索引的 QMD 根目录之外。

 ## 配置

-有关完整配置表面（`memory.qmd.*`）、搜索模式、更新间隔、范围规则及所有其他旋钮，请参见
-[记忆配置参考](/zh-CN/reference/memory-config)。
+如需查看完整的配置项（`memory.qmd.*`）、搜索模式、更新间隔、范围规则以及其他所有可调参数，请参阅
+[Memory 配置参考](/zh-CN/reference/memory-config)。

 ## 相关内容

- [记忆概览](/zh-CN/concepts/memory)
- [内置记忆引擎](/zh-CN/concepts/memory-builtin)
- [Honcho 记忆](/zh-CN/concepts/memory-honcho)
+- [Memory 概览](/zh-CN/concepts/memory)
+- [Builtin memory 引擎](/zh-CN/concepts/memory-builtin)
+- [Honcho memory](/zh-CN/concepts/memory-honcho)
--- a/docs/zh-CN/concepts/memory-search.md
+++ b/docs/zh-CN/concepts/memory-search.md
@ -1,49 +1,49 @@
 ---
 read_when:
-    - 你想了解 `memory_search` 的工作原理
+    - 你想了解 `memory_search` 是如何工作的
    - 你想选择一个嵌入提供商
-    - 你想调优搜索质量
+    - 你想调整搜索质量
 summary: 记忆搜索如何使用嵌入和混合检索来查找相关笔记
 title: 记忆搜索
 x-i18n:
-    generated_at: "2026-04-23T22:56:51Z"
+    generated_at: "2026-04-25T07:22:21Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 04db62e519a691316ce40825c082918094bcaa9c36042cc8101c6504453d238e
+    source_hash: 5cc6bbaf7b0a755bbe44d3b1b06eed7f437ebdc41a81c48cca64bd08bbc546b7
    source_path: concepts/memory-search.md
    workflow: 15
 ---

-`memory_search` 会从你的记忆文件中查找相关笔记，即使措辞与原文不同也可以。它通过将记忆索引为小块，并使用嵌入、关键词或两者结合来进行搜索。
+`memory_search` 会从你的记忆文件中查找相关笔记，即使措辞与原始文本不同也可以。它通过将记忆索引为小块，并使用嵌入、关键词或两者结合来搜索这些内容。

 ## 快速开始

-如果你已配置 GitHub Copilot 订阅，或 OpenAI、Gemini、Voyage、Mistral 的 API key，记忆搜索会自动生效。若要显式设置提供商：
+如果你已配置 GitHub Copilot 订阅、OpenAI、Gemini、Voyage 或 Mistral 的 API key，记忆搜索会自动生效。要显式设置提供商：

 ```json5
 {
  agents: {
    defaults: {
      memorySearch: {
-        provider: "openai", // or "gemini", "local", "ollama", etc.
+        provider: "openai", // 或 "gemini"、"local"、"ollama" 等
      },
    },
  },
 }
 ```

-对于不使用 API key 的本地嵌入，请使用 `provider: "local"`（需要 `node-llama-cpp`）。
+如果你想使用无需 API key 的本地嵌入，请在 OpenClaw 旁边安装可选的 `node-llama-cpp` 运行时包，并使用 `provider: "local"`。

 ## 支持的提供商

 | 提供商 | ID | 需要 API key | 说明 |
 | -------------- | ---------------- | ------------- | ---------------------------------------------------- |
-| Bedrock | `bedrock` | 否 | 当 AWS 凭证链可解析时自动检测 |
+| Bedrock | `bedrock` | 否 | 当 AWS 凭证链解析成功时自动检测 |
 | Gemini | `gemini` | 是 | 支持图像/音频索引 |
 | GitHub Copilot | `github-copilot` | 否 | 自动检测，使用 Copilot 订阅 |
 | Local | `local` | 否 | GGUF 模型，下载大小约 0.6 GB |
 | Mistral | `mistral` | 是 | 自动检测 |
-| Ollama | `ollama` | 否 | 本地提供商，必须显式设置 |
+| Ollama | `ollama` | 否 | 本地，必须显式设置 |
 | OpenAI | `openai` | 是 | 自动检测，速度快 |
 | Voyage | `voyage` | 是 | 自动检测 |

@ -62,28 +62,28 @@ flowchart LR
    M --> R["Top Results"]
 ```

- **向量搜索** 用于查找语义相近的笔记（例如 “gateway host” 可匹配 “the machine running OpenClaw”）。
- **BM25 关键词搜索** 用于查找精确匹配项（ID、错误字符串、配置键）。
+- **向量搜索** 会查找语义相近的笔记（“gateway host” 可匹配 “the machine running OpenClaw”）。
+- **BM25 关键词搜索** 会查找精确匹配（ID、错误字符串、配置键）。

-如果只有一条路径可用（没有嵌入或没有 FTS），则仅运行另一条路径。
+如果只有一条路径可用（没有嵌入或没有 FTS），则只运行另一条路径。

-当嵌入不可用时，OpenClaw 仍会基于 FTS 结果使用词法排序，而不是只回退到原始精确匹配顺序。在这种降级模式下，它会提升查询词覆盖度更高且文件路径更相关的块，因此即使没有 `sqlite-vec` 或嵌入提供商，召回效果仍然可用。
+当嵌入不可用时，OpenClaw 仍会对 FTS 结果使用词法排序，而不是只退回到原始精确匹配顺序。这种降级模式会提升那些查询词覆盖更强、文件路径更相关的内容块，因此即使没有 `sqlite-vec` 或嵌入提供商，也能保持较好的召回效果。

-## 提升搜索质量
+## 改进搜索质量

-当你有大量笔记历史时，两个可选功能会很有帮助：
+当你拥有大量笔记历史时，有两个可选功能会很有帮助：

 ### 时间衰减

-旧笔记的排名权重会逐渐降低，因此最近的信息会优先显示。使用默认的 30 天半衰期时，上个月的笔记得分会降至原始权重的 50%。像 `MEMORY.md` 这样的常青文件永远不会衰减。
+旧笔记的排序权重会逐渐降低，因此最近的信息会优先显示。使用默认的 30 天半衰期时，上个月的笔记得分会降到原始权重的 50%。像 `MEMORY.md` 这样的常青文件永远不会衰减。

 <Tip>
-如果你的智能体已有数月的每日笔记，并且过时信息总是排在最新上下文前面，请启用时间衰减。
+如果你的智能体已经积累了数月的每日笔记，而过时信息总是排在最近上下文之前，请启用时间衰减。
 </Tip>

 ### MMR（多样性）

-减少重复结果。如果有五条笔记都提到同一个路由器配置，MMR 会确保顶部结果覆盖不同主题，而不是重复展示。
+减少重复结果。如果五条笔记都提到了同一个路由器配置，MMR 会确保顶部结果覆盖不同主题，而不是重复相同内容。

 <Tip>
 如果 `memory_search` 总是从不同的每日笔记中返回几乎重复的片段，请启用 MMR。
@ -110,28 +110,28 @@ flowchart LR

 ## 多模态记忆

-通过 Gemini Embedding 2，你可以将图像和音频文件与 Markdown 一起建立索引。搜索查询仍然是文本，但它们会匹配视觉和音频内容。设置方法请参见[记忆配置参考](/zh-CN/reference/memory-config)。
+使用 Gemini Embedding 2 时，你可以在 Markdown 之外为图像和音频文件建立索引。搜索查询仍然是文本，但会匹配视觉和音频内容。设置方法请参阅[记忆配置参考](/zh-CN/reference/memory-config)。

 ## 会话记忆搜索

-你也可以选择为会话转录建立索引，这样 `memory_search` 就能回忆更早的对话。这是通过 `memorySearch.experimental.sessionMemory` 主动启用的。详见[配置参考](/zh-CN/reference/memory-config)。
+你还可以选择为会话转录建立索引，这样 `memory_search` 就能回忆更早的对话。这是通过 `memorySearch.experimental.sessionMemory` 选择启用的。详情请参阅[配置参考](/zh-CN/reference/memory-config)。

 ## 故障排除

 **没有结果？** 运行 `openclaw memory status` 检查索引。如果为空，运行 `openclaw memory index --force`。

-**只有关键词匹配？** 你的嵌入提供商可能未配置。检查 `openclaw memory status --deep`。
+**只有关键词匹配？** 你的嵌入提供商可能尚未配置。检查 `openclaw memory status --deep`。

 **找不到 CJK 文本？** 使用 `openclaw memory index --force` 重建 FTS 索引。

 ## 延伸阅读

 - [Active Memory](/zh-CN/concepts/active-memory) -- 用于交互式聊天会话的子智能体记忆
- [记忆](/zh-CN/concepts/memory) -- 文件布局、后端、工具
+- [Memory](/zh-CN/concepts/memory) -- 文件布局、后端、工具
 - [记忆配置参考](/zh-CN/reference/memory-config) -- 所有配置项

-## 相关
+## 相关内容

 - [记忆概览](/zh-CN/concepts/memory)
- [Active Memory](/zh-CN/concepts/active-memory)
+- [Active memory](/zh-CN/concepts/active-memory)
 - [内置记忆引擎](/zh-CN/concepts/memory-builtin)
--- a/docs/zh-CN/logging.md
+++ b/docs/zh-CN/logging.md
@ -6,26 +6,26 @@ read_when:
 summary: 日志概览：文件日志、控制台输出、CLI 尾随查看，以及 Control UI
 title: 日志概览
 x-i18n:
-    generated_at: "2026-04-25T07:01:13Z"
+    generated_at: "2026-04-25T07:22:21Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 7f9593b117ef2ba76dbe91d5b38e3f463b358631961c9d44beed3aee6152f9a2
+    source_hash: c1a8ec7992c0c1b59036ccfd2b6d1d844c68f78cec14ff8eebddeac67f3fc607
    source_path: logging.md
    workflow: 15
 ---

 # 日志

-OpenClaw 有两个主要的日志界面：
+OpenClaw 有两个主要的日志表面：

 - 由 Gateway 网关写入的**文件日志**（JSON 行）。
 - 在终端和 Gateway 网关调试 UI 中显示的**控制台输出**。

-Control UI 的**日志**标签页会尾随显示 gateway 文件日志。本页说明日志位于哪里、如何读取，以及如何配置日志级别和格式。
+Control UI 的**日志**标签页会尾随显示 gateway 文件日志。此页面会说明日志位于哪里、如何读取日志，以及如何配置日志级别和格式。

-## 日志位置
+## 日志存放位置

-默认情况下，Gateway 网关会将滚动日志文件写入以下位置：
+默认情况下，Gateway 网关会在以下位置写入滚动日志文件：

 `/tmp/openclaw/openclaw-YYYY-MM-DD.log`

@ -51,32 +51,32 @@ Control UI 的**日志**标签页会尾随显示 gateway 文件日志。本页
 openclaw logs --follow
 ```

-当前实用选项：
+当前有用的选项：

- `--local-time`：使用你的本地时区渲染时间戳
+- `--local-time`：使用你的本地时区显示时间戳
 - `--url <url>` / `--token <token>` / `--timeout <ms>`：标准 Gateway 网关 RPC 标志
- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（此处通过共享客户端层接受）
+- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（通过共享客户端层在此处接受）

 输出模式：

- **TTY 会话**：美观、彩色、结构化的日志行。
+- **TTY 会话**：美观、带颜色、结构化的日志行。
 - **非 TTY 会话**：纯文本。
 - `--json`：按行分隔的 JSON（每行一个日志事件）。
 - `--plain`：在 TTY 会话中强制使用纯文本。
 - `--no-color`：禁用 ANSI 颜色。

-当你传入显式的 `--url` 时，CLI 不会自动应用配置或环境变量凭证；如果目标 Gateway 网关需要身份验证，请自行包含 `--token`。
+当你显式传入 `--url` 时，CLI 不会自动应用配置或环境变量中的凭证；如果目标 Gateway 网关需要认证，请自行附带 `--token`。

-在 JSON 模式下，CLI 会输出带 `type` 标签的对象：
+在 JSON 模式下，CLI 会输出带 `type` 标记的对象：

 - `meta`：流元数据（文件、游标、大小）
 - `log`：已解析的日志条目
 - `notice`：截断 / 轮转提示
 - `raw`：未解析的原始日志行

-如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式 `--url` 目标不会使用此回退。
+如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式指定的 `--url` 目标不会使用此回退机制。

-如果 Gateway 网关不可达，CLI 会打印一条简短提示，建议运行：
+如果 Gateway 网关无法连接，CLI 会打印一个简短提示，建议运行：

 ```bash
 openclaw doctor
@ -84,7 +84,7 @@ openclaw doctor

 ### Control UI（网页）

-Control UI 的**日志**标签页会使用 `logs.tail` 尾随查看同一个文件。
+Control UI 的**日志**标签页使用 `logs.tail` 尾随查看同一个文件。
 有关如何打开它，请参见 [/web/control-ui](/zh-CN/web/control-ui)。

 ### 仅渠道日志
@ -103,7 +103,7 @@ openclaw channels logs --channel whatsapp

 ### 控制台输出

-控制台日志是**TTY 感知的**，并针对可读性进行了格式化：
+控制台日志是**感知 TTY** 的，并针对可读性进行了格式化：

 - 子系统前缀（例如 `gateway/channels/whatsapp`）
 - 级别颜色（info/warn/error）
@ -113,11 +113,11 @@ openclaw channels logs --channel whatsapp

 ### Gateway 网关 WebSocket 日志

-`openclaw gateway` 还支持用于 RPC 流量的 WebSocket 协议日志：
+`openclaw gateway` 还提供用于 RPC 流量的 WebSocket 协议日志：

- 普通模式：仅显示重要结果（错误、解析错误、慢调用）
- `--verbose`：显示所有请求 / 响应流量
- `--ws-log auto|compact|full`：选择详细日志的渲染样式
+- 普通模式：仅显示值得关注的结果（错误、解析错误、慢调用）
+- `--verbose`：显示所有请求/响应流量
+- `--ws-log auto|compact|full`：选择详细输出的渲染样式
 - `--compact`：`--ws-log compact` 的别名

 示例：
@ -128,9 +128,9 @@ openclaw gateway --verbose --ws-log compact
 openclaw gateway --verbose --ws-log full
 ```

-## 配置日志记录
+## 配置日志

-所有日志配置都位于 `~/.openclaw/openclaw.json` 的 `logging` 下。
+所有日志配置都位于 `~/.openclaw/openclaw.json` 中的 `logging` 下。

 ```json
 {
@ -150,7 +150,7 @@ openclaw gateway --verbose --ws-log full
 - `logging.level`：**文件日志**（JSONL）级别。
 - `logging.consoleLevel`：**控制台**详细程度级别。

-你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两个设置（例如 `OPENCLAW_LOG_LEVEL=debug`）。环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅针对单次运行提高详细程度。你也可以传递全局 CLI 选项 **`--log-level <level>`**（例如，`openclaw --log-level debug gateway run`），它会为该命令覆盖环境变量。
+你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两者（例如 `OPENCLAW_LOG_LEVEL=debug`）。环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅针对单次运行提高详细程度。你也可以传入全局 CLI 选项 **`--log-level <level>`**（例如，`openclaw --log-level debug gateway run`），它会在该命令中覆盖环境变量。

 `--verbose` 只影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。

@ -159,48 +159,48 @@ openclaw gateway --verbose --ws-log full
 `logging.consoleStyle`：

 - `pretty`：适合人工阅读、带颜色、带时间戳。
- `compact`：更紧凑的输出（最适合长时间会话）。
- `json`：每行一个 JSON（用于日志处理器）。
+- `compact`：更紧凑的输出（适合长时间会话）。
+- `json`：每行一个 JSON（适用于日志处理器）。

 ### 脱敏

-工具摘要可以在输出到控制台之前，对敏感令牌进行脱敏：
+工具摘要在输出到控制台之前可以对敏感令牌进行脱敏：

 - `logging.redactSensitive`：`off` | `tools`（默认：`tools`）
 - `logging.redactPatterns`：用于覆盖默认集合的正则表达式字符串列表

 脱敏**仅影响控制台输出**，不会修改文件日志。

-## Diagnostics + OpenTelemetry
+## 诊断 + OpenTelemetry

-诊断是面向模型运行**以及**消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志；它们的存在是为了向指标、追踪和其他导出器提供数据。
+诊断是用于模型运行**以及**消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志；它们的存在是为了向指标、追踪和其他导出器提供数据。

 诊断事件会在进程内发出，但只有在启用 diagnostics 和导出器插件后，导出器才会附加。

-### OpenTelemetry 与 OTLP
+### OpenTelemetry 与 OTLP 的区别

 - **OpenTelemetry（OTel）**：用于追踪、指标和日志的数据模型 + SDK。
- **OTLP**：用于将 OTel 数据导出到采集器 / 后端的线协议。
+- **OTLP**：用于将 OTel 数据导出到收集器 / 后端的线协议。
 - OpenClaw 当前通过 **OTLP/HTTP（protobuf）** 导出。

 ### 导出的信号

- **指标**：计数器 + 直方图（令牌使用、消息流、排队）。
- **追踪**：用于模型使用和 webhook / 消息处理的 span。
- **日志**：当启用 `diagnostics.otel.logs` 时，通过 OTLP 导出。日志量可能很大；请留意 `logging.level` 和导出器过滤器。
+- **指标**：计数器 + 直方图（令牌使用量、消息流、排队）。
+- **追踪**：用于模型使用 + webhook / 消息处理的 span。
+- **日志**：当启用 `diagnostics.otel.logs` 时通过 OTLP 导出。日志量可能很大；请留意 `logging.level` 和导出器过滤器。

 ### 诊断事件目录

 模型使用：

- `model.usage`：令牌、成本、持续时间、上下文、provider / 模型 / 渠道、会话 id。
+- `model.usage`：令牌、成本、持续时间、上下文、提供商 / 模型 / 渠道、会话 ID。

 消息流：

- `webhook.received`：每个渠道的 webhook 入站。
+- `webhook.received`：按渠道统计的 webhook 入站。
 - `webhook.processed`：webhook 已处理 + 持续时间。
 - `webhook.error`：webhook 处理器错误。
- `message.queued`：消息已入队等待处理。
+- `message.queued`：消息已加入处理队列。
 - `message.processed`：结果 + 持续时间 + 可选错误。

 队列 + 会话：
@ -208,13 +208,17 @@ openclaw gateway --verbose --ws-log full
 - `queue.lane.enqueue`：命令队列 lane 入队 + 深度。
 - `queue.lane.dequeue`：命令队列 lane 出队 + 等待时间。
 - `session.state`：会话状态转换 + 原因。
- `session.stuck`：会话卡住警告 + 已持续时长。
+- `session.stuck`：会话卡住警告 + 持续时长。
 - `run.attempt`：运行重试 / 尝试元数据。
- `diagnostic.heartbeat`：聚合计数器（webhooks / queue / session）。
+- `diagnostic.heartbeat`：聚合计数器（webhook / 队列 / 会话）。
+
+执行：
+
+- `exec.process.completed`：终端 exec 进程结果、持续时间、目标、模式、退出码和失败类型。不包含命令文本和工作目录。

 ### 启用 diagnostics（无导出器）

-如果你希望 diagnostics 事件可供插件或自定义接收器使用，请使用此配置：
+如果你希望 diagnostics 事件可供插件或自定义接收端使用，请使用此配置：

 ```json
 {
@ -224,10 +228,9 @@ openclaw gateway --verbose --ws-log full
 }
 ```

-### Diagnostics 标志（定向日志）
+### diagnostics 标志（定向日志）

-使用标志启用额外的、定向的调试日志，而无需提高 `logging.level`。
-标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）。
+使用标志可以在不提高 `logging.level` 的情况下开启额外的定向调试日志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）。

 ```json
 {
@ -245,14 +248,13 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

 说明：

- 标志日志会进入标准日志文件（与 `logging.file` 相同）。
- 输出仍会按照 `logging.redactSensitive` 进行脱敏。
+- 标志日志会写入标准日志文件（与 `logging.file` 相同）。
+- 输出仍会根据 `logging.redactSensitive` 进行脱敏。
 - 完整指南：[/diagnostics/flags](/zh-CN/diagnostics/flags)。

 ### 导出到 OpenTelemetry

-Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。
-这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 采集器 / 后端。
+可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出 diagnostics。这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 收集器 / 后端。

 ```json
 {
@ -293,14 +295,14 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。

 - 你也可以使用 `openclaw plugins enable diagnostics-otel` 启用该插件。
 - `protocol` 当前仅支持 `http/protobuf`。`grpc` 会被忽略。
- 指标包括令牌使用、成本、上下文大小、运行时长，以及消息流计数器 / 直方图（webhooks、排队、会话状态、队列深度 / 等待）。
- 可以通过 `traces` / `metrics` 切换追踪 / 指标（默认：开启）。启用时，追踪包括模型使用 span，以及 webhook / 消息处理 span。
- 默认不会导出原始模型 / 工具内容。仅当你的采集器和保留策略已获批准，可处理提示词、响应、工具或系统提示词文本时，才使用 `diagnostics.otel.captureContent`。
- 当你的采集器需要身份验证时，请设置 `headers`。
+- 指标包括令牌使用量、成本、上下文大小、运行时长，以及消息流计数器 / 直方图（webhook、排队、会话状态、队列深度 / 等待时间）。
+- 可以使用 `traces` / `metrics` 开关来控制是否导出追踪 / 指标（默认：开启）。启用后，追踪包括模型使用 span，以及 webhook / 消息处理 span。
+- 默认不会导出原始模型 / 工具内容。仅当你的收集器和保留策略已批准保存提示词、响应、工具或系统提示文本时，才使用 `diagnostics.otel.captureContent`。
+- 当你的收集器需要认证时，请设置 `headers`。
 - 支持的环境变量：`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_PROTOCOL`。
- 当另一个预加载项或宿主进程已经注册了全局 OpenTelemetry SDK 时，请设置 `OPENCLAW_OTEL_PRELOADED=1`。在该模式下，插件不会启动或关闭其自己的 SDK，但它仍会连接 OpenClaw 诊断监听器，并遵循 `diagnostics.otel.traces`、`metrics` 和 `logs`。
+- 当另一个预加载项或宿主进程已经注册全局 OpenTelemetry SDK 时，设置 `OPENCLAW_OTEL_PRELOADED=1`。在该模式下，插件不会启动或关闭它自己的 SDK，但仍会连接 OpenClaw 诊断监听器，并遵循 `diagnostics.otel.traces`、`metrics` 和 `logs`。

-### 导出的指标（名称 + 类型）
+### 已导出的指标（名称 + 类型）

 模型使用：

@ -329,7 +331,11 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。
 - `openclaw.session.stuck_age_ms`（直方图，属性：`openclaw.state`）
 - `openclaw.run.attempt`（计数器，属性：`openclaw.attempt`）

-### 导出的 span（名称 + 关键属性）
+执行：
+
+- `openclaw.exec.duration_ms`（直方图，属性：`openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`）
+
+### 已导出的 span（名称 + 关键属性）

 - `openclaw.model.usage`
  - `openclaw.channel`、`openclaw.provider`、`openclaw.model`
@ -344,6 +350,10 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。
 - `openclaw.tool.execution`
  - `gen_ai.tool.name`、`openclaw.toolName`、`openclaw.errorCategory`、
    `openclaw.tool.params.*`
+- `openclaw.exec`
+  - `openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、
+    `openclaw.failureKind`、`openclaw.exec.command_length`、
+    `openclaw.exec.exit_code`、`openclaw.exec.timed_out`
 - `openclaw.webhook.processed`
  - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId`
 - `openclaw.webhook.error`
@ -355,7 +365,7 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。
 - `openclaw.session.stuck`
  - `openclaw.state`、`openclaw.ageMs`、`openclaw.queueDepth`

-当显式启用内容捕获时，模型 / 工具 span 还可以包含有界且已脱敏的 `openclaw.content.*` 属性，适用于你明确选择启用的特定内容类别。
+当显式启用内容捕获时，模型 / 工具 span 还可以包含有界且已脱敏的 `openclaw.content.*` 属性，用于你选择启用的特定内容类别。

 ### 采样 + 刷新

@ -364,12 +374,12 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。

 ### 协议说明

- OTLP/HTTP 端点可以通过 `diagnostics.otel.endpoint` 或
-  `OTEL_EXPORTER_OTLP_ENDPOINT` 设置。
+- 可以通过 `diagnostics.otel.endpoint` 或
+  `OTEL_EXPORTER_OTLP_ENDPOINT` 设置 OTLP/HTTP 端点。
 - 如果端点已包含 `/v1/traces` 或 `/v1/metrics`，则会按原样使用。
- 如果端点已包含 `/v1/logs`，则日志也会按原样使用该端点。
+- 如果端点已包含 `/v1/logs`，则会按原样用于日志。
 - `OPENCLAW_OTEL_PRELOADED=1` 会复用外部已注册的 OpenTelemetry SDK
-  来处理追踪 / 指标，而不是启动由插件拥有的 NodeSDK。
+  用于追踪 / 指标，而不是启动由插件拥有的 NodeSDK。
 - `diagnostics.otel.logs` 会为主日志记录器输出启用 OTLP 日志导出。

 ### 日志导出行为
@ -377,13 +387,13 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。
 - OTLP 日志使用与写入 `logging.file` 相同的结构化记录。
 - 遵循 `logging.level`（文件日志级别）。控制台脱敏**不会**应用于
  OTLP 日志。
- 高日志量的部署应优先使用 OTLP 采集器的采样 / 过滤功能。
+- 对于高流量安装，应该优先使用 OTLP 收集器采样 / 过滤。

 ## 故障排除提示

- **Gateway 网关不可达？** 先运行 `openclaw doctor`。
- **日志为空？** 检查 Gateway 网关是否正在运行，以及是否正在写入 `logging.file`
-  中的文件路径。
+- **Gateway 网关无法连接？** 请先运行 `openclaw doctor`。
+- **日志为空？** 检查 Gateway 网关是否正在运行，以及是否正在向
+  `logging.file` 中的文件路径写入。
 - **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace` 后重试。

 ## 相关内容
--- a/docs/zh-CN/plugins/google-meet.md
+++ b/docs/zh-CN/plugins/google-meet.md
@ -1,36 +1,37 @@
 ---
 read_when:
-    - 你希望一个 OpenClaw 智能体加入 Google Meet 通话
-    - 你希望一个 OpenClaw 智能体创建一个新的 Google Meet 通话
+    - 你想让一个 OpenClaw 智能体加入 Google Meet 通话
+    - 你想让一个 OpenClaw 智能体创建新的 Google Meet 通话
    - 你正在将 Chrome、Chrome 节点或 Twilio 配置为 Google Meet 传输方式
-summary: Google Meet 插件：通过 Chrome 或 Twilio 加入显式的 Meet URL，并默认启用实时语音
+summary: Google Meet 插件：通过 Chrome 或 Twilio 加入明确的 Meet URL，并使用默认的实时语音设置
 title: Google Meet 插件
 x-i18n:
-    generated_at: "2026-04-25T07:07:51Z"
+    generated_at: "2026-04-25T07:22:35Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 16291e144ff60b88af8ca182d5b67233af1ff3b00ea414fae18c46fb2ef909fb
+    source_hash: e03741b598614233496d208b2fff85077f31a4c37814c1c915dc6d6fda32ef2e
    source_path: plugins/google-meet.md
    workflow: 15
 ---

-OpenClaw 的 Google Meet 参与者支持——该插件在设计上是显式的：
+OpenClaw 的 Google Meet 参会支持——该插件在设计上就是显式的：

- 它只会加入显式的 `https://meet.google.com/...` URL。
- 它可以通过 Google Meet API 创建一个新的 Meet 空间，然后加入返回的 URL。
+- 它只会加入明确的 `https://meet.google.com/...` URL。
+- 它可以通过 Google Meet API 创建新的 Meet 空间，然后加入返回的 URL。
 - `realtime` 语音是默认模式。
 - 当需要更深入的推理或工具时，实时语音可以回调到完整的 OpenClaw 智能体。
- 智能体通过 `mode` 选择加入行为：实时收听/回话使用 `realtime`，加入/控制浏览器但不启用实时语音桥接则使用 `transcribe`。
- 认证起始方式可以是个人 Google OAuth，或一个已经登录的 Chrome 配置文件。
- 不会自动播报同意声明。
+- 智能体通过 `mode` 选择加入行为：使用 `realtime` 进行实时收听/回话，或使用 `transcribe` 在不启用实时语音桥接的情况下加入/控制浏览器。
+- 认证从个人 Google OAuth 或已登录的 Chrome 配置文件开始。
+- 没有自动的同意提示公告。
 - 默认的 Chrome 音频后端是 `BlackHole 2ch`。
 - Chrome 可以在本地运行，也可以在已配对的节点主机上运行。
- Twilio 接受一个拨入号码，以及可选的 PIN 或 DTMF 序列。
- CLI 命令是 `googlemeet`；`meet` 保留给更广义的智能体电话会议工作流。
+- Twilio 接受拨入号码，以及可选的 PIN 或 DTMF 序列。
+- CLI 命令是 `googlemeet`；`meet` 保留给更广泛的智能体电话会议工作流使用。

 ## 快速开始

-安装本地音频依赖，并配置一个后端实时语音提供商。OpenAI 是默认选项；Google Gemini Live 也可用，需配合 `realtime.provider: "google"`：
+安装本地音频依赖并配置一个后端实时语音提供商。OpenAI 是默认选项；Google Gemini Live 也可用，使用
+`realtime.provider: "google"`：

 ```bash
 brew install blackhole-2ch sox
@ -39,13 +40,13 @@ export OPENAI_API_KEY=sk-...
 export GEMINI_API_KEY=...
 ```

-`blackhole-2ch` 会安装 `BlackHole 2ch` 虚拟音频设备。Homebrew 的安装程序要求重启后，macOS 才会暴露该设备：
+`blackhole-2ch` 会安装 `BlackHole 2ch` 虚拟音频设备。Homebrew 的安装程序要求重启，macOS 才会暴露该设备：

 ```bash
 sudo reboot
 ```

-重启后，验证这两项都已就绪：
+重启后，验证这两项是否都已就绪：

 ```bash
 system_profiler SPAudioDataType | grep -i BlackHole
@ -73,9 +74,9 @@ command -v rec play
 openclaw googlemeet setup
 ```

-设置输出旨在便于智能体读取。它会报告 Chrome 配置文件、音频桥接、节点固定、延迟的实时介绍，以及在配置了 Twilio 委托时，`voice-call` 插件和 Twilio 凭证是否已就绪。
-将任何 `ok: false` 的检查都视为阻塞项，在要求智能体加入之前先解决。
-脚本或机器可读输出请使用 `openclaw googlemeet setup --json`。
+设置输出旨在让智能体可读。它会报告 Chrome 配置文件、音频桥接、节点固定、延迟实时介绍，以及在配置了 Twilio 委派时，`voice-call` 插件和 Twilio 凭证是否已就绪。
+在要求智能体加入之前，应将任何 `ok: false` 检查视为阻塞项。
+对脚本或机器可读输出，请使用 `openclaw googlemeet setup --json`。

 加入会议：

@ -94,13 +95,13 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij
 }
 ```

-创建一个新会议并加入：
+创建新会议并加入：

 ```bash
 openclaw googlemeet create --transport chrome-node --mode realtime
 ```

-仅创建 URL 而不加入：
+只创建 URL 而不加入：

 ```bash
 openclaw googlemeet create --no-join
@ -108,14 +109,17 @@ openclaw googlemeet create --no-join

 `googlemeet create` 有两条路径：

- API 创建：当配置了 Google Meet OAuth 凭证时使用。这是最可预测的路径，并且不依赖浏览器 UI 状态。
+- API 创建：当已配置 Google Meet OAuth 凭证时使用。这是最确定性的路径，不依赖浏览器 UI 状态。
 - 浏览器回退：当缺少 OAuth 凭证时使用。OpenClaw 会使用固定的 Chrome 节点，打开 `https://meet.google.com/new`，等待 Google 重定向到真实的会议代码 URL，然后返回该 URL。这条路径要求节点上的 OpenClaw Chrome 配置文件已经登录 Google。
-  浏览器自动化会处理 Meet 自身的首次运行麦克风提示；该提示不会被视为 Google 登录失败。
-  加入和创建流程也会尝试复用现有的 Meet 标签页，而不是新开一个。匹配时会忽略像 `authuser` 这样的无害 URL 查询字符串，因此智能体重试时应聚焦到已经打开的会议，而不是创建第二个 Chrome 标签页。
+  浏览器自动化会处理 Meet 自己的首次运行麦克风提示；该提示不会被视为 Google 登录失败。
+  加入和创建流程还会在打开新标签页之前尝试复用现有 Meet 标签页。匹配时会忽略无害的 URL 查询字符串，例如 `authuser`，因此智能体重试时应聚焦已打开的会议，而不是创建第二个 Chrome 标签页。

-命令/工具输出包含一个 `source` 字段（`api` 或 `browser`），因此智能体可以解释使用了哪条路径。`create` 默认会加入新会议，并返回 `joined: true` 以及加入会话。若仅需生成 URL，请在 CLI 中使用 `create --no-join`，或向工具传入 `"join": false`。
+命令/工具输出包含一个 `source` 字段（`api` 或 `browser`），这样智能体就能说明使用了哪条路径。
+`create` 默认会加入新会议，并返回 `joined: true` 以及加入会话。若只想生成 URL，请在 CLI 中使用
+`create --no-join`，或向工具传递 `"join": false`。

-或者你可以告诉智能体：“创建一个 Google Meet，用实时语音加入，然后把链接发给我。” 智能体应当使用 `action: "create"` 调用 `google_meet`，然后分享返回的 `meetingUri`。
+你也可以告诉智能体：“创建一个 Google Meet，用实时语音加入它，然后把链接发给我。”
+智能体应使用 `action: "create"` 调用 `google_meet`，然后分享返回的 `meetingUri`。

 ```json
 {
@ -125,17 +129,18 @@ openclaw googlemeet create --no-join
 }
 ```

-若只需观察/控制浏览器的加入方式，请设置 `"mode": "transcribe"`。这不会启动双向实时模型桥接，因此它不会在会议中回话。
+对于仅观察/浏览器控制的加入，请将 `"mode"` 设为 `"transcribe"`。这样不会启动双向实时模型桥接，因此它不会在会议中回话。

-在实时会话期间，`google_meet` 状态会包含浏览器和音频桥接的健康信息，例如 `inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最近的输入/输出时间戳、字节计数，以及桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在可能时处理它。登录、主持人准入，以及浏览器/操作系统权限提示会作为手动操作报告，并附带原因和消息，供智能体转达。
+在实时会话期间，`google_meet` 状态会包含浏览器和音频桥接健康信息，例如 `inCall`、`manualActionRequired`、`providerConnected`、
+`realtimeReady`、`audioInputActive`、`audioOutputActive`、最近输入/输出时间戳、字节计数以及桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在可能时处理它。登录、主持人准入以及浏览器/操作系统权限提示会作为手动操作报告，并带有原因和消息，供智能体转达。

-Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，选择 `BlackHole 2ch` 作为 OpenClaw 使用的麦克风/扬声器路径。若要获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的音频图；单个 BlackHole 设备足以完成首次冒烟测试，但可能会产生回声。
+Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，选择 `BlackHole 2ch` 作为 OpenClaw 使用的麦克风/扬声器路径。为了获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的音频图；单个 BlackHole 设备足够完成首次冒烟测试，但可能会产生回声。

 ### 本地 Gateway 网关 + Parallels Chrome

-你**不**需要在 macOS VM 中运行完整的 OpenClaw Gateway 网关或配置模型 API 密钥，仅仅为了让 VM 托管 Chrome。你可以在本地运行 Gateway 网关和智能体，然后在 VM 中运行一个节点主机。只需在 VM 中启用一次内置插件，这样节点就会宣告 Chrome 命令：
+你**不**需要在 macOS VM 中运行完整的 OpenClaw Gateway 网关或模型 API 密钥，仅仅为了让 VM 承担 Chrome。你可以在本地运行 Gateway 网关和智能体，然后在 VM 中运行一个节点主机。只需在 VM 中启用一次内置插件，这样节点就会通告 Chrome 命令：

-各组件运行位置如下：
+各组件运行位置：

 - Gateway 网关主机：OpenClaw Gateway 网关、智能体工作区、模型/API 密钥、实时提供商，以及 Google Meet 插件配置。
 - Parallels macOS VM：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch，以及一个已登录 Google 的 Chrome 配置文件。
@ -147,13 +152,13 @@ Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，选
 brew install blackhole-2ch sox
 ```

-安装 BlackHole 后重启 VM，这样 macOS 才会暴露 `BlackHole 2ch`：
+安装 BlackHole 后重启 VM，让 macOS 暴露 `BlackHole 2ch`：

 ```bash
 sudo reboot
 ```

-重启后，验证 VM 能看到该音频设备以及 SoX 命令：
+重启后，验证 VM 能看到音频设备和 SoX 命令：

 ```bash
 system_profiler SPAudioDataType | grep -i BlackHole
@ -172,14 +177,14 @@ openclaw plugins enable google-meet
 openclaw node run --host <gateway-host> --port 18789 --display-name parallels-macos
 ```

-如果 `<gateway-host>` 是局域网 IP，且你没有使用 TLS，则除非你显式为该受信任私有网络启用明文 WebSocket，否则节点会拒绝连接：
+如果 `<gateway-host>` 是局域网 IP，且你未使用 TLS，那么节点会拒绝明文 WebSocket，除非你为这个受信任的私有网络显式启用它：

 ```bash
 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
  openclaw node run --host <gateway-lan-ip> --port 18789 --display-name parallels-macos
 ```

-将节点安装为 LaunchAgent 时，也请使用相同的环境变量：
+将节点安装为 LaunchAgent 时也要使用相同的环境变量：

 ```bash
 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
@ -187,23 +192,24 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
 openclaw node restart
 ```

-`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是进程环境变量，不是 `openclaw.json` 设置。
-当 `openclaw node install` 执行安装命令时检测到该变量存在，就会把它存入 LaunchAgent 环境中。
+`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是进程环境，不是
+`openclaw.json` 设置。`openclaw node install` 会在安装命令中存在该变量时，将它存储到 LaunchAgent 环境中。

-在 Gateway 网关主机上批准该节点：
+从 Gateway 网关主机批准该节点：

 ```bash
 openclaw devices list
 openclaw devices approve <requestId>
 ```

-确认 Gateway 网关能看到该节点，并且它宣告了 `googlemeet.chrome` 以及浏览器能力/`browser.proxy`：
+确认 Gateway 网关能看到该节点，并且它同时通告了 `googlemeet.chrome`
+和浏览器能力/`browser.proxy`：

 ```bash
 openclaw nodes status
 ```

-在 Gateway 网关主机上将 Meet 路由到该节点：
+在 Gateway 网关主机上通过该节点路由 Meet：

 ```json5
 {
@ -233,7 +239,7 @@ openclaw nodes status
 }
 ```

-现在你就可以在 Gateway 网关主机上像平常一样加入：
+现在你可以从 Gateway 网关主机正常加入：

 ```bash
 openclaw googlemeet join https://meet.google.com/abc-defg-hij
@ -241,52 +247,60 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij

 或者要求智能体使用 `google_meet` 工具，并设置 `transport: "chrome-node"`。

-如果你想做一个单命令冒烟测试，用来创建或复用会话、说出一段已知短语，并打印会话健康状态：
+对于一个单命令冒烟测试，它会创建或复用会话、说出已知短语并打印会话健康状态：

 ```bash
 openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij
 ```

-在加入过程中，OpenClaw 浏览器自动化会填写访客名称、点击“加入/请求加入”，并在出现时接受 Meet 首次运行的“使用麦克风”选择。在仅浏览器创建会议期间，如果 Meet 没有显示“使用麦克风”按钮，它也可以在不使用麦克风的情况下继续通过相同提示。
-如果浏览器配置文件未登录、Meet 正在等待主持人准入、Chrome 需要麦克风/摄像头权限，或者 Meet 卡在某个自动化无法解决的提示上，则加入/`test-speech` 结果会报告 `manualActionRequired: true`，并附带 `manualActionReason` 和 `manualActionMessage`。智能体应停止重复重试加入，原样报告该消息以及当前的 `browserUrl`/`browserTitle`，并且只在手动浏览器操作完成后再重试。
+在加入期间，OpenClaw 浏览器自动化会填写访客名称，点击“加入/请求加入”，并在出现该提示时接受 Meet 首次运行的“使用麦克风”选项。在仅浏览器创建会议期间，如果 Meet 没有暴露使用麦克风按钮，它也可以在不启用麦克风的情况下继续通过同一个提示。
+如果浏览器配置文件未登录、Meet 正在等待主持人准入、Chrome 需要麦克风/摄像头权限，或者 Meet 卡在自动化无法解决的提示上，那么加入/`test-speech` 结果会报告
+`manualActionRequired: true`，并包含 `manualActionReason` 和
+`manualActionMessage`。智能体应停止重试加入，报告该精确消息以及当前的 `browserUrl`/`browserTitle`，并且只在手动浏览器操作完成后重试。

-如果省略 `chromeNode.node`，OpenClaw 只有在恰好只有一个已连接节点同时宣告 `googlemeet.chrome` 和浏览器控制时，才会自动选择该节点。如果连接了多个具备能力的节点，请将 `chromeNode.node` 设置为节点 id、显示名称或远程 IP。
+如果省略了 `chromeNode.node`，只有在恰好只有一个已连接节点同时通告 `googlemeet.chrome` 和浏览器控制时，OpenClaw 才会自动选择。
+如果连接了多个有能力的节点，请将 `chromeNode.node` 设置为节点 id、显示名称或远程 IP。

 常见故障检查：

- `No connected Google Meet-capable node`：在 VM 中启动 `openclaw node run`，批准配对，并确保已经在 VM 中运行 `openclaw plugins enable google-meet` 和 `openclaw plugins enable browser`。还要确认 Gateway 网关主机通过 `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` 允许这两个节点命令。
+- `No connected Google Meet-capable node`：在 VM 中启动 `openclaw node run`，批准配对，并确保在 VM 中运行过 `openclaw plugins enable google-meet` 和 `openclaw plugins enable browser`。还要确认 Gateway 网关主机允许这两个节点命令：
+  `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`。
 - `BlackHole 2ch audio device not found on the node`：在 VM 中安装 `blackhole-2ch` 并重启 VM。
- Chrome 能打开但无法加入：在 VM 内的浏览器配置文件中登录，或者保持设置 `chrome.guestName` 以供访客加入。访客自动加入会通过节点浏览器代理使用 OpenClaw 浏览器自动化；请确保节点浏览器配置指向你想使用的配置文件，例如 `browser.defaultProfile: "user"` 或一个已命名的现有会话配置文件。
- 重复的 Meet 标签页：保持启用 `chrome.reuseExistingTab: true`。OpenClaw 会在打开新标签页之前激活相同 Meet URL 的现有标签页，而浏览器创建会议时，也会在新开之前复用一个进行中的 `https://meet.google.com/new` 或 Google 账号提示标签页。
- 没有音频：在 Meet 中，将麦克风/扬声器路由到 OpenClaw 使用的虚拟音频设备路径；若要获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的路由方式。
+- Chrome 打开了但无法加入：在 VM 内的浏览器配置文件中登录，或者保持设置 `chrome.guestName` 用于访客加入。访客自动加入使用 OpenClaw 通过节点浏览器代理执行的浏览器自动化；请确保节点浏览器配置指向你想使用的配置文件，例如
+  `browser.defaultProfile: "user"` 或某个已有会话的命名配置文件。
+- Meet 标签页重复：保持启用 `chrome.reuseExistingTab: true`。OpenClaw 会在打开新标签页之前先激活同一个 Meet URL 的现有标签页，而浏览器会议创建也会在打开另一个标签页之前复用进行中的 `https://meet.google.com/new` 或 Google 账户提示标签页。
+- 没有音频：在 Meet 中，将麦克风/扬声器路由到 OpenClaw 使用的虚拟音频设备路径；使用独立的虚拟设备或类似 Loopback 的路由以获得干净的双工音频。

 ## 安装说明

-Chrome 实时默认配置会使用两个外部工具：
+Chrome 实时默认值使用两个外部工具：

- `sox`：命令行音频工具。插件使用它的 `rec` 和 `play` 命令来实现默认的 8 kHz G.711 mu-law 音频桥接。
- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 `BlackHole 2ch` 音频设备，供 Chrome/Meet 路由使用。
+- `sox`：命令行音频工具。插件使用它的 `rec` 和 `play`
+  命令作为默认的 8 kHz G.711 mu-law 音频桥接。
+- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 `BlackHole 2ch`
+  音频设备，供 Chrome/Meet 路由使用。

-OpenClaw 不会捆绑或重新分发这两个软件包。文档要求用户通过 Homebrew 将它们作为主机依赖安装。SoX 的许可证为 `LGPL-2.0-only AND GPL-2.0-only`；BlackHole 为 GPL-3.0。如果你要构建一个将 BlackHole 与 OpenClaw 一起打包的安装程序或设备，请审阅 BlackHole 上游的许可条款，或向 Existential Audio 获取单独许可。
+OpenClaw 不会内置或重新分发这两个软件包。文档要求用户通过 Homebrew 将它们作为主机依赖安装。SoX 的许可为
+`LGPL-2.0-only AND GPL-2.0-only`；BlackHole 为 GPL-3.0。如果你构建了一个将 BlackHole 与 OpenClaw 一起打包的安装器或设备，请查看 BlackHole 的上游许可条款，或从 Existential Audio 获取单独许可。

 ## 传输方式

 ### Chrome

-Chrome 传输方式会在 Google Chrome 中打开 Meet URL，并以已登录的 Chrome 配置文件身份加入。在 macOS 上，插件会在启动前检查 `BlackHole 2ch`。如果已配置，它还会在打开 Chrome 之前运行音频桥接健康检查命令和启动命令。当 Chrome/音频运行在 Gateway 网关主机上时使用 `chrome`；当 Chrome/音频运行在已配对节点（例如 Parallels macOS VM）上时使用 `chrome-node`。
+Chrome 传输方式会在 Google Chrome 中打开 Meet URL，并以已登录的 Chrome 配置文件身份加入。在 macOS 上，插件会在启动前检查是否存在 `BlackHole 2ch`。如果已配置，它还会在打开 Chrome 前运行音频桥接健康检查命令和启动命令。当 Chrome/音频位于 Gateway 网关主机上时，请使用 `chrome`；当 Chrome/音频位于已配对节点（例如 Parallels macOS VM）上时，请使用 `chrome-node`。

 ```bash
 openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome
 openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node
 ```

-将 Chrome 麦克风和扬声器音频通过本地 OpenClaw 音频桥接进行路由。如果未安装 `BlackHole 2ch`，加入操作会因设置错误而失败，而不是在没有音频路径的情况下静默加入。
+将 Chrome 麦克风和扬声器音频通过本地 OpenClaw 音频桥接进行路由。如果未安装 `BlackHole 2ch`，加入会因设置错误而失败，而不是在没有音频路径的情况下静默加入。

 ### Twilio

-Twilio 传输方式是一个严格的拨号计划，并委托给 Voice Call 插件。它不会解析 Meet 页面来提取电话号码。
+Twilio 传输方式是一个严格的拨号计划，委派给 Voice Call 插件处理。它不会解析 Meet 页面中的电话号码。

-当 Chrome 参与方式不可用，或你想使用电话拨入作为回退方案时，请使用此方式。Google Meet 必须为该会议提供电话拨入号码和 PIN；OpenClaw 不会从 Meet 页面中发现这些信息。
+当无法使用 Chrome 参会，或者你想要电话拨入作为回退方案时，请使用此方式。Google Meet 必须为该会议公开电话拨入号码和 PIN；OpenClaw 不会从 Meet 页面中发现这些信息。

 在 Gateway 网关主机上启用 Voice Call 插件，而不是在 Chrome 节点上：

@ -313,7 +327,7 @@ Twilio 传输方式是一个严格的拨号计划，并委托给 Voice Call 插
 }
 ```

-通过环境变量或配置提供 Twilio 凭证。环境变量可以让密钥不出现在 `openclaw.json` 中：
+通过环境变量或配置提供 Twilio 凭证。使用环境变量可以让密钥不出现在 `openclaw.json` 中：

 ```bash
 export TWILIO_ACCOUNT_SID=AC...
@ -321,9 +335,9 @@ export TWILIO_AUTH_TOKEN=...
 export TWILIO_FROM_NUMBER=+15550001234
 ```

-启用 `voice-call` 后，请重启或重新加载 Gateway 网关；在 Gateway 网关重新加载之前，已经运行中的 Gateway 网关进程不会看到插件配置更改。
+启用 `voice-call` 后，重启或重新加载 Gateway 网关；在 Gateway 网关进程重新加载之前，插件配置更改不会出现在已经运行的 Gateway 网关进程中。

-然后进行验证：
+然后验证：

 ```bash
 openclaw config validate
@ -331,7 +345,8 @@ openclaw plugins list | grep -E 'google-meet|voice-call'
 openclaw googlemeet setup
 ```

-当 Twilio 委托已正确接通时，`googlemeet setup` 会包含成功的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查。
+当 Twilio 委派已正确接线时，`googlemeet setup` 会包含成功的
+`twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查。

 ```bash
 openclaw googlemeet join https://meet.google.com/abc-defg-hij \
@ -351,11 +366,12 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \

 ## OAuth 和预检

-对于创建 Meet 链接来说，OAuth 是可选的，因为 `googlemeet create` 可以回退到浏览器自动化。当你需要官方 API 创建、空间解析或 Meet Media API 预检时，再配置 OAuth。
+对于创建 Meet 链接来说，OAuth 是可选的，因为 `googlemeet create` 可以回退到浏览器自动化。当你想使用官方 API 创建、空间解析或 Meet Media API 预检时，请配置 OAuth。

-Google Meet API 访问使用用户 OAuth：创建一个 Google Cloud OAuth 客户端，请求所需作用域，授权一个 Google 账号，然后将生成的刷新令牌存储到 Google Meet 插件配置中，或提供 `OPENCLAW_GOOGLE_MEET_*` 环境变量。
+Google Meet API 访问使用用户 OAuth：创建一个 Google Cloud OAuth 客户端，请求所需作用域，授权一个 Google 账户，然后将生成的刷新令牌存储到 Google Meet 插件配置中，或提供
+`OPENCLAW_GOOGLE_MEET_*` 环境变量。

-OAuth 不会替代 Chrome 加入路径。当你使用浏览器参与方式时，Chrome 和 chrome-node 传输方式仍然通过一个已登录的 Chrome 配置文件、BlackHole/SoX，以及一个已连接节点来加入。OAuth 只用于官方 Google Meet API 路径：创建会议空间、解析空间，以及执行 Meet Media API 预检。
+OAuth 不能替代 Chrome 加入路径。Chrome 和 Chrome-node 传输方式在你使用浏览器参会时，仍然通过已登录的 Chrome 配置文件、BlackHole/SoX 以及已连接节点进行加入。OAuth 仅用于官方 Google Meet API 路径：创建会议空间、解析空间以及运行 Meet Media API 预检。

 ### 创建 Google 凭证

@ -364,13 +380,13 @@ OAuth 不会替代 Chrome 加入路径。当你使用浏览器参与方式时，
 1. 创建或选择一个 Google Cloud 项目。
 2. 为该项目启用 **Google Meet REST API**。
 3. 配置 OAuth 同意屏幕。
-   - 对于 Google Workspace 组织，**Internal** 最简单。
-   - 对于个人/测试设置，**External** 也可以；当应用处于 Testing 状态时，将每个会授权该应用的 Google 账号添加为测试用户。
+   - **Internal** 对 Google Workspace 组织来说最简单。
+   - **External** 适用于个人/测试设置；当应用处于 Testing 状态时，将每个要授权该应用的 Google 账户添加为测试用户。
 4. 添加 OpenClaw 请求的作用域：
   - `https://www.googleapis.com/auth/meetings.space.created`
   - `https://www.googleapis.com/auth/meetings.space.readonly`
   - `https://www.googleapis.com/auth/meetings.conference.media.readonly`
-5. 创建一个 OAuth client ID。
+5. 创建一个 OAuth 客户端 ID。
   - 应用类型：**Web application**。
   - 已获授权的重定向 URI：

@ -378,22 +394,22 @@ OAuth 不会替代 Chrome 加入路径。当你使用浏览器参与方式时，
     http://localhost:8085/oauth2callback
     ```

-6. 复制 client ID 和 client secret。
+6. 复制客户端 ID 和客户端密钥。

 `meetings.space.created` 是 Google Meet `spaces.create` 所必需的。
-`meetings.space.readonly` 让 OpenClaw 能将 Meet URL/代码解析为会议空间。
-`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体相关工作；实际使用 Media API 时，Google 可能要求加入 Developer Preview。
-如果你只需要基于浏览器的 Chrome 加入方式，可以完全跳过 OAuth。
+`meetings.space.readonly` 让 OpenClaw 可以将 Meet URL/代码解析为空间。
+`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体相关工作；实际使用 Media API 时，Google 可能要求加入开发者预览计划。
+如果你只需要基于浏览器的 Chrome 加入，请完全跳过 OAuth。

 ### 生成刷新令牌

-配置 `oauth.clientId`，并可选配置 `oauth.clientSecret`，或者通过环境变量传入它们，然后运行：
+配置 `oauth.clientId`，并可选择配置 `oauth.clientSecret`，或者将它们作为环境变量传入，然后运行：

 ```bash
 openclaw googlemeet auth login --json
 ```

-该命令会打印一个包含刷新令牌的 `oauth` 配置块。它使用 PKCE、本地回调 `http://localhost:8085/oauth2callback`，并支持通过 `--manual` 进行手动复制/粘贴流程。
+该命令会打印一个带有刷新令牌的 `oauth` 配置块。它使用 PKCE、本地主机回调 `http://localhost:8085/oauth2callback`，并支持通过 `--manual` 使用手动复制/粘贴流程。

 示例：

@ -411,7 +427,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \
 openclaw googlemeet auth login --json --manual
 ```

-JSON 输出包含：
+JSON 输出包括：

 ```json
 {
@ -447,54 +463,52 @@ JSON 输出包含：
 }
 ```

-如果你不希望将刷新令牌写入配置中，优先使用环境变量。
-如果配置和环境变量同时存在，插件会优先解析配置，然后再回退到环境变量。
+如果你不希望将刷新令牌写入配置，优先使用环境变量。
+如果配置值和环境变量值同时存在，插件会优先解析配置，然后再回退到环境变量。

-OAuth 同意范围包括 Meet 空间创建、Meet 空间读取访问和 Meet 会议媒体读取访问。
-如果你是在会议创建支持存在之前完成认证的，请重新运行 `openclaw googlemeet auth login --json`，以便刷新令牌包含 `meetings.space.created` 作用域。
+OAuth 同意内容包括 Meet 空间创建、Meet 空间读取访问和 Meet conference media 读取访问。如果你在会议创建支持存在之前就已完成身份验证，请重新运行 `openclaw googlemeet auth login --json`，以便刷新令牌具备 `meetings.space.created` 作用域。

-### 使用 Doctor 验证 OAuth
+### 使用 doctor 验证 OAuth

-当你需要一个快速且不泄露敏感信息的健康检查时，请运行 OAuth Doctor：
+当你想进行快速、非敏感信息的健康检查时，运行 OAuth Doctor：

 ```bash
 openclaw googlemeet doctor --oauth --json
 ```

-这不会加载 Chrome 运行时，也不要求连接 Chrome 节点。
-它会检查 OAuth 配置是否存在，以及刷新令牌是否能够生成访问令牌。JSON 报告只包含 `ok`、`configured`、`tokenSource`、`expiresAt` 和检查消息等状态字段；不会打印访问令牌、刷新令牌或 client secret。
+这不会加载 Chrome 运行时，也不需要连接的 Chrome 节点。它会检查 OAuth 配置是否存在，以及刷新令牌是否能生成访问令牌。JSON 报告只包含 `ok`、`configured`、`tokenSource`、`expiresAt` 和检查消息等状态字段；不会打印访问令牌、刷新令牌或客户端密钥。

 常见结果：

-| 检查项               | 含义                                                                                    |
-| -------------------- | --------------------------------------------------------------------------------------- |
-| `oauth-config`       | 存在 `oauth.clientId` 加 `oauth.refreshToken`，或存在缓存的访问令牌。                   |
-| `oauth-token`        | 缓存的访问令牌仍然有效，或者刷新令牌已生成新的访问令牌。                                 |
-| `meet-spaces-get`    | 可选的 `--meeting` 检查已解析一个现有的 Meet 空间。                                      |
-| `meet-spaces-create` | 可选的 `--create-space` 检查已创建一个新的 Meet 空间。                                   |
+| 检查项                | 含义                                                                                     |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| `oauth-config`        | 存在 `oauth.clientId` 加 `oauth.refreshToken`，或存在缓存的访问令牌。                   |
+| `oauth-token`         | 缓存的访问令牌仍然有效，或者刷新令牌已生成新的访问令牌。                                 |
+| `meet-spaces-get`     | 可选的 `--meeting` 检查解析了一个现有 Meet 空间。                                        |
+| `meet-spaces-create`  | 可选的 `--create-space` 检查创建了一个新的 Meet 空间。                                   |

-如果还需要证明 Google Meet API 已启用，并且具备 `spaces.create` 作用域，请运行会产生副作用的创建检查：
+若还要证明 Google Meet API 已启用以及 `spaces.create` 作用域也可用，请运行带副作用的创建检查：

 ```bash
 openclaw googlemeet doctor --oauth --create-space --json
 openclaw googlemeet create --no-join --json
 ```

-`--create-space` 会创建一个一次性的 Meet URL。当你需要确认 Google Cloud 项目已启用 Meet API，并且授权账号具备 `meetings.space.created` 作用域时，请使用它。
+`--create-space` 会创建一个一次性的 Meet URL。当你需要确认 Google Cloud 项目已启用 Meet API，并且已授权账户具备 `meetings.space.created` 作用域时，请使用它。

-若要证明对现有会议空间具有读取权限：
+若要证明对现有会议空间的读取访问：

 ```bash
 openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json
 openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij
 ```

-`doctor --oauth --meeting` 和 `resolve-space` 可以证明已授权的 Google 账号对其可访问的现有空间具有读取权限。
-这些检查返回 `403` 通常意味着 Google Meet REST API 未启用、已同意的刷新令牌缺少所需作用域，或者该 Google 账号无法访问该 Meet 空间。若是刷新令牌错误，则表示你需要重新运行 `openclaw googlemeet auth login --json`，并存储新的 `oauth` 配置块。
+`doctor --oauth --meeting` 和 `resolve-space` 可以证明对已授权 Google 账户可访问的现有空间具有读取权限。这些检查返回 `403` 通常意味着 Google Meet REST API 未启用、用户同意的刷新令牌缺少所需作用域，或者该 Google 账户无法访问该 Meet 空间。若是刷新令牌错误，则表示需要重新运行 `openclaw googlemeet auth login
+--json` 并存储新的 `oauth` 块。

-浏览器回退模式不需要任何 OAuth 凭证。在该模式下，Google 认证来自所选节点上已登录的 Chrome 配置文件，而不是 OpenClaw 配置。
+浏览器回退模式不需要 OAuth 凭证。在该模式下，Google 认证来自所选节点上已登录的 Chrome 配置文件，而不是 OpenClaw 配置。

-以下环境变量可作为回退来源：
+接受以下环境变量作为回退：

 - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID`
 - `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` 或 `GOOGLE_MEET_CLIENT_SECRET`
@ -511,20 +525,33 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij
 openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij
 ```

-在执行媒体相关工作之前运行预检：
+在进行媒体相关工作前运行预检：

 ```bash
 openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij
 ```

-在 Meet 创建会议记录后，列出会议工件和出席情况：
+在 Meet 创建 conference records 之后，列出会议工件和出席情况：

 ```bash
 openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij
 openclaw googlemeet attendance --meeting https://meet.google.com/abc-defg-hij
+openclaw googlemeet export --meeting https://meet.google.com/abc-defg-hij --output ./meet-export
 ```

-如果你已经知道 conference record id，可以直接使用它：
+配合 `--meeting` 时，`artifacts` 和 `attendance` 默认使用最新的 conference record。若你想获取该会议的所有保留记录，请传递 `--all-conference-records`。
+
+Calendar 查找可以先从 Google Calendar 解析会议 URL，然后再读取 Meet 工件：
+
+```bash
+openclaw googlemeet latest --today
+openclaw googlemeet artifacts --event "Weekly sync"
+openclaw googlemeet attendance --today --format csv --output attendance.csv
+```
+
+`--today` 会在今天的 `primary` 日历中查找包含 Google Meet 链接的 Calendar 事件。使用 `--event <query>` 搜索匹配的事件文本，使用 `--calendar <id>` 指定非主日历。Calendar 查找需要重新进行一次 OAuth 登录，并包含 Calendar events readonly 作用域。
+
+如果你已经知道 conference record id，可以直接指定它：

 ```bash
 openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij
@ -532,17 +559,21 @@ openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --jso
 openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json
 ```

-输出一份可读报告：
+写出可读报告：

 ```bash
 openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 \
  --format markdown --output meet-artifacts.md
 openclaw googlemeet attendance --conference-record conferenceRecords/abc123 \
  --format markdown --output meet-attendance.md
+openclaw googlemeet attendance --conference-record conferenceRecords/abc123 \
+  --format csv --output meet-attendance.csv
 ```

-`artifacts` 会返回会议记录元数据，以及当 Google 为该会议提供这些资源时的参与者、录制、转录、结构化 transcript-entry 和智能笔记资源元数据。对于大型会议，可使用 `--no-transcript-entries` 跳过条目查询。
-`attendance` 会将参与者展开为 participant-session 行，并包含加入/离开时间戳。这些命令只使用 Meet REST API；Google Docs/Drive 文档正文下载被有意排除在范围之外，因为那需要额外的 Google Docs/Drive 访问权限。
+`artifacts` 会返回 conference record 元数据，以及当 Google 为该会议公开这些内容时，参与者、录音、转录、结构化 transcript-entry 和 smart-note 资源元数据。对大型会议，请使用 `--no-transcript-entries` 跳过条目查找。`attendance` 会将参与者展开为 participant-session 行，包含首次/最后出现时间、总会话时长、迟到/提前离开标记，以及按已登录用户或显示名称合并的重复参与者资源。传递 `--no-merge-duplicates` 可保持原始参与者资源彼此分离，传递 `--late-after-minutes` 可调整迟到判定，传递 `--early-before-minutes` 可调整提前离开判定。
+
+`export` 会写出一个文件夹，其中包含 `summary.md`、`attendance.csv`、
+`transcript.md`、`artifacts.json` 和 `attendance.json`。这些命令仅对 Meet 资源使用 Meet REST API；Google Docs/Drive 文档正文下载被有意排除在范围之外，因为那需要单独的 Google Docs/Drive 访问权限。

 创建一个新的 Meet 空间：

@ -550,9 +581,9 @@ openclaw googlemeet attendance --conference-record conferenceRecords/abc123 \
 openclaw googlemeet create
 ```

-该命令会打印新的 `meeting uri`、来源以及加入会话。有 OAuth 凭证时，它会使用官方 Google Meet API。没有 OAuth 凭证时，它会使用固定的 Chrome 节点中已登录的浏览器配置文件作为回退。智能体可以通过使用 `action: "create"` 的 `google_meet` 工具一步完成创建和加入。若只创建 URL，请传入 `"join": false`。
+该命令会打印新的 `meeting uri`、来源和加入会话。有 OAuth 凭证时，它会使用官方 Google Meet API。没有 OAuth 凭证时，它会回退为使用固定 Chrome 节点上已登录的浏览器配置文件。智能体可以使用带有 `action: "create"` 的 `google_meet` 工具，一步完成创建和加入。若只创建 URL，请传递 `"join": false`。

-浏览器回退模式下的 JSON 输出示例：
+来自浏览器回退的 JSON 输出示例：

 ```json
 {
@ -572,15 +603,15 @@ openclaw googlemeet create
 }
 ```

-如果浏览器回退在创建 URL 之前遇到 Google 登录或 Meet 权限阻塞，Gateway 网关方法会返回失败响应，而 `google_meet` 工具会返回结构化细节，而不是纯字符串：
+如果浏览器回退在创建 URL 之前遇到 Google 登录或 Meet 权限阻塞，Gateway 网关方法会返回失败响应，而 `google_meet` 工具会返回结构化细节，而不是普通字符串：

 ```json
 {
  "source": "browser",
-  "error": "google-login-required: 在 OpenClaw 浏览器配置文件中登录 Google，然后重试创建会议。",
+  "error": "google-login-required: Sign in to Google in the OpenClaw browser profile, then retry meeting creation.",
  "manualActionRequired": true,
  "manualActionReason": "google-login-required",
-  "manualActionMessage": "在 OpenClaw 浏览器配置文件中登录 Google，然后重试创建会议。",
+  "manualActionMessage": "Sign in to Google in the OpenClaw browser profile, then retry meeting creation.",
  "browser": {
    "nodeId": "ba0f4e4bc...",
    "targetId": "tab-1",
@ -590,9 +621,10 @@ openclaw googlemeet create
 }
 ```

-当智能体看到 `manualActionRequired: true` 时，它应报告 `manualActionMessage`，以及浏览器节点/标签页上下文，并停止打开新的 Meet 标签页，直到操作员完成该浏览器步骤。
+当智能体看到 `manualActionRequired: true` 时，它应报告
+`manualActionMessage` 以及浏览器节点/标签页上下文，并停止打开新的 Meet 标签页，直到操作员完成该浏览器步骤。

-API 创建的 JSON 输出示例：
+来自 API 创建的 JSON 输出示例：

 ```json
 {
@ -613,13 +645,14 @@ API 创建的 JSON 输出示例：
 }
 ```

-创建 Meet 默认会直接加入。`chrome` 或 `chrome-node` 传输方式仍然需要一个已登录 Google 的 Chrome 配置文件，才能通过浏览器加入。如果该配置文件已登出，OpenClaw 会报告 `manualActionRequired: true` 或浏览器回退错误，并要求操作员先完成 Google 登录，再进行重试。
+创建 Meet 默认也会加入。Chrome 或 Chrome-node 传输方式仍然需要一个已登录的 Google Chrome 配置文件，才能通过浏览器加入。如果该配置文件已退出登录，OpenClaw 会报告 `manualActionRequired: true` 或浏览器回退错误，并要求操作员先完成 Google 登录，再重试。

-只有在确认你的 Cloud 项目、OAuth 主体以及会议参与者都已加入用于 Meet 媒体 API 的 Google Workspace Developer Preview Program 后，才设置 `preview.enrollmentAcknowledged: true`。
+仅在确认你的 Cloud 项目、OAuth 主体和会议参与者都已加入 Google Workspace Developer Preview Program for Meet media APIs 后，才设置 `preview.enrollmentAcknowledged: true`。

 ## 配置

-常见的 Chrome 实时路径只需要启用插件、安装 BlackHole 和 SoX，以及一个后端实时语音提供商密钥。OpenAI 是默认值；设置 `realtime.provider: "google"` 可使用 Google Gemini Live：
+常见的 Chrome 实时路径只需要启用插件、安装 BlackHole 和 SoX，并提供一个后端实时语音提供商密钥。OpenAI 是默认选项；设置
+`realtime.provider: "google"` 可使用 Google Gemini Live：

 ```bash
 brew install blackhole-2ch sox
@ -647,18 +680,19 @@ export GEMINI_API_KEY=...

 - `defaultTransport: "chrome"`
 - `defaultMode: "realtime"`
- `chromeNode.node`：`chrome-node` 的可选节点 id/名称/IP
+- `chromeNode.node`：用于 `chrome-node` 的可选节点 id/名称/IP
 - `chrome.audioBackend: "blackhole-2ch"`
- `chrome.guestName: "OpenClaw Agent"`：用于已登出 Meet 访客界面的名称
- `chrome.autoJoin: true`：通过 OpenClaw 浏览器自动化，在 `chrome-node` 上尽力填写访客名并点击“立即加入”
+- `chrome.guestName: "OpenClaw Agent"`：在未登录的 Meet 访客界面上使用的名称
+- `chrome.autoJoin: true`：通过 OpenClaw 浏览器自动化，在 `chrome-node` 上尽力完成访客名称填写并点击“立即加入”
 - `chrome.reuseExistingTab: true`：激活现有 Meet 标签页，而不是打开重复标签页
- `chrome.waitForInCallMs: 20000`：等待 Meet 标签页报告已在通话中，然后才触发实时介绍
+- `chrome.waitForInCallMs: 20000`：等待 Meet 标签页报告已在通话中，然后再触发实时介绍
 - `chrome.audioInputCommand`：将 8 kHz G.711 mu-law 音频写入 stdout 的 SoX `rec` 命令
 - `chrome.audioOutputCommand`：从 stdin 读取 8 kHz G.711 mu-law 音频的 SoX `play` 命令
 - `realtime.provider: "openai"`
 - `realtime.toolPolicy: "safe-read-only"`
- `realtime.instructions`：简短口头回复，需要更深入回答时使用 `openclaw_agent_consult`
- `realtime.introMessage`：当实时桥接连接时，做一个简短口头就绪检查；将其设为 `""` 可静默加入
+- `realtime.instructions`：简短的口语回复，较深入的回答使用
+  `openclaw_agent_consult`
+- `realtime.introMessage`：实时桥接连接时的简短口头就绪检查；将其设为 `""` 可静默加入

 可选覆盖项：

@ -689,7 +723,7 @@ export GEMINI_API_KEY=...
 }
 ```

-仅 Twilio 配置：
+仅使用 Twilio 的配置：

 ```json5
 {
@ -704,7 +738,7 @@ export GEMINI_API_KEY=...
 }
 ```

-`voiceCall.enabled` 默认为 `true`；使用 Twilio 传输方式时，它会将实际 PSTN 呼叫和 DTMF 委托给 Voice Call 插件。如果未启用 `voice-call`，Google Meet 仍然可以验证并记录拨号计划，但无法发起 Twilio 呼叫。
+`voiceCall.enabled` 默认为 `true`；使用 Twilio 传输方式时，它会将实际的 PSTN 呼叫和 DTMF 委派给 Voice Call 插件。如果未启用 `voice-call`，Google Meet 仍然可以验证并记录拨号计划，但无法发起 Twilio 呼叫。

 ## 工具

@ -719,17 +753,20 @@ export GEMINI_API_KEY=...
 }
 ```

-当 Chrome 运行在 Gateway 网关主机上时，使用 `transport: "chrome"`。当 Chrome 运行在已配对节点（如 Parallels VM）上时，使用 `transport: "chrome-node"`。无论哪种情况，实时模型和 `openclaw_agent_consult` 都运行在 Gateway 网关主机上，因此模型凭证会留在那里。
+当 Chrome 运行在 Gateway 网关主机上时，使用
+`transport: "chrome"`。当 Chrome 运行在已配对节点上，例如 Parallels
+VM 时，使用 `transport: "chrome-node"`。在这两种情况下，实时模型和 `openclaw_agent_consult` 都运行在 Gateway 网关主机上，因此模型凭证会留在那里。

-使用 `action: "status"` 可列出活动会话或检查某个会话 ID。使用带 `sessionId` 和 `message` 的 `action: "speak"` 可让实时智能体立即发言。使用 `action: "test_speech"` 可创建或复用会话、触发一段已知短语，并在 Chrome 主机可报告时返回 `inCall` 健康状态。使用 `action: "leave"` 可将会话标记为结束。
+使用 `action: "status"` 列出活动会话或检查某个会话 ID。使用
+`action: "speak"` 并提供 `sessionId` 和 `message`，可以让实时智能体立即发言。使用 `action: "test_speech"` 可创建或复用会话、触发一个已知短语，并在 Chrome 主机能够报告时返回 `inCall` 健康状态。使用 `action: "leave"` 将会话标记为结束。

 在可用时，`status` 包含 Chrome 健康信息：

 - `inCall`：Chrome 看起来已进入 Meet 通话
- `micMuted`：尽力检测的 Meet 麦克风状态
- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、Meet 主持人准入、权限授予，或浏览器控制修复后，语音功能才能工作
+- `micMuted`：尽力获取的 Meet 麦克风状态
+- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、Meet 主持人准入、权限授权或浏览器控制修复，语音功能才能正常工作
 - `providerConnected` / `realtimeReady`：实时语音桥接状态
- `lastInputAt` / `lastOutputAt`：最近一次从桥接接收/发送音频的时间
+- `lastInputAt` / `lastOutputAt`：最后一次从桥接收到或发送到桥接的音频时间

 ```json
 {
@ -741,25 +778,27 @@ export GEMINI_API_KEY=...

 ## 实时智能体咨询

-Chrome 实时模式针对实时语音循环做了优化。实时语音提供商会听取会议音频，并通过配置的音频桥接发声。当实时模型需要更深入的推理、最新信息或常规 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。
+Chrome 实时模式针对实时语音循环进行了优化。实时语音提供商会听取会议音频，并通过已配置的音频桥接发声。当实时模型需要更深入的推理、当前信息或普通 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。

-咨询工具会在后台运行常规 OpenClaw 智能体，并带上最近的会议转录上下文，然后向实时语音会话返回一个简洁的口头回答。随后语音模型可以将该回答说回会议中。它与 Voice Call 共用同一个实时咨询工具。
+咨询工具会在幕后运行常规 OpenClaw 智能体，并结合最近的会议转录上下文，向实时语音会话返回简洁的口头答复。然后语音模型可以把该答复说回会议中。它与 Voice Call 共用相同的实时咨询工具。

 `realtime.toolPolicy` 控制咨询运行方式：

- `safe-read-only`：暴露咨询工具，并将常规智能体限制为使用 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`
- `owner`：暴露咨询工具，并允许常规智能体使用正常的智能体工具策略
- `none`：不向实时语音模型暴露咨询工具
+- `safe-read-only`：公开咨询工具，并将常规智能体限制为使用
+  `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和
+  `memory_get`。
+- `owner`：公开咨询工具，并允许常规智能体使用正常的智能体工具策略。
+- `none`：不向实时语音模型公开咨询工具。

-咨询会话键按 Meet 会话分别作用域，因此在同一次会议期间，后续咨询调用可以复用先前的咨询上下文。
+咨询会话键按每个 Meet 会话划分作用域，因此在同一场会议中，后续咨询调用可以复用之前的咨询上下文。

-若要在 Chrome 完全加入通话后强制执行一次口头就绪检查：
+要在 Chrome 完全加入通话后强制执行口头就绪检查：

 ```bash
 openclaw googlemeet speak meet_... "Say exactly: I'm here and listening."
 ```

-若要执行完整的加入并发言冒烟测试：
+对于完整的加入并发言冒烟测试：

 ```bash
 openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \
@ -767,9 +806,9 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \
  --message "Say exactly: I'm here and listening."
 ```

-## 实时测试检查清单
+## 实时测试清单

-在将会议交给无人值守智能体之前，使用以下流程：
+在将会议交给无人值守的智能体之前，请使用以下顺序：

 ```bash
 openclaw googlemeet setup
@ -779,15 +818,16 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \
  --message "Say exactly: Google Meet speech test complete."
 ```

-预期的 chrome-node 状态：
+预期的 Chrome-node 状态：

 - `googlemeet setup` 全部为绿色。
- 当 `chrome-node` 是默认传输方式或已固定节点时，`googlemeet setup` 包含 `chrome-node-connected`。
+- 当 `chrome-node` 是默认传输方式或已固定节点时，`googlemeet setup` 会包含 `chrome-node-connected`。
 - `nodes status` 显示所选节点已连接。
- 所选节点同时宣告 `googlemeet.chrome` 和 `browser.proxy`。
- Meet 标签页加入通话，并且 `test-speech` 返回包含 `inCall: true` 的 Chrome 健康状态。
+- 所选节点同时通告 `googlemeet.chrome` 和 `browser.proxy`。
+- Meet 标签页成功加入通话，且 `test-speech` 返回的 Chrome 健康状态中包含
+  `inCall: true`。

-对于远程 Chrome 主机（如 Parallels macOS VM），在更新 Gateway 网关或 VM 后，这是最短且安全的检查流程：
+对于远程 Chrome 主机，例如 Parallels macOS VM，在更新 Gateway 网关或 VM 后，这是最短且安全的检查方式：

 ```bash
 openclaw googlemeet setup
@ -798,9 +838,9 @@ openclaw nodes invoke \
  --params '{"action":"setup"}'
 ```

-这可以证明 Gateway 网关插件已加载、VM 节点已使用当前令牌连接，并且 Meet 音频桥接可用，然后智能体才会打开真实的会议标签页。
+这可以证明 Gateway 网关插件已加载、VM 节点使用当前令牌完成连接，并且 Meet 音频桥接可用，然后智能体才会打开真实的会议标签页。

-对于 Twilio 冒烟测试，请使用一个公开电话拨入详情的会议：
+对于 Twilio 冒烟测试，请使用一个公开了电话拨入详细信息的会议：

 ```bash
 openclaw googlemeet setup
@ -812,24 +852,24 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \

 预期的 Twilio 状态：

- `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查。
+- `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin` 和
+  `twilio-voice-call-credentials` 检查。
 - Gateway 网关重新加载后，CLI 中可用 `voicecall`。
 - 返回的会话包含 `transport: "twilio"` 和一个 `twilio.voiceCallId`。
- `googlemeet leave <sessionId>` 会挂断已委托的语音呼叫。
+- `googlemeet leave <sessionId>` 会挂断委派出去的语音呼叫。

 ## 故障排除

 ### 智能体看不到 Google Meet 工具

-确认插件已在 Gateway 网关配置中启用，并重新加载 Gateway 网关：
+确认该插件已在 Gateway 网关配置中启用，并重新加载 Gateway 网关：

 ```bash
 openclaw plugins list | grep google-meet
 openclaw googlemeet setup
 ```

-如果你刚修改了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。
-运行中的智能体只能看到当前 Gateway 网关进程已注册的插件工具。
+如果你刚刚编辑了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。正在运行的智能体只能看到由当前 Gateway 网关进程注册的插件工具。

 ### 没有已连接的 Google Meet 可用节点

@ -842,7 +882,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
  openclaw node run --host <gateway-lan-ip> --port 18789 --display-name parallels-macos
 ```

-在 Gateway 网关主机上，批准节点并验证命令：
+在 Gateway 网关主机上，批准该节点并验证命令：

 ```bash
 openclaw devices list
@ -850,7 +890,7 @@ openclaw devices approve <requestId>
 openclaw nodes status
 ```

-该节点必须已连接，并列出 `googlemeet.chrome` 以及 `browser.proxy`。
+节点必须已连接，并列出 `googlemeet.chrome` 和 `browser.proxy`。
 Gateway 网关配置必须允许这些节点命令：

 ```json5
@ -863,7 +903,8 @@ Gateway 网关配置必须允许这些节点命令：
 }
 ```

-如果 `googlemeet setup` 中的 `chrome-node-connected` 失败，或 Gateway 网关日志报告 `gateway token mismatch`，请使用当前 Gateway 网关令牌重新安装或重启节点。对于局域网 Gateway 网关，这通常意味着：
+如果 `googlemeet setup` 的 `chrome-node-connected` 检查失败，或者 Gateway 网关日志报告
+`gateway token mismatch`，请使用当前 Gateway 网关令牌重新安装或重启节点。对于局域网 Gateway 网关，通常意味着：

 ```bash
 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
@ -874,40 +915,44 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
  --force
 ```

-然后重新加载节点服务，并再次运行：
+然后重新加载节点服务并再次运行：

 ```bash
 openclaw googlemeet setup
 openclaw nodes status --connected
 ```

-### 浏览器打开了，但智能体无法加入
+### 浏览器已打开，但智能体无法加入

-运行 `googlemeet test-speech` 并检查返回的 Chrome 健康信息。如果它报告 `manualActionRequired: true`，请向操作员显示 `manualActionMessage`，并停止重试，直到浏览器操作完成。
+运行 `googlemeet test-speech` 并检查返回的 Chrome 健康状态。如果它报告 `manualActionRequired: true`，请向操作员显示 `manualActionMessage`，并在浏览器操作完成之前停止重试。

 常见的手动操作：

 - 登录 Chrome 配置文件。
- 从 Meet 主持人账号允许该访客进入。
- 当出现 Chrome 原生权限提示时，授予 Chrome 麦克风/摄像头权限。
+- 通过 Meet 主持人账户准入该访客。
+- 当 Chrome 的原生权限提示出现时，授予 Chrome 麦克风/摄像头权限。
 - 关闭或修复卡住的 Meet 权限对话框。

-不要仅因为 Meet 显示 “Do you want people to hear you in the meeting?” 就报告“未登录”。那是 Meet 的音频选择过渡页；OpenClaw 会在可用时通过浏览器自动化点击 **Use microphone**，并继续等待真正的会议状态。对于仅创建 URL 的浏览器回退，OpenClaw 可能会点击 **Continue without microphone**，因为创建 URL 不需要实时音频路径。
+不要仅仅因为 Meet 显示“Do you want people to hear you in the meeting?” 就报告“未登录”。那是 Meet 的音频选择过渡页；在可用时，OpenClaw 会通过浏览器自动化点击 **Use microphone**，并继续等待真正的会议状态。对于仅创建的浏览器回退，OpenClaw 可能会点击 **Continue without microphone**，因为创建 URL 不需要实时音频路径。

 ### 会议创建失败

-当配置了 OAuth 凭证时，`googlemeet create` 会首先使用 Google Meet API `spaces.create` 端点。
-如果没有 OAuth 凭证，它会回退到固定的 Chrome 节点浏览器。请确认：
+当已配置 OAuth 凭证时，`googlemeet create` 会首先使用 Google Meet API 的 `spaces.create` 端点。没有 OAuth 凭证时，它会回退到固定的 Chrome 节点浏览器。请确认：

- 对于 API 创建：已配置 `oauth.clientId` 和 `oauth.refreshToken`，或存在对应的 `OPENCLAW_GOOGLE_MEET_*` 环境变量。
- 对于 API 创建：刷新令牌是在添加创建支持之后生成的。旧令牌可能缺少 `meetings.space.created` 作用域；请重新运行 `openclaw googlemeet auth login --json` 并更新插件配置。
- 对于浏览器回退：`defaultTransport: "chrome-node"`，并且 `chromeNode.node` 指向一个已连接、具备 `browser.proxy` 和 `googlemeet.chrome` 的节点。
- 对于浏览器回退：该节点上的 OpenClaw Chrome 配置文件已登录 Google，并且可以打开 `https://meet.google.com/new`。
- 对于浏览器回退：重试会复用现有的 `https://meet.google.com/new` 或 Google 账号提示标签页，而不是打开新标签页。如果智能体超时，请重试工具调用，而不是手动再打开一个 Meet 标签页。
- 对于浏览器回退：如果工具返回 `manualActionRequired: true`，请使用返回的 `browser.nodeId`、`browser.targetId`、`browserUrl` 和 `manualActionMessage` 来引导操作员。在该操作完成之前，不要循环重试。
- 对于浏览器回退：如果 Meet 显示 “Do you want people to hear you in the meeting?”，请保持该标签页打开。OpenClaw 应通过浏览器自动化点击 **Use microphone**，或者在仅创建的回退模式下点击 **Continue without microphone**，然后继续等待生成的 Meet URL。如果无法做到，错误中应提到 `meet-audio-choice-required`，而不是 `google-login-required`。
+- 对于 API 创建：已配置 `oauth.clientId` 和 `oauth.refreshToken`，或存在匹配的 `OPENCLAW_GOOGLE_MEET_*` 环境变量。
+- 对于 API 创建：刷新令牌是在添加创建支持之后生成的。较旧的令牌可能缺少 `meetings.space.created` 作用域；请重新运行 `openclaw googlemeet auth login --json` 并更新插件配置。
+- 对于浏览器回退：`defaultTransport: "chrome-node"` 和
+  `chromeNode.node` 指向一个已连接节点，且该节点具备 `browser.proxy` 和
+  `googlemeet.chrome`。
+- 对于浏览器回退：该节点上的 OpenClaw Chrome 配置文件已登录 Google，并且能够打开 `https://meet.google.com/new`。
+- 对于浏览器回退：重试会复用现有的 `https://meet.google.com/new` 或 Google 账户提示标签页，而不是打开新标签页。如果智能体超时，请重试工具调用，而不是手动再打开一个 Meet 标签页。
+- 对于浏览器回退：如果工具返回 `manualActionRequired: true`，请使用返回的
+  `browser.nodeId`、`browser.targetId`、`browserUrl` 和
+  `manualActionMessage` 来引导操作员。在该操作完成前，不要循环重试。
+- 对于浏览器回退：如果 Meet 显示“Do you want people to hear you in the
+  meeting?”，请保持标签页打开。OpenClaw 应通过浏览器自动化点击 **Use microphone**，或者在仅创建的回退中点击 **Continue without microphone**，然后继续等待生成的 Meet URL。如果它无法做到，错误应提及 `meet-audio-choice-required`，而不是 `google-login-required`。

-### 智能体已加入，但不会说话
+### 智能体已加入，但没有说话

 检查实时路径：

@ -918,29 +963,31 @@ openclaw googlemeet doctor

 使用 `mode: "realtime"` 进行收听/回话。`mode: "transcribe"` 按设计不会启动双向实时语音桥接。

-另外还要验证：
+还要验证：

- Gateway 网关主机上可用一个实时提供商密钥，例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。
- `BlackHole 2ch` 在 Chrome 主机上可见。
- `rec` 和 `play` 在 Chrome 主机上存在。
+- Gateway 网关主机上可用一个实时提供商密钥，例如
+  `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。
+- 在 Chrome 主机上可以看到 `BlackHole 2ch`。
+- 在 Chrome 主机上存在 `rec` 和 `play`。
 - Meet 的麦克风和扬声器已通过 OpenClaw 使用的虚拟音频路径进行路由。

-`googlemeet doctor [session-id]` 会打印会话、节点、通话中状态、手动操作原因、实时提供商连接、`realtimeReady`、音频输入/输出活动、最近音频时间戳、字节计数，以及浏览器 URL。当你需要原始 JSON 时，请使用 `googlemeet status [session-id]`。当你需要在不暴露令牌的情况下验证 Google Meet OAuth 刷新时，请使用 `googlemeet doctor --oauth`；当你还需要 Google Meet API 证明时，添加 `--meeting` 或 `--create-space`。
+`googlemeet doctor [session-id]` 会打印会话、节点、是否在通话中、手动操作原因、实时提供商连接状态、`realtimeReady`、音频输入/输出活动、最近的音频时间戳、字节计数以及浏览器 URL。当你需要原始 JSON 时，请使用
+`googlemeet status [session-id]`。当你需要验证 Google Meet OAuth 刷新且不暴露令牌时，请使用 `googlemeet doctor --oauth`；当你还需要 Google Meet API 证明时，可添加 `--meeting` 或 `--create-space`。

-如果智能体超时了，而你看到一个 Meet 标签页已经打开，请检查该标签页，而不是再打开一个：
+如果智能体超时，而你能看到已有一个 Meet 标签页打开，请在不打开新标签页的情况下检查该标签页：

 ```bash
 openclaw googlemeet recover-tab
 openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij
 ```

-对应的工具操作是 `recover_current_tab`。它会在已配置的 Chrome 节点上聚焦并检查现有的 Meet 标签页。它不会打开新标签页，也不会创建新会话；它会报告当前阻塞项，例如登录、准入、权限或音频选择状态。CLI 命令会与已配置的 Gateway 网关通信，因此 Gateway 网关必须正在运行，并且 Chrome 节点必须已连接。
+对应的工具动作是 `recover_current_tab`。它会聚焦并检查已配置 Chrome 节点上的现有 Meet 标签页。它不会打开新标签页，也不会创建新会话；它会报告当前阻塞项，例如登录、准入、权限或音频选择状态。CLI 命令会与已配置的 Gateway 网关通信，因此 Gateway 网关必须正在运行，且 Chrome 节点必须已连接。

 ### Twilio 设置检查失败

-当 `voice-call` 未被允许或未启用时，`twilio-voice-call-plugin` 会失败。将其添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，然后重新加载 Gateway 网关。
+当 `voice-call` 未被允许或未启用时，`twilio-voice-call-plugin` 会失败。请将它添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，然后重新加载 Gateway 网关。

-当 Twilio 后端缺少 account SID、auth token 或主叫号码时，`twilio-voice-call-credentials` 会失败。在 Gateway 网关主机上设置这些变量：
+当 Twilio 后端缺少 account SID、auth token 或 caller number 时，`twilio-voice-call-credentials` 会失败。请在 Gateway 网关主机上设置这些值：

 ```bash
 export TWILIO_ACCOUNT_SID=AC...
@ -956,13 +1003,13 @@ openclaw voicecall setup
 openclaw voicecall smoke
 ```

-`voicecall smoke` 默认仅做就绪性检查。若要对某个特定号码进行 dry-run：
+`voicecall smoke` 默认仅检查就绪状态。若要对特定号码进行 dry-run：

 ```bash
 openclaw voicecall smoke --to "+15555550123"
 ```

-只有在你明确要发起真实的外呼通知电话时，才添加 `--yes`：
+只有在你明确想发起真实的出站通知呼叫时，才添加 `--yes`：

 ```bash
 openclaw voicecall smoke --to "+15555550123" --yes
@ -970,7 +1017,7 @@ openclaw voicecall smoke --to "+15555550123" --yes

 ### Twilio 呼叫已开始，但始终未进入会议

-确认 Meet 事件公开了电话拨入详情。传入准确的拨入号码以及 PIN 或自定义 DTMF 序列：
+确认 Meet 事件公开了电话拨入详细信息。传入准确的拨入号码和 PIN，或自定义 DTMF 序列：

 ```bash
 openclaw googlemeet join https://meet.google.com/abc-defg-hij \
@ -983,20 +1030,21 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \

 ## 说明

-Google Meet 的官方媒体 API 偏向接收，因此要向 Meet 通话中发声，仍然需要一个参与者路径。这个插件让这一边界保持清晰可见：
-Chrome 负责浏览器参与和本地音频路由；Twilio 负责电话拨入参与。
+Google Meet 的官方媒体 API 偏向接收，因此要向 Meet 通话中发言，仍然需要一个参会者路径。该插件让这一边界保持可见：
+Chrome 负责浏览器参会和本地音频路由；Twilio 负责电话拨入参会。

-Chrome 实时模式需要以下二者之一：
+Chrome 实时模式需要以下之一：

 - `chrome.audioInputCommand` 加 `chrome.audioOutputCommand`：OpenClaw 拥有实时模型桥接，并在这些命令与所选实时语音提供商之间传输 8 kHz G.711 mu-law 音频。
- `chrome.audioBridgeCommand`：外部桥接命令拥有整个本地音频路径，并且必须在启动或验证其守护进程后退出。
+- `chrome.audioBridgeCommand`：一个外部桥接命令拥有整个本地音频路径，并且必须在启动或验证其守护进程后退出。

-若要获得干净的双工音频，请通过独立的虚拟设备或类似 Loopback 的虚拟设备图来分别路由 Meet 输出和 Meet 麦克风。单个共享的 BlackHole 设备可能会把其他参与者的声音回送进通话中。
+为了获得干净的双工音频，请通过独立的虚拟设备或类似 Loopback 的虚拟设备图来路由 Meet 输出和 Meet 麦克风。单个共享的 BlackHole 设备可能会把其他参与者的声音回送到通话中。

-`googlemeet speak` 会触发 Chrome 会话的活动实时音频桥接。`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委托的 Twilio 会话，`leave` 还会挂断底层语音呼叫。
+`googlemeet speak` 会触发 Chrome 会话的活动实时音频桥接。
+`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委派的 Twilio 会话，`leave` 还会挂断底层语音呼叫。

 ## 相关内容

- [Voice call 插件](/zh-CN/plugins/voice-call)
+- [Voice call plugin](/zh-CN/plugins/voice-call)
 - [Talk mode](/zh-CN/nodes/talk)
 - [构建插件](/zh-CN/plugins/building-plugins)
--- a/docs/zh-CN/tools/browser.md
+++ b/docs/zh-CN/tools/browser.md
@ -1,39 +1,40 @@
 ---
 read_when:
    - 添加由智能体控制的浏览器自动化
-    - 调试为什么 openclaw 会干扰你自己的 Chrome
+    - 调试为什么 openclaw 正在干扰你自己的 Chrome
    - 在 macOS 应用中实现浏览器设置 + 生命周期
-summary: 集成式浏览器控制服务 + 操作命令
+summary: 集成的浏览器控制服务 + 操作命令
 title: 浏览器（由 OpenClaw 管理）
 x-i18n:
-    generated_at: "2026-04-25T06:35:03Z"
+    generated_at: "2026-04-25T07:22:23Z"
    model: gpt-5.4
    provider: openai
-    source_hash: f529cbcc4e818a89274fd9fc25e46b3cc5b30913278d62652ee1100e8ae6dcef
+    source_hash: 3f56eae24f9e247589037a00532c2066699ea7b8595bb18f9e756b4e6a5be2dc
    source_path: tools/browser.md
    workflow: 15
 ---

 OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。  
-它与你的个人浏览器隔离，并通过 Gateway 网关内部的一个小型本地控制服务进行管理（仅限 loopback）。
+它与你的个人浏览器隔离，并通过 Gateway 网关内的一个小型本地控制服务进行管理  
+（仅限 loopback）。

-初学者视角：
+新手视角：

- 可以把它理解为一个**独立的、仅供智能体使用的浏览器**。
+- 可以把它看作一个**独立的、仅供智能体使用的浏览器**。
 - `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。
- 智能体可以在一条安全通道中**打开标签页、读取页面、点击和输入**。
+- 智能体可以在安全通道中**打开标签页、读取页面、点击和输入**。
 - 内置的 `user` 配置文件会通过 Chrome MCP 附加到你真实的已登录 Chrome 会话。

-## 你将获得的内容
+## 你将获得什么

 - 一个名为 **openclaw** 的独立浏览器配置文件（默认使用橙色强调色）。
 - 可预测的标签页控制（列出/打开/聚焦/关闭）。
- 智能体操作（点击/输入/拖拽/选择）、快照、截图、PDF。
- 一个内置的 `browser-automation` Skills，它会在启用浏览器插件时教会智能体使用 snapshot、stable-tab、stale-ref 和 manual-blocker 恢复循环。
+- 智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。
+- 一个内置的 `browser-automation` Skills，用于在启用浏览器插件时教会智能体使用快照、稳定标签页、陈旧引用和手动阻塞恢复循环。
 - 可选的多配置文件支持（`openclaw`、`work`、`remote`，等等）。

-这个浏览器**不是**你日常使用的主浏览器。  
-它是一个安全、隔离的界面，用于智能体自动化和验证。
+这个浏览器**不是**你日常使用的主浏览器。它是一个安全、隔离的表面，用于
+智能体自动化和验证。

 ## 快速开始

@ -45,13 +46,14 @@ 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
 {
@ -65,23 +67,22 @@ openclaw browser --browser-profile openclaw snapshot
 }
 ```

-默认情况下需要同时设置 `plugins.entries.browser.enabled` **和** `browser.enabled=true`。如果只禁用插件，会一次性移除 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具和控制服务；你的 `browser.*` 配置会保留，以供替代方案使用。
+默认设置同时需要 `plugins.entries.browser.enabled` **和** `browser.enabled=true`。仅禁用插件会一次性移除 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具和控制服务；你的 `browser.*` 配置会保持不变，以供替代方案使用。

 浏览器配置变更需要重启 Gateway 网关，这样插件才能重新注册其服务。

 ## 智能体指引

-浏览器插件附带两级智能体指引：
+浏览器插件提供两层智能体指引：

- `browser` 工具描述承载了始终启用的精简契约：选择正确的配置文件、在同一标签页上保持 refs、使用 `tabId`/labels 进行标签页定位，并在进行多步骤工作时加载浏览器 skill。
- 内置的 `browser-automation` Skills 承载更长的操作循环：先检查状态/标签页，为任务标签页打标签，在操作前先做 snapshot，在 UI 变化后重新 snapshot，遇到 stale refs 时恢复一次，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为需要手动操作，而不是猜测处理。
+- `browser` 工具描述承载了始终启用的精简契约：选择正确的配置文件、在同一标签页上保持引用、使用 `tabId`/标签来定位标签页，以及在多步骤任务中加载浏览器 Skills。
+- 内置的 `browser-automation` Skills 承载更完整的操作循环：先检查状态/标签页、为任务标签页加标签、在操作前做快照、在 UI 变化后重新快照、一次性恢复陈旧引用，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为需要手动操作，而不是猜测处理。

-启用插件后，插件内置的 Skills 会显示在智能体的可用技能列表中。  
-完整的技能说明按需加载，因此常规轮次不会承担完整的 token 成本。
+当插件启用时，插件内置的 Skills 会列在智能体可用的 Skills 中。完整的 Skills 指令按需加载，因此日常轮次无需承担完整的 token 成本。

 ## 缺少浏览器命令或工具

-如果升级后 `openclaw browser` 无法识别、缺少 `browser.request`，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中遗漏了 `browser`。请将它加上：
+如果升级后 `openclaw browser` 未知、`browser.request` 缺失，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表遗漏了 `browser`。请把它加上：

 ```json5
 {
@ -91,20 +92,20 @@ openclaw browser --browser-profile openclaw snapshot
 }
 ```

-`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 都不能替代 allowlist 成员资格——allowlist 决定插件是否加载，而工具策略只会在加载之后才生效。完全移除 `plugins.allow` 也会恢复默认行为。
+`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 都不能替代允许列表成员资格——允许列表控制插件是否加载，而工具策略仅在加载后才会运行。完全移除 `plugins.allow` 也会恢复默认行为。

 ## 配置文件：`openclaw` 与 `user`

- `openclaw`：受管理、隔离的浏览器（不需要扩展）。
+- `openclaw`：受管、隔离的浏览器（无需扩展）。
 - `user`：内置的 Chrome MCP 附加配置文件，用于你的**真实已登录 Chrome** 会话。

 对于智能体浏览器工具调用：

 - 默认：使用隔离的 `openclaw` 浏览器。
- 当现有登录会话很重要，并且用户就在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。
- 当你想指定特定浏览器模式时，使用 `profile` 作为显式覆盖。
+- 当现有已登录会话很重要，且用户就在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。
+- 当你希望使用特定浏览器模式时，`profile` 是显式覆盖项。

-如果你想默认使用受管模式，请设置 `browser.defaultProfile: "openclaw"`。
+如果你希望默认使用受管模式，请设置 `browser.defaultProfile: "openclaw"`。

 ## 配置

@ -113,20 +114,21 @@ openclaw browser --browser-profile openclaw snapshot
 ```json5
 {
  browser: {
-    enabled: true, // 默认：true
+    enabled: true, // 默认值：true
    ssrfPolicy: {
-      // dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问场景下选择启用
-      // allowPrivateNetwork: true, // 旧别名
+      // dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问场景中显式启用
+      // allowPrivateNetwork: true, // 旧版别名
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
-    // cdpUrl: "http://127.0.0.1:18792", // 旧的单配置文件覆盖项
-    remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时（毫秒）
-    remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒）
+    // cdpUrl: "http://127.0.0.1:18792", // 旧版单配置文件覆盖项
+    remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时时间（毫秒）
+    remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时时间（毫秒）
+    actionTimeoutMs: 60000, // 默认浏览器 act 超时时间（毫秒）
    tabCleanup: {
-      enabled: true, // 默认：true
-      idleMinutes: 120, // 设为 0 以禁用空闲清理
-      maxTabsPerSession: 8, // 设为 0 以禁用每个会话的上限
+      enabled: true, // 默认值：true
+      idleMinutes: 120, // 设为 0 可禁用空闲清理
+      maxTabsPerSession: 8, // 设为 0 可禁用每会话上限
      sweepMinutes: 5,
    },
    defaultProfile: "openclaw",
@ -164,42 +166,45 @@ openclaw browser --browser-profile openclaw snapshot

 <Accordion title="端口与可达性">

- 控制服务绑定到 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 握手。
- `tabCleanup` 是对主智能体浏览器会话所打开标签页的尽力清理机制。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭它们显式跟踪的标签页；主会话会保留活动标签页以便重复使用，然后在后台关闭空闲或超出数量的已跟踪标签页。
+- `actionTimeoutMs` 是浏览器 `act` 请求的默认时间预算，当调用方未传入 `timeoutMs` 时使用。客户端传输层会额外增加一个很小的缓冲窗口，以便长时间等待能完成，而不会在 HTTP 边界超时。
+- `tabCleanup` 是对主智能体浏览器会话所打开标签页的尽力清理。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭其显式跟踪的标签页；主会话会让活动标签页保持可复用，然后在后台关闭空闲或超额的跟踪标签页。

 </Accordion>

 <Accordion title="SSRF 策略">

- 浏览器导航和打开标签页会在导航前经过 SSRF 防护，并在事后对最终 `http(s)` URL 进行尽力复查。
+- 浏览器导航和打开标签页在导航前会受到 SSRF 防护，并会在最终 `http(s)` URL 上进行尽力的再次检查。
 - 在严格 SSRF 模式下，远程 CDP 端点发现和 `/json/version` 探测（`cdpUrl`）也会被检查。
- Gateway 网关/提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动代理由 OpenClaw 管理的浏览器。默认情况下，受管 Chrome 会直接启动，因此提供商代理设置不会削弱浏览器 SSRF 检查。
- 如果要代理受管浏览器本身，请通过 `browser.extraArgs` 传入显式的 Chrome 代理标志，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。除非你明确启用了私有网络浏览器访问，否则严格 SSRF 模式会阻止显式浏览器代理路由。
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅在你明确可信任私有网络浏览器访问时启用。
- `browser.ssrfPolicy.allowPrivateNetwork` 作为旧别名仍然受支持。
+- Gateway 网关/提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动代理由 OpenClaw 管理的浏览器。受管 Chrome 默认直接启动，因此提供商代理设置不会削弱浏览器 SSRF 检查。
+- 如果要代理受管浏览器本身，请通过 `browser.extraArgs` 传入显式的 Chrome 代理标志，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。严格 SSRF 模式会阻止显式浏览器代理路由，除非已明确启用私有网络浏览器访问。
+- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅当你有意信任私有网络浏览器访问时才启用。
+- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。

 </Accordion>

 <Accordion title="配置文件行为">

- `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`。
+- `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。不要为该驱动设置 `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"
@ -238,47 +243,47 @@ openclaw config set browser.profiles.work.executablePath "/Applications/Google C
  </Tab>
 </Tabs>

-每个配置文件的 `executablePath` 只会影响由 OpenClaw 启动的本地受管配置文件。`existing-session` 配置文件会改为附加到已在运行的浏览器，而远程 CDP 配置文件则使用 `cdpUrl` 背后的浏览器。
+每配置文件的 `executablePath` 只影响由 OpenClaw 启动的本地受管配置文件。`existing-session` 配置文件会改为附加到已运行的浏览器，而远程 CDP 配置文件则使用 `cdpUrl` 背后的浏览器。

 ## 本地控制与远程控制

- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并且可以启动本地浏览器。
- **远程控制（节点主机）：** 在拥有浏览器的机器上运行一个节点主机；Gateway 网关会将浏览器操作代理到它。
- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`）以附加到远程 Chromium 内核浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
- `headless` 只影响由 OpenClaw 启动的本地受管配置文件。它不会重启或改变 existing-session 或远程 CDP 浏览器。
- `executablePath` 也遵循同样的本地受管配置文件规则。在正在运行的本地受管配置文件上更改它，会将该配置文件标记为需要重启/协调，以便下一次启动时使用新的二进制文件。
+- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并可启动本地浏览器。
+- **远程控制（节点主机）：** 在拥有浏览器的机器上运行节点主机；Gateway 网关会将浏览器操作代理到该主机。
+- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`）以附加到远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
+- `headless` 仅影响由 OpenClaw 启动的本地受管配置文件。它不会重启或更改 existing-session 或远程 CDP 浏览器。
+- `executablePath` 遵循同样的本地受管配置文件规则。在正在运行的本地受管配置文件上更改它时，该配置文件会被标记为需要重启/协调，以便下次启动时使用新的二进制文件。

-停止行为会因配置文件模式不同而有所区别：
+停止行为因配置文件模式而异：

 - 本地受管配置文件：`openclaw browser stop` 会停止由 OpenClaw 启动的浏览器进程
- 仅附加和远程 CDP 配置文件：`openclaw browser stop` 会关闭当前控制会话，并释放 Playwright/CDP 模拟覆盖项（视口、配色方案、区域设置、时区、离线模式以及类似状态），即使 OpenClaw 并未启动任何浏览器进程
+- 仅附加和远程 CDP 配置文件：`openclaw browser stop` 会关闭活动控制会话，并释放 Playwright/CDP 仿真覆盖项（视口、配色方案、语言区域、时区、离线模式及类似状态），即使没有任何浏览器进程是由 OpenClaw 启动的

 远程 CDP URL 可以包含认证信息：

 - 查询 token（例如 `https://provider.example?token=<token>`）
- HTTP Basic auth（例如 `https://user:pass@provider.example`）
+- 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 中的配置文件可以作为目标，并且持久化配置文件的创建/删除路由会在代理界面上被阻止。
- 如果你不想使用它，可以禁用：
+- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空可保留旧版/默认行为：所有已配置的配置文件都仍可通过代理访问，包括配置文件创建/删除路由。
+- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有允许列表中的配置文件可作为目标，且持久化配置文件创建/删除路由会在代理表面被阻止。
+- 如果你不想启用它，可以关闭：
  - 在节点上：`nodeHost.browserProxy.enabled=false`
-  - 在 Gateway 网关上：`gateway.nodes.browser.mode="off"`
+  - 在网关上：`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。

 示例：

@ -299,27 +304,27 @@ OpenClaw 在调用 `/json/*` 端点以及连接 CDP WebSocket 时都会保留这
 }
 ```

-注意事项：
+说明：

- 请将 `<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 调试器 URL，然后连接。没有 WebSocket 回退。
+  OpenClaw 会调用 `/json/version` 来发现 WebSocket 调试器 URL，然后再连接。没有 WebSocket 回退。
 - **直接 WebSocket 端点** — `ws://host[:port]/devtools/<kind>/<id>` 或  
-  `wss://...` 且路径为 `/devtools/browser|page|worker|shared_worker|service_worker/<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 升级。
+- **裸 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
 {
@ -338,53 +343,55 @@ OpenClaw 在调用 `/json/*` 端点以及连接 CDP WebSocket 时都会保留这
 }
 ```

-注意事项：
+说明：

- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview dashboard](https://www.browserbase.com/overview) 复制你的 **API Key**。
- 请将 `<BROWSERBASE_API_KEY>` 替换为你真实的 Browserbase API key。
+- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview 仪表板](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)。
+- 完整 API 参考、SDK 指南和集成示例请参见 [Browserbase 文档](https://docs.browserbase.com)。

-## 安全性
+## 安全

 关键概念：

- 浏览器控制仅限 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` 并将其持久化到配置中。
+- 浏览器控制仅限 loopback；访问通过 Gateway 网关认证或节点配对流转。
+- 独立的 loopback 浏览器 HTTP API **仅**使用共享密钥认证：  
+  gateway token bearer 认证、`x-openclaw-password`，或带有已配置 gateway 密码的 HTTP Basic 认证。
+- Tailscale Serve 身份头和 `gateway.auth.mode: "trusted-proxy"`  
+  **不会**为这个独立的 loopback 浏览器 API 提供认证。
+- 如果启用了浏览器控制且未配置任何共享密钥认证，OpenClaw 会在启动时自动生成 `gateway.auth.token`，并将其持久化到配置中。
 - 当 `gateway.auth.mode` 已经是 `password`、`none` 或 `trusted-proxy` 时，OpenClaw **不会**自动生成该 token。
- 请将 Gateway 网关和任何节点主机保持在私有网络（Tailscale）中；避免公开暴露。
- 请将远程 CDP URL/token 视为机密；优先使用环境变量或密钥管理器。
+- 请将 Gateway 网关和任何节点主机放在私有网络（Tailscale）中；避免公开暴露。
+- 将远程 CDP URL/token 视为机密；优先使用环境变量或密钥管理器。

 远程 CDP 提示：

- 尽可能优先使用加密端点（HTTPS 或 WSS）以及短期 token。
- 避免将长期 token 直接嵌入配置文件。
+- 尽可能优先使用加密端点（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` 创建它们。
+- 如果缺少 `openclaw` 配置文件，会自动创建它。
+- `user` 配置文件是内置的，用于 Chrome MCP existing-session 附加。
+- 除 `user` 之外，existing-session 配置文件需要显式启用；可使用 `--driver existing-session` 创建。
 - 本地 CDP 端口默认从 **18800–18899** 分配。
- 删除配置文件会将其本地数据目录移到废纸篓。
+- 删除配置文件时，其本地数据目录会被移到废纸篓。

 所有控制端点都接受 `?profile=<name>`；CLI 使用 `--browser-profile`。

-## 通过 Chrome DevTools MCP 连接现有会话
+## 通过 Chrome DevTools MCP 使用现有会话

-OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运行的 Chromium 内核浏览器配置文件。这样可以复用该浏览器配置文件中已经打开的标签页和登录状态。
+OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运行的基于 Chromium 的浏览器配置文件。这样可以复用该浏览器配置文件中已经打开的标签页和登录状态。

 官方背景与设置参考：

@ -395,13 +402,13 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运

 - `user`

-可选：如果你想使用不同的名称、颜色或浏览器数据目录，也可以创建自己的自定义 existing-session 配置文件。
+可选：如果你想使用不同的名称、颜色或浏览器数据目录，可以创建你自己的自定义 existing-session 配置文件。

 默认行为：

- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，目标是默认的本地 Google Chrome 配置文件。
+- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，其目标是默认的本地 Google Chrome 配置文件。

-如果要用于 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`：
+对 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`：

 ```json5
 {
@ -420,11 +427,11 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运

 然后在对应的浏览器中：

-1. 打开该浏览器用于远程调试的 inspect 页面。
+1. 打开该浏览器的远程调试检查页面。
 2. 启用远程调试。
 3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。

-常见的 inspect 页面：
+常见的检查页面：

 - Chrome：`chrome://inspect/#remote-debugging`
 - Brave：`brave://inspect/#remote-debugging`
@ -439,51 +446,51 @@ openclaw browser --browser-profile user tabs
 openclaw browser --browser-profile user snapshot --format ai
 ```

-成功时的表现：
+成功时应看到：

 - `status` 显示 `driver: existing-session`
 - `status` 显示 `transport: chrome-mcp`
 - `status` 显示 `running: true`
- `tabs` 会列出你已经打开的浏览器标签页
- `snapshot` 会返回所选实时标签页中的 refs
+- `tabs` 列出你已打开的浏览器标签页
+- `snapshot` 返回所选实时标签页中的引用

 如果附加不起作用，请检查：

- 目标 Chromium 内核浏览器版本是否为 `144+`
- 该浏览器的 inspect 页面中是否启用了远程调试
- 浏览器是否显示了附加同意提示，并且你已经接受
- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法替你启用浏览器侧的远程调试
+- 目标的基于 Chromium 的浏览器版本为 `144+`
+- 该浏览器的检查页面中已启用远程调试
+- 浏览器显示了附加授权提示，且你已接受
+- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法替你启用浏览器侧远程调试

 智能体使用：

- 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。
- 如果你使用自定义 existing-session 配置文件，请传入该显式配置文件名。
- 仅当用户就在电脑前可以批准附加提示时才选择此模式。
+- 当你需要用户已登录浏览器状态时，使用 `profile="user"`。
+- 如果你使用自定义 existing-session 配置文件，请传入该明确的配置文件名称。
+- 仅当用户就在电脑前可以批准附加提示时，才选择此模式。
 - Gateway 网关或节点主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect`

-注意事项：
+说明：

- 与隔离的 `openclaw` 配置文件相比，这条路径风险更高，因为它可以在你的已登录浏览器会话中操作。
- 对于这个 driver，OpenClaw 不会启动浏览器；它只会进行附加。
- OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果设置了 `userDataDir`，它会一并传入以定位该用户数据目录。
- existing-session 可以附加到所选主机上，或者通过已连接的浏览器节点附加。如果 Chrome 位于其他地方且没有连接任何浏览器节点，请改用远程 CDP 或节点主机。
+- 与隔离的 `openclaw` 配置文件相比，此路径风险更高，因为它可以在你已登录的浏览器会话中执行操作。
+- 对于这个驱动，OpenClaw 不会启动浏览器；它只会附加。
+- OpenClaw 在此处使用官方 Chrome DevTools MCP `--autoConnect` 流程。如果设置了 `userDataDir`，则会将其一并传递，以定位该用户数据目录。
+- Existing-session 可以附加到所选主机上，也可以通过已连接的浏览器节点附加。如果 Chrome 位于其他地方且未连接任何浏览器节点，请改用远程 CDP 或节点主机。

-<Accordion title="existing-session 功能限制">
+<Accordion title="Existing-session 功能限制">

-与受管的 `openclaw` 配置文件相比，existing-session driver 的限制更多：
+与受管的 `openclaw` 配置文件相比，existing-session 驱动有更多限制：

- **截图** — 支持页面截图和 `--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` 仍然需要受管浏览器路径。
+- **截图** —— 支持页面截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面截图或基于 ref 的元素截图不需要 Playwright。
+- **操作** —— `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要快照 ref（不支持 CSS 选择器）。`click-coords` 点击可见视口坐标，不需要快照 ref。`click` 仅支持左键。`type` 不支持 `slowly=true`；请改用 `fill` 或 `press`。`press` 不支持 `delayMs`。`type`、`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用设置超时。`select` 接受单个值。
+- **等待 / 上传 / 对话框** —— `wait --url` 支持精确匹配、子串匹配和 glob 模式；不支持 `wait --load networkidle`。上传钩子需要 `ref` 或 `inputRef`，一次只能上传一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。
+- **仅受管模式功能** —— 批量操作、PDF 导出、下载拦截和 `responsebody` 仍然需要受管浏览器路径。

 </Accordion>

 ## 隔离保证

- **专用用户数据目录**：绝不会接触你的个人浏览器配置文件。
+- **专用用户数据目录**：绝不会触碰你的个人浏览器配置文件。
 - **专用端口**：避免使用 `9222`，以防与开发工作流冲突。
- **可预测的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId` 句柄，例如 `t1`、可选 labels，以及原始 `targetId`。智能体应复用 `suggestedTargetId`；原始 id 仍然保留，以便调试和兼容。
+- **可预测的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后返回稳定的 `tabId` 句柄，如 `t1`、可选标签以及原始 `targetId`。智能体应复用 `suggestedTargetId`；原始 id 仍保留用于调试和兼容性。

 ## 浏览器选择

@ -495,7 +502,7 @@ openclaw browser --browser-profile user snapshot --format ai
 4. Chromium
 5. Chrome Canary

-你可以通过 `browser.executablePath` 进行覆盖。
+你可以通过 `browser.executablePath` 覆盖此行为。

 平台说明：

@ -505,32 +512,33 @@ openclaw browser --browser-profile user snapshot --format ai

 ## 控制 API（可选）

-为了便于脚本编写和调试，Gateway 网关暴露了一个小型的**仅限 loopback 的 HTTP 控制 API**，并提供与之匹配的 `openclaw browser` CLI（快照、refs、wait 增强功能、JSON 输出、调试工作流）。完整参考请参见 [Browser control API](/zh-CN/tools/browser-control)。
+为了便于编写脚本和调试，Gateway 网关暴露了一个小型的**仅 loopback 的 HTTP 控制 API**，以及与之匹配的 `openclaw browser` CLI（快照、引用、等待增强、JSON 输出、调试工作流）。完整参考请参见  
+[浏览器控制 API](/zh-CN/tools/browser-control)。

 ## 故障排除

-有关 Linux 特定问题（尤其是 snap Chromium），请参见  
-[Browser 故障排除](/zh-CN/tools/browser-linux-troubleshooting)。
+对于 Linux 特定问题（尤其是 snap Chromium），请参见  
+[浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)。

 对于 WSL2 Gateway 网关 + Windows Chrome 分离主机设置，请参见  
 [WSL2 + Windows + 远程 Chrome CDP 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)。

-### CDP 启动失败 vs 导航 SSRF 阻止
+### CDP 启动失败与导航 SSRF 拦截

-这是两类不同的失败，它们指向不同的代码路径。
+这是两类不同的失败，它们对应不同的代码路径。

- **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。
- **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但页面导航目标因策略被拒绝。
+- **CDP 启动或就绪性失败** 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。
+- **导航 SSRF 拦截** 表示浏览器控制平面是健康的，但页面导航目标因策略而被拒绝。

 常见示例：

- CDP 启动或就绪失败：
+- CDP 启动或就绪性失败：
  - `Chrome CDP websocket for profile "openclaw" is not reachable after start`
  - `Remote CDP for profile "<name>" is not reachable at <cdpUrl>`
- 导航 SSRF 阻止：
-  - 当 `start` 和 `tabs` 仍然可用时，`open`、`navigate`、snapshot 或打开标签页流程因浏览器/网络策略错误而失败
+- 导航 SSRF 拦截：
+  - 当 `start` 和 `tabs` 仍然可用时，`open`、`navigate`、快照或打开标签页流程因浏览器/网络策略错误而失败

-使用以下最小序列来区分两者：
+使用下面这个最小序列来区分两者：

 ```bash
 openclaw browser --browser-profile openclaw start
@ -540,46 +548,46 @@ openclaw browser --browser-profile openclaw open https://example.com

 结果解读方式：

- 如果 `start` 因 `not reachable after start` 失败，请先排查 CDP 就绪性。
- 如果 `start` 成功但 `tabs` 失败，说明控制平面仍然不健康。请将其视为 CDP 可达性问题，而不是页面导航问题。
- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，说明浏览器控制平面已经启动，失败点在导航策略或目标页面。
+- 如果 `start` 失败，并显示 `not reachable after start`，请先排查 CDP 就绪性问题。
+- 如果 `start` 成功但 `tabs` 失败，说明控制平面仍然不健康。应将其视为 CDP 可达性问题，而不是页面导航问题。
+- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，说明浏览器控制平面已启动，失败发生在导航策略或目标页面上。
 - 如果 `start`、`tabs` 和 `open` 全部成功，说明基础的受管浏览器控制路径是健康的。

 重要行为细节：

 - 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会使用一个失败即关闭的 SSRF 策略对象。
- 对于本地 loopback 的 `openclaw` 受管配置文件，CDP 健康检查会有意跳过对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制执行。
+- 对于本地 loopback 的 `openclaw` 受管配置文件，CDP 健康检查会有意跳过对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制检查。
 - 导航保护是独立的。`start` 或 `tabs` 成功，并不意味着之后的 `open` 或 `navigate` 目标一定被允许。

 安全建议：

 - **不要**默认放宽浏览器 SSRF 策略。
- 相比广泛开放私有网络访问，优先使用更窄范围的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`。
- 仅在明确受信任、确实需要并且已审查私有网络浏览器访问的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。
+- 优先使用精确的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`，而不是宽泛的私有网络访问。
+- 仅在明确受信任、确实需要且已审查私有网络浏览器访问的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。

 ## 智能体工具 + 控制工作方式

-智能体会获得**一个工具**用于浏览器自动化：
+智能体获得**一个工具**用于浏览器自动化：

 - `browser` — doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

-映射关系如下：
+它的映射方式如下：

 - `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。
- `browser act` 使用 snapshot `ref` ID 来执行点击/输入/拖拽/选择。
- `browser screenshot` 捕获像素截图（整页、元素或带标签的 refs）。
- `browser doctor` 检查 Gateway 网关、插件、配置文件、浏览器和标签页就绪情况。
+- `browser act` 使用快照中的 `ref` ID 来执行点击/输入/拖动/选择。
+- `browser screenshot` 捕获像素内容（整页、元素或带标签的引用）。
+- `browser doctor` 检查 Gateway 网关、插件、配置文件、浏览器和标签页的就绪状态。
 - `browser` 接受：
-  - `profile`，用于选择命名浏览器配置文件（openclaw、chrome 或远程 CDP）。
-  - `target`（`sandbox` | `host` | `node`），用于选择浏览器所在位置。
+  - `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/tools) — 所有可用的智能体工具
 - [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的浏览器控制
- [安全性](/zh-CN/gateway/security) — 浏览器控制的风险与加固
+- [安全](/zh-CN/gateway/security) — 浏览器控制的风险与加固