From fef87fe905c58a0a0330e2ab834a84fc5a1210b9 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 3 May 2026 23:55:22 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/pairing.md | 104 +++++++++++++------------ docs/zh-CN/concepts/progress-drafts.md | 82 +++++++++---------- docs/zh-CN/gateway/operator-scopes.md | 93 +++++++++++----------- 3 files changed, 142 insertions(+), 137 deletions(-) diff --git a/docs/zh-CN/channels/pairing.md b/docs/zh-CN/channels/pairing.md index 637944bc3..714e71322 100644 --- a/docs/zh-CN/channels/pairing.md +++ b/docs/zh-CN/channels/pairing.md @@ -3,41 +3,41 @@ read_when: - 设置私信访问控制 - 配对新的 iOS/Android 节点 - 审查 OpenClaw 的安全态势 -summary: 配对概览：批准谁可以私信你 + 哪些节点可以加入 +summary: 配对概览：批准谁可以给你发私信 + 哪些节点可以加入 title: 配对 x-i18n: - generated_at: "2026-05-01T23:03:13Z" + generated_at: "2026-05-03T23:54:50Z" model: gpt-5.5 provider: openai - source_hash: bb68d87c0e1dfe7c9a6a6d9415f4c63625755fb43a2e22a1d1374ff0a63e49c4 + source_hash: 4fb27840f7c9ef55e7270cc29f813e6db90b240aa2180f30952eb9485f0f8874 source_path: channels/pairing.md workflow: 16 --- “配对”是 OpenClaw 的显式访问批准步骤。 -它用于两个地方： +它用于两个位置： -1. **私信配对**（谁被允许与机器人对话） -2. **节点配对**（哪些设备/节点被允许加入 Gateway 网关网络） +1. **私信配对**（谁可以与机器人对话） +2. **节点配对**（哪些设备/节点可以加入 Gateway 网关网络） 安全上下文：[安全](/zh-CN/gateway/security) ## 1) 私信配对（入站聊天访问） -当某个渠道配置了私信策略 `pairing` 时，未知发送者会收到一个短代码，并且在你批准之前，他们的消息**不会被处理**。 +当某个渠道配置为私信策略 `pairing` 时，未知发送者会收到一个短代码，并且在你批准之前，他们的消息**不会被处理**。 默认私信策略记录在：[安全](/zh-CN/gateway/security) -只有当有效的私信允许列表包含 `"*"` 时，`dmPolicy: "open"` 才是公开的。 +`dmPolicy: "open"` 仅当有效私信允许列表包含 `"*"` 时才是公开的。 设置和验证要求公开开放配置使用该通配符。如果现有 -状态包含 `open` 和具体的 `allowFrom` 条目，运行时仍然只接纳 -这些发送者，并且配对存储中的批准不会扩大 `open` 访问权限。 +状态包含 `open` 且带有具体的 `allowFrom` 条目，运行时仍然只允许 +这些发送者，并且配对存储中的批准不会扩大 `open` 访问范围。 -配对代码： +配对码： - 8 个字符，大写，不含易混淆字符（`0O1I`）。 -- **1 小时后过期**。机器人只会在创建新请求时发送配对消息（大约每个发送者每小时一次）。 -- 默认情况下，待处理的私信配对请求上限为**每个渠道 3 个**；更多请求会被忽略，直到其中一个过期或获批。 +- **1 小时后过期**。机器人只会在创建新请求时发送配对消息（每个发送者大约每小时一次）。 +- 待处理的私信配对请求默认每个渠道上限为 **3 个**；额外请求会被忽略，直到有请求过期或获批。 ### 批准发送者 @@ -46,21 +46,20 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` -如果尚未配置命令所有者，批准私信配对代码也会将 +如果尚未配置命令所有者，批准私信配对码也会将 `commands.ownerAllowFrom` 引导设置为已批准的发送者，例如 `telegram:123456789`。 -这会为首次设置提供一个用于特权命令和 exec -批准提示的显式所有者。已有所有者之后，后续配对批准只授予私信 +这会为首次设置提供一个显式所有者，用于特权命令和 exec +批准提示。所有者存在后，后续配对批准只授予私信 访问权限；它们不会添加更多所有者。 支持的渠道：`bluebubbles`、`discord`、`feishu`、`googlechat`、`imessage`、`irc`、`line`、`matrix`、`mattermost`、`msteams`、`nextcloud-talk`、`nostr`、`openclaw-weixin`、`signal`、`slack`、`synology-chat`、`telegram`、`twitch`、`whatsapp`、`zalo`、`zalouser`。 ### 可复用的发送者组 -当同一组受信任发送者需要应用于多个消息渠道，或同时应用于私信和群组允许列表时， -请使用顶层 `accessGroups`。 +当同一组受信任发送者应适用于多个消息渠道，或同时适用于私信和群组允许列表时，请使用顶层 `accessGroups`。 -静态组使用 `type: "message.senders"`，并在渠道允许列表中通过 -`accessGroup:` 引用： +静态组使用 `type: "message.senders"`，并通过 +渠道允许列表中的 `accessGroup:` 引用： ```json5 { @@ -83,7 +82,7 @@ openclaw pairing approve telegram 访问组的详细文档在这里：[访问组](/zh-CN/channels/access-groups) -### 状态的存储位置 +### 状态存储位置 存储在 `~/.openclaw/credentials/` 下： @@ -95,49 +94,49 @@ openclaw pairing approve telegram 账户作用域行为： - 非默认账户只读写其作用域内的允许列表文件。 -- 默认账户使用渠道作用域的无作用域允许列表文件。 +- 默认账户使用渠道作用域的未限定作用域允许列表文件。 -请将这些文件视为敏感信息（它们控制对你的助手的访问）。 +请将这些文件视为敏感内容（它们控制对你的助手的访问）。 -配对允许列表存储用于私信访问。群组授权是独立的。 -批准私信配对代码不会自动允许该发送者运行群组 -命令或在群组中控制机器人。首次所有者引导是 -`commands.ownerAllowFrom` 中的独立配置状态，群聊投递仍然遵循该 -渠道的群组允许列表（例如 `groupAllowFrom`、`groups`，或取决于渠道的按群组 -或按话题覆盖）。 +配对允许列表存储用于私信访问。群组授权是分开的。 +批准私信配对码不会自动允许该发送者运行群组 +命令或在群组中控制机器人。首个所有者引导是单独的配置 +状态，位于 `commands.ownerAllowFrom`，群组聊天投递仍然遵循 +该渠道的群组允许列表（例如 `groupAllowFrom`、`groups`，或根据渠道不同使用每群组 +或每主题覆盖）。 ## 2) 节点设备配对（iOS/Android/macOS/无头节点） -节点以带有 `role: node` 的**设备**身份连接到 Gateway 网关。Gateway 网关 +节点以 `role: node` 的**设备**身份连接到 Gateway 网关。Gateway 网关 会创建设备配对请求，必须批准该请求。 ### 通过 Telegram 配对（推荐用于 iOS） 如果你使用 `device-pair` 插件，可以完全通过 Telegram 完成首次设备配对： -1. 在 Telegram 中，给你的机器人发送消息：`/pair` +1. 在 Telegram 中，向你的机器人发送消息：`/pair` 2. 机器人会回复两条消息：一条说明消息，以及一条单独的**设置代码**消息（便于在 Telegram 中复制/粘贴）。 -3. 在手机上，打开 OpenClaw iOS 应用 → 设置 → Gateway 网关。 +3. 在手机上打开 OpenClaw iOS 应用 → 设置 → Gateway 网关。 4. 粘贴设置代码并连接。 5. 回到 Telegram：`/pair pending`（查看请求 ID、角色和作用域），然后批准。 -设置代码是一个 base64 编码的 JSON 载荷，其中包含： +设置代码是一个 base64 编码的 JSON 载荷，包含： - `url`：Gateway 网关 WebSocket URL（`ws://...` 或 `wss://...`） - `bootstrapToken`：用于初始配对握手的短期单设备引导令牌 -该引导令牌携带内置的配对引导配置文件： +该引导令牌携带内置配对引导配置文件： -- 主要移交的 `node` 令牌保持为 `scopes: []` -- 任何移交的 `operator` 令牌都保持受限于引导允许列表： +- 主要交接的 `node` 令牌保持 `scopes: []` +- 任何交接的 `operator` 令牌都限定在引导允许列表内： `operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write` -- 引导作用域检查按角色加前缀，而不是一个扁平的作用域池： +- 引导作用域检查按角色加前缀，而不是一个扁平作用域池： operator 作用域条目只满足 operator 请求，非 operator 角色 - 仍必须在自己的角色前缀下请求作用域 -- 后续令牌轮换/吊销仍然同时受设备已批准的 - 角色契约和调用方会话的 operator 作用域限制 + 仍必须在其自己的角色前缀下请求作用域 +- 后续令牌轮换/吊销仍同时受设备已批准 + 角色合约和调用方会话 operator 作用域的限制 设置代码有效期间，请像对待密码一样对待它。 @@ -149,18 +148,25 @@ openclaw devices approve openclaw devices reject ``` -如果同一设备使用不同的认证详情重试（例如不同的 +当显式批准被拒绝，原因是执行批准的已配对设备会话 +以仅配对作用域打开时，CLI 会使用 +`operator.admin` 重试同一请求。这让现有具备管理员能力的已配对设备无需手动编辑 +`devices/paired.json`，即可恢复新的 +Control UI/浏览器配对。Gateway 网关仍会验证重试的连接；无法使用 +`operator.admin` 进行身份验证的令牌仍会被阻止。 + +如果同一设备使用不同身份验证详情重试（例如不同的 角色/作用域/公钥），先前的待处理请求会被取代，并创建新的 `requestId`。 -已配对的设备不会静默获得更广泛的访问权限。如果它重新连接并请求更多作用域或更宽泛的角色，OpenClaw 会保持现有批准不变，并创建新的待处理升级请求。在批准前，请使用 `openclaw devices list` 比较当前已批准的访问权限与新请求的访问权限。 +已配对设备不会静默获得更宽的访问权限。如果它重新连接时请求更多作用域或更宽的角色，OpenClaw 会保持现有批准不变，并创建一个新的待处理升级请求。批准之前，请使用 `openclaw devices list` 对比当前已批准访问权限和新请求的访问权限。 ### 可选的受信任 CIDR 节点自动批准 -设备配对默认保持手动。对于严格控制的节点网络， -你可以通过显式 CIDR 或精确 IP 选择加入首次节点自动批准： +设备配对默认仍然是手动的。对于严格受控的节点网络， +你可以通过显式 CIDR 或精确 IP，选择为首次节点配对启用自动批准： ```json5 { @@ -174,9 +180,9 @@ openclaw devices reject } ``` -这只适用于没有请求 -作用域的全新 `role: node` 配对请求。Operator、浏览器、Control UI 和 WebChat 客户端仍然需要手动 -批准。角色、作用域、元数据和公钥变更仍然需要手动 +这仅适用于没有请求 +作用域的新 `role: node` 配对请求。Operator、浏览器、Control UI 和 WebChat 客户端仍需要手动 +批准。角色、作用域、元数据和公钥变更仍需要手动 批准。 ### 节点配对状态存储 @@ -189,9 +195,9 @@ openclaw devices reject ### 备注 - 旧版 `node.pair.*` API（CLI：`openclaw nodes pending|approve|reject|remove|rename`）是一个 - 独立的 Gateway 网关所有的配对存储。WS 节点仍然需要设备配对。 + 独立的 Gateway 网关自有配对存储。WS 节点仍需要设备配对。 - 配对记录是已批准角色的持久事实来源。活动 - 设备令牌保持受限于该已批准角色集；已批准角色之外的零散令牌条目 + 设备令牌仍限定于该已批准角色集合；已批准角色之外的零散令牌条目 不会创建新的访问权限。 ## 相关文档 diff --git a/docs/zh-CN/concepts/progress-drafts.md b/docs/zh-CN/concepts/progress-drafts.md index 33a495959..96b1d0384 100644 --- a/docs/zh-CN/concepts/progress-drafts.md +++ b/docs/zh-CN/concepts/progress-drafts.md @@ -1,23 +1,23 @@ --- read_when: - - 为长时间运行的聊天回合配置可见进度更新 - - 在部分、分块和进度流式传输模式之间选择 - - 说明 OpenClaw 如何在工作进行中更新一条渠道消息 + - 为长时间运行的聊天轮次配置可见进度更新 + - 在部分流式传输、分块流式传输和进度流式传输模式之间选择 + - 说明 OpenClaw 如何在工作进行期间更新一条渠道消息 - 进度草稿、独立进度消息或最终化回退的故障排除 -summary: 进度草稿：一条可见的进行中消息，会在智能体运行时更新 +summary: 进度草稿：一条可见的进行中消息，会在智能体运行期间更新 title: 进度草稿 x-i18n: - generated_at: "2026-05-03T23:27:01Z" + generated_at: "2026-05-03T23:54:52Z" model: gpt-5.5 provider: openai - source_hash: 04e87e81b5b256a3dcd52b70d46e85c80a5d05ecb32df00ccf59782ab47bde2c + source_hash: 079d4b63554fee0fc968027195d2707f2f0a16fa527b0ec81f88baedfe809c1e source_path: concepts/progress-drafts.md workflow: 16 --- -进度草稿让长时间运行的智能体回合在聊天中显得有动态，而不会把对话变成一堆临时状态回复。 +进度草稿让长时间运行的智能体轮次在聊天中显得仍在活动，而不会把对话变成一叠临时状态回复。 -启用进度草稿后，OpenClaw 只会在该回合证明自己正在执行真实工作后创建一条可见的进行中消息，在智能体阅读、规划、调用工具或等待批准时更新它，然后在渠道可以安全执行时，将该草稿转换为最终回答。 +启用进度草稿后，OpenClaw 只会在该轮次证明自己正在执行实际工作后创建一条可见的进行中消息，在智能体读取、规划、调用工具或等待批准时更新它，然后在渠道可以安全执行时，将该草稿转换为最终回答。 ```text Shelling... @@ -26,7 +26,7 @@ Shelling... - preparing reply ``` -当你希望在工具密集型工作期间显示一条整洁的状态消息，并在回合完成时显示最终回答时，请使用进度草稿。 +当你希望在工具密集型工作期间只显示一条整洁的状态消息，并在轮次完成后显示最终回答时，请使用进度草稿。 ## 快速开始 @@ -44,41 +44,41 @@ Shelling... } ``` -这通常就足够了。OpenClaw 会自动选择一个单词标签，等到工作至少持续五秒或发出第二个工作事件后，添加紧凑的进度行，并在该回合中抑制重复的独立进度提示。 +这通常就足够了。OpenClaw 会自动选择一个单词标签，等到工作持续至少五秒或发出第二个工作事件后，随着有用工作发生添加紧凑的进度行，并在该轮次中抑制重复的独立进度闲聊。 -## 用户会看到什么 +## 用户看到的内容 -进度草稿有两部分： +进度草稿包含两个部分： | 部分 | 目的 | -| -------------- | ----------------------------------------------------------------- | -| 标签 | 一个简短标题，例如 `Thinking...` 或 `Shelling...`。 | -| 进度行 | 紧凑的运行更新，例如工具调用、任务步骤或批准。 | +| -------------- | --------------------------------------------------------------------------- | +| 标签 | 短标题，例如 `Thinking...` 或 `Shelling...`。 | +| 进度行 | 使用与详细输出相同工具标签和图标的紧凑运行更新。 | -标签会在智能体开始有意义的工作，并且持续忙碌五秒或发出第二个工作事件后出现。纯文本回复不会显示进度草稿。只有当智能体发出有用的工作更新时，才会添加进度行。最终回答会尽可能替换草稿；否则，OpenClaw 会正常发送最终回答，并根据渠道的传输机制清理草稿或停止更新草稿。 +标签会在智能体开始有意义的工作后出现，并且工作持续五秒或发出第二个工作事件时显示。纯文本回复不会显示进度草稿。只有在智能体发出有用的工作更新时才会添加进度行，例如 `🛠️ Exec`、`🔎 Web Search` 或 `✍️ Write: to /tmp/file`。如果可能，最终回答会替换草稿；否则 OpenClaw 会正常发送最终回答，并根据渠道的传输方式清理草稿或停止更新草稿。 ## 选择模式 `channels..streaming.mode` 控制可见的进行中行为： -| 模式 | 最适合 | 聊天中显示什么 | +| 模式 | 最适合 | 聊天中显示的内容 | | ---------- | -------------------------------- | ------------------------------------------------- | | `off` | 安静渠道 | 只有最终回答。 | -| `partial` | 观察回答文本出现 | 一个使用最新回答文本编辑的草稿。 | +| `partial` | 观察回答文本出现 | 一个用最新回答文本编辑的草稿。 | | `block` | 更大的回答预览分块 | 一个以更大分块更新或追加的预览。 | -| `progress` | 工具密集型或长时间运行的回合 | 一个状态草稿，然后是最终回答。 | +| `progress` | 工具密集型或长时间运行的轮次 | 一个状态草稿，然后是最终回答。 | -当用户更关心“正在发生什么”，而不是逐个 token 观看回答文本流式输出时，请选择 `progress`。 +当用户更关心“正在发生什么”，而不是逐 token 观看回答文本流式输出时，请选择 `progress`。 当回答本身就是进度信号时，请选择 `partial`。 -当你希望以更大的文本分块更新草稿预览时，请选择 `block`。在 Discord 和 Telegram 上，`streaming.mode: "block"` 仍然是预览流式传输，而不是普通的分块发送。如果你想要普通的分块回复，请使用 `streaming.block.enabled` 或旧版 `blockStreaming`。 +当你想以更大的文本分块进行草稿预览更新时，请选择 `block`。在 Discord 和 Telegram 上，`streaming.mode: "block"` 仍然是预览流式传输，而不是普通分块交付。当你想要普通分块回复时，请使用 `streaming.block.enabled` 或旧版 `blockStreaming`。 ## 配置标签 进度标签位于 `channels..streaming.progress` 下。 -默认标签是 `auto`，它会从 OpenClaw 内置的单词加省略号标签池中选择： +默认标签是 `auto`，它会从 OpenClaw 内置的带省略号单词标签池中选择： ```text Thinking... @@ -157,7 +157,7 @@ Surfacing... ## 控制进度行 -在进度模式下，进度行默认启用。它们来自真实的运行事件：工具启动、项目更新、任务计划、批准、命令输出、补丁摘要以及类似的智能体活动。 +在进度模式中，进度行默认启用。它们来自真实的运行事件：工具启动、项目更新、任务计划、批准、命令输出、补丁摘要，以及类似的智能体活动。 限制保留可见的行数： @@ -193,54 +193,54 @@ Surfacing... } ``` -使用 `toolProgress: false` 时，OpenClaw 仍会为该回合抑制较旧的独立工具进度消息。除了已配置的标签之外，渠道在最终回答出现前会保持视觉上的安静。 +使用 `toolProgress: false` 时，OpenClaw 仍会在该轮次中抑制较旧的独立工具进度消息。除了已配置的标签外，渠道在视觉上会保持安静，直到最终回答出现。 ## 渠道行为 -每个渠道都会使用其支持的最简洁传输方式： +每个渠道都会使用其支持的最干净传输方式： -| 渠道 | 进度传输 | 说明 | +| 渠道 | 进度传输 | 备注 | | --------------- | -------------------------------------- | --------------------------------------------------------------------- | -| Discord | 发送一条消息，然后编辑它。 | 当最终文本适合一条安全预览消息时，会在原位编辑。 | -| Matrix | 发送一个事件，然后编辑它。 | 账号级流式传输配置控制账号级草稿。 | -| Microsoft Teams | 个人聊天中的原生 Teams 流。 | `streaming.mode: "block"` 映射到 Teams 分块发送。 | +| Discord | 发送一条消息，然后编辑它。 | 当最终文本适合一条安全预览消息时，会原地编辑。 | +| Matrix | 发送一个事件，然后编辑它。 | 账户级流式传输配置控制账户级草稿。 | +| Microsoft Teams | 个人聊天中的原生 Teams 流。 | `streaming.mode: "block"` 映射到 Teams 分块交付。 | | Slack | 原生流或可编辑草稿帖子。 | 线程可用性会影响是否可以使用原生流式传输。 | -| Telegram | 发送一条消息，然后编辑它。 | 较旧的可见草稿可能会被替换，以便最终时间戳保持有用。 | -| Mattermost | 可编辑草稿帖子。 | 工具活动会折叠进同一个草稿样式帖子中。 | +| Telegram | 发送一条消息，然后编辑它。 | 较早的可见草稿可能会被替换，以便最终时间戳保持有用。 | +| Mattermost | 可编辑草稿帖子。 | 工具活动会折叠进同一个草稿式帖子。 | -没有安全编辑支持的渠道通常会回退到输入指示器或仅最终回答发送。 +没有安全编辑支持的渠道通常会回退到输入指示器或仅最终交付。 ## 最终化 -当最终回答准备好后，OpenClaw 会尝试保持聊天整洁： +当最终回答准备好时，OpenClaw 会尝试保持聊天整洁： -- 如果草稿可以安全地变成最终回答，OpenClaw 会在原位编辑它。 +- 如果草稿可以安全地变成最终回答，OpenClaw 会原地编辑它。 - 如果渠道使用原生进度流式传输，OpenClaw 会在原生传输接受最终文本时最终化该流。 -- 如果最终回答包含媒体、批准提示、显式回复目标、过多分块，或者编辑/发送失败，OpenClaw 会通过正常的渠道发送路径发送最终回答。 +- 如果最终回答包含媒体、批准提示、显式回复目标、过多分块，或编辑/发送失败，OpenClaw 会通过普通渠道交付路径发送最终回答。 -回退路径是有意设计的。发送一条新的最终回答，比丢失文本、把回复串错线程，或用渠道无法安全表示的载荷覆盖草稿更好。 +回退路径是有意设计的。发送一条新的最终回答，比丢失文本、把回复发错线程，或用渠道无法安全表示的载荷覆盖草稿更好。 ## 故障排除 **我只看到最终回答。** -检查 `channels..streaming.mode` 是否已为处理该消息的账号或渠道设置为 `progress`。当渠道无法安全编辑正确消息时，某些群组或引用回复路径可能会为某个回合禁用草稿预览。 +检查处理该消息的账户或渠道是否已将 `channels..streaming.mode` 设置为 `progress`。当渠道无法安全编辑正确消息时，某些群组或引用回复路径可能会禁用该轮次的草稿预览。 **我看到标签，但没有工具行。** 检查 `streaming.progress.toolProgress`。如果它是 `false`，OpenClaw 会保留单草稿行为，但隐藏工具和任务进度行。 -**我看到的是一条新的最终消息，而不是被编辑的草稿。** +**我看到的是一条新的最终消息，而不是编辑后的草稿。** -这是安全回退。它可能出现在媒体回复、较长回答、显式回复目标、旧 Telegram 草稿、缺失 Slack 线程目标、已删除的预览消息，或原生流最终化失败等情况下。 +这是安全回退。媒体回复、长回答、显式回复目标、旧 Telegram 草稿、缺失的 Slack 线程目标、已删除的预览消息，或原生流最终化失败，都可能导致这种情况。 **我仍然看到独立进度消息。** -当草稿处于活动状态时，进度模式会抑制默认的独立工具进度消息。如果仍然出现独立消息，请确认该回合确实使用的是进度模式，而不是 `streaming.mode: "off"`，也不是无法为该消息创建草稿的渠道路径。 +当草稿处于活动状态时，进度模式会抑制默认的独立工具进度消息。如果仍然出现独立消息，请确认该轮次确实在使用进度模式，而不是 `streaming.mode: "off"`，也不是某条无法为该消息创建草稿的渠道路径。 **Teams 的行为与 Discord 或 Telegram 不同。** -Microsoft Teams 在个人聊天中使用原生流，而不是通用的发送并编辑预览传输。Teams 还会将 `streaming.mode: "block"` 视为 Teams 分块发送，因为它没有 Discord 和 Telegram 所用的相同草稿预览分块模式。 +Microsoft Teams 在个人聊天中使用原生流，而不是通用的发送并编辑预览传输。Teams 还会把 `streaming.mode: "block"` 视为 Teams 分块交付，因为它没有 Discord 和 Telegram 所使用的同类草稿预览分块模式。 ## 相关 diff --git a/docs/zh-CN/gateway/operator-scopes.md b/docs/zh-CN/gateway/operator-scopes.md index 3f7614c0c..b60f5f712 100644 --- a/docs/zh-CN/gateway/operator-scopes.md +++ b/docs/zh-CN/gateway/operator-scopes.md @@ -1,76 +1,76 @@ --- read_when: - 调试缺少操作员作用域的错误 - - 查看设备或节点配对审批 + - 审核设备或节点配对批准 - 添加或分类 Gateway 网关 RPC 方法 summary: Gateway 网关客户端的操作员角色、作用域和批准时检查 -title: 操作员作用域 +title: 操作员权限范围 x-i18n: - generated_at: "2026-05-03T00:43:07Z" + generated_at: "2026-05-03T23:54:49Z" model: gpt-5.5 provider: openai - source_hash: 48f59f96b41333af9124ad4083ac5442eedb2d6cebdfff74e3ba256f06d36add + source_hash: f05d6bdbf9bdad2aef1c9664bb7ebb4b6241334b8aefac7993104e9977e40450 source_path: gateway/operator-scopes.md workflow: 16 --- -Operator 作用域定义了 Gateway 网关客户端在认证后可以执行什么操作。 -它们是一个受信任 Gateway 网关 operator 域内的控制平面防护栏， -不是敌意多租户隔离。如果你需要在人员、团队或机器之间实现强隔离， -请在不同 OS 用户或主机下运行独立的 Gateway 网关。 +Operator 作用域定义了 Gateway 网关客户端在完成身份验证后可以执行的操作。 +它们是一个受信任 Gateway 网关操作员域内的控制平面护栏， +不是针对恶意多租户的隔离。如果你需要在人、团队或机器之间实现强隔离， +请在单独的 OS 用户或主机下运行独立的 Gateway 网关。 相关：[安全](/zh-CN/gateway/security)、[Gateway 网关协议](/zh-CN/gateway/protocol)、 [Gateway 网关配对](/zh-CN/gateway/pairing)、[设备 CLI](/zh-CN/cli/devices)。 ## 角色 -Gateway 网关 WebSocket 客户端以一种角色连接： +Gateway 网关 WebSocket 客户端使用一种角色连接： -- `operator`：控制平面客户端，例如 CLI、Control UI、自动化以及 +- `operator`：控制平面客户端，例如 CLI、Control UI、自动化和 受信任的辅助进程。 -- `node`：能力主机，例如 macOS、iOS、Android，或通过 - `node.invoke` 暴露命令的无头节点。 +- `node`：能力宿主，例如 macOS、iOS、Android，或通过 `node.invoke` + 暴露命令的无头节点。 -Operator RPC 方法要求 `operator` 角色。节点发起的方法 -要求 `node` 角色。 +Operator RPC 方法需要 `operator` 角色。节点发起的方法需要 +`node` 角色。 ## 作用域级别 -| 作用域 | 含义 | +| 作用域 | 含义 | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `operator.read` | 只读 Status、列表、目录、日志、会话读取，以及其他不会变更控制平面的调用。 | -| `operator.write` | 常规可变更 operator 操作，例如发送消息、调用工具、更新 talk/voice 设置，以及节点命令转发。也满足 `operator.read`。 | -| `operator.admin` | 管理性控制平面访问。满足每个 `operator.*` 作用域。配置变更、更新、原生钩子、敏感保留命名空间和高风险批准都需要它。 | -| `operator.pairing` | 设备和节点配对管理，包括列出、批准、拒绝、移除、轮换和撤销配对记录或设备令牌。 | +| `operator.read` | 只读 Status、列表、目录、日志、会话读取，以及其他不会改变状态的控制平面调用。 | +| `operator.write` | 常规的可变更 operator 操作，例如发送消息、调用工具、更新 talk/voice 设置，以及节点命令中继。也满足 `operator.read`。 | +| `operator.admin` | 管理性控制平面访问。满足所有 `operator.*` 作用域。配置变更、更新、原生钩子、敏感保留命名空间和高风险批准都需要它。 | +| `operator.pairing` | 设备和节点配对管理，包括列出、批准、拒绝、移除、轮换和吊销配对记录或设备令牌。 | | `operator.approvals` | Exec 和插件批准 API。 | | `operator.talk.secrets` | 读取包含密钥的 Talk 配置。 | 未知的未来 `operator.*` 作用域需要精确匹配，除非调用方拥有 `operator.admin`。 -## 方法作用域只是第一道门槛 +## 方法作用域只是第一道检查 每个 Gateway 网关 RPC 都有一个最小权限方法作用域。该方法作用域决定 -请求是否可以到达处理程序。然后，一些处理程序会根据具体要批准或变更的对象， -在批准时应用更严格的检查。 +请求是否可以到达处理器。然后，一些处理器会根据正在批准或变更的具体对象 +应用更严格的批准时检查。 示例： -- `device.pair.approve` 可通过 `operator.pairing` 访问，但批准 +- `device.pair.approve` 可通过 `operator.pairing` 访问，但批准一个 operator 设备时，只能签发或保留调用方已经持有的作用域。 -- `node.pair.approve` 可通过 `operator.pairing` 访问，然后从待处理的节点命令列表中 - 派生额外的批准作用域。 -- `chat.send` 通常是写入作用域方法，但持久化的 `/config set` - 和 `/config unset` 在命令级别要求 `operator.admin`。 +- `node.pair.approve` 可通过 `operator.pairing` 访问，然后从待处理的 + 节点命令列表派生额外的批准作用域。 +- `chat.send` 通常是一个写入作用域方法，但持久化的 `/config set` + 和 `/config unset` 在命令级别需要 `operator.admin`。 -这让较低作用域的 operator 可以执行低风险配对操作，而不必让 -所有配对批准都只能由管理员执行。 +这让较低作用域的 operator 可以执行低风险配对操作，而无需把 +所有配对批准都设为仅管理员可用。 ## 设备配对批准 设备配对记录是已批准角色和作用域的持久来源。 -已配对设备不会静默获得更广泛访问权限：重新连接时如果请求 -更广泛角色或更广泛作用域，会创建新的待处理升级请求。 +已配对设备不会静默获得更大的访问权限：如果重连时请求更大的角色或更大的作用域， +会创建一个新的待处理升级请求。 批准设备请求时： @@ -79,35 +79,34 @@ Operator RPC 方法要求 `operator` 角色。节点发起的方法 `operator.pairing` 或 `operator.talk.secrets` 时，调用方必须持有 这些作用域，或持有 `operator.admin`。 - 请求 `operator.admin` 时需要 `operator.admin`。 -- 没有显式作用域的修复请求可以继承现有 operator - 令牌作用域。如果该现有令牌具有 admin 作用域，批准仍然需要 +- 没有显式作用域的修复请求可以继承现有 operator 令牌作用域。 + 如果该现有令牌带有管理员作用域，批准仍然需要 `operator.admin`。 -对于已配对设备令牌会话，除非调用方也拥有 `operator.admin`， -否则管理操作受自身作用域限制：非管理员调用方只能轮换、撤销或移除 -自己的设备条目。 +对于已配对设备的令牌会话，除非调用方同时拥有 `operator.admin`， +否则管理是自作用域的：非管理员调用方只能看到自己的配对条目， +只能批准或拒绝自己的待处理请求，并且只能轮换、吊销或移除自己的设备条目。 ## 节点配对批准 -旧版 `node.pair.*` 使用单独的 Gateway 网关拥有的节点配对存储。WS 节点 -使用带有 `role: node` 的设备配对，但适用相同的批准级别词汇。 +旧版 `node.pair.*` 使用一个独立的 Gateway 网关拥有的节点配对存储。 +WS 节点使用带有 `role: node` 的设备配对，但适用相同的批准级别词汇。 -`node.pair.approve` 使用待处理请求命令列表来派生额外的 -必需作用域： +`node.pair.approve` 使用待处理请求命令列表来派生额外的必需作用域： - 无命令请求：`operator.pairing` - 非 exec 节点命令：`operator.pairing` + `operator.write` - `system.run`、`system.run.prepare` 或 `system.which`： `operator.pairing` + `operator.admin` -节点配对建立身份和信任。它不会替代节点自身的 +节点配对建立身份和信任。它不会替代节点自己的 `system.run` exec 批准策略。 -## 共享密钥认证 +## 共享密钥身份验证 -共享 gateway 令牌/密码认证会被视为该 Gateway 网关的受信任 operator 访问。 -OpenAI 兼容 HTTP 接口和 `/tools/invoke` 会为共享密钥 bearer 认证 -恢复正常的完整 operator 默认作用域集合，即使调用方发送了更窄的声明作用域。 +共享 Gateway 网关令牌/密码身份验证会被视为该 Gateway 网关的受信任 operator 访问。 +OpenAI 兼容 HTTP surface 和 `/tools/invoke` 会为共享密钥 bearer 身份验证恢复 +常规的完整 operator 默认作用域集，即使调用方发送了更窄的声明作用域。 -带身份的模式，例如受信任代理认证或私有入口 `none`， -仍然可以遵守显式声明的作用域。对于真正的信任边界隔离，请使用独立的 Gateway 网关。 +带身份的模式，例如受信任代理身份验证或私有入口 `none`， +仍然可以遵循显式声明的作用域。请使用独立的 Gateway 网关来实现真正的信任边界隔离。