diff --git a/docs/zh-CN/cli/acp.md b/docs/zh-CN/cli/acp.md
index 0e51dcace..c2cfd11c6 100644
--- a/docs/zh-CN/cli/acp.md
+++ b/docs/zh-CN/cli/acp.md
@@ -1,29 +1,33 @@
 ---
 read_when:
     - 设置基于 ACP 的 IDE 集成
-    - 调试到 Gateway 网关的 ACP 会话路由
-summary: 运行用于 IDE 集成的 ACP bridge
+    - 调试 ACP 会话路由到 Gateway 网关
+summary: 为 IDE 集成运行 ACP 桥接器
 title: ACP
 x-i18n:
-    generated_at: "2026-04-23T20:42:42Z"
+    generated_at: "2026-04-24T02:39:42Z"
     model: gpt-5.4
     provider: openai
-    source_hash: b535e84f8ba5f143340af5b6a1e651b0711ba8d5fa58bfb76863612718ed07bb
+    source_hash: 04a1413c23464489a192f5d99cd97f128c0ddc080f3ae637073147a2b07ce305
     source_path: cli/acp.md
     workflow: 15
 ---
 
-运行与 OpenClaw Gateway 网关通信的 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) bridge。
+运行与 OpenClaw Gateway 网关通信的 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) 桥接器。
 
-此命令通过 stdio 为 IDE 提供 ACP，并通过 WebSocket 将提示转发到 Gateway 网关。它会将 ACP 会话持续映射到 Gateway 网关会话键。
+此命令通过 `stdio` 为 IDE 提供 ACP，并通过 WebSocket 将提示转发到 Gateway 网关。
+它会让 ACP 会话持续映射到 Gateway 网关会话键。
 
-`openclaw acp` 是一个由 Gateway 网关支持的 ACP bridge，而不是完整的原生 ACP 编辑器运行时。它专注于会话路由、提示传递和基础流式更新。
+`openclaw acp` 是一个由 Gateway 网关支持的 ACP 桥接器，不是完整的 ACP 原生编辑器
+运行时。它专注于会话路由、提示传递和基础的流式更新。
 
-如果你希望外部 MCP 客户端直接与 OpenClaw 渠道会话通信，而不是托管 ACP harness 会话，请改用 [`openclaw mcp serve`](/zh-CN/cli/mcp)。
+如果你希望外部 MCP 客户端直接与 OpenClaw 渠道
+会话通信，而不是托管 ACP harness 会话，请改用
+[`openclaw mcp serve`](/zh-CN/cli/mcp)。
 
 ## 这不是什么
 
-本页经常与 ACP harness 会话混淆。
+此页面经常与 ACP harness 会话混淆。
 
 `openclaw acp` 的含义是：
 
@@ -31,47 +35,61 @@ x-i18n:
 - IDE 或 ACP 客户端连接到 OpenClaw
 - OpenClaw 将这些工作转发到 Gateway 网关会话中
 
-这与 [ACP Agents](/zh-CN/tools/acp-agents) 不同，后者是 OpenClaw 通过 `acpx` 运行外部 harness，例如 Codex 或 Claude Code。
+这不同于 [ACP Agents](/zh-CN/tools/acp-agents)，后者中 OpenClaw 会通过 `acpx` 运行
+外部 harness，例如 Codex 或 Claude Code。
 
-快速判断规则：
+快速规则：
 
 - 编辑器/客户端想通过 ACP 与 OpenClaw 通信：使用 `openclaw acp`
 - OpenClaw 应启动 Codex/Claude/Gemini 作为 ACP harness：使用 `/acp spawn` 和 [ACP Agents](/zh-CN/tools/acp-agents)
 
 ## 兼容性矩阵
 
-| ACP 区域                                                              | 状态      | 说明                                                                                                                                                                                                                                             |
-| --------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `initialize`、`newSession`、`prompt`、`cancel`                        | 已实现    | 通过 stdio 到 Gateway 网关 `chat/send` + 中止的核心 bridge 流程。                                                                                                                                                                               |
-| `listSessions`、斜杠命令                                              | 已实现    | 会话列表可基于 Gateway 网关会话状态工作；命令通过 `available_commands_update` 对外公布。                                                                                                                                                        |
-| `loadSession`                                                         | 部分支持  | 将 ACP 会话重新绑定到 Gateway 网关会话键，并重放已存储的用户/助手文本历史。工具/系统历史目前尚未重建。                                                                                                                                         |
-| 提示内容（`text`、嵌入式 `resource`、图像）                           | 部分支持  | 文本/资源会被展平成聊天输入；图像会变为 Gateway 网关附件。                                                                                                                                                                                       |
-| 会话模式                                                              | 部分支持  | 支持 `session/set_mode`，且 bridge 会暴露初始的 Gateway 网关支持的会话控制，包括 thought level、tool verbosity、reasoning、usage detail 和 elevated actions。更广泛的 ACP 原生模式/配置界面仍不在范围内。                                     |
-| 会话信息和使用量更新                                                  | 部分支持  | bridge 会根据缓存的 Gateway 网关会话快照发出 `session_info_update` 和尽力而为的 `usage_update` 通知。使用量是近似值，且仅当 Gateway 网关将 token 总量标记为新鲜时才会发送。                                                                  |
-| 工具流式传输                                                          | 部分支持  | `tool_call` / `tool_call_update` 事件包含原始 I/O、文本内容，以及在 Gateway 网关工具参数/结果暴露这些内容时尽力而为提取的文件位置。嵌入式终端和更丰富的原生 Diffs 输出目前仍未暴露。                                                        |
-| 每会话 MCP 服务器（`mcpServers`）                                     | 不支持    | bridge 模式会拒绝每会话 MCP 服务器请求。请改为在 OpenClaw gateway 或智能体上配置 MCP。                                                                                                                                                          |
-| 客户端文件系统方法（`fs/read_text_file`、`fs/write_text_file`）       | 不支持    | bridge 不会调用 ACP 客户端文件系统方法。                                                                                                                                                                                                         |
-| 客户端终端方法（`terminal/*`）                                        | 不支持    | bridge 不会创建 ACP 客户端终端，也不会通过工具调用流式传输终端 ID。                                                                                                                                                                             |
-| 会话计划 / thought 流式传输                                           | 不支持    | bridge 当前发出的是输出文本和工具状态，而不是 ACP 计划或 thought 更新。                                                                                                                                                                         |
+| ACP 区域                                                              | 状态 | 说明                                                                                                                                                                                                                                   |
+| --------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initialize`, `newSession`, `prompt`, `cancel`                        | 已实现 | 通过 `stdio` 到 Gateway 网关 chat/send + abort 的核心桥接流程。                                                                                                                                                                         |
+| `listSessions`, 斜杠命令                                               | 已实现 | 会话列表基于 Gateway 网关会话状态工作；命令通过 `available_commands_update` 进行通告。                                                                                                                                                  |
+| `loadSession`                                                         | 部分支持 | 将 ACP 会话重新绑定到 Gateway 网关会话键，并重放存储的用户/助手文本历史。工具/系统历史尚未重建。                                                                                                                                       |
+| 提示内容（`text`、嵌入式 `resource`、图片）                           | 部分支持 | 文本/资源会被展平为 chat 输入；图片会成为 Gateway 网关附件。                                                                                                                                                                             |
+| 会话模式                                                              | 部分支持 | 支持 `session/set_mode`，并且桥接器公开了初始的 Gateway 网关支持会话控制，用于 thought level、tool verbosity、reasoning、usage detail 和 elevated actions。更广泛的 ACP 原生模式/配置表面仍不在当前范围内。                            |
+| 会话信息和用量更新                                                    | 部分支持 | 桥接器会根据缓存的 Gateway 网关会话快照发出 `session_info_update` 和尽力而为的 `usage_update` 通知。用量是近似值，且仅当 Gateway 网关将 token 总量标记为最新时才会发送。                                                             |
+| 工具流式传输                                                          | 部分支持 | `tool_call` / `tool_call_update` 事件会包含原始 I/O、文本内容，以及当 Gateway 网关工具参数/结果暴露这些信息时尽力而为提供的文件位置。嵌入式终端和更丰富的原生 Diffs 输出仍未暴露。                                                     |
+| 每会话 MCP 服务器（`mcpServers`）                                     | 不支持 | 桥接模式会拒绝每会话 MCP 服务器请求。请改为在 OpenClaw gateway 或智能体上配置 MCP。                                                                                                                                                     |
+| 客户端文件系统方法（`fs/read_text_file`, `fs/write_text_file`）       | 不支持 | 该桥接器不会调用 ACP 客户端文件系统方法。                                                                                                                                                                                                |
+| 客户端终端方法（`terminal/*`）                                        | 不支持 | 该桥接器不会创建 ACP 客户端终端，也不会通过工具调用流式传输终端 ID。                                                                                                                                                                    |
+| 会话计划 / thought 流式传输                                           | 不支持 | 该桥接器当前会发出输出文本和工具状态，而不是 ACP 计划或 thought 更新。                                                                                                                                                                  |
 
 ## 已知限制
 
-- `loadSession` 会重放已存储的用户和助手文本历史，但不会重建历史工具调用、系统通知或更丰富的 ACP 原生事件类型。
-- 如果多个 ACP 客户端共享同一个 Gateway 网关会话键，事件和取消路由仅为尽力而为，而不是严格按客户端隔离。若你需要清晰的编辑器本地轮次，优先使用默认隔离的 `acp:<uuid>` 会话。
-- Gateway 网关停止状态会被转换为 ACP 停止原因，但这种映射的表达能力弱于完整的 ACP 原生运行时。
-- 初始会话控制目前只暴露一组聚焦的 Gateway 网关选项：thought level、tool verbosity、reasoning、usage detail 和 elevated actions。模型选择和 exec-host 控制尚未作为 ACP 配置选项暴露。
-- `session_info_update` 和 `usage_update` 来源于 Gateway 网关会话快照，而不是实时 ACP 原生运行时统计。使用量是近似值，不包含成本数据，并且只有当 Gateway 网关将总 token 数据标记为新鲜时才会发出。
-- 工具跟随数据是尽力而为的。bridge 可以展示已知工具参数/结果中出现的文件路径，但目前尚不会发出 ACP 终端或结构化文件 Diffs。
+- `loadSession` 会重放存储的用户和助手文本历史，但不会
+  重建历史工具调用、系统通知或更丰富的 ACP 原生事件
+  类型。
+- 如果多个 ACP 客户端共享同一个 Gateway 网关会话键，事件和取消
+  路由将是尽力而为，而不是严格按客户端完全隔离。若你需要
+  干净的编辑器本地轮次，优先使用默认隔离的 `acp:<uuid>` 会话。
+- Gateway 网关停止状态会被转换为 ACP 停止原因，但这种映射
+  不如完整 ACP 原生运行时那样具有表现力。
+- 初始会话控制当前只公开一组聚焦的 Gateway 网关旋钮：
+  thought level、tool verbosity、reasoning、usage detail 和 elevated
+  actions。模型选择和 exec-host 控制尚未作为 ACP
+  配置选项公开。
+- `session_info_update` 和 `usage_update` 来源于 Gateway 网关会话
+  快照，而不是实时 ACP 原生运行时统计。用量是近似值，
+  不包含成本数据，并且仅在 Gateway 网关将总 token
+  数据标记为最新时发出。
+- 工具跟随数据是尽力而为的。桥接器可以公开已知工具参数/结果中
+  出现的文件路径，但它尚不会发出 ACP 终端或
+  结构化文件 Diffs。
 
 ## 用法
 
 ```bash
 openclaw acp
 
-# 远程 Gateway 网关
+# 远程 Gateway
 openclaw acp --url wss://gateway-host:18789 --token <token>
 
-# 远程 Gateway 网关（从文件读取 token）
+# 远程 Gateway（从文件读取 token）
 openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
 
 # 附加到现有会话键
@@ -80,19 +98,19 @@ openclaw acp --session agent:main:main
 # 按标签附加（必须已存在）
 openclaw acp --session-label "support inbox"
 
-# 在第一条提示前重置会话键
+# 在第一个提示之前重置会话键
 openclaw acp --session agent:main:main --reset-session
 ```
 
 ## ACP 客户端（调试）
 
-使用内置 ACP 客户端可在无需 IDE 的情况下对 bridge 做完整性检查。
-它会启动 ACP bridge，并允许你以交互方式输入提示。
+使用内置 ACP 客户端在没有 IDE 的情况下对桥接器进行安装完整性检查。
+它会启动 ACP 桥接器，并允许你以交互方式输入提示。
 
 ```bash
 openclaw acp client
 
-# 让启动的 bridge 指向远程 Gateway 网关
+# 让启动的桥接器指向远程 Gateway 网关
 openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
 
 # 覆盖服务器命令（默认：openclaw）
@@ -101,19 +119,20 @@ openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://12
 
 权限模型（客户端调试模式）：
 
-- 自动批准基于允许列表，并且只适用于受信任的核心工具 ID。
-- `read` 自动批准范围限制在当前工作目录（设置了 `--cwd` 时）。
-- ACP 只会自动批准狭窄的只读类别：活动 cwd 下受限范围内的 `read` 调用，以及只读搜索工具（`search`、`web_search`、`memory_search`）。未知/非核心工具、超出范围的读取、具备执行能力的工具、控制平面工具、会修改状态的工具和交互式流程始终需要显式提示批准。
+- 自动批准基于 allowlist，并且只适用于受信任的核心工具 ID。
+- `read` 自动批准仅限当前工作目录（设置了 `--cwd` 时）。
+- ACP 仅会自动批准范围很窄的只读类别：活动 cwd 下受限的 `read` 调用，以及只读搜索工具（`search`、`web_search`、`memory_search`）。未知/非核心工具、超范围读取、可执行工具、控制平面工具、变更型工具和交互式流程始终需要显式提示批准。
 - 服务器提供的 `toolCall.kind` 被视为不受信任的元数据（不是授权来源）。
-- 此 ACP bridge 策略与 ACPX harness 权限无关。如果你通过 `acpx` 后端运行 OpenClaw，`plugins.entries.acpx.config.permissionMode=approve-all` 是该 harness 会话的紧急放行 “yolo” 开关。
+- 此 ACP 桥接器策略独立于 ACPX harness 权限。如果你通过 `acpx` 后端运行 OpenClaw，`plugins.entries.acpx.config.permissionMode=approve-all` 是该 harness 会话的紧急放开式 “yolo” 开关。
 
 ## 如何使用
 
-当 IDE（或其他客户端）支持 Agent Client Protocol，并且你希望它驱动 OpenClaw Gateway 网关会话时，请使用 ACP。
+当 IDE（或其他客户端）支持 Agent Client Protocol，并且你希望
+它驱动一个 OpenClaw Gateway 网关会话时，请使用 ACP。
 
 1. 确保 Gateway 网关正在运行（本地或远程）。
-2. 配置 Gateway 网关目标（通过配置或命令行标志）。
-3. 将你的 IDE 指向通过 stdio 运行 `openclaw acp`。
+2. 配置 Gateway 网关目标（配置或标志）。
+3. 让你的 IDE 通过 `stdio` 运行 `openclaw acp`。
 
 示例配置（持久化）：
 
@@ -126,15 +145,15 @@ openclaw config set gateway.remote.token <token>
 
 ```bash
 openclaw acp --url wss://gateway-host:18789 --token <token>
-# 本地进程安全的推荐方式
+# 本地进程安全时优先推荐
 openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
 ```
 
 ## 选择智能体
 
-ACP 不会直接选择智能体。它通过 Gateway 网关会话键进行路由。
+ACP 不会直接选择智能体。它按 Gateway 网关会话键进行路由。
 
-使用带智能体作用域的会话键来定位特定智能体：
+使用带有智能体作用域的会话键来定位特定智能体：
 
 ```bash
 openclaw acp --session agent:main:main
@@ -142,35 +161,44 @@ openclaw acp --session agent:design:main
 openclaw acp --session agent:qa:bug-123
 ```
 
-每个 ACP 会话都映射到单个 Gateway 网关会话键。一个智能体可以拥有多个会话；ACP 默认使用隔离的 `acp:<uuid>` 会话，除非你覆盖该键或标签。
+每个 ACP 会话都映射到单个 Gateway 网关会话键。一个智能体可以拥有多个
+会话；除非你覆盖该键或标签，否则 ACP 默认使用隔离的 `acp:<uuid>` 会话。
 
-bridge 模式不支持每会话 `mcpServers`。如果 ACP 客户端在 `newSession` 或 `loadSession` 期间发送它们，bridge 会返回清晰的错误，而不是悄悄忽略。
+桥接模式不支持每会话 `mcpServers`。如果 ACP 客户端
+在 `newSession` 或 `loadSession` 期间发送它们，桥接器会返回清晰的
+错误，而不是静默忽略。
 
-如果你希望由 ACPX 支持的会话能够看到 OpenClaw 渠道插件工具或选定的内置工具（例如 `cron`），请启用 Gateway 网关侧的 ACPX MCP bridges，而不是尝试传递每会话 `mcpServers`。请参阅 [ACP Agents](/zh-CN/tools/acp-agents#plugin-tools-mcp-bridge) 和 [OpenClaw 工具 MCP bridge](/zh-CN/tools/acp-agents#openclaw-tools-mcp-bridge)。
+如果你希望由 ACPX 支持的会话看到 OpenClaw 插件工具或选定的
+内置工具，例如 `cron`，请启用 Gateway 网关侧的 ACPX MCP 桥接，
+而不是尝试传递每会话 `mcpServers`。请参见
+[ACP Agents](/zh-CN/tools/acp-agents-setup#plugin-tools-mcp-bridge) 和
+[OpenClaw tools MCP bridge](/zh-CN/tools/acp-agents-setup#openclaw-tools-mcp-bridge)。
 
 ## 从 `acpx` 使用（Codex、Claude、其他 ACP 客户端）
 
-如果你希望 Codex 或 Claude Code 这样的编码智能体通过 ACP 与你的 OpenClaw 机器人通信，请使用 `acpx` 及其内置的 `openclaw` 目标。
+如果你希望 Codex 或 Claude Code 这类编码智能体
+通过 ACP 与你的 OpenClaw bot 通信，请使用带有其内置 `openclaw` 目标的 `acpx`。
 
 典型流程：
 
-1. 运行 Gateway 网关，并确保 ACP bridge 可以连接到它。
-2. 将 `acpx openclaw` 指向 `openclaw acp`。
-3. 指定你希望该编码智能体使用的 OpenClaw 会话键。
+1. 运行 Gateway 网关，并确保 ACP 桥接器可以访问它。
+2. 让 `acpx openclaw` 指向 `openclaw acp`。
+3. 定位你希望编码智能体使用的 OpenClaw 会话键。
 
 示例：
 
 ```bash
-# 向默认 OpenClaw ACP 会话发起一次性请求
+# 向你的默认 OpenClaw ACP 会话发送一次性请求
 acpx openclaw exec "Summarize the active OpenClaw session state."
 
-# 用于后续轮次的持久化命名会话
+# 用于后续轮次的持久命名会话
 acpx openclaw sessions ensure --name codex-bridge
 acpx openclaw -s codex-bridge --cwd /path/to/repo \
   "Ask my OpenClaw work agent for recent context relevant to this repo."
 ```
 
-如果你希望 `acpx openclaw` 每次都指向特定的 Gateway 网关和会话键，可在 `~/.acpx/config.json` 中覆盖 `openclaw` 智能体命令：
+如果你希望 `acpx openclaw` 每次都定位特定的 Gateway 网关和会话键，
+请在 `~/.acpx/config.json` 中覆盖 `openclaw` 智能体命令：
 
 ```json
 {
@@ -182,17 +210,19 @@ acpx openclaw -s codex-bridge --cwd /path/to/repo \
 }
 ```
 
-对于仓库本地的 OpenClaw 检出，请使用直接 CLI 入口点，而不是开发运行器，以保持 ACP 流干净。例如：
+对于仓库本地的 OpenClaw 检出，请使用直接 CLI 入口点，而不是
+dev runner，这样 ACP 流才能保持干净。例如：
 
 ```bash
 env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
 ```
 
-这是让 Codex、Claude Code 或其他支持 ACP 的客户端从 OpenClaw 智能体中提取上下文信息、而无需抓取终端内容的最简单方式。
+这是让 Codex、Claude Code 或其他支持 ACP 的客户端
+从 OpenClaw 智能体提取上下文信息、而无需抓取终端内容的最简单方式。
 
 ## Zed 编辑器设置
 
-在 `~/.config/zed/settings.json` 中添加自定义 ACP 智能体（或使用 Zed 的设置 UI）：
+在 `~/.config/zed/settings.json` 中添加一个自定义 ACP 智能体（或使用 Zed 的设置 UI）：
 
 ```json
 {
@@ -207,7 +237,7 @@ env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
 }
 ```
 
-若要指定特定的 Gateway 网关或智能体：
+若要定位特定 Gateway 网关或智能体：
 
 ```json
 {
@@ -230,18 +260,18 @@ env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
 }
 ```
 
-在 Zed 中，打开智能体面板并选择“OpenClaw ACP”以开始一个线程。
+在 Zed 中，打开 Agent 面板并选择“OpenClaw ACP”以启动一个线程。
 
 ## 会话映射
 
 默认情况下，ACP 会话会获得一个带有 `acp:` 前缀的隔离 Gateway 网关会话键。
 若要复用已知会话，请传入会话键或标签：
 
-- `--session <key>`：使用特定的 Gateway 网关会话键。
+- `--session <key>`：使用特定 Gateway 网关会话键。
 - `--session-label <label>`：按标签解析现有会话。
-- `--reset-session`：为该键生成一个全新的会话 ID（相同键，不同新 transcript）。
+- `--reset-session`：为该键生成一个新的会话 id（同一键，新 transcript）。
 
-如果你的 ACP 客户端支持元数据，你可以按会话覆盖：
+如果你的 ACP 客户端支持元数据，则可以按会话覆盖：
 
 ```json
 {
@@ -253,11 +283,11 @@ env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
 }
 ```
 
-有关会话键的更多信息，请参阅 [/concepts/session](/zh-CN/concepts/session)。
+在 [/concepts/session](/zh-CN/concepts/session) 了解有关会话键的更多信息。
 
 ## 选项
 
-- `--url <url>`：Gateway WebSocket URL（如果已配置，默认使用 `gateway.remote.url`）。
+- `--url <url>`：Gateway WebSocket URL（若已配置，默认为 `gateway.remote.url`）。
 - `--token <token>`：Gateway 网关认证 token。
 - `--token-file <path>`：从文件读取 Gateway 网关认证 token。
 - `--password <password>`：Gateway 网关认证密码。
@@ -267,19 +297,19 @@ env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
 - `--require-existing`：如果会话键/标签不存在则失败。
 - `--reset-session`：在首次使用前重置会话键。
 - `--no-prefix-cwd`：不要在提示前添加工作目录前缀。
-- `--provenance <off|meta|meta+receipt>`：包含 ACP provenance 元数据或回执。
-- `--verbose, -v`：向 stderr 输出详细日志。
+- `--provenance <off|meta|meta+receipt>`：包含 ACP 来源元数据或回执。
+- `--verbose, -v`：向 `stderr` 输出详细日志。
 
 安全说明：
 
 - 在某些系统上，`--token` 和 `--password` 可能会出现在本地进程列表中。
-- 建议使用 `--token-file`/`--password-file` 或环境变量（`OPENCLAW_GATEWAY_TOKEN`、`OPENCLAW_GATEWAY_PASSWORD`）。
-- Gateway 网关认证解析遵循与其他 Gateway 网关客户端共用的契约：
-  - 本地模式：环境变量（`OPENCLAW_GATEWAY_*`）-> `gateway.auth.*` -> 仅当 `gateway.auth.*` 未设置时才回退到 `gateway.remote.*`（已配置但未解析的本地 SecretRef 会以失败关闭方式处理）
-  - 远程模式：`gateway.remote.*`，并按远程优先级规则回退到环境变量/配置
-  - `--url` 是安全的覆盖项，不会复用隐式配置/环境凭证；请传入显式的 `--token`/`--password`（或其文件变体）
-- ACP 运行时后端子进程会收到 `OPENCLAW_SHELL=acp`，可用于特定上下文的 shell/profile 规则。
-- `openclaw acp client` 会在启动的 bridge 进程上设置 `OPENCLAW_SHELL=acp-client`。
+- 优先使用 `--token-file`/`--password-file` 或环境变量（`OPENCLAW_GATEWAY_TOKEN`、`OPENCLAW_GATEWAY_PASSWORD`）。
+- Gateway 网关认证解析遵循其他 Gateway 网关客户端使用的共享契约：
+  - 本地模式：环境变量（`OPENCLAW_GATEWAY_*`）-> `gateway.auth.*` -> 仅当 `gateway.auth.*` 未设置时才回退到 `gateway.remote.*`（已配置但未解析的本地 SecretRefs 将以失败关闭）
+  - 远程模式：`gateway.remote.*`，并按远程优先级规则进行环境变量/配置回退
+  - `--url` 可安全覆盖，不会复用隐式配置/环境变量凭证；请传入显式 `--token`/`--password`（或其文件变体）
+- ACP 运行时后端子进程会接收 `OPENCLAW_SHELL=acp`，可用于上下文特定的 shell/profile 规则。
+- `openclaw acp client` 会在其启动的桥接器进程上设置 `OPENCLAW_SHELL=acp-client`。
 
 ### `acp client` 选项
 
@@ -287,4 +317,4 @@ env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
 - `--server <command>`：ACP 服务器命令（默认：`openclaw`）。
 - `--server-args <args...>`：传递给 ACP 服务器的额外参数。
 - `--server-verbose`：在 ACP 服务器上启用详细日志。
-- `--verbose, -v`：启用客户端详细日志。
+- `--verbose, -v`：详细客户端日志。
diff --git a/docs/zh-CN/tools/acp-agents-setup.md b/docs/zh-CN/tools/acp-agents-setup.md
new file mode 100644
index 000000000..8cf36e60e
--- /dev/null
+++ b/docs/zh-CN/tools/acp-agents-setup.md
@@ -0,0 +1,281 @@
+---
+read_when:
+    - 为 Claude Code / Codex / Gemini CLI 安装或配置 `acpx` harness
+    - 启用 `plugin-tools` 或 OpenClaw-tools MCP 桥接器
+    - 配置 ACP 权限模式
+summary: 设置 ACP 智能体：`acpx` harness 配置、插件设置、权限
+title: ACP 智能体——设置
+x-i18n:
+    generated_at: "2026-04-24T02:39:43Z"
+    model: gpt-5.4
+    provider: openai
+    source_hash: 7f1b34217b0709c85173ca13d952e996676b73b7ac7b9db91a5069e19ff76013
+    source_path: tools/acp-agents-setup.md
+    workflow: 15
+---
+
+关于概览、运维手册和核心概念，请参见 [ACP 智能体](/zh-CN/tools/acp-agents)。
+本页介绍 `acpx` harness 配置、MCP 桥接器的插件设置，以及权限配置。
+
+## `acpx` harness 支持（当前）
+
+当前 `acpx` 内置 harness 别名：
+
+- `claude`
+- `codex`
+- `copilot`
+- `cursor`（Cursor CLI：`cursor-agent acp`）
+- `droid`
+- `gemini`
+- `iflow`
+- `kilocode`
+- `kimi`
+- `kiro`
+- `openclaw`
+- `opencode`
+- `pi`
+- `qwen`
+
+当 OpenClaw 使用 `acpx` 后端时，除非你的 `acpx` 配置定义了自定义智能体别名，否则建议为 `agentId` 优先使用这些值。
+如果你本地安装的 Cursor 仍然将 ACP 暴露为 `agent acp`，请在你的 `acpx` 配置中覆盖 `cursor` 智能体命令，而不是修改内置默认值。
+
+直接使用 `acpx` CLI 时，也可以通过 `--agent <command>` 指向任意适配器，但这个原始逃生口是 `acpx` CLI 的功能（不是 OpenClaw 常规的 `agentId` 路径）。
+
+## 必需配置
+
+核心 ACP 基线配置：
+
+```json5
+{
+  acp: {
+    enabled: true,
+    // 可选。默认值为 true；设为 false 可暂停 ACP 分发，同时保留 /acp 控制。
+    dispatch: { enabled: true },
+    backend: "acpx",
+    defaultAgent: "codex",
+    allowedAgents: [
+      "claude",
+      "codex",
+      "copilot",
+      "cursor",
+      "droid",
+      "gemini",
+      "iflow",
+      "kilocode",
+      "kimi",
+      "kiro",
+      "openclaw",
+      "opencode",
+      "pi",
+      "qwen",
+    ],
+    maxConcurrentSessions: 8,
+    stream: {
+      coalesceIdleMs: 300,
+      maxChunkChars: 1200,
+    },
+    runtime: {
+      ttlMinutes: 120,
+    },
+  },
+}
+```
+
+线程绑定配置与渠道适配器相关。以下是 Discord 的示例：
+
+```json5
+{
+  session: {
+    threadBindings: {
+      enabled: true,
+      idleHours: 24,
+      maxAgeHours: 0,
+    },
+  },
+  channels: {
+    discord: {
+      threadBindings: {
+        enabled: true,
+        spawnAcpSessions: true,
+      },
+    },
+  },
+}
+```
+
+如果基于线程绑定的 ACP 派生不起作用，请先检查适配器功能开关：
+
+- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
+
+当前会话绑定不需要创建子线程。它们需要一个活跃的会话上下文，以及一个暴露 ACP 会话绑定能力的渠道适配器。
+
+参见 [Configuration Reference](/zh-CN/gateway/configuration-reference)。
+
+## `acpx` 后端的插件设置
+
+全新安装默认会启用内置的 `acpx` 运行时插件，因此 ACP 通常无需手动安装插件即可工作。
+
+先运行：
+
+```text
+/acp doctor
+```
+
+如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或者想切换到本地开发检出版本，请使用显式插件路径：
+
+```bash
+openclaw plugins install acpx
+openclaw config set plugins.entries.acpx.enabled true
+```
+
+开发期间安装本地工作区版本：
+
+```bash
+openclaw plugins install ./path/to/local/acpx-plugin
+```
+
+然后验证后端健康状态：
+
+```text
+/acp doctor
+```
+
+### `acpx` 命令与版本配置
+
+默认情况下，内置的 `acpx` 插件使用其插件本地固定版本的二进制文件（插件包内的 `node_modules/.bin/acpx`）。启动时会先将后端注册为未就绪状态，并由后台任务验证 `acpx --version`；如果缺少该二进制文件或版本不匹配，它会运行 `npm install --omit=dev --no-save acpx@<pinned>`，然后再次验证。整个过程中，Gateway 网关始终保持非阻塞。
+
+你可以在插件配置中覆盖命令或版本：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "acpx": {
+        "enabled": true,
+        "config": {
+          "command": "../acpx/dist/cli.js",
+          "expectedVersion": "any"
+        }
+      }
+    }
+  }
+}
+```
+
+- `command` 接受绝对路径、相对路径（相对于 OpenClaw 工作区解析）或命令名。
+- `expectedVersion: "any"` 会禁用严格版本匹配。
+- 自定义 `command` 路径会禁用插件本地自动安装。
+
+参见 [Plugins](/zh-CN/tools/plugin)。
+
+### 自动安装依赖
+
+当你通过 `npm install -g openclaw` 全局安装 OpenClaw 时，`acpx`
+运行时依赖（平台相关二进制文件）会通过 `postinstall` 钩子自动安装。如果自动安装失败，Gateway 网关仍会正常启动，并通过 `openclaw acp doctor` 报告缺失的依赖。
+
+### Plugin tools MCP 桥接器
+
+默认情况下，ACPX 会话**不会**将 OpenClaw 插件注册的工具暴露给
+ACP harness。
+
+如果你希望 Codex 或 Claude Code 等 ACP 智能体调用已安装的
+OpenClaw 插件工具，例如 memory recall/store，请启用专用桥接器：
+
+```bash
+openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
+```
+
+这会带来以下效果：
+
+- 在 ACPX 会话引导过程中注入一个名为 `openclaw-plugin-tools` 的内置 MCP 服务器。
+- 暴露已安装并启用的 OpenClaw 插件已注册的插件工具。
+- 使该功能保持显式启用，且默认关闭。
+
+安全与信任说明：
+
+- 这会扩大 ACP harness 的工具暴露面。
+- ACP 智能体只能访问 Gateway 网关中已经激活的插件工具。
+- 请将其视为与允许这些插件在 OpenClaw 自身中执行相同的信任边界。
+- 启用前请检查已安装的插件。
+
+自定义 `mcpServers` 仍然和以前一样可用。内置的 `plugin-tools` 桥接器只是额外的可选便利功能，不是通用 MCP 服务器配置的替代方案。
+
+### OpenClaw tools MCP 桥接器
+
+默认情况下，ACPX 会话也**不会**通过 MCP 暴露 OpenClaw 内置工具。当 ACP 智能体需要使用 `cron` 等选定的内置工具时，请启用单独的核心工具桥接器：
+
+```bash
+openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true
+```
+
+这会带来以下效果：
+
+- 在 ACPX 会话引导过程中注入一个名为 `openclaw-tools` 的内置 MCP 服务器。
+- 暴露选定的 OpenClaw 内置工具。初始服务器会暴露 `cron`。
+- 使核心工具暴露保持显式启用，且默认关闭。
+
+### 运行时超时配置
+
+内置的 `acpx` 插件默认将嵌入式运行时轮次的超时时间设置为 120 秒。这让 Gemini CLI 等较慢的 harness 有足够时间完成 ACP 启动和初始化。如果你的主机需要不同的运行时限制，可以覆盖此值：
+
+```bash
+openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
+```
+
+修改此值后，请重启 Gateway 网关。
+
+### 健康探测智能体配置
+
+内置的 `acpx` 插件在判断嵌入式运行时后端是否就绪时，会探测一个 harness 智能体。默认值为 `codex`。如果你的部署使用其他默认 ACP 智能体，请将探测智能体设置为相同的 id：
+
+```bash
+openclaw config set plugins.entries.acpx.config.probeAgent claude
+```
+
+修改此值后，请重启 Gateway 网关。
+
+## 权限配置
+
+ACP 会话以非交互方式运行——没有 TTY 可用于批准或拒绝文件写入和 shell 执行权限提示。`acpx` 插件提供了两个配置键，用于控制权限处理方式：
+
+这些 ACPX harness 权限与 OpenClaw 的执行审批是分开的，也与 CLI 后端供应商的绕过标志分开，例如 Claude CLI 的 `--permission-mode bypassPermissions`。对于 ACP 会话，ACPX 的 `approve-all` 是 harness 层级的紧急放开开关。
+
+### `permissionMode`
+
+控制 harness 智能体无需提示即可执行哪些操作。
+
+| 值              | 行为                                        |
+| --------------- | ------------------------------------------- |
+| `approve-all`   | 自动批准所有文件写入和 shell 命令。         |
+| `approve-reads` | 仅自动批准读取；写入和执行仍需要提示。      |
+| `deny-all`      | 拒绝所有权限提示。                          |
+
+### `nonInteractivePermissions`
+
+控制当本应显示权限提示但没有可交互 TTY 时会发生什么（ACP 会话始终都是这种情况）。
+
+| 值     | 行为                                                              |
+| ------ | ----------------------------------------------------------------- |
+| `fail` | 使用 `AcpRuntimeError` 中止会话。**（默认）**                     |
+| `deny` | 静默拒绝该权限并继续执行（优雅降级）。                            |
+
+### 配置方式
+
+通过插件配置设置：
+
+```bash
+openclaw config set plugins.entries.acpx.config.permissionMode approve-all
+openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
+```
+
+修改这些值后，请重启 Gateway 网关。
+
+> **重要：** OpenClaw 当前默认使用 `permissionMode=approve-reads` 和 `nonInteractivePermissions=fail`。在非交互式 ACP 会话中，任何触发权限提示的写入或执行操作都可能因 `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` 而失败。
+>
+> 如果你需要限制权限，请将 `nonInteractivePermissions` 设为 `deny`，这样会话会优雅降级，而不是直接崩溃。
+
+## 相关内容
+
+- [ACP 智能体](/zh-CN/tools/acp-agents) —— 概览、运维手册、核心概念
+- [Sub-agents](/zh-CN/tools/subagents)
+- [Multi-agent routing](/zh-CN/concepts/multi-agent)
diff --git a/docs/zh-CN/tools/acp-agents.md b/docs/zh-CN/tools/acp-agents.md
index 0b7967434..74d63d7cd 100644
--- a/docs/zh-CN/tools/acp-agents.md
+++ b/docs/zh-CN/tools/acp-agents.md
@@ -1,138 +1,140 @@
 ---
 read_when:
     - 通过 ACP 运行编码 harness
-    - 在消息渠道上设置绑定到对话的 ACP 会话
-    - 将消息渠道中的一个对话绑定到持久化 ACP 会话
+    - 在消息渠道上设置与对话绑定的 ACP 会话
+    - 将消息渠道中的对话绑定到持久化 ACP 会话
     - 排查 ACP 后端和插件接线问题
-    - 调试 ACP 完成结果投递或智能体到智能体循环
-    - 从聊天中使用 /acp 命令进行操作
-summary: 为 Codex、Claude Code、Cursor、Gemini CLI、OpenClaw ACP 和其他 harness 智能体使用 ACP 运行时会话
+    - 调试 ACP 完成结果传递或智能体到智能体循环问题
+    - 从聊天中操作 `/acp` 命令
+summary: 对 Codex、Claude Code、Cursor、Gemini CLI、OpenClaw ACP 和其他 harness 智能体使用 ACP 运行时会话
 title: ACP 智能体
 x-i18n:
-    generated_at: "2026-04-23T23:04:20Z"
+    generated_at: "2026-04-24T02:39:43Z"
     model: gpt-5.4
     provider: openai
-    source_hash: cfbce828d3c74b340cedf86c2e771401a618524b4fc1a716a84d85c5d2cd106d
+    source_hash: d09d4142ad56d9782ed5d7e40f7eab4c89f22131d35f749fcb07700c4d354e30
     source_path: tools/acp-agents.md
     workflow: 15
 ---
 
-[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话允许 OpenClaw 通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI，以及其他受支持的 ACPX harness）。
+[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI，以及其他受支持的 ACPX harness）。
 
-如果你用自然语言要求 OpenClaw “在 Codex 中运行这个”或“在线程中启动 Claude Code”，OpenClaw 应将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。每个 ACP 会话启动都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。
+如果你用自然语言让 OpenClaw “在 Codex 里运行这个”或“在线程里启动 Claude Code”，OpenClaw 应该将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。每次 ACP 会话启动都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。
 
-如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的 OpenClaw 渠道对话，请使用 [`openclaw mcp serve`](/zh-CN/cli/mcp)，而不是 ACP。
+如果你想让 Codex 或 Claude Code 作为外部 MCP 客户端直接连接
+到现有的 OpenClaw 渠道对话，请使用 [`openclaw mcp serve`](/zh-CN/cli/mcp)
+而不是 ACP。
 
-## 我需要哪个页面？
+## 我需要看哪个页面？
 
-这里有三个相邻但很容易混淆的功能面：
+这里有三个相近且容易混淆的功能面：
 
 | 你想要…… | 使用这个 | 说明 |
 | ---------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| 通过 OpenClaw 运行 Codex、Claude Code、Gemini CLI 或其他外部 harness | 本页：ACP 智能体 | 绑定聊天的会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 |
-| 将一个 OpenClaw Gateway 网关会话暴露为一个 ACP 服务器，供编辑器或客户端使用 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端通过 stdio/WebSocket 以 ACP 方式与 OpenClaw 通信 |
-| 将本地 AI CLI 复用为纯文本回退模型 | [CLI Backends](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有 harness 运行时 |
+| 通过 OpenClaw 运行 Codex、Claude Code、Gemini CLI 或其他外部 harness | 本页：ACP 智能体 | 与聊天绑定的会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 |
+| 将 OpenClaw Gateway 网关会话作为 ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端 通过 stdio/WebSocket 使用 ACP 与 OpenClaw 通信 |
+| 将本地 AI CLI 复用为仅文本的回退模型 | [CLI Backends](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有 harness 运行时 |
 
 ## 开箱即用吗？
 
-通常可以。全新安装默认启用了内置的 `acpx` 运行时插件，并带有插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自我修复。运行 `/acp doctor` 可进行就绪性检查。
+通常可以。全新安装会默认启用内置的 `acpx` 运行时插件，并附带一个插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自我修复它。运行 `/acp doctor` 可进行就绪性检查。
 
-首次运行的常见问题：
+首次运行的常见注意事项：
 
-- 目标 harness 适配器（Codex、Claude 等）可能会在你首次使用时通过 `npx` 按需拉取。
-- 该 harness 的供应商凭证仍然必须已存在于主机上。
-- 如果主机没有 npm 或网络访问能力，首次适配器拉取将失败，直到缓存被预热或适配器通过其他方式安装。
+- 目标 harness 适配器（Codex、Claude 等）可能会在你第一次使用时通过 `npx` 按需拉取。
+- 该 harness 对应的供应商认证仍然必须已存在于宿主机上。
+- 如果宿主机没有 npm 或网络访问能力，首次运行时的适配器拉取会失败，直到缓存被预热或以其他方式安装该适配器。
 
 ## 操作手册
 
 在聊天中快速使用 `/acp` 的流程：
 
-1. **启动** —— `/acp spawn codex --bind here` 或 `/acp spawn codex --mode persistent --thread auto`
-2. 在已绑定的对话或线程中**工作**（或者显式指定该会话键）。
-3. **检查状态** —— `/acp status`
-4. **调优** —— `/acp model <provider/model>`、`/acp permissions <profile>`、`/acp timeout <seconds>`
-5. 在不替换上下文的情况下进行**引导** —— `/acp steer tighten logging and continue`
-6. **停止** —— `/acp cancel`（当前轮次）或 `/acp close`（会话 + 绑定）
+1. **启动** — `/acp spawn codex --bind here` 或 `/acp spawn codex --mode persistent --thread auto`
+2. 在绑定的对话或线程中**处理工作**（或者显式指定会话键）。
+3. **检查状态** — `/acp status`
+4. **调优** — `/acp model <provider/model>`、`/acp permissions <profile>`、`/acp timeout <seconds>`
+5. **引导**而不替换上下文 — `/acp steer tighten logging and continue`
+6. **停止** — `/acp cancel`（当前轮次）或 `/acp close`（会话 + 绑定）
 
 应当路由到 ACP 运行时的自然语言触发示例：
 
 - “把这个 Discord 频道绑定到 Codex。”
-- “在这里的一个线程中启动一个持久的 Codex 会话。”
-- “把这个作为一次性 Claude Code ACP 会话运行，并总结结果。”
-- “这个任务使用 Gemini CLI 在线程中运行，然后后续继续在同一个线程中处理。”
+- “在这里的线程里启动一个持久的 Codex 会话。”
+- “把这个作为一次性的 Claude Code ACP 会话来运行，并总结结果。”
+- “这个任务使用 Gemini CLI 在线程中处理，然后后续继续在同一个线程里进行。”
 
-OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑定到当前对话或线程，并将后续消息路由到该会话，直到关闭或过期。
+OpenClaw 会选择 `runtime: "acp"`，解析 harness 的 `agentId`，在支持的情况下绑定到当前对话或线程，并将后续消息路由到该会话，直到关闭或过期。
 
-## ACP 与子智能体
+## ACP 与子智能体的区别
 
-当你想使用外部 harness 运行时时，请使用 ACP。当你想使用 OpenClaw 原生委派运行时，请使用子智能体。
+如果你想使用外部 harness 运行时，请使用 ACP。如果你想使用 OpenClaw 原生委派运行，请使用子智能体。
 
-| 领域 | ACP 会话 | 子智能体运行 |
+| 区域 | ACP 会话 | 子智能体运行 |
 | ------------- | ------------------------------------- | ---------------------------------- |
 | 运行时 | ACP 后端插件（例如 acpx） | OpenClaw 原生子智能体运行时 |
 | 会话键 | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
-| 主命令 | `/acp ...` | `/subagents ...` |
-| 启动工具 | 带 `runtime:"acp"` 的 `sessions_spawn` | `sessions_spawn`（默认运行时） |
+| 主要命令 | `/acp ...` | `/subagents ...` |
+| 启动工具 | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn`（默认运行时） |
 
-另请参见 [Sub-agents](/zh-CN/tools/subagents)。
+另见 [Sub-agents](/zh-CN/tools/subagents)。
 
 ## ACP 如何运行 Claude Code
 
-对于通过 ACP 运行的 Claude Code，其栈结构是：
+对于通过 ACP 运行的 Claude Code，其栈如下：
 
 1. OpenClaw ACP 会话控制平面
-2. 内置 `acpx` 运行时插件
+2. 内置的 `acpx` 运行时插件
 3. Claude ACP 适配器
-4. Claude 侧运行时/会话机制
+4. Claude 侧的运行时/会话机制
 
-重要区别：
+一个重要区别：
 
-- ACP Claude 是一种 harness 会话，具备 ACP 控制、会话恢复、后台任务跟踪，以及可选的对话/线程绑定。
-- CLI backends 是独立的纯文本本地回退运行时。参见 [CLI Backends](/zh-CN/gateway/cli-backends)。
+- ACP Claude 是一种 harness 会话，具有 ACP 控制、会话恢复、后台任务跟踪，以及可选的对话/线程绑定能力。
+- CLI 后端则是独立的、仅文本的本地回退运行时。参见 [CLI Backends](/zh-CN/gateway/cli-backends)。
 
-对于操作员来说，实用规则是：
+对操作人员来说，实用规则是：
 
-- 想要 `/acp spawn`、可绑定会话、运行时控制或持久化 harness 工作：使用 ACP
-- 想要通过原始 CLI 进行简单的本地文本回退：使用 CLI backends
+- 想要 `/acp spawn`、可绑定的会话、运行时控制或持久化 harness 工作：使用 ACP
+- 想要通过原始 CLI 获得简单的本地文本回退：使用 CLI 后端
 
-## 绑定会话
+## 绑定的会话
 
 ### 绑定到当前对话
 
-`/acp spawn <harness> --bind here` 会将当前对话固定到新启动的 ACP 会话——不会创建子线程，仍使用同一聊天界面。OpenClaw 继续负责传输、凭证、安全和投递；该对话中的后续消息会路由到同一个会话；`/new` 和 `/reset` 会在原地重置该会话；`/acp close` 会移除该绑定。
+`/acp spawn <harness> --bind here` 会将当前对话固定绑定到新启动的 ACP 会话 —— 不创建子线程，仍在同一个聊天界面中。OpenClaw 继续负责传输、认证、安全和消息投递；该对话中的后续消息会路由到同一个会话；`/new` 和 `/reset` 会在原位重置该会话；`/acp close` 会移除该绑定。
 
-心智模型：
+理解模型：
 
-- **聊天界面** —— 人们持续交流的地方（Discord 频道、Telegram 主题、iMessage 聊天）。
-- **ACP 会话** —— OpenClaw 路由到的持久化 Codex/Claude/Gemini 运行时状态。
-- **子线程/主题** —— 仅在使用 `--thread ...` 时才会创建的可选额外消息界面。
-- **运行时工作区** —— harness 实际运行的文件系统位置（`cwd`、代码仓库检出目录、后端工作区）。它独立于聊天界面。
+- **聊天界面** — 人们持续对话的地方（Discord 频道、Telegram 话题、iMessage 聊天）。
+- **ACP 会话** — OpenClaw 路由到的持久化 Codex/Claude/Gemini 运行时状态。
+- **子线程/话题** — 一个可选的额外消息界面，仅在使用 `--thread ...` 时创建。
+- **运行时工作区** — harness 运行所在的文件系统位置（`cwd`、仓库检出目录、后端工作区）。它独立于聊天界面。
 
 示例：
 
-- `/acp spawn codex --bind here` —— 保持当前聊天，启动或附加 Codex，并将未来消息路由到这里。
-- `/acp spawn codex --thread auto` —— OpenClaw 可能会创建一个子线程/主题并绑定到那里。
-- `/acp spawn codex --bind here --cwd /workspace/repo` —— 仍绑定当前聊天，但 Codex 在 `/workspace/repo` 中运行。
+- `/acp spawn codex --bind here` — 保持当前聊天，启动或附加 Codex，并将未来消息路由到这里。
+- `/acp spawn codex --thread auto` — OpenClaw 可能会创建一个子线程/话题并绑定到那里。
+- `/acp spawn codex --bind here --cwd /workspace/repo` — 仍绑定当前聊天，但 Codex 在 `/workspace/repo` 中运行。
 
 说明：
 
-- `--bind here` 和 `--thread ...` 互斥。
+- `--bind here` 与 `--thread ...` 互斥。
 - `--bind here` 仅适用于声明支持当前对话绑定的渠道；否则 OpenClaw 会返回清晰的不支持提示。绑定会在 Gateway 网关重启后继续保留。
 - 在 Discord 上，只有当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions` —— 对于 `--bind here` 则不需要。
-- 如果你在没有 `--cwd` 的情况下启动到另一个 ACP 智能体，OpenClaw 默认会继承**目标智能体的**工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误暴露。
+- 如果你启动到另一个 ACP 智能体且未指定 `--cwd`，OpenClaw 默认会继承**目标智能体的**工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误直接暴露。
 
 ### 绑定到线程的会话
 
 当某个渠道适配器启用了线程绑定时，ACP 会话可以绑定到线程：
 
-- OpenClaw 将一个线程绑定到目标 ACP 会话。
-- 该线程中的后续消息会路由到已绑定的 ACP 会话。
-- ACP 输出会投递回同一个线程。
-- 失焦/关闭/归档/空闲超时或最大存活时间到期后，会移除该绑定。
+- OpenClaw 将线程绑定到目标 ACP 会话。
+- 该线程中的后续消息会路由到绑定的 ACP 会话。
+- ACP 输出会回传到同一个线程。
+- 失焦/关闭/归档/空闲超时或最大存活时间到期都会移除该绑定。
 
 线程绑定支持取决于适配器。如果当前渠道适配器不支持线程绑定，OpenClaw 会返回清晰的不支持/不可用提示。
 
-线程绑定 ACP 所需功能标志：
+线程绑定 ACP 所需的功能标志：
 
 - `acp.enabled=true`
 - `acp.dispatch.enabled` 默认开启（设为 `false` 可暂停 ACP 分发）
@@ -145,25 +147,25 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑
 - 任何暴露会话/线程绑定能力的渠道适配器。
 - 当前内置支持：
   - Discord 线程/频道
-  - Telegram topics（群组/超级群组中的 forum topics 和私信 topics）
-- 插件渠道也可以通过同一绑定接口添加支持。
+  - Telegram 话题（群组/超级群组中的论坛话题，以及私信话题）
+- 渠道插件也可以通过同一绑定接口添加支持。
 
 ## 渠道特定设置
 
-对于非临时性工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。
+对于非临时工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。
 
 ### 绑定模型
 
-- `bindings[].type="acp"` 表示一个持久的 ACP 对话绑定。
-- `bindings[].match` 标识目标对话：
+- `bindings[].type="acp"` 表示一个持久化 ACP 对话绑定。
+- `bindings[].match` 用于标识目标对话：
   - Discord 频道或线程：`match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
-  - Telegram forum topic：`match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
-  - BlueBubbles 私聊/群聊：`match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
+  - Telegram 论坛话题：`match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
+  - BlueBubbles 私信/群聊：`match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
     对于稳定的群组绑定，优先使用 `chat_id:*` 或 `chat_identifier:*`。
-  - iMessage 私聊/群聊：`match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
+  - iMessage 私信/群聊：`match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
     对于稳定的群组绑定，优先使用 `chat_id:*`。
-- `bindings[].agentId` 是拥有该绑定的 OpenClaw 智能体 id。
-- 可选的 ACP 覆盖位于 `bindings[].acp` 下：
+- `bindings[].agentId` 是所属的 OpenClaw 智能体 id。
+- 可选的 ACP 覆盖项位于 `bindings[].acp` 下：
   - `mode`（`persistent` 或 `oneshot`）
   - `label`
   - `cwd`
@@ -267,22 +269,22 @@ ACP 绑定会话的覆盖优先级：
 
 行为：
 
-- OpenClaw 会在使用前确保已配置的 ACP 会话存在。
-- 该频道或主题中的消息会路由到已配置的 ACP 会话。
-- 在已绑定对话中，`/new` 和 `/reset` 会在原地重置同一个 ACP 会话键。
-- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍然适用。
+- OpenClaw 会在使用前确保已存在配置好的 ACP 会话。
+- 该频道或话题中的消息会路由到配置好的 ACP 会话。
+- 在绑定的对话中，`/new` 和 `/reset` 会在原位重置同一个 ACP 会话键。
+- 临时运行时绑定（例如通过线程聚焦流程创建的绑定）在存在时仍会生效。
 - 对于未显式指定 `cwd` 的跨智能体 ACP 启动，OpenClaw 会从智能体配置中继承目标智能体工作区。
-- 缺失的继承工作区路径会回退到后端默认 cwd；非缺失访问失败会作为启动错误暴露。
+- 缺失的继承工作区路径会回退到后端默认 `cwd`；非缺失类访问失败会作为启动错误直接暴露。
 
 ## 启动 ACP 会话（接口）
 
-### 从 `sessions_spawn`
+### 从 `sessions_spawn` 启动
 
-使用 `runtime: "acp"` 可以从智能体轮次或工具调用中启动一个 ACP 会话。
+使用 `runtime: "acp"` 可从智能体轮次或工具调用中启动 ACP 会话。
 
 ```json
 {
-  "task": "Open the repo and summarize failing tests",
+  "task": "打开仓库并总结失败的测试",
   "runtime": "acp",
   "agentId": "codex",
   "thread": true,
@@ -292,9 +294,9 @@ ACP 绑定会话的覆盖优先级：
 
 说明：
 
-- `runtime` 默认值是 `subagent`，因此对于 ACP 会话请显式设置 `runtime: "acp"`。
+- `runtime` 默认为 `subagent`，因此 ACP 会话必须显式设置 `runtime: "acp"`。
 - 如果省略 `agentId`，OpenClaw 会在已配置时使用 `acp.defaultAgent`。
-- `mode: "session"` 需要 `thread: true`，以保持持久的绑定对话。
+- `mode: "session"` 需要 `thread: true` 才能保持一个持久化的绑定对话。
 
 接口详情：
 
@@ -303,110 +305,110 @@ ACP 绑定会话的覆盖优先级：
 - `agentId`（可选）：ACP 目标 harness id。如果已设置，则回退到 `acp.defaultAgent`。
 - `thread`（可选，默认 `false`）：在支持时请求线程绑定流程。
 - `mode`（可选）：`run`（一次性）或 `session`（持久化）。
-  - 默认值为 `run`
-  - 如果 `thread: true` 且未指定 mode，OpenClaw 可能会根据运行时路径默认采用持久化行为
+  - 默认为 `run`
+  - 如果 `thread: true` 且省略 `mode`，OpenClaw 可能会根据运行时路径默认采用持久化行为
   - `mode: "session"` 需要 `thread: true`
-- `cwd`（可选）：请求的运行时工作目录（由后端/运行时策略验证）。如果省略，ACP 启动会在已配置时继承目标智能体工作区；缺失的继承路径会回退到后端默认值，而真实的访问错误会直接返回。
+- `cwd`（可选）：请求的运行时工作目录（由后端/运行时策略校验）。如果省略，ACP 启动会在已配置时继承目标智能体工作区；缺失的继承路径会回退到后端默认值，而真实的访问错误会被直接返回。
 - `label`（可选）：用于会话/横幅文本中的面向操作员标签。
 - `resumeSessionId`（可选）：恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load` 重放其对话历史。需要 `runtime: "acp"`。
-- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式回传给请求方会话。
-  - 在可用时，接受的响应中会包含 `streamLogPath`，指向一个按会话划分的 JSONL 日志（`<sessionId>.acp-stream.jsonl`），你可以对其执行 tail 以查看完整中继历史。
-- `model`（可选）：对子 ACP 会话显式覆盖模型。对于 `runtime: "acp"` 会生效，因此子会话会使用所请求的模型，而不是静默回退到目标智能体默认值。
+- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行的进度摘要作为系统事件流式回传给请求方会话。
+  - 可用时，接受的响应会包含 `streamLogPath`，指向一个按会话划分的 JSONL 日志（`<sessionId>.acp-stream.jsonl`），你可以 tail 它来查看完整的中继历史。
+- `model`（可选）：为 ACP 子会话显式覆盖模型。对 `runtime: "acp"` 生效，因此子会话会使用所请求的模型，而不是静默回退到目标智能体默认模型。
 
-## 投递模型
+## 交付模型
 
-ACP 会话既可以是交互式工作区，也可以是由父会话拥有的后台工作。投递路径取决于其形态。
+ACP 会话既可以是交互式工作区，也可以是由父级拥有的后台工作。交付路径取决于它的形态。
 
 ### 交互式 ACP 会话
 
-交互式会话旨在继续在可见的聊天界面中对话：
+交互式会话旨在让你持续在可见的聊天界面中交流：
 
-- `/acp spawn ... --bind here` 会将当前对话绑定到 ACP 会话。
-- `/acp spawn ... --thread ...` 会将一个渠道线程/主题绑定到 ACP 会话。
+- `/acp spawn ... --bind here` 将当前对话绑定到 ACP 会话。
+- `/acp spawn ... --thread ...` 将某个渠道线程/话题绑定到 ACP 会话。
 - 持久化配置的 `bindings[].type="acp"` 会将匹配的对话路由到同一个 ACP 会话。
 
-在绑定对话中的后续消息会直接路由到 ACP 会话，而 ACP 输出会投递回同一个渠道/线程/主题。
+绑定对话中的后续消息会直接路由到 ACP 会话，ACP 输出也会回传到同一个频道/线程/话题。
 
-### 由父会话拥有的一次性 ACP 会话
+### 由父级拥有的一次性 ACP 会话
 
-由另一智能体运行启动的一次性 ACP 会话属于后台子会话，类似于子智能体：
+由另一个智能体运行启动的一次性 ACP 会话是后台子级，类似子智能体：
 
-- 父会话通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。
-- 子会话在自己的 ACP harness 会话中运行。
+- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。
+- 子级在自己的 ACP harness 会话中运行。
 - 完成结果通过内部任务完成通知路径回报。
-- 当需要面向用户的回复时，父会话会用正常助手口吻重写子会话结果。
+- 当需要面向用户的回复时，父级会用普通助手口吻重写子级结果。
 
-不要将此路径视为父子之间的点对点聊天。子会话已经有一条回到父会话的完成结果通道。
+不要把这一路径视为父子之间的点对点聊天。子级已经有一条回传完成结果给父级的通道。
 
-### `sessions_send` 和 A2A 投递
+### `sessions_send` 与 A2A 交付
 
-`sessions_send` 可在启动后指向另一个会话。对于普通对等会话，OpenClaw 在注入消息后会使用一条智能体到智能体（A2A）的后续路径：
+`sessions_send` 可以在启动后将消息发送到另一个会话。对于普通对等会话，OpenClaw 在注入消息后会使用智能体到智能体（A2A）的后续跟进路径：
 
-- 等待目标会话回复
-- 可选地允许请求方和目标方交换有限数量的后续轮次
-- 请求目标方生成一条通知消息
-- 将该通知投递到可见渠道或线程
+- 等待目标会话的回复
+- 可选地让请求方与目标交换有限轮数的后续消息
+- 要求目标生成一条通知消息
+- 将该通知投递到可见的频道或线程
 
-这条 A2A 路径是用于对等发送的一种回退方案，适用于发送方需要一个可见后续结果的情况。当某个无关会话能够看到并给 ACP 目标发消息时，它仍保持启用，例如在较宽松的 `tools.sessions.visibility` 设置下。
+这条 A2A 路径是对等发送时的一种回退机制，用于发送方需要可见跟进结果的场景。当一个无关会话能够看到并向 ACP 目标发送消息时，它仍然保持启用，例如在较宽松的 `tools.sessions.visibility` 设置下。
 
-仅当请求方是其自己所拥有的、由父会话拥有的一次性 ACP 子会话的父会话时，OpenClaw 才会跳过 A2A 后续流程。在这种情况下，如果在任务完成之上再运行 A2A，可能会用子会话结果唤醒父会话，再把父会话的回复回送进子会话，从而形成父/子回声循环。对于这种已拥有的子会话场景，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为完成路径已经负责该结果。
+只有当请求方是其自有的一次性 ACP 子会话的父级时，OpenClaw 才会跳过 A2A 跟进。在这种情况下，如果在任务完成之上再运行 A2A，就可能用子级结果唤醒父级，再将父级回复转发回子级，从而形成父子回声循环。对于这种自有子级场景，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为完成路径已经负责处理结果。
 
 ### 恢复现有会话
 
-使用 `resumeSessionId` 可以继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其对话历史，因此它能够带着完整上下文继续之前的工作。
+使用 `resumeSessionId` 可继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其对话历史，因此它会带着之前的完整上下文继续工作。
 
 ```json
 {
-  "task": "Continue where we left off — fix the remaining test failures",
+  "task": "从我们上次停下的地方继续——修复剩余的测试失败",
   "runtime": "acp",
   "agentId": "codex",
   "resumeSessionId": "<previous-session-id>"
 }
 ```
 
-常见使用场景：
+常见用例：
 
-- 将一个 Codex 会话从你的笔记本电脑交接到手机——告诉你的智能体继续你之前的工作
-- 继续一个你最初在 CLI 中交互式启动、现在希望通过智能体无头继续的编码会话
+- 将一个 Codex 会话从你的笔记本电脑交接到手机 —— 告诉你的智能体从你上次停下的地方继续
+- 继续一个你此前在 CLI 中交互式启动、现在要通过智能体以无头方式继续的编码会话
 - 继续处理因 Gateway 网关重启或空闲超时而中断的工作
 
 说明：
 
-- `resumeSessionId` 需要 `runtime: "acp"` —— 如果与子智能体运行时一起使用会返回错误。
-- `resumeSessionId` 会恢复上游 ACP 对话历史；`thread` 和 `mode` 仍会正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然要求 `thread: true`。
-- 目标智能体必须支持 `session/load`（Codex 和 Claude Code 支持）。
-- 如果找不到该会话 ID，启动会以清晰错误失败——不会静默回退为新会话。
+- `resumeSessionId` 需要 `runtime: "acp"` —— 如果与子智能体运行时一起使用，会返回错误。
+- `resumeSessionId` 会恢复上游 ACP 对话历史；`thread` 和 `mode` 仍然会正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然要求 `thread: true`。
+- 目标智能体必须支持 `session/load`（Codex 和 Claude Code 都支持）。
+- 如果找不到该会话 id，启动会以清晰错误失败 —— 不会静默回退到新会话。
 
 <Accordion title="部署后冒烟测试">
 
-Gateway 网关部署后，请运行一次实时端到端检查，而不要只信任单元测试：
+Gateway 网关部署后，请运行一次真实的端到端检查，而不要只依赖单元测试：
 
-1. 验证目标主机上的已部署 Gateway 网关版本和提交。
-2. 打开一个指向实时智能体的临时 ACPX 桥接会话。
-3. 要求该智能体调用 `sessions_spawn`，参数为 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，任务内容为 `Reply with exactly LIVE-ACP-SPAWN-OK`。
-4. 验证 `accepted=yes`、存在真实的 `childSessionKey`，并且没有验证器错误。
+1. 在目标主机上验证已部署的 Gateway 网关版本和提交。
+2. 打开一个临时的 ACPX 桥接会话连接到在线智能体。
+3. 要求该智能体调用 `sessions_spawn`，并设置 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，任务内容为 `Reply with exactly LIVE-ACP-SPAWN-OK`。
+4. 验证 `accepted=yes`、存在真实的 `childSessionKey`，并且没有校验器错误。
 5. 清理该临时桥接会话。
 
-请将门槛保持在 `mode: "run"`，并跳过 `streamTo: "parent"` —— 绑定线程的 `mode: "session"` 和流式中继路径属于单独、更丰富的集成测试阶段。
+请将门槛保持在 `mode: "run"`，并跳过 `streamTo: "parent"` —— 绑定线程的 `mode: "session"` 和流中继路径属于另外更丰富的集成验证阶段。
 
 </Accordion>
 
 ## 沙箱兼容性
 
-ACP 会话当前运行在主机运行时中，而不是在 OpenClaw 沙箱内运行。
+ACP 会话当前运行在宿主运行时上，而不是 OpenClaw 沙箱内部。
 
 当前限制：
 
-- 如果请求方会话处于沙箱中，那么对于 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn`，ACP 启动都会被阻止。
+- 如果请求方会话处于沙箱中，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 启动都会被阻止。
   - 错误：`Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.`
-- 带 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。
+- 带有 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。
   - 错误：`sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`
 
-当你需要由沙箱强制执行时，请使用 `runtime: "subagent"`。
+当你需要由沙箱强制执行的运行时，请使用 `runtime: "subagent"`。
 
 ### 从 `/acp` 命令启动
 
-在聊天中需要显式操作员控制时，请使用 `/acp spawn`。
+在需要时，使用 `/acp spawn` 从聊天中进行显式的操作员控制。
 
 ```text
 /acp spawn codex --mode persistent --thread auto
@@ -427,15 +429,15 @@ ACP 会话当前运行在主机运行时中，而不是在 OpenClaw 沙箱内运
 
 ## 会话目标解析
 
-大多数 `/acp` 操作都接受一个可选会话目标（`session-key`、`session-id` 或 `session-label`）。
+大多数 `/acp` 操作都接受一个可选的会话目标（`session-key`、`session-id` 或 `session-label`）。
 
 解析顺序：
 
 1. 显式目标参数（或 `/acp steer` 的 `--session`）
    - 先尝试 key
-   - 再尝试 UUID 形状的 session id
-   - 然后尝试 label
-2. 当前线程绑定（如果这个对话/线程绑定到了某个 ACP 会话）
+   - 然后尝试 UUID 形状的 session id
+   - 再尝试 label
+2. 当前线程绑定（如果此对话/线程已绑定到 ACP 会话）
 3. 当前请求方会话回退
 
 当前对话绑定和线程绑定都会参与第 2 步。
@@ -448,15 +450,15 @@ ACP 会话当前运行在主机运行时中，而不是在 OpenClaw 沙箱内运
 
 | 模式 | 行为 |
 | ------ | ---------------------------------------------------------------------- |
-| `here` | 原地绑定当前活动对话；如果当前没有活动对话则失败。 |
+| `here` | 将当前活动对话原位绑定；如果当前没有活动对话则失败。 |
 | `off` | 不创建当前对话绑定。 |
 
 说明：
 
-- `--bind here` 是操作员实现“让这个频道或聊天由 Codex 驱动”的最简单路径。
+- `--bind here` 是“让这个频道或聊天由 Codex 支持”的最简单操作路径。
 - `--bind here` 不会创建子线程。
 - `--bind here` 仅在暴露当前对话绑定支持的渠道中可用。
-- `--bind` 和 `--thread` 不能在同一个 `/acp spawn` 调用中组合使用。
+- `--bind` 和 `--thread` 不能在同一次 `/acp spawn` 调用中同时使用。
 
 ## 启动线程模式
 
@@ -466,328 +468,77 @@ ACP 会话当前运行在主机运行时中，而不是在 OpenClaw 沙箱内运
 | ------ | --------------------------------------------------------------------------------------------------- |
 | `auto` | 在活动线程中：绑定该线程。在线程外：在支持时创建/绑定一个子线程。 |
 | `here` | 要求当前处于活动线程中；如果不在线程中则失败。 |
-| `off` | 不绑定。会话以未绑定状态启动。 |
+| `off` | 不进行绑定。会话以未绑定状态启动。 |
 
 说明：
 
 - 在不支持线程绑定的界面上，默认行为实际上等同于 `off`。
-- 绑定到线程的启动需要渠道策略支持：
+- 绑定线程的启动需要渠道策略支持：
   - Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
   - Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true`
-- 如果你希望固定当前对话而不创建子线程，请使用 `--bind here`。
+- 当你想固定当前对话且不创建子线程时，请使用 `--bind here`。
 
 ## ACP 控制
 
 | 命令 | 作用 | 示例 |
 | -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
-| `/acp spawn` | 创建 ACP 会话；可选当前绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` |
+| `/acp spawn` | 创建 ACP 会话；可选择当前对话绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` |
 | `/acp cancel` | 取消目标会话的进行中轮次。 | `/acp cancel agent:codex:acp:<uuid>` |
 | `/acp steer` | 向运行中的会话发送引导指令。 | `/acp steer --session support inbox prioritize failing tests` |
-| `/acp close` | 关闭会话并解绑线程目标。 | `/acp close` |
+| `/acp close` | 关闭会话并解除线程目标绑定。 | `/acp close` |
 | `/acp status` | 显示后端、模式、状态、运行时选项和能力。 | `/acp status` |
-| `/acp set-mode` | 设置目标会话的运行时模式。 | `/acp set-mode plan` |
-| `/acp set` | 通用运行时配置项写入。 | `/acp set model openai/gpt-5.4` |
+| `/acp set-mode` | 为目标会话设置运行时模式。 | `/acp set-mode plan` |
+| `/acp set` | 通用运行时配置选项写入。 | `/acp set model openai/gpt-5.4` |
 | `/acp cwd` | 设置运行时工作目录覆盖。 | `/acp cwd /Users/user/Projects/repo` |
 | `/acp permissions` | 设置审批策略配置文件。 | `/acp permissions strict` |
 | `/acp timeout` | 设置运行时超时（秒）。 | `/acp timeout 120` |
 | `/acp model` | 设置运行时模型覆盖。 | `/acp model anthropic/claude-opus-4-6` |
 | `/acp reset-options` | 移除会话运行时选项覆盖。 | `/acp reset-options` |
-| `/acp sessions` | 从存储中列出最近的 ACP 会话。 | `/acp sessions` |
-| `/acp doctor` | 后端健康、能力、可执行修复建议。 | `/acp doctor` |
+| `/acp sessions` | 列出存储中的最近 ACP 会话。 | `/acp sessions` |
+| `/acp doctor` | 后端健康状态、能力和可执行修复建议。 | `/acp doctor` |
 | `/acp install` | 打印确定性的安装和启用步骤。 | `/acp install` |
 
-`/acp status` 会显示生效的运行时选项，以及运行时级别和后端级别的会话标识符。当某个后端缺少某项能力时，不支持的控制错误会被清晰显示。`/acp sessions` 会为当前已绑定或请求方会话读取存储；目标令牌（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括按智能体自定义的 `session.store` 根路径。
+`/acp status` 会显示生效的运行时选项，以及运行时级别和后端级别的会话标识符。当后端缺少某项能力时，不支持控制的错误会被清晰地呈现出来。`/acp sessions` 会读取当前绑定会话或请求方会话的存储；目标标记（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括每个智能体自定义的 `session.store` 根路径。
 
 ## 运行时选项映射
 
-`/acp` 同时提供便捷命令和一个通用设置器。
+`/acp` 提供了便捷命令和一个通用设置器。
 
-等价操作：
+等效操作：
 
 - `/acp model <id>` 映射到运行时配置键 `model`。
 - `/acp permissions <profile>` 映射到运行时配置键 `approval_policy`。
 - `/acp timeout <seconds>` 映射到运行时配置键 `timeout`。
-- `/acp cwd <path>` 直接更新运行时 cwd 覆盖。
+- `/acp cwd <path>` 直接更新运行时 `cwd` 覆盖。
 - `/acp set <key> <value>` 是通用路径。
-  - 特殊情况：`key=cwd` 使用 cwd 覆盖路径。
+  - 特殊情况：`key=cwd` 使用 `cwd` 覆盖路径。
 - `/acp reset-options` 会清除目标会话的所有运行时覆盖。
 
-## acpx harness 支持（当前）
+## acpx harness、插件设置和权限
 
-当前 acpx 内置 harness 别名：
-
-- `claude`
-- `codex`
-- `copilot`
-- `cursor`（Cursor CLI：`cursor-agent acp`）
-- `droid`
-- `gemini`
-- `iflow`
-- `kilocode`
-- `kimi`
-- `kiro`
-- `openclaw`
-- `opencode`
-- `pi`
-- `qwen`
-
-当 OpenClaw 使用 acpx 后端时，除非你的 acpx 配置定义了自定义智能体别名，否则 `agentId` 应优先使用这些值。
-如果你本地安装的 Cursor 仍将 ACP 暴露为 `agent acp`，请在你的 acpx 配置中覆盖 `cursor` 智能体命令，而不是更改内置默认值。
-
-直接使用 acpx CLI 也可以通过 `--agent <command>` 指向任意适配器，但这个原始逃生舱口属于 acpx CLI 功能（不是正常的 OpenClaw `agentId` 路径）。
-
-## 必需配置
-
-核心 ACP 基线配置：
-
-```json5
-{
-  acp: {
-    enabled: true,
-    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
-    dispatch: { enabled: true },
-    backend: "acpx",
-    defaultAgent: "codex",
-    allowedAgents: [
-      "claude",
-      "codex",
-      "copilot",
-      "cursor",
-      "droid",
-      "gemini",
-      "iflow",
-      "kilocode",
-      "kimi",
-      "kiro",
-      "openclaw",
-      "opencode",
-      "pi",
-      "qwen",
-    ],
-    maxConcurrentSessions: 8,
-    stream: {
-      coalesceIdleMs: 300,
-      maxChunkChars: 1200,
-    },
-    runtime: {
-      ttlMinutes: 120,
-    },
-  },
-}
-```
-
-线程绑定配置取决于具体的渠道适配器。Discord 示例：
-
-```json5
-{
-  session: {
-    threadBindings: {
-      enabled: true,
-      idleHours: 24,
-      maxAgeHours: 0,
-    },
-  },
-  channels: {
-    discord: {
-      threadBindings: {
-        enabled: true,
-        spawnAcpSessions: true,
-      },
-    },
-  },
-}
-```
-
-如果绑定到线程的 ACP 启动不起作用，请先验证适配器功能标志：
-
-- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
-
-当前对话绑定不需要创建子线程。它们需要一个活动对话上下文，以及一个暴露 ACP 对话绑定能力的渠道适配器。
-
-参见 [配置参考](/zh-CN/gateway/configuration-reference)。
-
-## acpx 后端的插件设置
-
-全新安装默认启用了内置的 `acpx` 运行时插件，因此 ACP 通常无需手动安装插件即可工作。
-
-先从以下命令开始：
-
-```text
-/acp doctor
-```
-
-如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或者你想切换到本地开发检出版本，请使用显式插件路径：
-
-```bash
-openclaw plugins install acpx
-openclaw config set plugins.entries.acpx.enabled true
-```
-
-开发期间的本地工作区安装：
-
-```bash
-openclaw plugins install ./path/to/local/acpx-plugin
-```
-
-然后验证后端健康状态：
-
-```text
-/acp doctor
-```
-
-### acpx 命令和版本配置
-
-默认情况下，内置的 `acpx` 插件使用其插件本地固定版本的二进制文件（插件包内的 `node_modules/.bin/acpx`）。启动时会先将后端注册为未就绪，并由后台任务验证 `acpx --version`；如果二进制缺失或版本不匹配，它会运行 `npm install --omit=dev --no-save acpx@<pinned>` 后再重新验证。整个过程中 Gateway 网关始终保持非阻塞。
-
-在插件配置中覆盖命令或版本：
-
-```json
-{
-  "plugins": {
-    "entries": {
-      "acpx": {
-        "enabled": true,
-        "config": {
-          "command": "../acpx/dist/cli.js",
-          "expectedVersion": "any"
-        }
-      }
-    }
-  }
-}
-```
-
-- `command` 接受绝对路径、相对路径（相对于 OpenClaw 工作区解析）或命令名。
-- `expectedVersion: "any"` 会禁用严格版本匹配。
-- 自定义 `command` 路径会禁用插件本地自动安装。
-
-参见 [Plugins](/zh-CN/tools/plugin)。
-
-### 自动依赖安装
-
-当你通过 `npm install -g openclaw` 全局安装 OpenClaw 时，acpx
-运行时依赖（平台特定二进制文件）会通过 postinstall hook 自动安装。如果自动安装失败，Gateway 网关仍会正常启动，并通过 `openclaw acp doctor` 报告缺失的依赖。
-
-### 插件工具 MCP 桥接
-
-默认情况下，ACPX 会话**不会**将 OpenClaw 插件注册的工具暴露给 ACP harness。
-
-如果你希望 Codex 或 Claude Code 这样的 ACP 智能体能够调用已安装的
-OpenClaw 插件工具，例如记忆 recall/store，请启用专用桥接：
-
-```bash
-openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
-```
-
-其作用如下：
-
-- 在 ACPX 会话引导中注入一个名为 `openclaw-plugin-tools` 的内置 MCP 服务器。
-- 暴露已安装且已启用的 OpenClaw 插件已注册的插件工具。
-- 让该功能保持显式开启，并默认关闭。
-
-安全和信任说明：
-
-- 这会扩大 ACP harness 的工具接口范围。
-- ACP 智能体只能访问 Gateway 网关中已激活的插件工具。
-- 请将其视为与允许这些插件在 OpenClaw 自身中执行相同的信任边界。
-- 启用前请审查已安装的插件。
-
-自定义 `mcpServers` 仍可照常使用。内置的插件工具桥接只是一个额外的选择启用便利功能，并不是对通用 MCP 服务器配置的替代。
-
-### OpenClaw 工具 MCP 桥接
-
-默认情况下，ACPX 会话同样**不会**通过 MCP 暴露内置 OpenClaw 工具。当 ACP 智能体需要访问选定的内置工具（例如 `cron`）时，请启用单独的核心工具桥接：
-
-```bash
-openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true
-```
-
-其作用如下：
-
-- 在 ACPX 会话引导中注入一个名为 `openclaw-tools` 的内置 MCP 服务器。
-- 暴露选定的内置 OpenClaw 工具。初始服务器暴露的是 `cron`。
-- 让核心工具暴露保持显式开启，并默认关闭。
-
-### 运行时超时配置
-
-内置的 `acpx` 插件默认将嵌入式运行时轮次超时设为 120 秒。这为 Gemini CLI 等较慢的 harness 预留了足够时间来完成 ACP 启动和初始化。如果你的主机需要不同的运行时限制，请进行覆盖：
-
-```bash
-openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
-```
-
-更改该值后请重启 Gateway 网关。
-
-### 健康探针智能体配置
-
-内置的 `acpx` 插件在判定嵌入式运行时后端是否就绪时，会探测一个 harness 智能体。默认是 `codex`。如果你的部署使用了不同的默认 ACP 智能体，请将探针智能体设置为同样的 id：
-
-```bash
-openclaw config set plugins.entries.acpx.config.probeAgent claude
-```
-
-更改该值后请重启 Gateway 网关。
-
-## 权限配置
-
-ACP 会话以非交互方式运行——没有 TTY 可用于批准或拒绝文件写入和 shell 执行权限提示。acpx 插件提供了两个配置键来控制权限处理方式：
-
-这些 ACPX harness 权限独立于 OpenClaw exec 审批，也独立于 CLI-backend 的供应商绕过标志，例如 Claude CLI 的 `--permission-mode bypassPermissions`。ACPX 的 `approve-all` 是 ACP 会话在 harness 级别的破玻璃开关。
-
-### `permissionMode`
-
-控制 harness 智能体在不提示的情况下可执行哪些操作。
-
-| 值 | 行为 |
-| --------------- | --------------------------------------------------------- |
-| `approve-all` | 自动批准所有文件写入和 shell 命令。 |
-| `approve-reads` | 仅自动批准读取；写入和 exec 需要提示。 |
-| `deny-all` | 拒绝所有权限提示。 |
-
-### `nonInteractivePermissions`
-
-控制当本应显示权限提示、但没有可交互 TTY 可用时（ACP 会话始终如此）的行为。
-
-| 值 | 行为 |
-| ------ | ----------------------------------------------------------------- |
-| `fail` | 使用 `AcpRuntimeError` 中止会话。**（默认）** |
-| `deny` | 静默拒绝该权限并继续执行（优雅降级）。 |
-
-### 配置
-
-通过插件配置进行设置：
-
-```bash
-openclaw config set plugins.entries.acpx.config.permissionMode approve-all
-openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
-```
-
-更改这些值后请重启 Gateway 网关。
-
-> **重要：** OpenClaw 当前默认使用 `permissionMode=approve-reads` 和 `nonInteractivePermissions=fail`。在非交互式 ACP 会话中，任何会触发权限提示的写入或 exec 操作都可能以 `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` 失败。
->
-> 如果你需要限制权限，请将 `nonInteractivePermissions` 设置为 `deny`，这样会话会优雅降级，而不是直接崩溃。
+关于 acpx harness 配置（Claude Code / Codex / Gemini CLI 别名）、plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP 权限模式，请参见
+[ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)。
 
 ## 故障排除
 
-| 症状 | 可能原因 | 修复 |
+| 症状 | 可能原因 | 修复方法 |
 | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ACP runtime backend is not configured` | 后端插件缺失或已禁用。 | 安装并启用后端插件，然后运行 `/acp doctor`。 |
 | `ACP is disabled by policy (acp.enabled=false)` | ACP 已被全局禁用。 | 设置 `acp.enabled=true`。 |
-| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 来自普通线程消息的分发已被禁用。 | 设置 `acp.dispatch.enabled=true`。 |
-| `ACP agent "<id>" is not allowed by policy` | 智能体不在允许名单中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 |
-| `Unable to resolve session target: ...` | 错误的 key/id/label 令牌。 | 运行 `/acp sessions`，复制精确的 key/label 后重试。 |
-| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动且可绑定对话的情况下使用了 `--bind here`。 | 移动到目标聊天/频道后重试，或使用无绑定启动。 |
+| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 来自普通线程消息的分发已禁用。 | 设置 `acp.dispatch.enabled=true`。 |
+| `ACP agent "<id>" is not allowed by policy` | 智能体不在允许列表中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 |
+| `Unable to resolve session target: ...` | key/id/label 标记错误。 | 运行 `/acp sessions`，复制准确的 key/label 后重试。 |
+| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动可绑定对话的情况下使用了 `--bind here`。 | 切换到目标聊天/频道后重试，或使用不绑定的启动。 |
 | `Conversation bindings are unavailable for <channel>.` | 适配器缺少当前对话 ACP 绑定能力。 | 在支持时使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或切换到受支持的渠道。 |
-| `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文之外使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 |
-| `Only <user-id> can rebind this channel/conversation/thread.` | 当前活动绑定目标归另一位用户所有。 | 由所有者重新绑定，或使用不同的对话或线程。 |
+| `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文之外使用了 `--thread here`。 | 切换到目标线程，或使用 `--thread auto`/`off`。 |
+| `Only <user-id> can rebind this channel/conversation/thread.` | 另一个用户拥有当前活动绑定目标。 | 由拥有者重新绑定，或使用其他对话或线程。 |
 | `Thread bindings are unavailable for <channel>.` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或切换到受支持的适配器/渠道。 |
-| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于主机侧；请求方会话处于沙箱中。 | 在沙箱会话中使用 `runtime="subagent"`，或从非沙箱会话启动 ACP。 |
-| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 如需强制沙箱，请使用 `runtime="subagent"`，或者在非沙箱会话中以 `sandbox="inherit"` 使用 ACP。 |
-| 已绑定会话缺少 ACP 元数据 | ACP 会话元数据已陈旧/被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 |
-| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 阻止了非交互式 ACP 会话中的写入/exec。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见[权限配置](#permission-configuration)。 |
-| ACP 会话很早失败且输出很少 | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。如需完整权限，请设置 `permissionMode=approve-all`；如需优雅降级，请设置 `nonInteractivePermissions=deny`。 |
-| ACP 会话在完成工作后无限期卡住 | harness 进程已结束，但 ACP 会话没有报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动杀掉陈旧进程。 |
+| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于宿主侧；请求方会话处于沙箱中。 | 在沙箱会话中使用 `runtime="subagent"`，或从非沙箱会话运行 ACP 启动。 |
+| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对需要强制沙箱隔离的场景使用 `runtime="subagent"`，或从非沙箱会话中配合 `sandbox="inherit"` 使用 ACP。 |
+| 绑定会话缺少 ACP 元数据 | ACP 会话元数据已过期/被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 |
+| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互式 ACP 会话中阻止写入/执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见 [权限配置](#permission-configuration)。 |
+| ACP 会话在很少输出的情况下提前失败 | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。若需完整权限，设置 `permissionMode=approve-all`；若需优雅降级，设置 `nonInteractivePermissions=deny`。 |
+| ACP 会话在完成工作后无限期卡住 | harness 进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动终止陈旧进程。 |
 
 ## 相关内容
 
diff --git a/docs/zh-CN/tools/browser-control.md b/docs/zh-CN/tools/browser-control.md
new file mode 100644
index 000000000..8526fb3a7
--- /dev/null
+++ b/docs/zh-CN/tools/browser-control.md
@@ -0,0 +1,349 @@
+---
+read_when:
+    - 通过本地控制 API 编写脚本或调试智能体浏览器
+    - 正在查找 `openclaw browser` CLI 参考文档
+    - 添加带有快照和 refs 的自定义浏览器自动化
+summary: OpenClaw 浏览器控制 API、CLI 参考和脚本操作
+title: 浏览器控制 API
+x-i18n:
+    generated_at: "2026-04-24T02:39:52Z"
+    model: gpt-5.4
+    provider: openai
+    source_hash: e29ad295085e2c36a6c2ce01366a4186e45a7ecfe1d3c3072353c55794b05b5f
+    source_path: tools/browser-control.md
+    workflow: 15
+---
+
+有关设置、配置和故障排除，请参阅 [Browser](/zh-CN/tools/browser)。
+本页是本地控制 HTTP API、`openclaw browser`
+CLI 以及脚本模式（快照、refs、等待、调试流程）的参考文档。
+
+## 控制 API（可选）
+
+仅用于本地集成时，Gateway 网关会暴露一个小型的 loopback HTTP API：
+
+- 状态/启动/停止：`GET /`、`POST /start`、`POST /stop`
+- 标签页：`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId`
+- 快照/截图：`GET /snapshot`、`POST /screenshot`
+- 操作：`POST /navigate`、`POST /act`
+- Hooks：`POST /hooks/file-chooser`、`POST /hooks/dialog`
+- 下载：`POST /download`、`POST /wait/download`
+- 调试：`GET /console`、`POST /pdf`
+- 调试：`GET /errors`、`GET /requests`、`POST /trace/start`、`POST /trace/stop`、`POST /highlight`
+- 网络：`POST /response/body`
+- 状态：`GET /cookies`、`POST /cookies/set`、`POST /cookies/clear`
+- 状态：`GET /storage/:kind`、`POST /storage/:kind/set`、`POST /storage/:kind/clear`
+- 设置：`POST /set/offline`、`POST /set/headers`、`POST /set/credentials`、`POST /set/geolocation`、`POST /set/media`、`POST /set/timezone`、`POST /set/locale`、`POST /set/device`
+
+所有端点都接受 `?profile=<name>`。
+
+如果配置了共享密钥 Gateway 网关认证，浏览器 HTTP 路由也需要认证：
+
+- `Authorization: Bearer <gateway token>`
+- `x-openclaw-password: <gateway password>`，或使用该密码的 HTTP Basic auth
+
+注意：
+
+- 这个独立的 loopback 浏览器 API **不会** 使用受信任代理或
+  Tailscale Serve 身份标头。
+- 如果 `gateway.auth.mode` 为 `none` 或 `trusted-proxy`，这些 loopback 浏览器
+  路由不会继承这些携带身份信息的模式；请将它们保持为仅 loopback 可用。
+
+### `/act` 错误约定
+
+`POST /act` 对路由级验证和策略失败使用结构化错误响应：
+
+```json
+{ "error": "<message>", "code": "ACT_*" }
+```
+
+当前的 `code` 值：
+
+- `ACT_KIND_REQUIRED`（HTTP 400）：缺少 `kind` 或无法识别。
+- `ACT_INVALID_REQUEST`（HTTP 400）：操作负载标准化或验证失败。
+- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）：在不受支持的操作类型中使用了 `selector`。
+- `ACT_EVALUATE_DISABLED`（HTTP 403）：配置中禁用了 `evaluate`（或 `wait --fn`）。
+- `ACT_TARGET_ID_MISMATCH`（HTTP 403）：顶层或批处理中的 `targetId` 与请求目标冲突。
+- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：现有会话 profile 不支持此操作。
+
+其他运行时失败仍可能返回不带
+`code` 字段的 `{ "error": "<message>" }`。
+
+### Playwright 要求
+
+某些功能（navigate/act/AI 快照/role 快照、元素截图、
+PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回
+明确的 501 错误。
+
+未安装 Playwright 时仍可使用的功能：
+
+- ARIA 快照
+- 当每个标签页的 CDP
+  WebSocket 可用时，受管 `openclaw` 浏览器的页面截图
+- `existing-session` / Chrome MCP profiles 的页面截图
+- 来自快照输出的 `existing-session` 基于 ref 的截图（`--ref`）
+
+仍然需要 Playwright 的功能：
+
+- `navigate`
+- `act`
+- AI 快照 / role 快照
+- CSS 选择器元素截图（`--element`）
+- 完整浏览器 PDF 导出
+
+元素截图也会拒绝 `--full-page`；该路由会返回 `fullPage is
+not supported for element screenshots`。
+
+如果你看到 `Playwright is not available in this gateway build`，请修复
+内置浏览器插件运行时依赖，确保已安装 `playwright-core`，
+然后重启 Gateway 网关。对于打包安装，请运行 `openclaw doctor --fix`。
+对于 Docker，还需要安装下面所示的 Chromium 浏览器二进制文件。
+
+#### Docker Playwright 安装
+
+如果你的 Gateway 网关运行在 Docker 中，请避免使用 `npx playwright`（npm 覆盖冲突）。
+请改用内置 CLI：
+
+```bash
+docker compose run --rm openclaw-cli \
+  node /app/node_modules/playwright-core/cli.js install chromium
+```
+
+要持久化浏览器下载，请设置 `PLAYWRIGHT_BROWSERS_PATH`（例如
+`/home/node/.cache/ms-playwright`），并确保通过
+`OPENCLAW_HOME_VOLUME` 或 bind mount 持久化 `/home/node`。请参阅 [Docker](/zh-CN/install/docker)。
+
+## 工作原理（内部）
+
+一个小型 loopback 控制服务器接收 HTTP 请求，并通过 CDP 连接到基于 Chromium 的浏览器。高级操作（点击/输入/快照/PDF）通过 CDP 之上的 Playwright 执行；当缺少 Playwright 时，只有不依赖 Playwright 的操作可用。智能体看到的是一个稳定的接口，而底层的本地/远程浏览器和 profiles 可以自由切换。
+
+## CLI 快速参考
+
+所有命令都接受 `--browser-profile <name>` 以定位到特定 profile，并接受 `--json` 以输出机器可读格式。
+
+<AccordionGroup>
+
+<Accordion title="基础：状态、标签页、打开/聚焦/关闭">
+
+```bash
+openclaw browser status
+openclaw browser start
+openclaw browser stop            # 也会清除仅附加/远程 CDP 上的仿真
+openclaw browser tabs
+openclaw browser tab             # 当前标签页的快捷方式
+openclaw browser tab new
+openclaw browser tab select 2
+openclaw browser tab close 2
+openclaw browser open https://example.com
+openclaw browser focus abcd1234
+openclaw browser close abcd1234
+```
+
+</Accordion>
+
+<Accordion title="检查：截图、快照、控制台、错误、请求">
+
+```bash
+openclaw browser screenshot
+openclaw browser screenshot --full-page
+openclaw browser screenshot --ref 12        # 或 --ref e12
+openclaw browser snapshot
+openclaw browser snapshot --format aria --limit 200
+openclaw browser snapshot --interactive --compact --depth 6
+openclaw browser snapshot --efficient
+openclaw browser snapshot --labels
+openclaw browser snapshot --selector "#main" --interactive
+openclaw browser snapshot --frame "iframe#main" --interactive
+openclaw browser console --level error
+openclaw browser errors --clear
+openclaw browser requests --filter api --clear
+openclaw browser pdf
+openclaw browser responsebody "**/api" --max-chars 5000
+```
+
+</Accordion>
+
+<Accordion title="操作：navigate、click、type、drag、wait、evaluate">
+
+```bash
+openclaw browser navigate https://example.com
+openclaw browser resize 1280 720
+openclaw browser click 12 --double           # 或对 role refs 使用 e12
+openclaw browser type 23 "hello" --submit
+openclaw browser press Enter
+openclaw browser hover 44
+openclaw browser scrollintoview e12
+openclaw browser drag 10 11
+openclaw browser select 9 OptionA OptionB
+openclaw browser download e12 report.pdf
+openclaw browser waitfordownload report.pdf
+openclaw browser upload /tmp/openclaw/uploads/file.pdf
+openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
+openclaw browser dialog --accept
+openclaw browser wait --text "Done"
+openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
+openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
+openclaw browser highlight e12
+openclaw browser trace start
+openclaw browser trace stop
+```
+
+</Accordion>
+
+<Accordion title="状态：cookies、storage、offline、headers、geo、device">
+
+```bash
+openclaw browser cookies
+openclaw browser cookies set session abc123 --url "https://example.com"
+openclaw browser cookies clear
+openclaw browser storage local get
+openclaw browser storage local set theme dark
+openclaw browser storage session clear
+openclaw browser set offline on
+openclaw browser set headers --headers-json '{"X-Debug":"1"}'
+openclaw browser set credentials user pass            # 使用 --clear 移除
+openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
+openclaw browser set media dark
+openclaw browser set timezone America/New_York
+openclaw browser set locale en-US
+openclaw browser set device "iPhone 14"
+```
+
+</Accordion>
+
+</AccordionGroup>
+
+注意：
+
+- `upload` 和 `dialog` 是**预置**调用；请在触发文件选择器/对话框的点击或按键之前运行它们。
+- `click`/`type`/等操作需要来自 `snapshot` 的 `ref`（数字 `12` 或 role ref `e12`）。操作有意不支持 CSS 选择器。
+- 下载、trace 和上传路径被限制在 OpenClaw 临时根目录下：`/tmp/openclaw{,/downloads,/uploads}`（回退为：`${os.tmpdir()}/openclaw/...`）。
+- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入框。
+
+快照标志一览：
+
+- `--format ai`（安装了 Playwright 时为默认）：带数字 refs 的 AI 快照（`aria-ref="<n>"`）。
+- `--format aria`：无障碍树，不含 refs；仅用于检查。
+- `--efficient`（或 `--mode efficient`）：紧凑型 role 快照预设。设置 `browser.snapshotDefaults.mode: "efficient"` 可将其设为默认值（参见 [Gateway 配置](/zh-CN/gateway/configuration-reference#browser)）。
+- `--interactive`、`--compact`、`--depth`、`--selector` 会强制使用 role 快照，并生成 `ref=e12` refs。`--frame "<iframe>"` 会将 role 快照限定在某个 iframe 中。
+- `--labels` 会添加一张仅视口的截图，并叠加 ref 标签（输出 `MEDIA:<path>`）。
+
+## 快照和 refs
+
+OpenClaw 支持两种“快照”样式：
+
+- **AI 快照（数字 refs）**：`openclaw browser snapshot`（默认；`--format ai`）
+  - 输出：包含数字 refs 的文本快照。
+  - 操作：`openclaw browser click 12`、`openclaw browser type 23 "hello"`。
+  - 在内部，ref 通过 Playwright 的 `aria-ref` 解析。
+
+- **Role 快照（如 `e12` 的 role refs）**：`openclaw browser snapshot --interactive`（或 `--compact`、`--depth`、`--selector`、`--frame`）
+  - 输出：基于 role 的列表/树，带有 `[ref=e12]`（以及可选的 `[nth=1]`）。
+  - 操作：`openclaw browser click e12`、`openclaw browser highlight e12`。
+  - 在内部，ref 通过 `getByRole(...)` 解析（重复项会额外使用 `nth()`）。
+  - 添加 `--labels` 可附带一张叠加 `e12` 标签的视口截图。
+
+Ref 行为：
+
+- Refs **不会在导航之间保持稳定**；如果操作失败，请重新运行 `snapshot` 并使用新的 ref。
+- 如果 role 快照是在 `--frame` 下获取的，role refs 会限定在该 iframe 中，直到下一次 role 快照。
+
+## Wait 增强功能
+
+你可以等待的不只是时间或文本：
+
+- 等待 URL（支持 Playwright 的 glob）：
+  - `openclaw browser wait --url "**/dash"`
+- 等待加载状态：
+  - `openclaw browser wait --load networkidle`
+- 等待 JS 谓词：
+  - `openclaw browser wait --fn "window.ready===true"`
+- 等待选择器变为可见：
+  - `openclaw browser wait "#main"`
+
+这些条件可以组合使用：
+
+```bash
+openclaw browser wait "#main" \
+  --url "**/dash" \
+  --load networkidle \
+  --fn "window.ready===true" \
+  --timeout-ms 15000
+```
+
+## 调试工作流
+
+当某个操作失败时（例如“不可见”“严格模式违规”“被遮挡”）：
+
+1. `openclaw browser snapshot --interactive`
+2. 使用 `click <ref>` / `type <ref>`（在交互模式下优先使用 role refs）
+3. 如果仍然失败：运行 `openclaw browser highlight <ref>`，查看 Playwright 实际定位的目标
+4. 如果页面行为异常：
+   - `openclaw browser errors --clear`
+   - `openclaw browser requests --filter api --clear`
+5. 如需深入调试：记录 trace：
+   - `openclaw browser trace start`
+   - 复现问题
+   - `openclaw browser trace stop`（输出 `TRACE:<path>`）
+
+## JSON 输出
+
+`--json` 用于脚本编写和结构化工具。
+
+示例：
+
+```bash
+openclaw browser status --json
+openclaw browser snapshot --interactive --json
+openclaw browser requests --filter api --json
+openclaw browser cookies --json
+```
+
+JSON 格式的 role 快照包含 `refs`，以及一个小型 `stats` 块（lines/chars/refs/interactive），便于工具推断负载大小和密度。
+
+## 状态和环境调节项
+
+这些选项对于“让网站表现得像 X 一样”的工作流非常有用：
+
+- Cookies：`cookies`、`cookies set`、`cookies clear`
+- Storage：`storage local|session get|set|clear`
+- Offline：`set offline on|off`
+- Headers：`set headers --headers-json '{"X-Debug":"1"}'`（旧版 `set headers --json '{"X-Debug":"1"}'` 仍然受支持）
+- HTTP Basic auth：`set credentials user pass`（或 `--clear`）
+- 地理位置：`set geo <lat> <lon> --origin "https://example.com"`（或 `--clear`）
+- 媒体：`set media dark|light|no-preference|none`
+- 时区 / 区域设置：`set timezone ...`、`set locale ...`
+- 设备 / 视口：
+  - `set device "iPhone 14"`（Playwright 设备预设）
+  - `set viewport 1280 720`
+
+## 安全与隐私
+
+- openclaw 浏览器 profile 可能包含已登录的会话；请将其视为敏感信息。
+- `browser act kind=evaluate` / `openclaw browser evaluate` 和 `wait --fn`
+  会在页面上下文中执行任意 JavaScript。提示注入可能会引导
+  这一行为。如果你不需要它，请使用 `browser.evaluateEnabled=false` 将其禁用。
+- 关于登录和反机器人说明（X/Twitter 等），请参阅 [Browser login + X/Twitter posting](/zh-CN/tools/browser-login)。
+- 请将 Gateway 网关/节点主机保持为私有（仅 loopback 或仅 tailnet）。
+- 远程 CDP 端点权限很高；请通过隧道并加以保护。
+
+严格模式示例（默认阻止私有/内部目标）：
+
+```json5
+{
+  browser: {
+    ssrfPolicy: {
+      dangerouslyAllowPrivateNetwork: false,
+      hostnameAllowlist: ["*.example.com", "example.com"],
+      allowedHostnames: ["localhost"], // 可选精确允许
+    },
+  },
+}
+```
+
+## 相关内容
+
+- [Browser](/zh-CN/tools/browser) — 概览、配置、profiles、安全
+- [Browser login](/zh-CN/tools/browser-login) — 登录网站
+- [Browser Linux troubleshooting](/zh-CN/tools/browser-linux-troubleshooting)
+- [Browser WSL2 troubleshooting](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
diff --git a/docs/zh-CN/tools/browser.md b/docs/zh-CN/tools/browser.md
index 7414fdedc..fdf0b4be7 100644
--- a/docs/zh-CN/tools/browser.md
+++ b/docs/zh-CN/tools/browser.md
@@ -1,41 +1,39 @@
 ---
 read_when:
     - 添加由智能体控制的浏览器自动化
-    - |-
-      调试为什么 openclaw 会干扰你自己的 Chrome♀♀♀♀♀♀analysis to=functions.read code 】!【json
-      {"path":"/home/runner/work/docs/docs/source/scripts/docs-i18n/","offset":1,"limit":1}
+    - 调试为什么 openclaw 会干扰你自己的 Chrome
     - 在 macOS 应用中实现浏览器设置 + 生命周期
-summary: 集成式浏览器控制服务 + 动作命令
+summary: 集成浏览器控制服务 + 操作命令
 title: 浏览器（由 OpenClaw 管理）
 x-i18n:
-    generated_at: "2026-04-23T21:07:01Z"
+    generated_at: "2026-04-24T02:39:44Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 3232ec0627004aabd8fe7c73efa237949e4148a9648de7a12951c2af54608d4b
+    source_hash: 2fb0fc0b6235fa8a0324b754e247e015d5ca19d114d324d565ed4a19f9313f7e
     source_path: tools/browser.md
     workflow: 15
 ---
 
-OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium profile**，由智能体控制。
-它与您的个人浏览器隔离，并通过 Gateway 网关中的一个小型本地
-控制服务进行管理（仅限 loopback）。
+OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。  
+它与你的个人浏览器隔离，并通过 Gateway 网关内部一个小型本地控制服务进行管理  
+（仅限 loopback）。
 
-新手视角：
+初学者视角：
 
 - 可以把它看作一个**独立的、仅供智能体使用的浏览器**。
-- `openclaw` profile **不会**触碰你的个人浏览器 profile。
+- `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。
 - 智能体可以在一个安全通道中**打开标签页、读取页面、点击和输入**。
-- 内置的 `user` profile 会通过 Chrome MCP 连接到你真实的、已登录的 Chrome 会话。
+- 内置的 `user` 配置文件会通过 Chrome MCP 连接到你真实的、已登录的 Chrome 会话。
 
-## 你将获得什么
+## 你会获得什么
 
-- 一个名为 **openclaw** 的独立浏览器 profile（默认使用橙色强调色）。
+- 一个名为 **openclaw** 的独立浏览器配置文件（默认橙色强调色）。
 - 可预测的标签页控制（列出/打开/聚焦/关闭）。
-- 智能体动作（点击/输入/拖拽/选择）、快照、截图、PDF。
-- 可选的多 profile 支持（`openclaw`、`work`、`remote`，等等）。
+- 智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。
+- 可选的多配置文件支持（`openclaw`、`work`、`remote`，等等）。
 
-这个浏览器**不是**你的日常主浏览器。它是一个安全、隔离的表面，
-用于智能体自动化和验证。
+这个浏览器**不是**你的日常主力浏览器。它是一个安全、隔离的界面，用于  
+智能体自动化与验证。
 
 ## 快速开始
 
@@ -46,15 +44,14 @@ openclaw browser --browser-profile openclaw open https://example.com
 openclaw browser --browser-profile openclaw snapshot
 ```
 
-如果你看到 “Browser disabled”，请在配置中启用它（见下文），然后重启
+如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启  
 Gateway 网关。
 
-如果 `openclaw browser` 整体都不存在，或者智能体提示浏览器工具
-不可用，请直接跳转到 [缺少 browser 命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。
+如果根本没有 `openclaw browser`，或者智能体提示浏览器工具不可用，请跳转到 [缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。
 
 ## 插件控制
 
-默认的 `browser` 工具是一个内置插件。若要用另一个注册了相同 `browser` 工具名的插件来替换它，请先禁用该插件：
+默认的 `browser` 工具是一个内置插件。禁用它可以用另一个注册相同 `browser` 工具名称的插件来替换：
 
 ```json5
 {
@@ -68,13 +65,13 @@ Gateway 网关。
 }
 ```
 
-默认情况下需要同时满足 `plugins.entries.browser.enabled` **以及** `browser.enabled=true`。仅禁用插件会整体移除 `openclaw browser` CLI、`browser.request` gateway 方法、智能体工具和控制服务；你的 `browser.*` 配置会原样保留，以供替代插件使用。
+默认行为需要同时设置 `plugins.entries.browser.enabled` **和** `browser.enabled=true`。仅禁用插件会整体移除 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具以及控制服务；你的 `browser.*` 配置会保持不变，以供替代方案使用。
 
-浏览器配置变更需要重启 Gateway 网关，这样插件才能重新注册其服务。
+浏览器配置变更需要重启 Gateway 网关，以便插件重新注册其服务。
 
-## 缺少 browser 命令或工具
+## 缺少浏览器命令或工具
 
-如果升级后 `openclaw browser` 变成未知命令，`browser.request` 缺失，或智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中未包含 `browser`。请将它加上：
+如果升级后 `openclaw browser` 未知、缺少 `browser.request`，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中遗漏了 `browser`。请添加它：
 
 ```json5
 {
@@ -84,19 +81,18 @@ Gateway 网关。
 }
 ```
 
-`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` 也会恢复默认行为。
 
-## Profiles：`openclaw` vs `user`
+## 配置文件：`openclaw` 与 `user`
 
-- `openclaw`：受管理、隔离的浏览器（不需要扩展）。
-- `user`：内置的 Chrome MCP 附加 profile，用于连接你**真实的已登录 Chrome**
-  会话。
+- `openclaw`：受管理的隔离浏览器（无需扩展）。
+- `user`：内置的 Chrome MCP 连接配置文件，用于连接你**真实的已登录 Chrome** 会话。
 
 对于智能体浏览器工具调用：
 
 - 默认：使用隔离的 `openclaw` 浏览器。
-- 当已登录会话很重要，并且用户本人在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。
-- 当你想指定某种浏览器模式时，`profile` 是显式覆盖项。
+- 当现有登录会话很重要，且用户就在电脑前可以点击/批准任何连接提示时，优先使用 `profile="user"`。
+- 当你想要指定浏览器模式时，`profile` 是显式覆盖项。
 
 如果你希望默认使用受管理模式，请设置 `browser.defaultProfile: "openclaw"`。
 
@@ -107,16 +103,16 @@ Gateway 网关。
 ```json5
 {
   browser: {
-    enabled: true, // default: true
+    enabled: true, // 默认：true
     ssrfPolicy: {
-      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
-      // allowPrivateNetwork: true, // legacy alias
+      // dangerouslyAllowPrivateNetwork: true, // 仅在可信的私有网络访问场景下启用
+      // allowPrivateNetwork: true, // 旧别名
       // hostnameAllowlist: ["*.example.com", "example.com"],
       // allowedHostnames: ["localhost"],
     },
-    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
-    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
-    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
+    // cdpUrl: "http://127.0.0.1:18792", // 旧的单配置文件覆盖项
+    remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时（毫秒）
+    remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒）
     defaultProfile: "openclaw",
     color: "#FF4500",
     headless: false,
@@ -147,29 +143,29 @@ Gateway 网关。
 
 <Accordion title="端口与可达性">
 
-- 控制服务会绑定到 loopback，其端口由 `gateway.port` 派生（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会让同一族派生端口一起偏移。
-- 本地 `openclaw` profiles 会自动分配 `cdpPort`/`cdpUrl`；仅在远程 CDP 场景下才需要手动设置这些值。未设置时，`cdpUrl` 默认指向受管理的本地 CDP 端口。
+- 控制服务绑定到 loopback，端口基于 `gateway.port` 派生（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会同步移动同一组派生端口。
+- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；仅在远程 CDP 场景下才需要设置它们。未设置时，`cdpUrl` 默认指向受管理的本地 CDP 端口。
 - `remoteCdpTimeoutMs` 适用于远程（非 loopback）CDP HTTP 可达性检查；`remoteCdpHandshakeTimeoutMs` 适用于远程 CDP WebSocket 握手。
 
 </Accordion>
 
 <Accordion title="SSRF 策略">
 
-- 浏览器导航与 open-tab 会在导航前执行 SSRF 防护，并在导航后对最终 `http(s)` URL 做尽力复检。
-- 在严格 SSRF 模式下，远程 CDP 端点发现与 `/json/version` 探测（`cdpUrl`）也会被检查。
-- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅当你明确且信任私有网络浏览器访问时才启用。
-- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。
+- 浏览器导航与打开标签页会在导航前进行 SSRF 防护，并在最终 `http(s)` URL 上尽力再次检查。
+- 在严格 SSRF 模式下，远程 CDP 端点发现和 `/json/version` 探测（`cdpUrl`）也会被检查。
+- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅当你明确可信任私有网络浏览器访问时才启用。
+- `browser.ssrfPolicy.allowPrivateNetwork` 作为旧别名仍然受支持。
 
 </Accordion>
 
-<Accordion title="Profile 行为">
+<Accordion title="配置文件行为">
 
-- `attachOnly: true` 表示绝不启动本地浏览器；只有在浏览器已运行时才进行附加。
-- `color`（顶层和按 profile）会给浏览器 UI 着色，以便你看出当前激活的是哪个 profile。
-- 默认 profile 是 `openclaw`（受管理的独立实例）。使用 `defaultProfile: "user"` 可切换为已登录的用户浏览器。
-- 自动检测顺序：若系统默认浏览器是基于 Chromium，则优先使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。
-- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。对该驱动不要设置 `cdpUrl`。
-- 当某个 existing-session profile 应附加到非默认 Chromium 用户 profile（Brave、Edge 等）时，请设置 `browser.profiles.<name>.userDataDir`。
+- `attachOnly: true` 表示绝不启动本地浏览器；仅在浏览器已经运行时连接。
+- `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>
 
@@ -177,15 +173,15 @@ Gateway 网关。
 
 ## 使用 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"
 ```
 
-或者在配置中按平台设置：
+或者按平台在配置中设置：
 
 <Tabs>
   <Tab title="macOS">
@@ -219,50 +215,47 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
 
 ## 本地控制 vs 远程控制
 
-- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并可启动本地浏览器。
-- **远程控制（node host）：** 在有浏览器的机器上运行 node host；Gateway 网关会将浏览器动作代理到它。
-- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`），
-  以附加到远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
+- **本地控制（默认）：** Gateway 网关会启动 loopback 控制服务，并可启动本地浏览器。
+- **远程控制（节点主机）：** 在拥有浏览器的机器上运行一个节点主机；Gateway 网关会将浏览器操作代理过去。
+- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`）以连接到远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
 
-不同 profile 模式的停止行为不同：
+停止行为会因配置文件模式而不同：
 
-- 本地受管理 profiles：`openclaw browser stop` 会停止由
+- 本地受管理配置文件：`openclaw browser stop` 会停止  
   OpenClaw 启动的浏览器进程
-- attach-only 和远程 CDP profiles：`openclaw browser stop` 会关闭当前活动的
-  控制会话，并释放 Playwright/CDP 仿真覆盖（viewport、
-  color scheme、locale、timezone、offline mode 以及类似状态），即使
-  该浏览器进程并不是由 OpenClaw 启动的
+- 仅连接和远程 CDP 配置文件：`openclaw browser stop` 会关闭当前活动的  
+  控制会话，并释放 Playwright/CDP 仿真覆盖项（视口、  
+  配色方案、区域设置、时区、离线模式及类似状态），即使  
+  OpenClaw 并未启动任何浏览器进程
 
 远程 CDP URL 可以包含认证信息：
 
-- Query token（例如 `https://provider.example?token=<token>`）
-- HTTP Basic auth（例如 `https://user:pass@provider.example`）
+- 查询参数令牌（例如 `https://provider.example?token=<token>`）
+- HTTP Basic 认证（例如 `https://user:pass@provider.example`）
 
-OpenClaw 在调用 `/json/*` 端点以及连接
-CDP WebSocket 时都会保留这些认证信息。对于 token，建议优先使用环境变量或 secrets 管理器，
-而不是将其提交到配置文件中。
+OpenClaw 在调用 `/json/*` 端点以及连接  
+CDP WebSocket 时会保留这些认证信息。对于令牌，建议优先使用环境变量或秘密管理器，而不是将其提交到配置文件中。
 
 ## 节点浏览器代理（零配置默认）
 
-如果你在拥有浏览器的机器上运行了**node host**，OpenClaw 可以
-自动将浏览器工具调用路由到该节点，而无需额外的浏览器配置。
-这是远程 gateway 的默认路径。
+如果你在拥有浏览器的机器上运行了一个**节点主机**，OpenClaw 可以  
+在无需任何额外浏览器配置的情况下，自动将浏览器工具调用路由到该节点。  
+这是远程 Gateway 网关的默认路径。
 
 说明：
 
-- node host 会通过一个**代理命令**暴露其本地浏览器控制服务器。
-- Profiles 来自该节点自身的 `browser.profiles` 配置（与本地相同）。
-- `nodeHost.browserProxy.allowProfiles` 是可选的。保持为空即可获得旧版/默认行为：所有已配置的 profiles 都可以通过代理访问，包括 profile 创建/删除路由。
-- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有加入 allowlist 的 profiles 才能被访问，且持久化 profile 创建/删除路由会在代理表面被阻止。
-- 如果你不想使用它，可以禁用：
+- 节点主机会通过一个**代理命令**暴露其本地浏览器控制服务器。
+- 配置文件来自节点自身的 `browser.profiles` 配置（与本地相同）。
+- `nodeHost.browserProxy.allowProfiles` 是可选项。保持为空即可使用旧版/默认行为：所有已配置的配置文件都可通过代理访问，包括配置文件创建/删除路由。
+- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有允许列表中的配置文件可以被访问，而且持久化配置文件创建/删除路由会在代理层被阻止。
+- 如果你不想启用它，可以关闭：
   - 在节点上：`nodeHost.browserProxy.enabled=false`
-  - 在 gateway 上：`gateway.nodes.browser.mode="off"`
+  - 在 Gateway 网关上：`gateway.nodes.browser.mode="off"`
 
 ## Browserless（托管远程 CDP）
 
-[Browserless](https://browserless.io) 是一项托管 Chromium 服务，通过 HTTPS 和 WebSocket 暴露
-CDP 连接 URL。OpenClaw 两种形式都支持，但对于远程浏览器 profile，
-最简单的方案是直接使用 Browserless 连接文档中给出的 WebSocket URL。
+[Browserless](https://browserless.io) 是一项托管的 Chromium 服务，通过 HTTPS 和 WebSocket 暴露  
+CDP 连接 URL。OpenClaw 两种形式都支持，但对于远程浏览器配置文件，最简单的选择通常是 Browserless 连接文档中提供的直接 WebSocket URL。
 
 示例：
 
@@ -285,38 +278,38 @@ CDP 连接 URL。OpenClaw 两种形式都支持，但对于远程浏览器 profi
 
 说明：
 
-- 请将 `<BROWSERLESS_API_KEY>` 替换为你的真实 Browserless token。
+- 将 `<BROWSERLESS_API_KEY>` 替换为你真实的 Browserless 令牌。
 - 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。
-- 如果 Browserless 给你的是 HTTPS 基础 URL，你可以将其转换为
-  `wss://` 用于直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw
-  通过 `/json/version` 自动发现。
+- 如果 Browserless 提供给你的是 HTTPS 基础 URL，你既可以将其转换为  
+  `wss://` 以建立直接 CDP 连接，也可以保留 HTTPS URL，让 OpenClaw  
+  去发现 `/json/version`。
 
-## 直接 WebSocket CDP providers
+## 直接 WebSocket CDP 提供商
 
-有些托管浏览器服务暴露的是**直接 WebSocket**端点，而不是
-标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种
-CDP URL 形态，并会自动选择正确的连接策略：
+某些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是  
+标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种  
+CDP URL 形式，并会自动选择正确的连接策略：
 
-- **HTTP(S) 发现** —— `http://host[:port]` 或 `https://host[:port]`。  
-  OpenClaw 会调用 `/json/version` 来发现 WebSocket debugger URL，然后
-  进行连接。没有 WebSocket 回退。
-- **直接 WebSocket 端点** —— `ws://host[:port]/devtools/<kind>/<id>` 或
-  `wss://...`，其中路径为 `/devtools/browser|page|worker|shared_worker|service_worker/<id>`。  
-  OpenClaw 会直接通过 WebSocket 握手连接，并完全跳过
+- **HTTP(S) 发现** — `http://host[:port]` 或 `https://host[:port]`。  
+  OpenClaw 会调用 `/json/version` 来发现 WebSocket 调试器 URL，然后  
+  连接。没有 WebSocket 回退。
+- **直接 WebSocket 端点** — `ws://host[:port]/devtools/<kind>/<id>` 或  
+  `wss://...`，路径为 `/devtools/browser|page|worker|shared_worker|service_worker/<id>`。  
+  OpenClaw 会直接通过 WebSocket 握手连接，并完全跳过  
   `/json/version`。
-- **裸 WebSocket 根地址** —— `ws://host[:port]` 或 `wss://host[:port]`，没有
-  `/devtools/...` 路径（例如 [Browserless](https://browserless.io)、
-  [Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试 HTTP
-  `/json/version` 发现（并将 scheme 标准化为 `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
 {
@@ -337,76 +330,75 @@ CDP URL 形态，并会自动选择正确的连接策略：
 
 说明：
 
-- 前往 [注册](https://www.browserbase.com/sign-up)，并从 [Overview dashboard](https://www.browserbase.com/overview) 复制你的 **API Key**。
-- 请将 `<BROWSERBASE_API_KEY>` 替换为你真实的 Browserbase API key。
-- Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此
+- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview 控制台](https://www.browserbase.com/overview) 复制你的**API Key**。
+- 将 `<BROWSERBASE_API_KEY>` 替换为你真实的 Browserbase API key。
+- Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此  
   不需要手动创建会话。
-- 免费套餐每月允许一个并发会话和一个浏览器小时。
-  付费套餐限制请参见 [定价](https://www.browserbase.com/pricing)。
-- 完整 API
-  参考、SDK 指南和集成示例请参见 [Browserbase 文档](https://docs.browserbase.com)。
+- 免费套餐每月允许一个并发会话和一个浏览器小时。  
+  付费方案限制请参见 [pricing](https://www.browserbase.com/pricing)。
+- 完整 API 参考、SDK 指南和集成示例，请参见 [Browserbase docs](https://docs.browserbase.com)。
 
 ## 安全性
 
 关键概念：
 
 - 浏览器控制仅限 loopback；访问通过 Gateway 网关的认证或节点配对进行。
-- 独立的 loopback 浏览器 HTTP API 仅使用**共享 secret 认证**：
-  gateway token bearer 认证、`x-openclaw-password`，或带有
-  已配置 gateway 密码的 HTTP Basic auth。
-- Tailscale Serve 身份 headers 和 `gateway.auth.mode: "trusted-proxy"` 
+- 独立的 loopback 浏览器 HTTP API **仅使用共享密钥认证**：
+  Gateway 网关 token Bearer 认证、`x-openclaw-password`，或使用已配置 Gateway 网关密码的 HTTP Basic 认证。
+- Tailscale Serve 身份头和 `gateway.auth.mode: "trusted-proxy"`  
   **不能**为这个独立的 loopback 浏览器 API 提供认证。
-- 如果启用了浏览器控制但未配置共享 secret 认证，OpenClaw
-  会在启动时自动生成 `gateway.auth.token`，并将其持久化到配置中。
-- 当 `gateway.auth.mode` 已经是
-  `password`、`none` 或 `trusted-proxy` 时，OpenClaw **不会**自动生成该 token。
-- 请将 Gateway 网关和任何节点宿主机保持在私有网络中（如 Tailscale）；避免公开暴露。
-- 请将远程 CDP URL/token 视为 secrets；优先使用环境变量或 secrets 管理器。
+- 如果启用了浏览器控制且未配置共享密钥认证，OpenClaw  
+  会在启动时自动生成 `gateway.auth.token` 并将其持久化到配置中。
+- 如果 `gateway.auth.mode` 已经是  
+  `password`、`none` 或 `trusted-proxy`，OpenClaw **不会**自动生成该 token。
+- 请将 Gateway 网关和任何节点主机保持在私有网络上（Tailscale）；避免公开暴露。
+- 将远程 CDP URL/token 视为敏感信息；优先使用环境变量或秘密管理器。
 
 远程 CDP 提示：
 
 - 尽可能优先使用加密端点（HTTPS 或 WSS）和短期 token。
-- 避免将长期有效 token 直接嵌入到配置文件中。
+- 避免将长期 token 直接嵌入配置文件。
 
-## Profiles（多浏览器）
+## 配置文件（多浏览器）
 
-OpenClaw 支持多个命名 profile（路由配置）。Profiles 可以是：
+OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是：
 
-- **由 OpenClaw 管理**：一个专用的、基于 Chromium 的浏览器实例，拥有自己的用户数据目录 + CDP 端口
-- **远程**：一个显式的 CDP URL（运行在其他位置的基于 Chromium 的浏览器）
-- **现有会话**：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome profile
+- **openclaw-managed**：一个专用的基于 Chromium 的浏览器实例，拥有自己的用户数据目录 + CDP 端口
+- **remote**：显式的 CDP URL（运行在其他位置的基于 Chromium 的浏览器）
+- **existing session**：通过 Chrome DevTools MCP 自动连接你现有的 Chrome 配置文件
 
 默认值：
 
-- 如果缺失，会自动创建 `openclaw` profile。
-- `user` profile 是内置的，用于 Chrome MCP existing-session 附加。
-- 除 `user` 外，existing-session profiles 都是显式启用的；请使用 `--driver existing-session` 创建它们。
+- 如果缺少 `openclaw` 配置文件，会自动创建。
+- `user` 配置文件是内置的，用于 Chrome MCP existing-session 连接。
+- 除 `user` 外，existing-session 配置文件需要显式启用；请使用 `--driver existing-session` 创建。
 - 本地 CDP 端口默认从 **18800–18899** 分配。
-- 删除一个 profile 时，会将其本地数据目录移到废纸篓。
+- 删除配置文件时，会将其本地数据目录移到废纸篓。
 
 所有控制端点都接受 `?profile=<name>`；CLI 使用 `--browser-profile`。
 
 ## 通过 Chrome DevTools MCP 使用 existing-session
 
-OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器，附加到正在运行的基于 Chromium 的浏览器 profile。这样可以复用该浏览器 profile 中已经打开的标签页和登录状态。
+OpenClaw 也可以通过官方 Chrome DevTools MCP 服务器连接到一个正在运行的基于 Chromium 的浏览器配置文件。这样会复用该浏览器配置文件中  
+已经打开的标签页和登录状态。
 
 官方背景与设置参考：
 
-- [Chrome for Developers：Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
+- [Chrome for Developers：在你的浏览器会话中使用 Chrome DevTools MCP](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
 - [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
 
-内置 profile：
+内置配置文件：
 
 - `user`
 
-可选：如果你想使用不同的名称、颜色或浏览器数据目录，也可以创建自己的自定义 existing-session profile。
+可选：如果你想使用不同的名称、颜色或浏览器数据目录，可以创建你自己的自定义 existing-session 配置文件。
 
 默认行为：
 
-- 内置的 `user` profile 使用 Chrome MCP 自动连接，目标是
-  默认本地 Google Chrome profile。
+- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，目标是  
+  默认的本地 Google Chrome 配置文件。
 
-对于 Brave、Edge、Chromium 或非默认 Chrome profile，请使用 `userDataDir`：
+对于 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`：
 
 ```json5
 {
@@ -427,7 +419,7 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器，附加到正在
 
 1. 打开该浏览器用于远程调试的 inspect 页面。
 2. 启用远程调试。
-3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。
+3. 保持浏览器运行，并在 OpenClaw 连接时批准连接提示。
 
 常见 inspect 页面：
 
@@ -435,7 +427,7 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器，附加到正在
 - Brave：`brave://inspect/#remote-debugging`
 - Edge：`edge://inspect/#remote-debugging`
 
-实时附加冒烟测试：
+实时连接冒烟测试：
 
 ```bash
 openclaw browser --browser-profile user start
@@ -452,53 +444,52 @@ openclaw browser --browser-profile user snapshot --format ai
 - `tabs` 列出你已经打开的浏览器标签页
 - `snapshot` 返回所选实时标签页中的 refs
 
-如果附加无效，请检查：
+如果连接无效，请检查：
 
-- 目标的基于 Chromium 的浏览器版本是否为 `144+`
-- 是否已在该浏览器的 inspect 页面中启用远程调试
-- 浏览器是否弹出了附加同意提示，并且你已接受
-- `openclaw doctor` 可以迁移旧的基于扩展的浏览器配置，并检查
-  默认自动连接 profile 所需的 Chrome 是否已在本地安装，但它无法替你启用浏览器侧的远程调试
+- 目标的基于 Chromium 的浏览器版本为 `144+`
+- 已在该浏览器的 inspect 页面中启用远程调试
+- 浏览器已显示连接同意提示，并且你已接受
+- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查  
+  默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它不能  
+  替你启用浏览器端的远程调试
 
-智能体使用：
+智能体使用方式：
 
-- 当你需要使用用户已登录浏览器状态时，请使用 `profile="user"`。
-- 如果你使用的是自定义 existing-session profile，请传入那个显式 profile 名称。
-- 只有当用户本人在电脑前、可以批准附加
-  提示时，才应选择此模式。
-- Gateway 网关或节点宿主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect`
+- 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。
+- 如果你使用自定义 existing-session 配置文件，请传入其明确的配置文件名称。
+- 仅当用户就在电脑前、可以批准连接提示时才选择此模式。
+- Gateway 网关或节点主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect`
 
 说明：
 
-- 相比隔离的 `openclaw` profile，这条路径风险更高，因为它可以
-  在你已登录的浏览器会话中执行操作。
-- 对于这个驱动，OpenClaw 不会启动浏览器；它只会附加。
-- OpenClaw 在这里使用官方 Chrome DevTools MCP `--autoConnect` 流程。如果
-  设置了 `userDataDir`，它会被透传，以定位到对应的用户数据目录。
-- Existing-session 可以在所选宿主机上附加，也可以通过已连接的
-  浏览器节点附加。如果 Chrome 位于其他位置且没有连接浏览器节点，请改用
-  远程 CDP 或 node host。
+- 由于它可以在你已登录的浏览器会话中执行操作，因此这一路径比隔离的 `openclaw` 配置文件风险更高。
+- 对于该驱动，OpenClaw 不会启动浏览器；它只会连接。
+- OpenClaw 在此处使用官方 Chrome DevTools MCP `--autoConnect` 流程。如果  
+  设置了 `userDataDir`，则会一并传递，用于定位该用户数据目录。
+- existing-session 可以连接到所选主机，或通过已连接的  
+  浏览器节点进行连接。如果 Chrome 位于其他位置且未连接浏览器节点，请改用  
+  远程 CDP 或节点主机。
 
-<Accordion title="Existing-session 功能限制">
+<Accordion title="existing-session 功能限制">
 
-与受管理的 `openclaw` profile 相比，existing-session 驱动的能力会更受限：
+与受管理的 `openclaw` 配置文件相比，existing-session 驱动限制更多：
 
-- **截图** —— 页面截图和 `--ref` 元素截图可用；CSS `--element` 选择器不可用。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面或基于 ref 的元素截图不需要 Playwright。
-- **动作** —— `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要 snapshot refs（不支持 CSS 选择器）。`click` 仅支持左键。`type` 不支持 `slowly=true`；请使用 `fill` 或 `press`。`press` 不支持 `delayMs`。`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按次调用的超时。`select` 只接受单个值。
-- **等待 / 上传 / 对话框** —— `wait --url` 支持精确、子串和 glob 模式；不支持 `wait --load networkidle`。上传 hooks 需要 `ref` 或 `inputRef`，一次仅支持一个文件，不支持 CSS `element`。对话框 hooks 不支持超时覆盖。
-- **仅受管理模式支持的功能** —— 批量动作、PDF 导出、下载拦截和 `responsebody` 仍然需要受管理浏览器路径。
+- **截图** —— 支持页面截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面截图或基于 ref 的元素截图不需要 Playwright。
+- **操作** —— `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要使用快照 ref（不支持 CSS 选择器）。`click` 仅支持鼠标左键。`type` 不支持 `slowly=true`；请使用 `fill` 或 `press`。`press` 不支持 `delayMs`。`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用单独设置超时。`select` 接受单个值。
+- **Wait / upload / dialog** —— `wait --url` 支持精确、子串和 glob 模式；不支持 `wait --load networkidle`。上传钩子要求使用 `ref` 或 `inputRef`，每次一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。
+- **仅限 managed 的功能** —— 批量操作、PDF 导出、下载拦截以及 `responsebody` 仍然需要受管理浏览器路径。
 
 </Accordion>
 
 ## 隔离保证
 
-- **专用用户数据目录**：绝不触碰你的个人浏览器 profile。
+- **专用用户数据目录**：绝不会触碰你的个人浏览器配置文件。
 - **专用端口**：避免使用 `9222`，以防与开发工作流冲突。
-- **确定性的标签页控制**：通过 `targetId` 定位标签页，而不是依赖“最后一个标签页”。
+- **可预测的标签页控制**：通过 `targetId` 定位标签页，而不是“最后一个标签页”。
 
 ## 浏览器选择
 
-在本地启动时，OpenClaw 会选择第一个可用项：
+在本地启动时，OpenClaw 会选择第一个可用的浏览器：
 
 1. Chrome
 2. Brave
@@ -506,9 +497,9 @@ openclaw browser --browser-profile user snapshot --format ai
 4. Chromium
 5. Chrome Canary
 
-你可以通过 `browser.executablePath` 覆盖。
+你可以通过 `browser.executablePath` 覆盖它。
 
-平台差异：
+平台说明：
 
 - macOS：检查 `/Applications` 和 `~/Applications`。
 - Linux：查找 `google-chrome`、`brave`、`microsoft-edge`、`chromium` 等。
@@ -516,352 +507,33 @@ openclaw browser --browser-profile user snapshot --format ai
 
 ## 控制 API（可选）
 
-对于仅限本地的集成，Gateway 网关暴露了一个小型 loopback HTTP API：
-
-- 状态/启动/停止：`GET /`、`POST /start`、`POST /stop`
-- 标签页：`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId`
-- Snapshot/截图：`GET /snapshot`、`POST /screenshot`
-- 动作：`POST /navigate`、`POST /act`
-- Hooks：`POST /hooks/file-chooser`、`POST /hooks/dialog`
-- 下载：`POST /download`、`POST /wait/download`
-- 调试：`GET /console`、`POST /pdf`
-- 调试：`GET /errors`、`GET /requests`、`POST /trace/start`、`POST /trace/stop`、`POST /highlight`
-- 网络：`POST /response/body`
-- 状态：`GET /cookies`、`POST /cookies/set`、`POST /cookies/clear`
-- 状态：`GET /storage/:kind`、`POST /storage/:kind/set`、`POST /storage/:kind/clear`
-- 设置：`POST /set/offline`、`POST /set/headers`、`POST /set/credentials`、`POST /set/geolocation`、`POST /set/media`、`POST /set/timezone`、`POST /set/locale`、`POST /set/device`
-
-所有端点都接受 `?profile=<name>`。
-
-如果配置了共享 secret Gateway 网关认证，则浏览器 HTTP 路由也需要认证：
-
-- `Authorization: Bearer <gateway token>`
-- `x-openclaw-password: <gateway password>` 或带该密码的 HTTP Basic auth
-
-说明：
-
-- 这个独立的 loopback 浏览器 API **不会**消费 trusted-proxy 或
-  Tailscale Serve 身份 headers。
-- 如果 `gateway.auth.mode` 是 `none` 或 `trusted-proxy`，这些 loopback 浏览器
-  路由也不会继承这些基于身份的模式；请保持它们仅限 loopback。
-
-### `/act` 错误契约
-
-`POST /act` 对于路由级校验和
-策略失败使用结构化错误响应：
-
-```json
-{ "error": "<message>", "code": "ACT_*" }
-```
-
-当前 `code` 值：
-
-- `ACT_KIND_REQUIRED`（HTTP 400）：缺少 `kind` 或无法识别。
-- `ACT_INVALID_REQUEST`（HTTP 400）：动作负载标准化或校验失败。
-- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）：在不支持的动作类型中使用了 `selector`。
-- `ACT_EVALUATE_DISABLED`（HTTP 403）：`evaluate`（或 `wait --fn`）已被配置禁用。
-- `ACT_TARGET_ID_MISMATCH`（HTTP 403）：顶层或批量 `targetId` 与请求目标冲突。
-- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：该动作不支持 existing-session profiles。
-
-其他运行时故障仍可能只返回 `{ "error": "<message>" }`，
-而不包含 `code` 字段。
-
-### Playwright 要求
-
-部分功能（navigate/act/AI snapshot/role snapshot、元素截图、
-PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回
-明确的 501 错误。
-
-在没有 Playwright 的情况下仍可工作的内容：
-
-- ARIA snapshots
-- 当存在按标签页划分的 CDP
-  WebSocket 时，针对受管理 `openclaw` 浏览器的页面截图
-- 针对 `existing-session` / Chrome MCP profiles 的页面截图
-- 来自 snapshot 输出的 `existing-session` 基于 ref 的截图（`--ref`）
-
-仍然需要 Playwright 的内容：
-
-- `navigate`
-- `act`
-- AI snapshots / role snapshots
-- 基于 CSS 选择器的元素截图（`--element`）
-- 完整浏览器 PDF 导出
-
-元素截图也会拒绝 `--full-page`；该路由会返回 `fullPage is
-not supported for element screenshots`。
-
-如果你看到 `Playwright is not available in this gateway build`，请修复
-内置浏览器插件的运行时依赖，确保已安装 `playwright-core`，
-然后重启 gateway。对于打包安装，请运行 `openclaw doctor --fix`。
-对于 Docker，还需按下文所示安装 Chromium 浏览器二进制文件。
-
-#### Docker Playwright 安装
-
-如果你的 Gateway 网关运行在 Docker 中，请避免使用 `npx playwright`（会与 npm 覆盖产生冲突）。
-请改用内置 CLI：
-
-```bash
-docker compose run --rm openclaw-cli \
-  node /app/node_modules/playwright-core/cli.js install chromium
-```
-
-要持久化浏览器下载内容，请设置 `PLAYWRIGHT_BROWSERS_PATH`（例如
-`/home/node/.cache/ms-playwright`），并确保 `/home/node` 通过
-`OPENCLAW_HOME_VOLUME` 或 bind mount 持久化。参见 [Docker](/zh-CN/install/docker)。
-
-## 工作原理（内部）
-
-一个小型的 loopback 控制服务器接收 HTTP 请求，并通过 CDP 连接到基于 Chromium 的浏览器。高级动作（click/type/snapshot/PDF）通过建立在 CDP 之上的 Playwright 完成；当 Playwright 缺失时，只能使用非 Playwright 操作。对智能体来说，始终看到的是一个稳定接口，而本地/远程浏览器和 profile 可以在底层自由切换。
-
-## CLI 快速参考
-
-所有命令都接受 `--browser-profile <name>` 用于指定某个 profile，并接受 `--json` 用于机器可读输出。
-
-<AccordionGroup>
-
-<Accordion title="基础：status、tabs、open/focus/close">
-
-```bash
-openclaw browser status
-openclaw browser start
-openclaw browser stop            # also clears emulation on attach-only/remote CDP
-openclaw browser tabs
-openclaw browser tab             # shortcut for current tab
-openclaw browser tab new
-openclaw browser tab select 2
-openclaw browser tab close 2
-openclaw browser open https://example.com
-openclaw browser focus abcd1234
-openclaw browser close abcd1234
-```
-
-</Accordion>
-
-<Accordion title="检查：screenshot、snapshot、console、errors、requests">
-
-```bash
-openclaw browser screenshot
-openclaw browser screenshot --full-page
-openclaw browser screenshot --ref 12        # or --ref e12
-openclaw browser snapshot
-openclaw browser snapshot --format aria --limit 200
-openclaw browser snapshot --interactive --compact --depth 6
-openclaw browser snapshot --efficient
-openclaw browser snapshot --labels
-openclaw browser snapshot --selector "#main" --interactive
-openclaw browser snapshot --frame "iframe#main" --interactive
-openclaw browser console --level error
-openclaw browser errors --clear
-openclaw browser requests --filter api --clear
-openclaw browser pdf
-openclaw browser responsebody "**/api" --max-chars 5000
-```
-
-</Accordion>
-
-<Accordion title="动作：navigate、click、type、drag、wait、evaluate">
-
-```bash
-openclaw browser navigate https://example.com
-openclaw browser resize 1280 720
-openclaw browser click 12 --double           # or e12 for role refs
-openclaw browser type 23 "hello" --submit
-openclaw browser press Enter
-openclaw browser hover 44
-openclaw browser scrollintoview e12
-openclaw browser drag 10 11
-openclaw browser select 9 OptionA OptionB
-openclaw browser download e12 report.pdf
-openclaw browser waitfordownload report.pdf
-openclaw browser upload /tmp/openclaw/uploads/file.pdf
-openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
-openclaw browser dialog --accept
-openclaw browser wait --text "Done"
-openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
-openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
-openclaw browser highlight e12
-openclaw browser trace start
-openclaw browser trace stop
-```
-
-</Accordion>
-
-<Accordion title="状态：cookies、storage、offline、headers、geo、device">
-
-```bash
-openclaw browser cookies
-openclaw browser cookies set session abc123 --url "https://example.com"
-openclaw browser cookies clear
-openclaw browser storage local get
-openclaw browser storage local set theme dark
-openclaw browser storage session clear
-openclaw browser set offline on
-openclaw browser set headers --headers-json '{"X-Debug":"1"}'
-openclaw browser set credentials user pass            # --clear to remove
-openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
-openclaw browser set media dark
-openclaw browser set timezone America/New_York
-openclaw browser set locale en-US
-openclaw browser set device "iPhone 14"
-```
-
-</Accordion>
-
-</AccordionGroup>
-
-说明：
-
-- `upload` 和 `dialog` 是**预置**调用；请在触发文件选择器/对话框的 click/press 之前先执行它们。
-- `click`/`type`/等动作需要来自 `snapshot` 的 `ref`（数字 `12` 或角色引用 `e12`）。动作故意不支持 CSS 选择器。
-- 下载、trace 和 upload 路径被限制在 OpenClaw 临时根目录内：`/tmp/openclaw{,/downloads,/uploads}`（回退路径：`${os.tmpdir()}/openclaw/...`）。
-- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入。
-
-Snapshot 标志速览：
-
-- `--format ai`（装有 Playwright 时的默认值）：带数字引用的 AI snapshot（`aria-ref="<n>"`）。
-- `--format aria`：无障碍树，不含引用；仅用于检查。
-- `--efficient`（或 `--mode efficient`）：紧凑角色 snapshot 预设。将 `browser.snapshotDefaults.mode: "efficient"` 设为默认值（参见 [Gateway 网关配置](/zh-CN/gateway/configuration-reference#browser)）。
-- `--interactive`、`--compact`、`--depth`、`--selector` 会强制使用角色 snapshot，并生成 `ref=e12` 形式的引用。`--frame "<iframe>"` 可将角色 snapshot 限定在某个 iframe 内。
-- `--labels` 会附加一张仅限 viewport 的截图，并叠加 `e12` 标签（打印 `MEDIA:<path>`）。
-
-## Snapshots 与 refs
-
-OpenClaw 支持两种 “snapshot” 风格：
-
-- **AI snapshot（数字 refs）**：`openclaw browser snapshot`（默认；`--format ai`）
-  - 输出：包含数字 refs 的文本 snapshot。
-  - 动作：`openclaw browser click 12`、`openclaw browser type 23 "hello"`。
-  - 内部通过 Playwright 的 `aria-ref` 解析 ref。
-
-- **角色 snapshot（如 `e12` 这样的角色 refs）**：`openclaw browser snapshot --interactive`（或 `--compact`、`--depth`、`--selector`、`--frame`）
-  - 输出：带 `[ref=e12]`（以及可选 `[nth=1]`）的基于角色的列表/树。
-  - 动作：`openclaw browser click e12`、`openclaw browser highlight e12`。
-  - 内部通过 `getByRole(...)`（以及在重复场景下使用 `nth()`）解析 ref。
-  - 添加 `--labels` 可附带一张带有叠加 `e12` 标签的 viewport 截图。
-
-Ref 行为：
-
-- Refs **在导航之间并不稳定**；如果动作失败，请重新运行 `snapshot` 并使用新的 ref。
-- 如果角色 snapshot 是通过 `--frame` 获取的，则角色 refs 会被限定在该 iframe 中，直到下一次角色 snapshot 生成。
-
-## Wait 增强功能
-
-你可以等待的不只是时间/文本：
-
-- 等待 URL（支持 Playwright 风格 glob）：
-  - `openclaw browser wait --url "**/dash"`
-- 等待加载状态：
-  - `openclaw browser wait --load networkidle`
-- 等待 JS 谓词：
-  - `openclaw browser wait --fn "window.ready===true"`
-- 等待某个选择器变为可见：
-  - `openclaw browser wait "#main"`
-
-这些条件可以组合：
-
-```bash
-openclaw browser wait "#main" \
-  --url "**/dash" \
-  --load networkidle \
-  --fn "window.ready===true" \
-  --timeout-ms 15000
-```
-
-## 调试工作流
-
-当动作失败时（例如 “not visible”、“strict mode violation”、“covered”）：
-
-1. `openclaw browser snapshot --interactive`
-2. 使用 `click <ref>` / `type <ref>`（在交互模式下优先使用角色 refs）
-3. 如果仍然失败：运行 `openclaw browser highlight <ref>`，查看 Playwright 实际定位到的目标
-4. 如果页面行为异常：
-   - `openclaw browser errors --clear`
-   - `openclaw browser requests --filter api --clear`
-5. 对于深入调试：录制 trace：
-   - `openclaw browser trace start`
-   - 复现问题
-   - `openclaw browser trace stop`（会打印 `TRACE:<path>`）
-
-## JSON 输出
-
-`--json` 用于脚本和结构化工具链。
-
-示例：
-
-```bash
-openclaw browser status --json
-openclaw browser snapshot --interactive --json
-openclaw browser requests --filter api --json
-openclaw browser cookies --json
-```
-
-JSON 中的角色 snapshot 会包含 `refs` 以及一个小型 `stats` 块（lines/chars/refs/interactive），以便工具能够推断负载大小和密度。
-
-## 状态与环境调节项
-
-对于“让网站表现得像 X”之类的工作流，这些选项很有用：
-
-- Cookies：`cookies`、`cookies set`、`cookies clear`
-- Storage：`storage local|session get|set|clear`
-- Offline：`set offline on|off`
-- Headers：`set headers --headers-json '{"X-Debug":"1"}'`（旧版 `set headers --json '{"X-Debug":"1"}'` 仍受支持）
-- HTTP Basic auth：`set credentials user pass`（或 `--clear`）
-- Geolocation：`set geo <lat> <lon> --origin "https://example.com"`（或 `--clear`）
-- Media：`set media dark|light|no-preference|none`
-- Timezone / locale：`set timezone ...`、`set locale ...`
-- Device / viewport：
-  - `set device "iPhone 14"`（Playwright 设备预设）
-  - `set viewport 1280 720`
-
-## 安全与隐私
-
-- `openclaw` 浏览器 profile 可能包含已登录会话；请将其视为敏感对象。
-- `browser act kind=evaluate` / `openclaw browser evaluate` 以及 `wait --fn`
-  会在页面上下文中执行任意 JavaScript。提示注入可能会引导
-  这一行为。如果你不需要，请通过 `browser.evaluateEnabled=false` 禁用它。
-- 关于登录和反机器人注意事项（X/Twitter 等），请参见 [浏览器登录 + X/Twitter 发帖](/zh-CN/tools/browser-login)。
-- 请将 Gateway 网关/节点宿主机保持私有（仅限 loopback 或 tailnet）。
-- 远程 CDP 端点权限很高；请通过隧道并做好保护。
-
-严格模式示例（默认阻止私有/内部目标）：
-
-```json5
-{
-  browser: {
-    ssrfPolicy: {
-      dangerouslyAllowPrivateNetwork: false,
-      hostnameAllowlist: ["*.example.com", "example.com"],
-      allowedHostnames: ["localhost"], // optional exact allow
-    },
-  },
-}
-```
+为了便于脚本化和调试，Gateway 网关暴露了一个小型的**仅限 loopback 的 HTTP 控制 API**，并提供匹配的 `openclaw browser` CLI（快照、refs、wait 增强功能、JSON 输出、调试工作流）。完整参考请参见  
+[浏览器控制 API](/zh-CN/tools/browser-control)。
 
 ## 故障排除
 
-对于 Linux 特有问题（尤其是 snap Chromium），请参见
+有关 Linux 特有问题（尤其是 snap Chromium），请参见  
 [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)。
 
-对于 WSL2 Gateway 网关 + Windows Chrome 的分离宿主机场景，请参见
-[WSL2 + Windows + remote Chrome CDP 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)。
+有关 WSL2 Gateway 网关 + Windows Chrome 分离主机设置，请参见  
+[WSL2 + Windows + 远程 Chrome CDP 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)。
 
-### CDP 启动失败 vs 导航 SSRF 阻止
+### CDP 启动失败 vs 导航 SSRF 拦截
 
-这是两类不同的故障，它们指向不同的代码路径。
+这是两类不同的失败，它们指向不同的代码路径。
 
-- **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面是健康的。
-- **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但页面导航目标被策略拒绝了。
+- **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。
+- **导航 SSRF 拦截** 表示浏览器控制平面是健康的，但页面导航目标因策略而被拒绝。
 
 常见示例：
 
 - CDP 启动或就绪失败：
   - `Chrome CDP websocket for profile "openclaw" is not reachable after start`
   - `Remote CDP for profile "<name>" is not reachable at <cdpUrl>`
-- 导航 SSRF 阻止：
-  - `open`、`navigate`、snapshot 或 tab-opening 流程因浏览器/网络策略错误而失败，而 `start` 和 `tabs` 仍然可以工作
+- 导航 SSRF 拦截：
+  - 当 `start` 和 `tabs` 仍然可用时，`open`、`navigate`、snapshot 或打开标签页流程因浏览器/网络策略错误而失败
 
-使用下面这组最小命令来区分两者：
+使用以下最小序列来区分两者：
 
 ```bash
 openclaw browser --browser-profile openclaw start
@@ -869,47 +541,47 @@ openclaw browser --browser-profile openclaw tabs
 openclaw browser --browser-profile openclaw open https://example.com
 ```
 
-结果解读：
+结果解读方式：
 
-- 如果 `start` 以 `not reachable after start` 失败，请先排查 CDP 就绪性。
-- 如果 `start` 成功但 `tabs` 失败，控制平面仍然不健康。这仍应视为 CDP 可达性问题，而不是页面导航问题。
-- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面已经正常，故障点在于导航策略或目标页面。
-- 如果 `start`、`tabs` 和 `open` 都成功，则说明基础的受管理浏览器控制路径是健康的。
+- 如果 `start` 以 `not reachable after start` 失败，先排查 CDP 就绪性。
+- 如果 `start` 成功但 `tabs` 失败，则控制平面仍不健康。应将其视为 CDP 可达性问题，而不是页面导航问题。
+- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则浏览器控制平面已正常运行，失败出在导航策略或目标页面。
+- 如果 `start`、`tabs` 和 `open` 全部成功，则基本的受管理浏览器控制路径是健康的。
 
 重要行为细节：
 
-- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会带有一个失败关闭的 SSRF 策略对象。
-- 对于本地 loopback 的受管理 `openclaw` profile，CDP 健康检查会有意跳过针对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制检查。
-- 导航保护是独立的。`start` 或 `tabs` 的成功结果并不意味着后续的 `open` 或 `navigate` 目标一定被允许。
+- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会使用失败即关闭的 SSRF 策略对象。
+- 对于本地 loopback 的受管理 `openclaw` 配置文件，CDP 健康检查会刻意跳过对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制检查。
+- 导航保护是独立的。`start` 或 `tabs` 成功并不意味着后续的 `open` 或 `navigate` 目标一定被允许。
 
-安全建议：
+安全指导：
 
-- **不要** 默认放宽浏览器 SSRF 策略。
-- 优先使用像 `hostnameAllowlist` 或 `allowedHostnames` 这样的精细主机例外，而不是开放广泛的私有网络访问。
-- 只有在明确受信任、且确实需要访问私有网络浏览器目标并已完成审查的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。
+- 默认情况下**不要**放宽浏览器 SSRF 策略。
+- 优先使用狭义的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`，而不是宽泛的私有网络访问。
+- 仅在明确受信任且已审查、确实需要私有网络浏览器访问的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。
 
-## 智能体工具 + 控制方式
+## 智能体工具 + 控制工作方式
 
-智能体会获得**一个工具**用于浏览器自动化：
+智能体获得**一个工具**用于浏览器自动化：
 
 - `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
 
-映射方式：
+其映射关系如下：
 
-- `browser snapshot` 会返回一个稳定的 UI 树（AI 或 ARIA）。
-- `browser act` 会使用 snapshot 中的 `ref` ID 来执行 click/type/drag/select。
-- `browser screenshot` 会捕获像素（整页或元素）。
+- `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。
+- `browser act` 使用快照中的 `ref` ID 执行点击/输入/拖动/选择。
+- `browser screenshot` 捕获像素（整页或元素）。
 - `browser` 接受：
-  - `profile`，用于选择命名浏览器 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"`。
 
-这样可以让智能体保持确定性，并避免脆弱的选择器。
+这样可以让智能体保持可预测性，并避免脆弱的选择器。
 
 ## 相关内容
 
 - [工具概览](/zh-CN/tools) — 所有可用的智能体工具
-- [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱环境中的浏览器控制
-- [安全](/zh-CN/gateway/security) — 浏览器控制风险与加固
+- [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的浏览器控制
+- [安全性](/zh-CN/gateway/security) — 浏览器控制的风险与加固