chore(i18n): refresh zh-CN translations

2026-04-30 04:08:26 +00:00 · 2026-04-30 04:08:26 +00:00 · e3eee552cd
commit e3eee552cd
parent 653ca8d0f9
2 changed files with 169 additions and 161 deletions
--- a/docs/zh-CN/nodes/index.md
+++ b/docs/zh-CN/nodes/index.md
@ -1,36 +1,37 @@
 ---
 read_when:
-    - 将 iOS/Android 节点与 Gateway 网关配对
-    - 将节点画布/摄像头用于智能体上下文
-    - 添加新的 node 命令或 CLI 辅助工具
-summary: 节点：画布/摄像头/屏幕/设备/通知/系统的配对、能力、权限和 CLI 辅助工具
+    - 将 iOS/Android 节点配对到 Gateway 网关
+    - 使用节点画布/摄像头作为智能体上下文
+    - 添加新的 Node 命令或 CLI 辅助工具
+summary: 节点：用于画布/摄像头/屏幕/设备/通知/系统的配对、能力、权限和 CLI 辅助工具
 title: 节点
 x-i18n:
-    generated_at: "2026-04-28T11:57:25Z"
+    generated_at: "2026-04-30T04:07:28Z"
    model: gpt-5.5
    provider: openai
-    source_hash: fbe9fdeb21173a32f284810d0bd1e9219932ce7c74fdcbc8b5b197f2647659e8
+    source_hash: 060319f540fe3c4d168516df8cced9caad26d9281592c9a9537ab6df393dce43
    source_path: nodes/index.md
    workflow: 16
 ---

-**节点**是一台连接到 Gateway 网关 **WebSocket**（与操作者使用同一端口）的配套设备（macOS/iOS/Android/headless），它使用 `role: "node"`，并通过 `node.invoke` 暴露命令接口（例如 `canvas.*`、`camera.*`、`device.*`、`notifications.*`、`system.*`）。协议详情：[Gateway 网关协议](/zh-CN/gateway/protocol)。
+**节点** 是一种配套设备（macOS/iOS/Android/无头设备），它会使用 `role: "node"` 连接到 Gateway 网关 **WebSocket**（与操作者使用同一端口），并通过 `node.invoke` 暴露命令表面（例如 `canvas.*`、`camera.*`、`device.*`、`notifications.*`、`system.*`）。协议详情：[Gateway 网关协议](/zh-CN/gateway/protocol)。

-旧版传输：[Bridge protocol](/zh-CN/gateway/bridge-protocol)（TCP JSONL；
-仅作为当前节点的历史参考）。
+旧版传输协议：[Bridge protocol](/zh-CN/gateway/bridge-protocol)（TCP JSONL；
+仅供当前节点历史参考）。

-macOS 也可以在**节点模式**下运行：菜单栏应用连接到 Gateway 网关的
-WS 服务器，并将本地 canvas/camera 命令作为节点暴露（因此
+macOS 也可以在 **节点模式** 下运行：菜单栏应用会连接到 Gateway 网关的
+WS 服务器，并将其本地画布/相机命令作为节点暴露（因此
 `openclaw nodes …` 可针对这台 Mac 工作）。在远程 Gateway 网关模式下，浏览器
-自动化由 CLI 节点主机（`openclaw node run` 或已安装的节点服务）处理，而不是由原生应用节点处理。
+自动化由 CLI 节点主机（`openclaw node run` 或已安装的
+节点服务）处理，而不是由原生应用节点处理。

-注意：
+注意事项：

- 节点是**外围设备**，不是 Gateway 网关。它们不运行 Gateway 网关服务。
- Telegram/WhatsApp 等消息会到达 **Gateway 网关**，而不是节点。
- 故障排除手册：[/nodes/troubleshooting](/zh-CN/nodes/troubleshooting)
+- 节点是 **外围设备**，不是网关。它们不会运行网关服务。
+- Telegram/WhatsApp 等消息会落到 **网关**，不是节点。
+- 故障排除运行手册：[/nodes/troubleshooting](/zh-CN/nodes/troubleshooting)

-## 配对 + Status
+## 配对 + 状态

 **WS 节点使用设备配对。** 节点在 `connect` 期间提供设备身份；Gateway 网关
 会为 `role: node` 创建设备配对请求。通过设备 CLI（或 UI）批准。
@ -45,20 +46,20 @@ openclaw nodes status
 openclaw nodes describe --node <idOrNameOrIp>
 ```

-如果节点使用变更后的认证详情（角色/作用域/公钥）重试，则先前的
+如果节点使用已更改的身份验证详情（角色/范围/公钥）重试，先前的
 待处理请求会被取代，并创建新的 `requestId`。批准前请重新运行
 `openclaw devices list`。

-注意：
+注意事项：

- 当设备配对角色包含 `node` 时，`nodes status` 会将节点标记为**已配对**。
+- 当设备配对角色包含 `node` 时，`nodes status` 会将节点标记为 **已配对**。
 - 设备配对记录是持久的已批准角色契约。令牌
-  轮换保持在该契约内；它不能将已配对节点升级为
+  轮换会保持在该契约内；它不能把已配对节点升级为
  配对批准从未授予的其他角色。
- `node.pair.*`（CLI：`openclaw nodes pending/approve/reject/remove/rename`）是一个单独的、由 Gateway 网关拥有的
-  节点配对存储；它**不会**门控 WS `connect` 握手。
+- `node.pair.*`（CLI：`openclaw nodes pending/approve/reject/remove/rename`）是单独的 Gateway 网关自有
+  节点配对存储；它 **不会** 控制 WS `connect` 握手。
 - `openclaw nodes remove --node <id|name|ip>` 会从该
-  单独的、由 Gateway 网关拥有的节点配对存储中删除过时条目。
+  单独的 Gateway 网关自有节点配对存储中删除过期条目。
 - 批准范围遵循待处理请求声明的命令：
  - 无命令请求：`operator.pairing`
  - 非 exec 节点命令：`operator.pairing` + `operator.write`
@ -66,9 +67,8 @@ openclaw nodes describe --node <idOrNameOrIp>

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

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

 ### 运行位置

@ -78,12 +78,12 @@ openclaw nodes describe --node <idOrNameOrIp>

 批准说明：

- 基于批准的节点运行会绑定精确的请求上下文。
- 对于直接的 shell/运行时文件执行，OpenClaw 还会尽力绑定一个具体的本地
-  文件操作数，并在该文件在执行前发生变化时拒绝运行。
- 如果 OpenClaw 无法为解释器/运行时命令精确识别一个具体的本地文件，
-  基于批准的执行会被拒绝，而不是假装具备完整的运行时覆盖。若需要更广泛的解释器语义，请使用沙箱隔离、
-  独立主机，或显式可信的允许列表/完整工作流。
+- 基于批准的节点运行会绑定确切的请求上下文。
+- 对于直接 shell/运行时文件执行，OpenClaw 还会尽力绑定一个具体本地
+  文件操作数，并在该文件执行前发生变化时拒绝运行。
+- 如果 OpenClaw 无法为解释器/运行时命令准确识别一个具体本地文件，
+  基于批准的执行会被拒绝，而不是假装已覆盖完整运行时。对于更广泛的解释器语义，请使用沙箱隔离、
+  独立主机，或显式受信任的允许列表/完整工作流。

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

@ -93,10 +93,10 @@ openclaw nodes describe --node <idOrNameOrIp>
 openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"
 ```

-### 通过 SSH 隧道连接远程 Gateway 网关（loopback 绑定）
+### 通过 SSH 隧道访问远程 Gateway 网关（loopback 绑定）

-如果 Gateway 网关绑定到 loopback（`gateway.bind=loopback`，本地模式下默认），
-远程节点主机无法直接连接。请创建 SSH 隧道，并让
+如果 Gateway 网关绑定到 loopback（`gateway.bind=loopback`，本地模式默认值），
+远程节点主机无法直接连接。创建 SSH 隧道，并将
 节点主机指向隧道的本地端。

 示例（节点主机 -> Gateway 网关主机）：
@ -110,15 +110,15 @@ export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
 openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"
 ```

-注意：
+注意事项：

- `openclaw node run` 支持令牌或密码认证。
+- `openclaw node run` 支持令牌或密码身份验证。
 - 首选环境变量：`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`。
- 配置回退项是 `gateway.auth.token` / `gateway.auth.password`。
+- 配置回退为 `gateway.auth.token` / `gateway.auth.password`。
 - 在本地模式下，节点主机会有意忽略 `gateway.remote.token` / `gateway.remote.password`。
 - 在远程模式下，`gateway.remote.token` / `gateway.remote.password` 可按远程优先级规则使用。
- 如果已配置但未解析的活动本地 `gateway.auth.*` SecretRefs，节点主机认证会失败关闭。
- 节点主机认证解析只认可 `OPENCLAW_GATEWAY_*` 环境变量。
+- 如果已配置活动的本地 `gateway.auth.*` SecretRefs 但无法解析，节点主机身份验证会失败关闭。
+- 节点主机身份验证解析只认可 `OPENCLAW_GATEWAY_*` 环境变量。

 ### 启动节点主机（服务）

@ -138,28 +138,28 @@ openclaw devices approve <requestId>
 openclaw nodes status
 ```

-如果节点使用变更后的认证详情重试，请重新运行 `openclaw devices list`
+如果节点使用已更改的身份验证详情重试，请重新运行 `openclaw devices list`
 并批准当前的 `requestId`。

 命名选项：

- 在 `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"`（网关覆盖）。

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

-Exec 批准是**按节点主机**生效的。从 Gateway 网关添加允许列表条目：
+Exec 批准是 **按节点主机** 生效的。从网关添加允许列表条目：

 ```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 网关配置）：
+配置默认值（网关配置）：

 ```bash
 openclaw config set tools.exec.host node
@ -167,18 +167,18 @@ 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` 调用都会在节点主机上运行（受
 节点允许列表/批准约束）。

-`host=auto` 不会自行隐式选择节点，但 `auto` 允许显式的逐调用 `host=node` 请求。如果你希望节点 exec 成为会话默认值，请显式设置 `tools.exec.host=node` 或 `/exec host=node ...`。
+`host=auto` 不会自行隐式选择节点，但允许从 `auto` 发出显式的按调用 `host=node` 请求。如果你希望节点 exec 成为会话默认值，请显式设置 `tools.exec.host=node` 或 `/exec host=node ...`。

-相关：
+相关内容：

 - [节点主机 CLI](/zh-CN/cli/node)
 - [Exec 工具](/zh-CN/tools/exec)
@ -186,32 +186,38 @@ openclaw config set tools.exec.node "<id-or-name>"

 ## 调用命令

-低级方式（原始 RPC）：
+底层方式（原始 RPC）：

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

-针对常见的“给智能体一个 MEDIA 附件”工作流，也有更高级的辅助命令。
+针对常见的“给智能体一个 MEDIA 附件”工作流，也提供了更高层的辅助命令。

 ## 命令策略

-节点命令在可调用前必须通过两道门控：
+节点命令必须通过两道门禁后才能被调用：

 1. 节点必须在其 WebSocket `connect.commands` 列表中声明该命令。
-2. Gateway 网关的平台策略必须允许声明的命令。
+2. 网关的平台策略必须允许已声明的命令。

 Windows 和 macOS 配套节点默认允许安全的已声明命令，例如
 `canvas.*`、`camera.list`、`location.get` 和 `screen.snapshot`。
-危险或高度涉及隐私的命令，例如 `camera.snap`、`camera.clip` 和
+危险或涉及较多隐私的命令，例如 `camera.snap`、`camera.clip` 和
 `screen.record`，仍然需要通过
 `gateway.nodes.allowCommands` 显式选择启用。`gateway.nodes.denyCommands` 始终优先于
-默认值和额外的允许列表条目。
+默认值和额外允许列表条目。
+
+插件拥有的节点命令可以添加 Gateway 网关 node-invoke 策略。该策略
+会在允许列表检查之后、转发到节点之前运行，因此原始
+`node.invoke`、CLI 辅助命令和专用智能体工具共享同一个插件
+权限边界。危险的插件节点命令仍然需要显式
+`gateway.nodes.allowCommands` 选择启用。

 节点更改其声明的命令列表后，请拒绝旧的设备配对
-并批准新请求，以便 Gateway 网关存储更新后的命令快照。
+并批准新请求，以便网关存储更新后的命令快照。

-## 截图（canvas 快照）
+## 屏幕截图（画布快照）

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

@ -231,9 +237,9 @@ openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>
 openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"
 ```

-注意：
+注意事项：

- `canvas present` 接受 URL 或本地文件路径（`--target`），另可选用 `--x/--y/--width/--height` 进行定位。
+- `canvas present` 接受 URL 或本地文件路径（`--target`），还可使用可选的 `--x/--y/--width/--height` 进行定位。
 - `canvas eval` 接受内联 JS（`--js`）或位置参数。

 ### A2UI（Canvas）
@ -244,11 +250,11 @@ openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
 openclaw nodes canvas a2ui reset --node <idOrNameOrIp>
 ```

-注意：
+注意事项：

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

-## 照片 + 视频（节点摄像头）
+## 照片 + 视频（节点相机）

 照片（`jpg`）：

@ -265,11 +271,11 @@ openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
 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` 失败。

 ## 屏幕录制（节点）

@ -280,16 +286,16 @@ openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
 openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio
 ```

-注意：
+注意事项：

 - `screen.record` 可用性取决于节点平台。
 - 屏幕录制会被限制为 `<= 60s`。
- `--no-audio` 会在受支持平台上禁用麦克风捕获。
+- `--no-audio` 会在受支持的平台上禁用麦克风捕获。
 - 当有多个屏幕可用时，使用 `--screen <index>` 选择显示器。

 ## 位置（节点）

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

 CLI 辅助命令：

@ -298,30 +304,30 @@ openclaw nodes location get --node <idOrNameOrIp>
 openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000
 ```

-注意：
+注意事项：

- 位置默认**关闭**。
- “始终”需要系统权限；后台获取是尽力而为。
- 响应包含纬度/经度、精度（米）和时间戳。
+- 位置默认 **关闭**。
+- “始终”需要系统权限；后台获取会尽力执行。
+- 响应包含纬度/经度、准确度（米）和时间戳。

 ## SMS（Android 节点）

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

-低级调用：
+底层调用：

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

-注意：
+注意事项：

- 必须先在 Android 设备上接受权限提示，之后才会公布该能力。
- 没有电话功能的 Wi-Fi-only 设备不会公布 `sms.send`。
+- 必须先在 Android 设备上接受权限提示，能力才会被公布。
+- 不带电话功能的仅 Wi-Fi 设备不会公布 `sms.send`。

 ## Android 设备 + 个人数据命令

-当对应能力启用时，Android 节点可以公布额外的命令系列。
+当相应能力已启用时，Android 节点可以公布额外的命令系列。

 可用系列：

@ -344,7 +350,7 @@ openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"

 注意：

- 运动命令会按可用传感器进行能力门控。
+- 动作命令受可用传感器的能力门控限制。

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

@ -358,28 +364,28 @@ openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready
 openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"name":"git"}'
 ```

-注意事项：
+注意：

- `system.run` 会在载荷中返回 stdout/stderr/退出码。
- Shell 执行现在通过带有 `host=node` 的 `exec` 工具进行；`nodes` 仍然是显式节点命令的直接 RPC 接口。
+- `system.run` 在载荷中返回 stdout/stderr/退出码。
+- Shell 执行现在通过 `exec` 工具并使用 `host=node`；`nodes` 仍是显式节点命令的直接 RPC 接口。
 - `nodes invoke` 不公开 `system.run` 或 `system.run.prepare`；它们只保留在 exec 路径上。
- exec 路径会在批准前准备规范的 `systemRunPlan`。一旦批准授予，Gateway 网关会转发该已存储的计划，而不是任何后续由调用方编辑的 command/cwd/session 字段。
- `system.notify` 会遵守 macOS 应用上的通知权限状态。
- 未识别的节点 `platform` / `deviceFamily` 元数据会使用保守的默认允许列表，该列表排除 `system.run` 和 `system.which`。如果你确实需要在未知平台上使用这些命令，请通过 `gateway.nodes.allowCommands` 显式添加它们。
+- exec 路径会在批准前准备一个规范的 `systemRunPlan`。一旦批准被授予，Gateway 网关会转发该已存储的计划，而不是后续由调用方编辑过的 command/cwd/session 字段。
+- `system.notify` 遵循 macOS 应用上的通知权限状态。
+- 无法识别的节点 `platform` / `deviceFamily` 元数据会使用保守的默认允许列表，其中不包含 `system.run` 和 `system.which`。如果你确实需要为未知平台使用这些命令，请通过 `gateway.nodes.allowCommands` 显式添加它们。
 - `system.run` 支持 `--cwd`、`--env KEY=VAL`、`--command-timeout` 和 `--needs-screen-recording`。
- 对于 Shell 包装器（`bash|sh|zsh ... -c/-lc`），请求作用域的 `--env` 值会被缩减为显式允许列表（`TERM`、`LANG`、`LC_*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`）。
- 对于允许列表模式中的“始终允许”决策，已知的分发包装器（`env`、`nice`、`nohup`、`stdbuf`、`timeout`）会持久化内部可执行文件路径，而不是包装器路径。如果无法安全解包，则不会自动持久化任何允许列表条目。
- 在允许列表模式下的 Windows 节点主机上，通过 `cmd.exe /c` 运行 Shell 包装器需要批准（仅有允许列表条目不会自动允许包装器形式）。
+- 对于 Shell 包装器（`bash|sh|zsh ... -c/-lc`），请求范围内的 `--env` 值会被缩减为显式允许列表（`TERM`、`LANG`、`LC_*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`）。
+- 在允许列表模式下，对于始终允许决策，已知的分发包装器（`env`、`nice`、`nohup`、`stdbuf`、`timeout`）会持久化内部可执行文件路径，而不是包装器路径。如果无法安全解包，则不会自动持久化允许列表条目。
+- 在允许列表模式下，Windows 节点主机通过 `cmd.exe /c` 运行 Shell 包装器时需要批准（仅有允许列表条目不会自动允许该包装器形式）。
 - `system.notify` 支持 `--priority <passive|active|timeSensitive>` 和 `--delivery <system|overlay|auto>`。
 - 节点主机会忽略 `PATH` 覆盖，并剥离危险的启动/ Shell 键（`DYLD_*`、`LD_*`、`NODE_OPTIONS`、`PYTHON*`、`PERL*`、`RUBYOPT`、`SHELLOPTS`、`PS4`）。如果你需要额外的 PATH 条目，请改为配置节点主机服务环境（或将工具安装到标准位置），而不是通过 `--env` 传递 `PATH`。
- 在 macOS 节点模式下，`system.run` 受 macOS 应用中的 exec 批准控制（设置 → Exec approvals）。
+- 在 macOS 节点模式下，`system.run` 受 macOS 应用中的 exec 批准门控（Settings → Exec approvals）。
  Ask/allowlist/full 的行为与无头节点主机相同；被拒绝的提示会返回 `SYSTEM_RUN_DENIED`。
- 在无头节点主机上，`system.run` 受 exec 批准控制（`~/.openclaw/exec-approvals.json`）。
+- 在无头节点主机上，`system.run` 受 exec 批准门控（`~/.openclaw/exec-approvals.json`）。

 ## Exec 节点绑定

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

 全局默认值：

@ -387,7 +393,7 @@ openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"n
 openclaw config set tools.exec.node "node-id-or-name"
 ```

-每个智能体覆盖：
+按智能体覆盖：

 ```bash
 openclaw config get agents.list
@ -403,11 +409,13 @@ 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 上很有用，
+也适合在服务器旁运行一个最小节点。

 启动它：

@ -415,15 +423,18 @@ OpenClaw 可以运行一个**无头节点主机**（无 UI），它会连接到
 openclaw node run --host <gateway-host> --port 18789
 ```

-注意事项：
+注意：

 - 仍然需要配对（Gateway 网关会显示设备配对提示）。
 - 节点主机会将其节点 ID、令牌、显示名称和 Gateway 网关连接信息存储在 `~/.openclaw/node.json` 中。
- Exec 批准会通过 `~/.openclaw/exec-approvals.json` 在本地强制执行（请参阅 [Exec 批准](/zh-CN/tools/exec-approvals)）。
- 在 macOS 上，无头节点主机默认会在本地执行 `system.run`。设置 `OPENCLAW_NODE_EXEC_HOST=app` 可通过配套应用 exec 主机路由 `system.run`；添加 `OPENCLAW_NODE_EXEC_FALLBACK=0` 可要求使用应用主机，并在其不可用时关闭失败。
- 当 Gateway 网关 WS 使用 TLS 时，请添加 `--tls` / `--tls-fingerprint`。
+- Exec 批准会通过 `~/.openclaw/exec-approvals.json` 在本地强制执行
+  （参见 [Exec 批准](/zh-CN/tools/exec-approvals)）。
+- 在 macOS 上，无头节点主机默认在本地执行 `system.run`。设置
+  `OPENCLAW_NODE_EXEC_HOST=app` 可将 `system.run` 路由到配套应用的 exec 主机；添加
+  `OPENCLAW_NODE_EXEC_FALLBACK=0` 可要求使用应用主机，并在它不可用时安全失败。
+- 当 Gateway 网关 WS 使用 TLS 时，添加 `--tls` / `--tls-fingerprint`。

 ## Mac 节点模式

- macOS 菜单栏应用会作为节点连接到 Gateway 网关 WS 服务器（因此 `openclaw nodes …` 可以针对这台 Mac 工作）。
+- macOS 菜单栏应用作为节点连接到 Gateway 网关 WS 服务器（因此 `openclaw nodes …` 可对此 Mac 生效）。
 - 在远程模式下，应用会为 Gateway 网关端口打开 SSH 隧道并连接到 `localhost`。
--- a/docs/zh-CN/plugins/sdk-runtime.md
+++ b/docs/zh-CN/plugins/sdk-runtime.md
@ -1,28 +1,28 @@
 ---
 read_when:
-    - 你需要从插件调用核心辅助函数（文本转语音、语音转文本、图像生成、网页搜索、子智能体、节点）
-    - 你想了解 api.runtime 公开了什么
+    - 你需要从插件调用核心辅助函数（TTS、STT、图像生成、网页搜索、子智能体、节点）
+    - 你想了解 api.runtime 暴露了什么
    - 你正在从插件代码访问配置、智能体或媒体辅助函数
 sidebarTitle: Runtime helpers
-summary: api.runtime -- 可供插件使用的注入式运行时辅助函数
-title: 插件运行时帮助程序
+summary: api.runtime -- 可供插件使用的注入式运行时辅助工具
+title: 插件运行时辅助函数
 x-i18n:
-    generated_at: "2026-04-29T13:06:12Z"
+    generated_at: "2026-04-30T04:07:31Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 399e2433e272fe30e7451690a64826df8e30a064269b8d9a7aa2dd2b0c5688b8
+    source_hash: f2264090e062be9892a2bac7d313cad80a550f79b0bf0d74635bf6b80aea5060
    source_path: plugins/sdk-runtime.md
    workflow: 16
 ---

-每个插件注册期间都会注入 `api.runtime` 对象，这是其参考说明。请使用这些辅助工具，而不是直接导入主机内部机制。
+OpenClaw 会在注册期间向每个插件注入 `api.runtime` 对象，本文是它的参考。请使用这些辅助函数，而不是直接导入宿主内部实现。

 <CardGroup cols={2}>
-  <Card title="渠道插件" href="/zh-CN/plugins/sdk-channel-plugins">
-    分步指南，展示如何在渠道插件的上下文中使用这些辅助工具。
+  <Card title="Channel plugins" href="/zh-CN/plugins/sdk-channel-plugins">
+    在渠道插件上下文中使用这些辅助函数的分步指南。
  </Card>
-  <Card title="提供商插件" href="/zh-CN/plugins/sdk-provider-plugins">
-    分步指南，展示如何在提供商插件的上下文中使用这些辅助工具。
+  <Card title="Provider plugins" href="/zh-CN/plugins/sdk-provider-plugins">
+    在提供商插件上下文中使用这些辅助函数的分步指南。
  </Card>
 </CardGroup>

@ -32,34 +32,29 @@ register(api) {
 }
 ```

-## 配置加载与写入
+## 配置加载和写入

-优先使用已经传入当前活动调用路径的配置，例如注册期间的 `api.config`，或渠道/提供商回调中的 `cfg` 参数。这样可以让一个进程快照贯穿整个工作流程，而不是在热路径上重新解析配置。
+优先使用已传入当前活动调用路径的配置，例如注册期间的 `api.config`，或渠道/提供商回调中的 `cfg` 参数。这样可以让一个进程快照在工作中流动，而不是在热路径上重新解析配置。

-只有当长期存在的处理程序需要当前进程快照，且没有配置传给该函数时，才使用 `api.runtime.config.current()`。返回值是只读的；编辑前请先克隆，或使用变更辅助工具。
+只有当长生命周期处理程序需要当前进程快照，并且没有向该函数传入配置时，才使用 `api.runtime.config.current()`。返回值是只读的；编辑前请克隆，或使用变更辅助函数。

-工具工厂会收到 `ctx.runtimeConfig` 和 `ctx.getRuntimeConfig()`。当配置可能在工具定义创建后发生变化时，请在长期存在的工具 `execute` 回调中使用这个 getter。
+工具工厂会收到 `ctx.runtimeConfig` 和 `ctx.getRuntimeConfig()`。当配置可能在工具定义创建后发生变化时，请在长生命周期工具的 `execute` 回调中使用该 getter。

-使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 持久化更改。每次写入都必须选择显式的 `afterWrite` 策略：
+使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 持久化更改。每次写入都必须选择一个显式的 `afterWrite` 策略：

 - `afterWrite: { mode: "auto" }` 让 Gateway 网关重载规划器决定。
 - `afterWrite: { mode: "restart", reason: "..." }` 会在写入方知道热重载不安全时强制干净重启。
- `afterWrite: { mode: "none", reason: "..." }` 仅在调用方负责后续处理时抑制自动重载/重启。
+- `afterWrite: { mode: "none", reason: "..." }` 仅当调用方负责后续处理时，才抑制自动重载/重启。

-变更辅助工具会返回 `afterWrite` 以及类型化的 `followUp` 摘要，让调用方可以记录或测试自己是否请求了重启。Gateway 网关仍然负责决定实际何时重启。
+变更辅助函数会返回 `afterWrite` 以及一个带类型的 `followUp` 摘要，以便调用方记录或测试自己是否请求了重启。Gateway 网关仍然负责决定重启实际何时发生。

-`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是 `runtime-config-load-write` 下已弃用的兼容性辅助工具。它们会在运行时警告一次，并且在迁移窗口期间仍可供旧的外部插件使用。内置插件不得使用它们；如果插件代码调用它们，或从插件 SDK 子路径导入这些辅助工具，配置边界守卫会失败。
+`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是 `runtime-config-load-write` 下已弃用的兼容性辅助函数。它们会在运行时警告一次，并在迁移窗口期间继续供旧的外部插件使用。内置插件不得使用它们；如果插件代码调用它们，或从插件 SDK 子路径导入这些辅助函数，配置边界守卫会失败。

-对于直接 SDK 导入，请使用聚焦的配置子路径，而不是宽泛的
-`openclaw/plugin-sdk/config-runtime` 兼容性 barrel：`config-types` 用于
-类型，`plugin-config-runtime` 用于已加载配置断言和插件
-入口查找，`runtime-config-snapshot` 用于当前进程快照，`config-mutation`
-用于写入。内置插件测试应直接 mock 这些聚焦的
-子路径，而不是 mock 宽泛的兼容性 barrel。
+对于直接的 SDK 导入，请使用聚焦的配置子路径，而不是宽泛的 `openclaw/plugin-sdk/config-runtime` 兼容性 barrel：`config-types` 用于类型，`plugin-config-runtime` 用于已加载配置断言和插件入口查找，`runtime-config-snapshot` 用于当前进程快照，`config-mutation` 用于写入。内置插件测试应直接 mock 这些聚焦子路径，而不是 mock 宽泛的兼容性 barrel。

-OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关或进程边界加载一次配置，然后传递该值。成功的变更写入会刷新进程运行时快照并推进其内部修订版本；长期存在的缓存应基于运行时拥有的缓存键，而不是在本地序列化配置。长期存在的运行时模块对环境中的 `loadConfig()` 调用执行零容忍扫描；请使用传入的 `cfg`、请求的 `context.getRuntimeConfig()`，或在显式进程边界使用 `getRuntimeConfig()`。
+OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关或进程边界加载一次配置，然后传递该值。成功的变更写入会刷新进程运行时快照，并推进其内部修订；长生命周期缓存应基于运行时拥有的缓存键，而不是在本地序列化配置。长生命周期运行时模块对环境中的 `loadConfig()` 调用采用零容忍扫描；请使用传入的 `cfg`、请求的 `context.getRuntimeConfig()`，或在显式进程边界使用 `getRuntimeConfig()`。

-提供商和渠道执行路径必须使用活动的运行时配置快照，而不是用于配置读回或编辑的文件快照。文件快照会保留源值，例如 UI 和写入所需的 SecretRef 标记；提供商回调需要已解析的运行时视图。当某个辅助工具可能被传入活动源快照或活动运行时快照时，请在读取凭证前通过 `selectApplicableRuntimeConfig()` 路由。
+提供商和渠道执行路径必须使用活动运行时配置快照，而不是为配置回读或编辑返回的文件快照。文件快照会为 UI 和写入保留源值，例如 SecretRef 标记；提供商回调需要已解析的运行时视图。当某个辅助函数可能接收活动源快照或活动运行时快照时，请在读取凭证前通过 `selectApplicableRuntimeConfig()` 路由。

 ## 运行时命名空间

@ -109,15 +104,15 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    });
    ```

-    `runEmbeddedAgent(...)` 是从插件代码启动普通 OpenClaw 智能体轮次的中立辅助工具。它使用与渠道触发回复相同的提供商/模型解析和 agent-harness 选择。
+    `runEmbeddedAgent(...)` 是从插件代码启动普通 OpenClaw 智能体轮次的中立辅助函数。它使用与渠道触发回复相同的提供商/模型解析和 agent-harness 选择。

    `runEmbeddedPiAgent(...)` 仍作为兼容性别名保留。

-    `resolveThinkingPolicy(...)` 会返回提供商/模型支持的 thinking 级别和可选默认值。提供商插件通过自己的 thinking 钩子拥有模型专属配置文件，因此工具插件应调用这个运行时辅助工具，而不是导入或复制提供商列表。
+    `resolveThinkingPolicy(...)` 返回提供商/模型支持的思考级别以及可选默认值。提供商插件通过自己的思考钩子拥有特定于模型的配置文件，因此工具插件应调用这个运行时辅助函数，而不是导入或复制提供商列表。

-    `normalizeThinkingLevel(...)` 会将 `on`、`x-high` 或 `extra high` 等用户文本转换为规范的已存储级别，然后再对照解析后的策略进行检查。
+    `normalizeThinkingLevel(...)` 会在依据已解析策略检查前，把 `on`、`x-high` 或 `extra high` 等用户文本转换为规范的已存储级别。

-    **会话存储辅助工具** 位于 `api.runtime.agent.session` 下：
+    **会话存储辅助函数**位于 `api.runtime.agent.session` 下：

    ```typescript
    const storePath = api.runtime.agent.session.resolveStorePath(cfg);
@ -137,7 +132,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关

  </Accordion>
  <Accordion title="api.runtime.subagent">
-    启动并管理后台子智能体运行。
+    启动并管理后台 subagent 运行。

    ```typescript
    // Start a subagent run
@ -165,14 +160,14 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    ```

    <Warning>
-    模型覆盖（`provider`/`model`）需要操作员通过配置中的 `plugins.entries.<id>.subagent.allowModelOverride: true` 选择启用。不受信任的插件仍然可以运行子智能体，但覆盖请求会被拒绝。
+    模型覆盖（`provider`/`model`）需要操作员通过配置中的 `plugins.entries.<id>.subagent.allowModelOverride: true` 选择启用。不受信任的插件仍然可以运行 subagent，但覆盖请求会被拒绝。
    </Warning>

-    `deleteSession(...)` 可以删除由同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作员会话仍需要管理员范围的 Gateway 网关请求。
+    `deleteSession(...)` 可以删除同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作员会话仍需要管理员范围的 Gateway 网关请求。

  </Accordion>
  <Accordion title="api.runtime.nodes">
-    列出已连接节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令调用节点托管命令。当插件拥有配对设备上的本地工作时使用它，例如另一台 Mac 上的浏览器或音频桥接。
+    列出已连接节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令调用节点宿主命令。当插件拥有配对设备上的本地工作时使用它，例如另一台 Mac 上的浏览器或音频桥。

    ```typescript
    const { nodes } = await api.runtime.nodes.list({ connected: true });
@ -185,11 +180,13 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    });
    ```

-    在 Gateway 网关内部，这个运行时位于进程内。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此 `openclaw googlemeet recover-tab` 等命令可以从终端检查配对节点。节点命令仍会经过正常的 Gateway 网关节点配对、命令允许列表和节点本地命令处理。
+    在 Gateway 网关内部，这个运行时在进程内运行。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此 `openclaw googlemeet recover-tab` 等命令可以从终端检查配对节点。节点命令仍会经过常规 Gateway 网关节点配对、命令允许列表、插件节点调用策略，以及节点本地命令处理。
+
+    暴露危险节点宿主命令的插件应使用 `api.registerNodeInvokePolicy(...)` 注册节点调用策略。该策略会在 Gateway 网关中运行，位于命令允许列表检查之后、命令转发到节点之前，因此直接的 `node.invoke` 调用和更高层的插件工具会共享同一条强制执行路径。

  </Accordion>
  <Accordion title="api.runtime.tasks.managedFlows">
-    将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具上下文，然后创建和管理 Task Flow，而无需在每次调用时传递所有者。
+    将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具上下文，然后创建并管理 Task Flow，而无需在每次调用时传入所有者。

    ```typescript
    const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
@ -216,7 +213,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    });
    ```

-    当你已经从自己的绑定层获得受信任的 OpenClaw 会话键时，请使用 `bindSession({ sessionKey, requesterOrigin })`。不要从原始用户输入进行绑定。
+    当你已经从自己的绑定层获得受信任的 OpenClaw 会话键时，请使用 `bindSession({ sessionKey, requesterOrigin })`。不要从原始用户输入绑定。

  </Accordion>
  <Accordion title="api.runtime.tts">
@ -242,7 +239,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    });
    ```

-    使用核心 `messages.tts` 配置和提供商选择。返回 PCM 音频缓冲区 + 采样率。
+    使用核心 `messages.tts` 配置和提供商选择。返回 PCM 音频缓冲区和采样率。

  </Accordion>
  <Accordion title="api.runtime.mediaUnderstanding">
@ -276,10 +273,10 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    });
    ```

-    未产生输出时（例如跳过的输入），返回 `{ text: undefined }`。
+    未生成输出时（例如跳过的输入），返回 `{ text: undefined }`。

    <Info>
-    `api.runtime.stt.transcribeAudioFile(...)` 仍作为 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容性别名保留。
+    `api.runtime.stt.transcribeAudioFile(...)` 仍作为 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容别名保留。
    </Info>

  </Accordion>
@ -310,7 +307,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关

  </Accordion>
  <Accordion title="api.runtime.media">
-    底层媒体实用工具。
+    底层媒体工具。

    ```typescript
    const webMedia = await api.runtime.media.loadWebMedia(url);
@ -335,7 +332,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关

  </Accordion>
  <Accordion title="api.runtime.config">
-    当前运行时配置快照和事务性配置写入。优先使用已经传入活动调用路径的配置；仅在处理器需要直接使用进程快照时才使用 `current()`。
+    当前运行时配置快照和事务式配置写入。优先使用已经传入当前活动调用路径的配置；仅当处理程序需要直接读取进程快照时，才使用 `current()`。

    ```typescript
    const cfg = api.runtime.config.current();
@ -347,11 +344,11 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    });
    ```

-    `mutateConfigFile(...)` 和 `replaceConfigFile(...)` 返回一个 `followUp` 值，例如 `{ mode: "restart", requiresRestart: true, reason }`，它会记录写入方意图，而不会从 Gateway 网关手中接管重启控制。
+    `mutateConfigFile(...)` 和 `replaceConfigFile(...)` 会返回一个 `followUp` 值，例如 `{ mode: "restart", requiresRestart: true, reason }`，用于记录写入方意图，而不会从 Gateway 网关手中接管重启控制。

  </Accordion>
  <Accordion title="api.runtime.system">
-    系统级实用工具。
+    系统级工具。

    ```typescript
    await api.runtime.system.enqueueSystemEvent(event);
@ -384,7 +381,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关

  </Accordion>
  <Accordion title="api.runtime.modelAuth">
-    模型和提供商凭证解析。
+    模型和提供商认证解析。

    ```typescript
    const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
@ -396,7 +393,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关

  </Accordion>
  <Accordion title="api.runtime.state">
-    状态目录解析和基于 SQLite 的键控存储。
+    状态目录解析和基于 SQLite 的键值存储。

    ```typescript
    const stateDir = api.runtime.state.resolveStateDir(process.env);
@ -412,7 +409,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    await store.clear();
    ```

-    键控存储会在重启后保留，并按运行时绑定的插件 ID 隔离。限制：每个命名空间 `maxEntries`，每个插件 1,000 行存活记录，JSON 值小于 64KB，以及可选的 TTL 过期。
+    键值存储会在重启后保留，并按运行时绑定的插件 ID 隔离。限制：每个命名空间 `maxEntries`、每个插件 1,000 行活跃记录、JSON 值小于 64KB，以及可选的 TTL 过期。

    <Warning>
    此版本仅限内置插件。
@ -420,7 +417,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关

  </Accordion>
  <Accordion title="api.runtime.tools">
-    Memory 工具工厂和 CLI。
+    记忆工具工厂和 CLI。

    ```typescript
    const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
@ -430,7 +427,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关

  </Accordion>
  <Accordion title="api.runtime.channel">
-    渠道特定的运行时辅助工具（在加载渠道插件时可用）。
+    渠道专用运行时帮助程序（在加载渠道插件时可用）。

    `api.runtime.channel.mentions` 是使用运行时注入的内置渠道插件共享的入站提及策略表面：

@ -459,7 +456,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    });
    ```

-    可用的提及辅助工具：
+    可用的提及帮助程序：

    - `buildMentionRegexes`
    - `matchesMentionPatterns`
@ -467,7 +464,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    - `implicitMentionKindWhen`
    - `resolveInboundMentionDecision`

-    `api.runtime.channel.mentions` 有意不暴露较旧的 `resolveMentionGating*` 兼容性辅助工具。优先使用规范化的 `{ facts, policy }` 路径。
+    `api.runtime.channel.mentions` 有意不暴露较旧的 `resolveMentionGating*` 兼容帮助程序。优先使用规范化的 `{ facts, policy }` 路径。

  </Accordion>
 </AccordionGroup>
@ -477,7 +474,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
 使用 `createPluginRuntimeStore` 存储运行时引用，以便在 `register` 回调之外使用：

 <Steps>
-  <Step title="创建存储">
+  <Step title="Create the store">
    ```typescript
    import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
    import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
@ -489,7 +486,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    ```

  </Step>
-  <Step title="接入入口点">
+  <Step title="Wire into the entry point">
    ```typescript
    export default defineChannelPluginEntry({
      id: "my-plugin",
@ -500,7 +497,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    });
    ```
  </Step>
-  <Step title="从其他文件访问">
+  <Step title="Access from other files">
    ```typescript
    export function getRuntime() {
      return store.getRuntime(); // throws if not initialized
@ -515,12 +512,12 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
 </Steps>

 <Note>
-运行时存储身份优先使用 `pluginId`。较底层的 `key` 形式用于一个插件有意需要多个运行时槽位的少见情况。
+运行时存储身份优先使用 `pluginId`。较低层级的 `key` 形式用于少见场景，即一个插件有意需要多个运行时槽位。
 </Note>

 ## 其他顶层 `api` 字段

-除了 `api.runtime` 之外，API 对象还提供：
+除 `api.runtime` 外，API 对象还提供：

 <ParamField path="api.id" type="string">
  插件 ID。
@ -532,19 +529,19 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
  当前配置快照（可用时为活动的内存中运行时快照）。
 </ParamField>
 <ParamField path="api.pluginConfig" type="Record<string, unknown>">
-  来自 `plugins.entries.<id>.config` 的插件特定配置。
+  来自 `plugins.entries.<id>.config` 的插件专用配置。
 </ParamField>
 <ParamField path="api.logger" type="PluginLogger">
  作用域日志记录器（`debug`、`info`、`warn`、`error`）。
 </ParamField>
 <ParamField path="api.registrationMode" type="PluginRegistrationMode">
-  当前加载模式；`"setup-runtime"` 是完整入口启动前的轻量启动/设置窗口。
+  当前加载模式；`"setup-runtime"` 是轻量级的完整入口前启动/设置窗口。
 </ParamField>
 <ParamField path="api.resolvePath(input)" type="(string) => string">
  解析相对于插件根目录的路径。
 </ParamField>

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

 - [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和注册表
 - [SDK 入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 选项