Docs: update zh-CN translations and pipeline

What: - update zh-CN glossary, TM, and translator prompt - regenerate zh-CN docs and apply targeted fixes - add zh-CN AGENTS pipeline guidance Why: - address terminology/spacing feedback from #6995 Tests: - pnpm build && pnpm check && pnpm test
2026-06-28 21:01:43 +03:00 · 2026-02-03 13:23:00 -08:00
parent 9f03791aa9
commit a3ec2d0734
228 changed files with 10651 additions and 10475 deletions
@@ -1,11 +1,11 @@
 ---
 read_when:
-  - 在 iOS 节点或 macOS 上添加或修改相机捕获功能
+  - 在 iOS 节点或 macOS 上添加或修改相机捕获
  - 扩展智能体可访问的 MEDIA 临时文件工作流
-summary: 相机捕获（iOS 节点 + macOS 应用）供智能体使用：照片（jpg）和短视频片段（mp4）
+summary: 用于智能体的相机捕获（iOS 节点 + macOS 应用）：照片（jpg）和短视频片段（mp4）
 title: 相机捕获
 x-i18n:
-  generated_at: "2026-02-01T21:17:51Z"
+  generated_at: "2026-02-03T07:50:55Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: b4d5f5ecbab6f70597cf1e1f9cc5f7f54681253bd747442db16cc681203b5813
@@ -15,23 +15,23 @@ x-i18n:

 # 相机捕获（智能体）

-OpenClaw 支持智能体工作流中的**相机捕获**：
+OpenClaw 支持用于智能体工作流的**相机捕获**：

- **iOS 节点**（通过 Gateway网关配对）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
- **Android 节点**（通过 Gateway网关配对）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
- **macOS 应用**（通过 Gateway网关的节点）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
+- **iOS 节点**（通过 Gateway 网关配对）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
+- **Android 节点**（通过 Gateway 网关配对）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
+- **macOS 应用**（通过 Gateway 网关的节点）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。

-所有相机访问都受**用户控制的设置**保护。
+所有相机访问都受**用户控制的设置**限制。

 ## iOS 节点

 ### 用户设置（默认开启）

 - iOS 设置标签页 → **相机** → **允许相机**（`camera.enabled`）
-  - 默认：**开启**（缺少该键时视为已启用）。
+  - 默认：**开启**（缺少键时视为启用）。
  - 关闭时：`camera.*` 命令返回 `CAMERA_DISABLED`。

-### 命令（通过 Gateway网关 `node.invoke`）
+### 命令（通过 Gateway 网关 `node.invoke`）

 - `camera.list`
  - 响应载荷：
@@ -49,12 +49,12 @@ OpenClaw 支持智能体工作流中的**相机捕获**：
    - `format: "jpg"`
    - `base64: "<...>"`
    - `width`、`height`
-  - 载荷保护：照片会被重新压缩，以将 base64 载荷控制在 5 MB 以内。
+  - 载荷保护：照片会重新压缩以保持 base64 载荷小于 5 MB。

 - `camera.clip`
  - 参数：
    - `facing`：`front|back`（默认：`front`）
-    - `durationMs`：数字（默认 `3000`，上限为 `60000`）
+    - `durationMs`：数字（默认 `3000`，上限 `60000`）
    - `includeAudio`：布尔值（默认 `true`）
    - `format`：当前为 `mp4`
    - `deviceId`：字符串（可选；来自 `camera.list`）
@@ -66,16 +66,16 @@ OpenClaw 支持智能体工作流中的**相机捕获**：

 ### 前台要求

-与 `canvas.*` 类似，iOS 节点仅在**前台**允许 `camera.*` 命令。后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`。
+与 `canvas.*` 类似，iOS 节点仅允许在**前台**执行 `camera.*` 命令。后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`。

 ### CLI 辅助工具（临时文件 + MEDIA）

-获取附件最简单的方式是使用 CLI 辅助工具，它会将解码后的媒体写入临时文件并输出 `MEDIA:<path>`。
+获取附件最简单的方法是通过 CLI 辅助工具，它将解码的媒体写入临时文件并打印 `MEDIA:<path>`。

 示例：

 ```bash
-openclaw nodes camera snap --node <id>               # 默认：前后摄像头都拍摄（2 行 MEDIA 输出）
+openclaw nodes camera snap --node <id>               # default: both front + back (2 MEDIA lines)
 openclaw nodes camera snap --node <id> --facing front
 openclaw nodes camera clip --node <id> --duration 3000
 openclaw nodes camera clip --node <id> --no-audio
@@ -83,42 +83,42 @@ openclaw nodes camera clip --node <id> --no-audio

 注意事项：

- `nodes camera snap` 默认拍摄**两个**朝向，以便为智能体提供两个视角。
- 输出文件是临时的（位于操作系统临时目录中），除非你自行构建包装器。
+- `nodes camera snap` 默认拍摄**两个**方向以给智能体提供两个视角。
+- 输出文件是临时的（在操作系统临时目录中），除非你构建自己的包装器。

 ## Android 节点

 ### 用户设置（默认开启）

- Android 设置面板 → **相机** → **允许相机**（`camera.enabled`）
-  - 默认：**开启**（缺少该键时视为已启用）。
+- Android 设置页 → **相机** → **允许相机**（`camera.enabled`）
+  - 默认：**开启**（缺少键时视为启用）。
  - 关闭时：`camera.*` 命令返回 `CAMERA_DISABLED`。

 ### 权限

 - Android 需要运行时权限：
-  - `CAMERA`：用于 `camera.snap` 和 `camera.clip`。
-  - `RECORD_AUDIO`：用于 `includeAudio=true` 时的 `camera.clip`。
+  - `CAMERA` 用于 `camera.snap` 和 `camera.clip`。
+  - `RECORD_AUDIO` 用于 `includeAudio=true` 时的 `camera.clip`。

-如果缺少权限，应用会在可能时弹出提示；如果被拒绝，`camera.*` 请求将以 `*_PERMISSION_REQUIRED` 错误失败。
+如果缺少权限，应用会在可能时提示；如果被拒绝，`camera.*` 请求会失败并返回 `*_PERMISSION_REQUIRED` 错误。

 ### 前台要求

-与 `canvas.*` 类似，Android 节点仅在**前台**允许 `camera.*` 命令。后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`。
+与 `canvas.*` 类似，Android 节点仅允许在**前台**执行 `camera.*` 命令。后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`。

 ### 载荷保护

-照片会被重新压缩，以将 base64 载荷控制在 5 MB 以内。
+照片会重新压缩以保持 base64 载荷小于 5 MB。

 ## macOS 应用

 ### 用户设置（默认关闭）

-macOS 伴侣应用提供一个复选框：
+macOS 配套应用暴露一个复选框：

 - **设置 → 通用 → 允许相机**（`openclaw.cameraEnabled`）
  - 默认：**关闭**
-  - 关闭时：相机请求返回"Camera disabled by user"。
+  - 关闭时：相机请求返回"用户已禁用相机"。

 ### CLI 辅助工具（节点调用）

@@ -127,13 +127,13 @@ macOS 伴侣应用提供一个复选框：
 示例：

 ```bash
-openclaw nodes camera list --node <id>            # 列出相机 ID
-openclaw nodes camera snap --node <id>            # 输出 MEDIA:<path>
+openclaw nodes camera list --node <id>            # list camera ids
+openclaw nodes camera snap --node <id>            # prints MEDIA:<path>
 openclaw nodes camera snap --node <id> --max-width 1280
 openclaw nodes camera snap --node <id> --delay-ms 2000
 openclaw nodes camera snap --node <id> --device-id <id>
-openclaw nodes camera clip --node <id> --duration 10s          # 输出 MEDIA:<path>
-openclaw nodes camera clip --node <id> --duration-ms 3000      # 输出 MEDIA:<path>（旧版标志）
+openclaw nodes camera clip --node <id> --duration 10s          # prints MEDIA:<path>
+openclaw nodes camera clip --node <id> --duration-ms 3000      # prints MEDIA:<path> (legacy flag)
 openclaw nodes camera clip --node <id> --device-id <id>
 openclaw nodes camera clip --node <id> --no-audio
 ```
@@ -141,20 +141,20 @@ openclaw nodes camera clip --node <id> --no-audio
 注意事项：

 - `openclaw nodes camera snap` 默认 `maxWidth=1600`，除非被覆盖。
- 在 macOS 上，`camera.snap` 在预热/曝光稳定后等待 `delayMs`（默认 2000ms）再进行捕获。
- 照片载荷会被重新压缩，以将 base64 控制在 5 MB 以内。
+- 在 macOS 上，`camera.snap` 在预热/曝光稳定后等待 `delayMs`（默认 2000ms）再捕获。
+- 照片载荷会重新压缩以保持 base64 小于 5 MB。

 ## 安全性 + 实际限制

- 相机和麦克风访问会触发常规的操作系统权限提示（且需要在 Info.plist 中添加用途说明字符串）。
- 视频片段有长度上限（当前 `<= 60s`），以避免过大的节点载荷（base64 开销 + 消息大小限制）。
+- 相机和麦克风访问会触发通常的操作系统权限提示（并需要 Info.plist 中的使用说明字符串）。
+- 视频片段有上限（当前 `<= 60s`）以避免过大的节点载荷（base64 开销 + 消息限制）。

-## macOS 屏幕录制（操作系统级别）
+## macOS 屏幕视频（操作系统级别）

-如需*屏幕*录制（非相机），请使用 macOS 伴侣应用：
+对于*屏幕*视频（非相机），使用 macOS 配套应用：

 ```bash
-openclaw nodes screen record --node <id> --duration 10s --fps 15   # 输出 MEDIA:<path>
+openclaw nodes screen record --node <id> --duration 10s --fps 15   # prints MEDIA:<path>
 ```

 注意事项：
@@ -1,10 +1,10 @@
 ---
 read_when:
-  - 修改媒体处理管道或附件
-summary: 发送、Gateway网关和智能体回复的图片与媒体处理规则
-title: 图片与媒体支持
+  - 修改媒体管道或附件
+summary: 发送、Gateway 网关和智能体回复的图像和媒体处理规则
+title: 图像和媒体支持
 x-i18n:
-  generated_at: "2026-02-01T21:17:54Z"
+  generated_at: "2026-02-03T07:50:42Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 971aed398ea01078efbad7a8a4bca17f2a975222a2c4db557565e4334c9450e0
@@ -12,68 +12,68 @@ x-i18n:
  workflow: 15
 ---

-# 图片与媒体支持 — 2025-12-05
+# 图像与媒体支持 — 2025-12-05

-WhatsApp 渠道通过 **Baileys Web** 运行。本文档记录了发送、Gateway网关和智能体回复的当前媒体处理规则。
+WhatsApp 渠道通过 **Baileys Web** 运行。本文档记录了发送、Gateway 网关和智能体回复的当前媒体处理规则。

 ## 目标

- 通过 `openclaw message send --media` 发送带可选说明文字的媒体。
- 允许来自 Web 收件箱的自动回复在文本旁包含媒体。
+- 通过 `openclaw message send --media` 发送带可选标题的媒体。
+- 允许来自网页收件箱的自动回复在文本旁边包含媒体。
 - 保持每种类型的限制合理且可预测。

 ## CLI 接口

 - `openclaw message send --media <path-or-url> [--message <caption>]`
-  - `--media` 可选；说明文字可以为空，用于仅发送媒体。
-  - `--dry-run` 打印解析后的载荷；`--json` 输出 `{ channel, to, messageId, mediaUrl, caption }`。
+  - `--media` 可选；标题可以为空以进行纯媒体发送。
+  - `--dry-run` 打印解析后的负载；`--json` 输出 `{ channel, to, messageId, mediaUrl, caption }`。

 ## WhatsApp Web 渠道行为

 - 输入：本地文件路径**或** HTTP(S) URL。
- 流程：加载到 Buffer 中，检测媒体类型，并构建正确的载荷：
-  - **图片：** 调整大小并重新压缩为 JPEG（最大边 2048px），目标大小为 `agents.defaults.mediaMaxMb`（默认 5 MB），上限 6 MB。
-  - **音频/语音/视频：** 直通传输，上限 16 MB；音频作为语音消息发送（`ptt: true`）。
-  - **文档：** 其他所有类型，上限 100 MB，可用时保留文件名。
+- 流程：加载到 Buffer，检测媒体类型，并构建正确的负载：
+  - **图像：** 调整大小并重新压缩为 JPEG（最大边 2048px），目标为 `agents.defaults.mediaMaxMb`（默认 5 MB），上限 6 MB。
+  - **音频/语音/视频：** 直通最大 16 MB；音频作为语音消息发送（`ptt: true`）。
+  - **文档：** 其他任何内容，最大 100 MB，可用时保留文件名。
 - WhatsApp GIF 风格播放：发送带 `gifPlayback: true` 的 MP4（CLI：`--gif-playback`），使移动客户端内联循环播放。
- MIME 检测优先使用魔术字节，其次是请求头，最后是文件扩展名。
- 说明文字来自 `--message` 或 `reply.text`；允许空说明文字。
+- MIME 检测优先使用魔数字节，然后是头信息，最后是文件扩展名。
+- 标题来自 `--message` 或 `reply.text`；允许空标题。
 - 日志：非详细模式显示 `↩️`/`✅`；详细模式包含大小和源路径/URL。

 ## 自动回复管道

 - `getReplyFromConfig` 返回 `{ text?, mediaUrl?, mediaUrls? }`。
- 当存在媒体时，Web 发送器使用与 `openclaw message send` 相同的管道解析本地路径或 URL。
- 如果提供了多个媒体条目，则按顺序依次发送。
+- 当存在媒体时，网页发送器使用与 `openclaw message send` 相同的管道解析本地路径或 URL。
+- 如果提供多个媒体条目，则按顺序发送。

-## 入站媒体转命令 (Pi)
+## 入站媒体到命令（Pi）

- 当入站 Web 消息包含媒体时，OpenClaw 会下载到临时文件并暴露模板变量：
+- 当入站网页消息包含媒体时，OpenClaw 下载到临时文件并暴露模板变量：
  - `{{MediaUrl}}` 入站媒体的伪 URL。
  - `{{MediaPath}}` 运行命令前写入的本地临时路径。
- 当启用了每会话 Docker 沙箱时，入站媒体会被复制到沙箱工作区中，`MediaPath`/`MediaUrl` 会被重写为类似 `media/inbound/<filename>` 的相对路径。
+- 当启用每会话 Docker 沙箱时，入站媒体被复制到沙箱工作区，`MediaPath`/`MediaUrl` 被重写为相对路径如 `media/inbound/<filename>`。
 - 媒体理解（如果通过 `tools.media.*` 或共享的 `tools.media.models` 配置）在模板化之前运行，可以将 `[Image]`、`[Audio]` 和 `[Video]` 块插入 `Body`。
-  - 音频设置 `{{Transcript}}` 并使用转录文本进行命令解析，因此斜杠命令仍然有效。
-  - 视频和图片描述会保留说明文字用于命令解析。
- 默认仅处理第一个匹配的图片/音频/视频附件；设置 `tools.media.<cap>.attachments` 可处理多个附件。
+  - 音频设置 `{{Transcript}}` 并使用转录进行命令解析，因此斜杠命令仍然有效。
+  - 视频和图像描述保留任何标题文本用于命令解析。
+- 默认情况下只处理第一个匹配的图像/音频/视频附件；设置 `tools.media.<cap>.attachments` 以处理多个附件。

 ## 限制与错误

-**出站发送上限（WhatsApp Web 发送）**
+**出站发送上限（WhatsApp 网页发送）**

- 图片：重新压缩后约 6 MB 上限。
+- 图像：重新压缩后约 6 MB 上限。
 - 音频/语音/视频：16 MB 上限；文档：100 MB 上限。
- 超大或不可读的媒体 → 日志中显示明确错误，回复将被跳过。
+- 超大或无法读取的媒体 → 日志中有明确错误，回复被跳过。

 **媒体理解上限（转录/描述）**

- 图片默认：10 MB（`tools.media.image.maxBytes`）。
+- 图像默认：10 MB（`tools.media.image.maxBytes`）。
 - 音频默认：20 MB（`tools.media.audio.maxBytes`）。
 - 视频默认：50 MB（`tools.media.video.maxBytes`）。
- 超大媒体会跳过理解处理，但回复仍会以原始正文发送。
+- 超大媒体跳过理解，但回复仍然使用原始正文通过。

-## 测试注意事项
+## 测试说明

- 覆盖图片/音频/文档场景的发送 + 回复流程。
- 验证图片的重新压缩（大小限制）和音频的语音消息标志。
- 确保多媒体回复以顺序发送的方式展开。
+- 覆盖图像/音频/文档情况的发送 + 回复流程。
+- 验证图像的重新压缩（大小限制）和音频的语音消息标志。
+- 确保多媒体回复作为顺序发送扇出。
@@ -1,35 +1,36 @@
 ---
 read_when:
-  - 将 iOS/Android 节点配对到 Gateway网关
-  - 使用节点 canvas/相机为智能体提供上下文
-  - 添加新的节点命令或 CLI 辅助工具
-summary: 节点：配对、能力、权限，以及 canvas/相机/屏幕/系统的 CLI 辅助工具
+  - 将 iOS/Android 节点配对到 Gateway 网关时
+  - 使用节点 canvas/camera 为智能体提供上下文时
+  - 添加新的节点命令或 CLI 辅助工具时
+summary: 节点：配对、能力、权限以及 canvas/camera/screen/system 的 CLI 辅助工具
 title: 节点
 x-i18n:
-  generated_at: "2026-02-01T21:18:35Z"
+  generated_at: "2026-02-03T07:51:55Z"
  model: claude-opus-4-5
  provider: pi
-  source_hash: 7f7cc1934cfbb4176f0a7ce21371e51d9a9fb459dd73b8fce5a214b58877521f
+  source_hash: 74e9420f61c653e4ceeb00f5a27e4266bd1c7715c1000edd969c3ee185e74de9
  source_path: nodes/index.md
  workflow: 15
 ---

 # 节点

-**节点**是一个伴侣设备（macOS/iOS/Android/无头），通过 **WebSocket**（与操作员相同的端口）以 `role: "node"` 连接到 Gateway网关，并通过 `node.invoke` 暴露命令接口（例如 `canvas.*`、`camera.*`、`system.*`）。协议详情：[Gateway网关协议](/gateway/protocol)。
+**节点**是一个配套设备（macOS/iOS/Android/无头），它以 `role: "node"` 连接到 Gateway 网关 **WebSocket**（与操作员相同的端口），并通过 `node.invoke` 暴露命令接口（例如 `canvas.*`、`camera.*`、`system.*`）。协议详情：[Gateway 网关协议](/gateway/protocol)。

 旧版传输：[Bridge 协议](/gateway/bridge-protocol)（TCP JSONL；当前节点已弃用/移除）。

-macOS 也可以在**节点模式**下运行：菜单栏应用连接到 Gateway网关的 WS 服务器，并将其本地 canvas/相机命令作为节点暴露（因此 `openclaw nodes …` 可以对该 Mac 使用）。
+macOS 也可以在**节点模式**下运行：菜单栏应用连接到 Gateway 网关的 WS 服务器，并将其本地 canvas/camera 命令作为节点暴露（因此 `openclaw nodes …` 可以针对这台 Mac 工作）。

 注意事项：

- 节点是**外围设备**，不是 Gateway网关。它们不运行 Gateway网关服务。
- Telegram/WhatsApp 等消息到达的是 **Gateway网关**，而非节点。
+- 节点是**外围设备**，不是 Gateway 网关。它们不运行 Gateway 网关服务。
+- Telegram/WhatsApp 等消息落在 **Gateway 网关**上，而不是节点上。

 ## 配对 + 状态

-**WS 节点使用设备配对。** 节点在 `connect` 时提供设备身份；Gateway网关为 `role: node` 创建设备配对请求。通过设备 CLI（或 UI）审批。
+**WS 节点使用设备配对。** 节点在 `connect` 期间呈现设备身份；Gateway 网关
+为 `role: node` 创建设备配对请求。通过设备 CLI（或 UI）批准。

 快速 CLI：

@@ -43,18 +44,21 @@ openclaw nodes describe --node <idOrNameOrIp>

 注意事项：

- `nodes status` 在设备配对角色包含 `node` 时将节点标记为**已配对**。
- `node.pair.*`（CLI：`openclaw nodes pending/approve/reject`）是一个独立的 Gateway网关拥有的节点配对存储；它**不会**拦截 WS `connect` 握手。
+- 当节点的设备配对角色包含 `node` 时，`nodes status` 将节点标记为**已配对**。
+- `node.pair.*`（CLI：`openclaw nodes pending/approve/reject`）是一个单独的 Gateway 网关拥有的
+  节点配对存储；它**不会**限制 WS `connect` 握手。

 ## 远程节点主机（system.run）

-当你的 Gateway网关运行在一台机器上而你希望命令在另一台机器上执行时，使用**节点主机**。模型仍然与 **Gateway网关** 通信；当选择 `host=node` 时，Gateway网关将 `exec` 调用转发给**节点主机**。
+当你的 Gateway 网关在一台机器上运行而你希望命令
+在另一台机器上执行时，使用**节点主机**。模型仍然与 **Gateway 网关**通信；当选择 `host=node` 时，Gateway 网关
+将 `exec` 调用转发到**节点主机**。

-### 各部分运行位置
+### 什么在哪里运行

- **Gateway网关主机**：接收消息，运行模型，路由工具调用。
+- **Gateway 网关主机**：接收消息，运行模型，路由工具调用。
 - **节点主机**：在节点机器上执行 `system.run`/`system.which`。
- **审批**：通过节点主机上的 `~/.openclaw/exec-approvals.json` 执行。
+- **批准**：通过 `~/.openclaw/exec-approvals.json` 在节点主机上执行。

 ### 启动节点主机（前台）

@@ -64,6 +68,28 @@ openclaw nodes describe --node <idOrNameOrIp>
 openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"
 ```

+### 通过 SSH 隧道访问远程 Gateway 网关（loopback 绑定）
+
+如果 Gateway 网关绑定到 loopback（`gateway.bind=loopback`，本地模式下的默认值），
+远程节点主机无法直接连接。创建 SSH 隧道并将
+节点主机指向隧道的本地端。
+
+示例（节点主机 -> Gateway 网关主机）：
+
+```bash
+# 终端 A（保持运行）：转发本地 18790 -> Gateway 网关 127.0.0.1:18789
+ssh -N -L 18790:127.0.0.1:18789 user@gateway-host
+
+# 终端 B：导出 Gateway 网关令牌并通过隧道连接
+export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
+openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"
+```
+
+注意事项：
+
+- 令牌是 Gateway 网关配置中的 `gateway.auth.token`（Gateway 网关主机上的 `~/.openclaw/openclaw.json`）。
+- `openclaw node run` 读取 `OPENCLAW_GATEWAY_TOKEN` 进行认证。
+
 ### 启动节点主机（服务）

 ```bash
@@ -73,7 +99,7 @@ openclaw node restart

 ### 配对 + 命名

-在 Gateway网关主机上：
+在 Gateway 网关主机上：

 ```bash
 openclaw nodes pending
@@ -83,23 +109,23 @@ openclaw nodes list

 命名选项：

- 在 `openclaw node run` / `openclaw node install` 上使用 `--display-name`（持久保存在节点的 `~/.openclaw/node.json` 中）。
- `openclaw nodes rename --node <id|name|ip> --name "Build Node"`（Gateway网关覆盖）。
+- 在 `openclaw node run` / `openclaw node install` 上使用 `--display-name`（持久化在节点上的 `~/.openclaw/node.json` 中）。
+- `openclaw nodes rename --node <id|name|ip> --name "Build Node"`（Gateway 网关覆盖）。

 ### 将命令加入允许列表

-执行审批是**按节点主机**的。从 Gateway网关添加允许列表条目：
+Exec 批准是**每个节点主机**的。从 Gateway 网关添加允许列表条目：

 ```bash
 openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
 openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"
 ```

-审批存储在节点主机的 `~/.openclaw/exec-approvals.json` 中。
+批准存储在节点主机的 `~/.openclaw/exec-approvals.json` 中。

-### 将执行指向节点
+### 将 exec 指向节点

-配置默认值（Gateway网关配置）：
+配置默认值（Gateway 网关配置）：

 ```bash
 openclaw config set tools.exec.host node
@@ -107,35 +133,36 @@ openclaw config set tools.exec.security allowlist
 openclaw config set tools.exec.node "<id-or-name>"
 ```

-或按会话设置：
+或按会话：

 ```
 /exec host=node security=allowlist node=<id-or-name>
 ```

-设置后，任何 `host=node` 的 `exec` 调用都会在节点主机上运行（受节点允许列表/审批限制）。
+设置后，任何带有 `host=node` 的 `exec` 调用都会在节点主机上运行（受
+节点允许列表/批准约束）。

-相关链接：
+相关：

 - [节点主机 CLI](/cli/node)
 - [Exec 工具](/tools/exec)
- [Exec 审批](/tools/exec-approvals)
+- [Exec 批准](/tools/exec-approvals)

 ## 调用命令

-低级别（原始 RPC）：
+低级（原始 RPC）：

 ```bash
 openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'
 ```

-对于常见的"为智能体提供 MEDIA 附件"工作流，有更高级的辅助工具。
+对于常见的"给智能体一个 MEDIA 附件"工作流，存在更高级的辅助工具。

 ## 截图（canvas 快照）

 如果节点正在显示 Canvas（WebView），`canvas.snapshot` 返回 `{ format, base64 }`。

-CLI 辅助工具（写入临时文件并输出 `MEDIA:<path>`）：
+CLI 辅助工具（写入临时文件并打印 `MEDIA:<path>`）：

 ```bash
 openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
@@ -166,7 +193,7 @@ openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

 注意事项：

- 仅支持 A2UI v0.8 JSONL（v0.9/createSurface 会被拒绝）。
+- 仅支持 A2UI v0.8 JSONL（v0.9/createSurface 被拒绝）。

 ## 照片 + 视频（节点相机）

@@ -174,7 +201,7 @@ openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

 ```bash
 openclaw nodes camera list --node <idOrNameOrIp>
-openclaw nodes camera snap --node <idOrNameOrIp>            # 默认：两个朝向（2 行 MEDIA 输出）
+openclaw nodes camera snap --node <idOrNameOrIp>            # 默认：两个朝向（2 个 MEDIA 行）
 openclaw nodes camera snap --node <idOrNameOrIp> --facing front
 ```

@@ -187,9 +214,9 @@ openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

 注意事项：

- `canvas.*` 和 `camera.*` 要求节点处于**前台**（后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`）。
- 片段时长有上限（当前 `<= 60s`），以避免过大的 base64 载荷。
- Android 会在可能时提示 `CAMERA`/`RECORD_AUDIO` 权限；拒绝权限时以 `*_PERMISSION_REQUIRED` 失败。
+- 节点必须处于**前台**才能使用 `canvas.*` 和 `camera.*`（后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`）。
+- 片段时长被限制（当前 `<= 60s`）以避免过大的 base64 负载。
+- Android 会在可能时提示 `CAMERA`/`RECORD_AUDIO` 权限；权限被拒绝会以 `*_PERMISSION_REQUIRED` 失败。

 ## 屏幕录制（节点）

@@ -202,15 +229,15 @@ openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-

 注意事项：

- `screen.record` 要求节点应用处于前台。
+- `screen.record` 需要节点应用处于前台。
 - Android 会在录制前显示系统屏幕捕获提示。
- 屏幕录制上限为 `<= 60s`。
+- 屏幕录制被限制为 `<= 60s`。
 - `--no-audio` 禁用麦克风捕获（iOS/Android 支持；macOS 使用系统捕获音频）。
 - 当有多个屏幕可用时，使用 `--screen <index>` 选择显示器。

 ## 位置（节点）

-当设置中启用了位置功能时，节点暴露 `location.get`。
+当在设置中启用位置时，节点暴露 `location.get`。

 CLI 辅助工具：

@@ -221,15 +248,15 @@ openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 1

 注意事项：

- 位置功能**默认关闭**。
- "始终"需要系统权限；后台获取为尽力而为。
- 响应包含经纬度、精度（米）和时间戳。
+- 位置**默认关闭**。
+- "始终"需要系统权限；后台获取是尽力而为的。
+- 响应包括纬度/经度、精度（米）和时间戳。

 ## 短信（Android 节点）

 当用户授予 **SMS** 权限且设备支持电话功能时，Android 节点可以暴露 `sms.send`。

-低级别调用：
+低级调用：

 ```bash
 openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'
@@ -237,10 +264,10 @@ openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"

 注意事项：

- 必须在 Android 设备上接受权限提示后，该功能才会被广播。
+- 在能力被广播之前，必须在 Android 设备上接受权限提示。
 - 没有电话功能的纯 Wi-Fi 设备不会广播 `sms.send`。

-## 系统命令（节点主机 / Mac 节点）
+## 系统命令（节点主机 / mac 节点）

 macOS 节点暴露 `system.run`、`system.notify` 和 `system.execApprovals.get/set`。
 无头节点主机暴露 `system.run`、`system.which` 和 `system.execApprovals.get/set`。
@@ -249,24 +276,24 @@ macOS 节点暴露 `system.run`、`system.notify` 和 `system.execApprovals.get/

 ```bash
 openclaw nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
-openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway网关 ready"
+openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
 ```

 注意事项：

- `system.run` 在载荷中返回 stdout/stderr/退出码。
- `system.notify` 遵循 macOS 应用的通知权限状态。
+- `system.run` 在负载中返回 stdout/stderr/退出码。
+- `system.notify` 遵守 macOS 应用上的通知权限状态。
 - `system.run` 支持 `--cwd`、`--env KEY=VAL`、`--command-timeout` 和 `--needs-screen-recording`。
 - `system.notify` 支持 `--priority <passive|active|timeSensitive>` 和 `--delivery <system|overlay|auto>`。
- macOS 节点会丢弃 `PATH` 覆盖；无头节点主机仅在 `PATH` 前置于节点主机 PATH 时才接受。
- 在 macOS 节点模式下，`system.run` 受 macOS 应用中的执行审批限制（设置 → 执行审批）。
-  询问/允许列表/完全访问的行为与无头节点主机相同；拒绝的提示返回 `SYSTEM_RUN_DENIED`。
- 在无头节点主机上，`system.run` 受执行审批限制（`~/.openclaw/exec-approvals.json`）。
+- macOS 节点会丢弃 `PATH` 覆盖；无头节点主机仅在 `PATH` 前置到节点主机 PATH 时才接受它。
+- 在 macOS 节点模式下，`system.run` 受 macOS 应用中的 exec 批准限制（设置 → Exec 批准）。
+  Ask/allowlist/full 的行为与无头节点主机相同；被拒绝的提示返回 `SYSTEM_RUN_DENIED`。
+- 在无头节点主机上，`system.run` 受 exec 批准限制（`~/.openclaw/exec-approvals.json`）。

 ## Exec 节点绑定

 当有多个节点可用时，你可以将 exec 绑定到特定节点。
-这会设置 `exec host=node` 的默认节点（可以按智能体覆盖）。
+这设置了 `exec host=node` 的默认节点（可以按智能体覆盖）。

 全局默认：

@@ -281,7 +308,7 @@ openclaw config get agents.list
 openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
 ```

-取消设置以允许任意节点：
+取消设置以允许任何节点：

 ```bash
 openclaw config unset tools.exec.node
@@ -290,13 +317,15 @@ openclaw config unset agents.list[0].tools.exec.node

 ## 权限映射

-节点可能在 `node.list` / `node.describe` 中包含 `permissions` 映射，以权限名称为键（例如 `screenRecording`、`accessibility`），布尔值为值（`true` = 已授予）。
+节点可能在 `node.list` / `node.describe` 中包含 `permissions` 映射，按权限名称（例如 `screenRecording`、`accessibility`）键入，值为布尔值（`true` = 已授予）。

 ## 无头节点主机（跨平台）

-OpenClaw 可以运行**无头节点主机**（无 UI），它连接到 Gateway网关 WebSocket 并暴露 `system.run` / `system.which`。这适用于 Linux/Windows 或在服务器旁运行一个最小节点。
+OpenClaw 可以运行**无头节点主机**（无 UI），它连接到 Gateway 网关
+WebSocket 并暴露 `system.run` / `system.which`。这在 Linux/Windows
+上或在服务器旁运行最小节点时很有用。

-启动方式：
+启动它：

 ```bash
 openclaw node run --host <gateway-host> --port 18789
@@ -304,13 +333,16 @@ openclaw node run --host <gateway-host> --port 18789

 注意事项：

- 仍然需要配对（Gateway网关会显示节点审批提示）。
- 节点主机将其节点 ID、令牌、显示名称和 Gateway网关连接信息存储在 `~/.openclaw/node.json` 中。
- 执行审批通过 `~/.openclaw/exec-approvals.json` 在本地执行（参见[执行审批](/tools/exec-approvals)）。
- 在 macOS 上，无头节点主机在伴侣应用执行主机可达时优先使用它，不可用时回退到本地执行。设置 `OPENCLAW_NODE_EXEC_HOST=app` 以要求使用应用，或设置 `OPENCLAW_NODE_EXEC_FALLBACK=0` 以禁用回退。
- 当 Gateway网关 WS 使用 TLS 时，添加 `--tls` / `--tls-fingerprint`。
+- 仍然需要配对（Gateway 网关会显示节点批准提示）。
+- 节点主机将其节点 id、令牌、显示名称和 Gateway 网关连接信息存储在 `~/.openclaw/node.json` 中。
+- Exec 批准通过 `~/.openclaw/exec-approvals.json` 在本地执行
+  （参见 [Exec 批准](/tools/exec-approvals)）。
+- 在 macOS 上，当配套应用 exec 主机可达时，无头节点主机优先使用它，
+  如果应用不可用则回退到本地执行。设置 `OPENCLAW_NODE_EXEC_HOST=app` 要求
+  使用应用，或设置 `OPENCLAW_NODE_EXEC_FALLBACK=0` 禁用回退。
+- 当 Gateway 网关 WS 使用 TLS 时，添加 `--tls` / `--tls-fingerprint`。

 ## Mac 节点模式

- macOS 菜单栏应用作为节点连接到 Gateway网关 WS 服务器（因此 `openclaw nodes …` 可以对该 Mac 使用）。
- 在远程模式下，应用为 Gateway网关端口打开 SSH 隧道并连接到 `localhost`。
+- macOS 菜单栏应用作为节点连接到 Gateway 网关 WS 服务器（因此 `openclaw nodes …` 可以针对这台 Mac 工作）。
+- 在远程模式下，应用为 Gateway 网关端口打开 SSH 隧道并连接到 `localhost`。
@@ -1,11 +1,11 @@
 ---
 read_when:
-  - 添加位置节点支持或权限界面
+  - 添加位置节点支持或权限 UI
  - 设计后台位置 + 推送流程
 summary: 节点的位置命令（location.get）、权限模式和后台行为
 title: 位置命令
 x-i18n:
-  generated_at: "2026-02-01T21:18:11Z"
+  generated_at: "2026-02-03T07:50:59Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 23124096256384d2b28157352b072309c61c970a20e009aac5ce4a8250dc3764
@@ -15,22 +15,22 @@ x-i18n:

 # 位置命令（节点）

-## 简要说明
+## 简要概述

 - `location.get` 是一个节点命令（通过 `node.invoke`）。
 - 默认关闭。
 - 设置使用选择器：关闭 / 使用时 / 始终。
 - 单独的开关：精确位置。

-## 为什么用选择器（而不是简单开关）
+## 为什么用选择器（而不只是开关）

-操作系统权限是多级的。我们可以在应用内提供选择器，但实际授权由操作系统决定。
+操作系统权限是多级的。我们可以在应用内暴露选择器，但操作系统仍然决定实际授权。

 - iOS/macOS：用户可以在系统提示/设置中选择**使用时**或**始终**。应用可以请求升级，但操作系统可能要求进入设置。
- Android：后台位置是独立的权限；在 Android 10+ 上通常需要进入设置流程。
- 精确位置是独立的授权（iOS 14+ "精确"，Android "精确" vs "粗略"）。
+- Android：后台位置是单独的权限；在 Android 10+ 上通常需要进入设置流程。
+- 精确位置是单独的授权（iOS 14+ "精确"，Android "精细" vs "粗略"）。

-界面中的选择器驱动我们请求的模式；实际授权存储在操作系统设置中。
+UI 中的选择器驱动我们请求的模式；实际授权存在于操作系统设置中。

 ## 设置模型

@@ -39,15 +39,15 @@ x-i18n:
 - `location.enabledMode`：`off | whileUsing | always`
 - `location.preciseEnabled`：bool

-界面行为：
+UI 行为：

 - 选择 `whileUsing` 请求前台权限。
- 选择 `always` 首先确保 `whileUsing`，然后请求后台权限（如果需要则引导用户进入设置）。
- 如果操作系统拒绝请求的级别，则回退到已授予的最高级别并显示状态。
+- 选择 `always` 首先确保 `whileUsing`，然后请求后台（或在需要时将用户引导到设置）。
+- 如果操作系统拒绝请求的级别，回退到已授予的最高级别并显示状态。

 ## 权限映射（node.permissions）

-可选。macOS 节点通过权限映射报告 `location`；iOS/Android 可能省略。
+可选。macOS 节点通过权限映射报告 `location`；iOS/Android 可能省略它。

 ## 命令：`location.get`

@@ -63,7 +63,7 @@ x-i18n:
 }
 ```

-响应载荷：
+响应负载：

 ```json
 {
@@ -79,42 +79,42 @@ x-i18n:
 }
 ```

-错误（稳定错误码）：
+错误（稳定代码）：

- `LOCATION_DISABLED`：选择器为关闭状态。
- `LOCATION_PERMISSION_REQUIRED`：缺少请求模式所需的权限。
- `LOCATION_BACKGROUND_UNAVAILABLE`：应用在后台运行但仅允许"使用时"。
- `LOCATION_TIMEOUT`：未在规定时间内获取定位。
- `LOCATION_UNAVAILABLE`：系统故障 / 无可用提供者。
+- `LOCATION_DISABLED`：选择器已关闭。
+- `LOCATION_PERMISSION_REQUIRED`：缺少请求模式的权限。
+- `LOCATION_BACKGROUND_UNAVAILABLE`：应用在后台但只允许使用时。
+- `LOCATION_TIMEOUT`：在时间内没有定位。
+- `LOCATION_UNAVAILABLE`：系统故障/没有提供商。

 ## 后台行为（未来）

-目标：即使节点在后台，模型也能请求位置，但仅在以下条件满足时：
+目标：模型可以在节点处于后台时请求位置，但仅当：

 - 用户选择了**始终**。
- 操作系统授予了后台位置权限。
- 应用被允许在后台运行位置服务（iOS 后台模式 / Android 前台服务或特殊许可）。
+- 操作系统授予后台位置权限。
+- 应用被允许在后台运行以获取位置（iOS 后台模式/Android 前台服务或特殊许可）。

 推送触发流程（未来）：

-1. Gateway网关向节点发送推送（静默推送或 FCM 数据）。
-2. 节点短暂唤醒并向设备请求位置。
-3. 节点将载荷转发给 Gateway网关。
+1. Gateway 网关向节点发送推送（静默推送或 FCM 数据）。
+2. 节点短暂唤醒并从设备请求位置。
+3. 节点将负载转发给 Gateway 网关。

-注意事项：
+说明：

- iOS：需要"始终"权限 + 后台位置模式。静默推送可能被限流；预期会有间歇性失败。
+- iOS：需要始终权限 + 后台位置模式。静默推送可能被限流；预期会有间歇性失败。
 - Android：后台位置可能需要前台服务；否则预期会被拒绝。

 ## 模型/工具集成

 - 工具接口：`nodes` 工具添加 `location_get` 操作（需要节点）。
 - CLI：`openclaw nodes location get --node <id>`。
- 智能体指南：仅在用户启用位置并了解范围时调用。
+- 智能体指南：仅在用户启用位置并理解范围时调用。

-## 界面文案（建议）
+## UX 文案（建议）

 - 关闭："位置共享已禁用。"
- 使用时："仅在 OpenClaw 打开时共享。"
- 始终："允许后台定位。需要系统权限。"
- 精确："使用精确 GPS 定位。关闭后将共享大致位置。"
+- 使用时："仅当 OpenClaw 打开时。"
+- 始终："允许后台位置。需要系统权限。"
+- 精确："使用精确 GPS 位置。关闭以共享大致位置。"
@@ -1,11 +1,11 @@
 ---
 read_when:
-  - 设计或重构媒体理解功能
+  - 设计或重构媒体理解
  - 调优入站音频/视频/图片预处理
-summary: 入站图片/音频/视频理解（可选），支持提供商 + CLI 回退
+summary: 入站图片/音频/视频理解（可选），带提供商 + CLI 回退
 title: 媒体理解
 x-i18n:
-  generated_at: "2026-02-01T21:18:50Z"
+  generated_at: "2026-02-03T07:51:40Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: f6c575662b7fcbf0b62c46e3fdfa4cdb7cfd455513097e4a2cdec8a34cbdbd48
@@ -13,42 +13,42 @@ x-i18n:
  workflow: 15
 ---

-# 媒体理解（入站） — 2026-01-17
+# 媒体理解（入站）— 2026-01-17

-OpenClaw 可以在回复管道运行之前**总结入站媒体**（图片/音频/视频）。它会在本地工具或提供商密钥可用时自动检测，也可以禁用或自定义。如果理解功能关闭，模型仍会照常接收原始文件/URL。
+OpenClaw 可以在回复流程运行之前**摘要入站媒体**（图片/音频/视频）。它会自动检测本地工具或提供商密钥是否可用，并且可以禁用或自定义。如果理解关闭，模型仍然会像往常一样接收原始文件/URL。

 ## 目标

- 可选：将入站媒体预处理为简短文本，以加快路由 + 改善命令解析。
- 始终保留原始媒体向模型的传递。
+- 可选：将入站媒体预先消化为短文本，以便更快路由 + 更好的命令解析。
+- 保留原始媒体传递给模型（始终）。
 - 支持**提供商 API** 和 **CLI 回退**。
- 允许多个模型按顺序回退（错误/大小/超时）。
+- 允许多个模型并按顺序回退（错误/大小/超时）。

 ## 高层行为

 1. 收集入站附件（`MediaPaths`、`MediaUrls`、`MediaTypes`）。
-2. 对每个已启用的能力（图片/音频/视频），按策略选择附件（默认：**第一个**）。
+2. 对于每个启用的能力（图片/音频/视频），根据策略选择附件（默认：**第一个**）。
 3. 选择第一个符合条件的模型条目（大小 + 能力 + 认证）。
-4. 如果模型失败或媒体过大，**回退到下一个条目**。
+4. 如果模型失败或媒体太大，**回退到下一个条目**。
 5. 成功时：
   - `Body` 变为 `[Image]`、`[Audio]` 或 `[Video]` 块。
-   - 音频设置 `{{Transcript}}`；命令解析在有说明文字时使用说明文字，否则使用转录文本。
-   - 说明文字作为 `User text:` 保留在块内。
+   - 音频设置 `{{Transcript}}`；命令解析在有标题文本时使用标题文本，否则使用转录。
+   - 标题作为 `User text:` 保留在块内。

-如果理解失败或已禁用，**回复流程继续**使用原始正文 + 附件。
+如果理解失败或被禁用，**回复流程继续**使用原始正文 + 附件。

-## 配置概览
+## 配置概述

-`tools.media` 支持**共享模型**加每能力覆盖：
+`tools.media` 支持**共享模型**加上每能力覆盖：

- `tools.media.models`：共享模型列表（使用 `capabilities` 进行能力筛选）。
+- `tools.media.models`：共享模型列表（使用 `capabilities` 来限定）。
 - `tools.media.image` / `tools.media.audio` / `tools.media.video`：
  - 默认值（`prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`）
  - 提供商覆盖（`baseUrl`、`headers`、`providerOptions`）
-  - Deepgram 音频选项通过 `tools.media.audio.providerOptions.deepgram` 设置
+  - 通过 `tools.media.audio.providerOptions.deepgram` 配置 Deepgram 音频选项
  - 可选的**每能力 `models` 列表**（优先于共享模型）
  - `attachments` 策略（`mode`、`maxAttachments`、`prefer`）
-  - `scope`（可选，按渠道/聊天类型/会话键筛选）
+  - `scope`（可选的按渠道/聊天类型/会话键限定）
 - `tools.media.concurrency`：最大并发能力运行数（默认 **2**）。

 ```json5
@@ -74,7 +74,7 @@ OpenClaw 可以在回复管道运行之前**总结入站媒体**（图片/音频

 ### 模型条目

-每个 `models[]` 条目可以是**提供商**或 **CLI** 类型：
+每个 `models[]` 条目可以是**提供商**或 **CLI**：

 ```json5
 {
@@ -119,8 +119,8 @@ CLI 模板还可以使用：

 推荐默认值：

- `maxChars`：图片/视频为 **500**（简短，适合命令解析）
- `maxChars`：音频**未设置**（完整转录，除非你设置限制）
+- `maxChars`：图片/视频为 **500**（简短，适合命令）
+- `maxChars`：音频**不设置**（完整转录，除非你设置限制）
 - `maxBytes`：
  - 图片：**10MB**
  - 音频：**20MB**
@@ -129,17 +129,17 @@ CLI 模板还可以使用：
 规则：

 - 如果媒体超过 `maxBytes`，该模型被跳过，**尝试下一个模型**。
- 如果模型返回超过 `maxChars`，输出会被裁剪。
- `prompt` 默认为简单的"描述该 {媒体}。"加上 `maxChars` 指导（仅图片/视频）。
- 如果 `<capability>.enabled: true` 但未配置模型，OpenClaw 会在其提供商支持该能力时尝试**当前回复模型**。
+- 如果模型返回超过 `maxChars`，输出被截断。
+- `prompt` 默认为简单的"Describe the {media}."加上 `maxChars` 指导（仅图片/视频）。
+- 如果 `<capability>.enabled: true` 但未配置模型，当提供商支持该能力时，OpenClaw 尝试**活动的回复模型**。

 ### 自动检测媒体理解（默认）

-如果 `tools.media.<capability>.enabled` **未**设置为 `false` 且你未配置模型，OpenClaw 会按以下顺序自动检测，并在**找到第一个可用选项时停止**：
+如果 `tools.media.<capability>.enabled` **未**设置为 `false` 且你没有配置模型，OpenClaw 按以下顺序自动检测并**在第一个可用选项处停止**：

-1. **本地 CLI**（仅音频；如已安装）
-   - `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR` 包含 encoder/decoder/joiner/tokens）
-   - `whisper-cli`（`whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置的 tiny 模型）
+1. **本地 CLI**（仅音频；如果已安装）
+   - `sherpa-onnx-offline`（需要带有 encoder/decoder/joiner/tokens 的 `SHERPA_ONNX_MODEL_DIR`）
+   - `whisper-cli`（`whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或捆绑的 tiny 模型）
   - `whisper`（Python CLI；自动下载模型）
 2. **Gemini CLI**（`gemini`）使用 `read_many_files`
 3. **提供商密钥**
@@ -147,7 +147,7 @@ CLI 模板还可以使用：
   - 图片：OpenAI → Anthropic → Google → MiniMax
   - 视频：Google

-要禁用自动检测，请设置：
+要禁用自动检测，设置：

 ```json5
 {
@@ -161,25 +161,24 @@ CLI 模板还可以使用：
 }
 ```

-注意：二进制检测在 macOS/Linux/Windows 上采用尽力而为的方式；请确保 CLI 在 `PATH` 中（我们会展开 `~`），或通过完整命令路径设置显式 CLI 模型。
+注意：二进制文件检测在 macOS/Linux/Windows 上是尽力而为的；确保 CLI 在 `PATH` 上（我们会展开 `~`），或设置带有完整命令路径的显式 CLI 模型。

 ## 能力（可选）

-如果你设置了 `capabilities`，该条目仅针对指定的媒体类型运行。对于共享列表，OpenClaw 可以推断默认值：
+如果你设置了 `capabilities`，该条目仅对这些媒体类型运行。对于共享列表，OpenClaw 可以推断默认值：

 - `openai`、`anthropic`、`minimax`：**图片**
 - `google`（Gemini API）：**图片 + 音频 + 视频**
 - `groq`：**音频**
 - `deepgram`：**音频**

-对于 CLI 条目，**请显式设置 `capabilities`** 以避免意外匹配。
-如果省略 `capabilities`，该条目对其所在列表中的所有类型均有效。
+对于 CLI 条目，**显式设置 `capabilities`** 以避免意外匹配。如果你省略 `capabilities`，该条目对它出现的列表都符合条件。

 ## 提供商支持矩阵（OpenClaw 集成）

 | 能力 | 提供商集成                                     | 说明                                    |
 | ---- | ---------------------------------------------- | --------------------------------------- |
-| 图片 | OpenAI / Anthropic / Google / 其他通过 `pi-ai` | 注册表中任何支持图片的模型均可使用。    |
+| 图片 | OpenAI / Anthropic / Google / 其他通过 `pi-ai` | 注册表中任何支持图片的模型都可用。      |
 | 音频 | OpenAI、Groq、Deepgram、Google                 | 提供商转录（Whisper/Deepgram/Gemini）。 |
 | 视频 | Google（Gemini API）                           | 提供商视频理解。                        |

@@ -187,8 +186,8 @@ CLI 模板还可以使用：

 **图片**

- 如果当前模型支持图片，优先使用当前模型。
- 推荐默认值：`openai/gpt-5.2`、`anthropic/claude-opus-4-5`、`google/gemini-3-pro-preview`。
+- 如果支持图片，优先使用你的活动模型。
+- 良好的默认值：`openai/gpt-5.2`、`anthropic/claude-opus-4-5`、`google/gemini-3-pro-preview`。

 **音频**

@@ -206,7 +205,7 @@ CLI 模板还可以使用：
 每能力的 `attachments` 控制处理哪些附件：

 - `mode`：`first`（默认）或 `all`
- `maxAttachments`：处理数量上限（默认 **1**）
+- `maxAttachments`：限制处理数量（默认 **1**）
 - `prefer`：`first`、`last`、`path`、`url`

 当 `mode: "all"` 时，输出标记为 `[Image 1/2]`、`[Audio 2/2]` 等。
@@ -367,15 +366,15 @@ CLI 模板还可以使用：
 📎 Media: image ok (openai/gpt-5.2) · audio skipped (maxBytes)
 ```

-这显示了每个能力的结果以及适用时选择的提供商/模型。
+这显示每能力的结果以及适用时选择的提供商/模型。

 ## 注意事项

- 理解是**尽力而为**的。错误不会阻塞回复。
- 即使理解功能禁用，附件仍会传递给模型。
- 使用 `scope` 限制理解功能的运行范围（例如仅私聊）。
+- 理解是**尽力而为**的。错误不会阻止回复。
+- 即使理解被禁用，附件仍然传递给模型。
+- 使用 `scope` 限制理解运行的位置（例如仅私信）。

 ## 相关文档

 - [配置](/gateway/configuration)
- [图片与媒体支持](/nodes/images)
+- [图片和媒体支持](/nodes/images)
@@ -1,11 +1,11 @@
 ---
 read_when:
-  - 在 macOS/iOS/Android 上实现对话模式
-  - 更改语音/TTS/打断行为
-summary: 对话模式：使用 ElevenLabs TTS 进行连续语音对话
-title: 对话模式
+  - 在 macOS/iOS/Android 上实现 Talk 模式
+  - 更改语音/TTS/中断行为
+summary: Talk 模式：使用 ElevenLabs TTS 进行连续语音对话
+title: Talk 模式
 x-i18n:
-  generated_at: "2026-02-01T21:18:51Z"
+  generated_at: "2026-02-03T10:07:59Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: ecbc3701c9e9502970cf13227fedbc9714d13668d8f4f3988fef2a4d68116a42
@@ -13,22 +13,22 @@ x-i18n:
  workflow: 15
 ---

-# 对话模式
+# Talk 模式

-对话模式是一个连续的语音对话循环：
+Talk 模式是一个连续的语音对话循环：

 1. 监听语音
-2. 将转录文本发送给模型（主会话，chat.send）
+2. 将转录文本发送到模型（main 会话，chat.send）
 3. 等待响应
 4. 通过 ElevenLabs 朗读（流式播放）

 ## 行为（macOS）

- 启用对话模式时显示**常驻悬浮窗**。
- **监听 → 思考 → 朗读**阶段切换。
- **短暂停顿**（静音窗口）后，当前转录文本会被发送。
- 回复会**写入 WebChat**（与打字相同）。
- **语音打断**（默认开启）：如果用户在助手朗读时开始说话，会停止播放并记录打断时间戳用于下一次提示。
+- Talk 模式启用时显示**常驻悬浮窗**。
+- **监听 → 思考 → 朗读**阶段转换。
+- **短暂停顿**（静音窗口）后，当前转录文本被发送。
+- 回复被**写入 WebChat**（与打字相同）。
+- **语音中断**（默认开启）：如果用户在助手朗读时开始说话，我们会停止播放并记录中断时间戳供下一个提示使用。

 ## 回复中的语音指令

@@ -40,10 +40,10 @@ x-i18n:

 规则：

- 仅限第一个非空行。
+- 仅适用于第一个非空行。
 - 未知键会被忽略。
- `once: true` 仅应用于当前回复。
- 不带 `once` 时，该语音将成为对话模式的新默认语音。
+- `once: true` 仅适用于当前回复。
+- 没有 `once` 时，该语音成为 Talk 模式的新默认值。
 - JSON 行在 TTS 播放前会被移除。

 支持的键：
@@ -71,27 +71,27 @@ x-i18n:
 默认值：

 - `interruptOnSpeech`：true
- `voiceId`：回退到 `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID`（或在 API 密钥可用时使用第一个 ElevenLabs 语音）
+- `voiceId`：回退到 `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID`（或当 API 密钥可用时使用第一个 ElevenLabs 语音）
 - `modelId`：未设置时默认为 `eleven_v3`
- `apiKey`：回退到 `ELEVENLABS_API_KEY`（或 Gateway网关 shell 配置文件，如可用）
- `outputFormat`：macOS/iOS 默认为 `pcm_44100`，Android 默认为 `pcm_24000`（设置 `mp3_*` 以强制 MP3 流式传输）
+- `apiKey`：回退到 `ELEVENLABS_API_KEY`（或 Gateway 网关 shell profile（如果可用））
+- `outputFormat`：macOS/iOS 上默认为 `pcm_44100`，Android 上默认为 `pcm_24000`（设置 `mp3_*` 以强制 MP3 流式传输）

 ## macOS UI

 - 菜单栏切换：**Talk**
- 配置标签页：**Talk Mode** 组（语音 ID + 打断开关）
+- 配置标签页：**Talk Mode** 组（voice id + 中断开关）
 - 悬浮窗：
-  - **监听中**：云朵随麦克风音量脉动
-  - **思考中**：下沉动画
-  - **朗读中**：辐射圆环
+  - **监听**：云朵随麦克风电平脉动
+  - **思考**：下沉动画
+  - **朗读**：辐射圆环
  - 点击云朵：停止朗读
-  - 点击 X：退出对话模式
+  - 点击 X：退出 Talk 模式

 ## 注意事项

- 需要语音识别 + 麦克风权限。
- 使用 `chat.send` 对会话键 `main` 发送。
- TTS 使用 ElevenLabs 流式 API，配合 `ELEVENLABS_API_KEY`，在 macOS/iOS/Android 上进行增量播放以降低延迟。
- `eleven_v3` 的 `stability` 验证值为 `0.0`、`0.5` 或 `1.0`；其他模型接受 `0..1`。
- `latency_tier` 设置时验证值为 `0..4`。
+- 需要语音 + 麦克风权限。
+- 使用 `chat.send` 针对会话键 `main`。
+- TTS 使用带有 `ELEVENLABS_API_KEY` 的 ElevenLabs 流式 API，并在 macOS/iOS/Android 上进行增量播放以降低延迟。
+- `eleven_v3` 的 `stability` 验证为 `0.0`、`0.5` 或 `1.0`；其他模型接受 `0..1`。
+- 设置时 `latency_tier` 验证为 `0..4`。
 - Android 支持 `pcm_16000`、`pcm_22050`、`pcm_24000` 和 `pcm_44100` 输出格式，用于低延迟 AudioTrack 流式传输。
@@ -2,10 +2,10 @@
 read_when:
  - 更改语音唤醒词行为或默认值
  - 添加需要唤醒词同步的新节点平台
-summary: 全局语音唤醒词（Gateway网关拥有）及其在节点间的同步方式
+summary: 全局语音唤醒词（Gateway 网关拥有）及其如何跨节点同步
 title: 语音唤醒
 x-i18n:
-  generated_at: "2026-02-01T21:19:01Z"
+  generated_at: "2026-02-03T07:51:10Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: eb34f52dfcdc3fc1ae088ae1f621f245546d3cf388299fbeea62face61788c37
@@ -15,15 +15,15 @@ x-i18n:

 # 语音唤醒（全局唤醒词）

-OpenClaw 将**唤醒词视为由 Gateway网关拥有的单一全局列表**。
+OpenClaw 将**唤醒词作为单一全局列表**，由 **Gateway 网关**拥有。

- **没有按节点自定义的唤醒词**。
- **任何节点/应用界面均可编辑**该列表；更改由 Gateway网关持久化并广播给所有人。
- 每个设备仍保留自己的**语音唤醒 启用/禁用**开关（本地用户体验和权限各异）。
+- **没有**每节点的自定义唤醒词。
+- **任何节点/应用 UI 都可以编辑**列表；更改由 Gateway 网关持久化并广播给所有人。
+- 每个设备仍保留自己的**语音唤醒启用/禁用**开关（本地用户体验 + 权限不同）。

-## 存储（Gateway网关主机）
+## 存储（Gateway 网关主机）

-唤醒词存储在 Gateway网关机器上：
+唤醒词存储在 Gateway 网关机器上：

 - `~/.openclaw/settings/voicewake.json`

@@ -40,33 +40,33 @@ OpenClaw 将**唤醒词视为由 Gateway网关拥有的单一全局列表**。
 - `voicewake.get` → `{ triggers: string[] }`
 - `voicewake.set`，参数 `{ triggers: string[] }` → `{ triggers: string[] }`

-说明：
+注意事项：

- 触发词会被规范化（去除空白、丢弃空值）。空列表会回退到默认值。
- 出于安全考虑，会强制执行限制（数量/长度上限）。
+- 触发词会被规范化（修剪空格、删除空值）。空列表回退到默认值。
+- 为安全起见会强制执行限制（数量/长度上限）。

 ### 事件

 - `voicewake.changed` 载荷 `{ triggers: string[] }`

-接收方：
+接收者：

 - 所有 WebSocket 客户端（macOS 应用、WebChat 等）
- 所有已连接的节点（iOS/Android），节点连接时也会作为初始"当前状态"推送。
+- 所有已连接的节点（iOS/Android），以及节点连接时作为初始"当前状态"推送。

 ## 客户端行为

 ### macOS 应用

- 使用全局列表来控制 `VoiceWakeRuntime` 触发词。
+- 使用全局列表来控制 `VoiceWakeRuntime` 触发器。
 - 在语音唤醒设置中编辑"触发词"会调用 `voicewake.set`，然后依赖广播保持其他客户端同步。

 ### iOS 节点

- 使用全局列表进行 `VoiceWakeManager` 触发词检测。
- 在设置中编辑唤醒词会调用 `voicewake.set`（通过 Gateway网关 WS），同时保持本地唤醒词检测的即时响应。
+- 使用全局列表进行 `VoiceWakeManager` 触发检测。
+- 在设置中编辑唤醒词会调用 `voicewake.set`（通过 Gateway 网关 WS），同时保持本地唤醒词检测的响应性。

 ### Android 节点

- 在设置中提供唤醒词编辑器。
- 通过 Gateway网关 WS 调用 `voicewake.set`，使编辑在所有设备间同步。
+- 在设置中暴露唤醒词编辑器。
+- 通过 Gateway 网关 WS 调用 `voicewake.set`，使编辑在所有地方同步。