diff --git a/docs/zh-CN/gateway/protocol.md b/docs/zh-CN/gateway/protocol.md index e4e275c7f..69cea3186 100644 --- a/docs/zh-CN/gateway/protocol.md +++ b/docs/zh-CN/gateway/protocol.md @@ -6,10 +6,10 @@ read_when: summary: Gateway 网关 WebSocket 协议：握手、帧、版本控制 title: Gateway 网关协议 x-i18n: - generated_at: "2026-04-25T22:27:13Z" + generated_at: "2026-04-25T23:29:48Z" model: gpt-5.4 provider: openai - source_hash: a2411ebd50a883028e2d8e88a4a79e4c1350cefd37a12f293de9686e3bc067ea + source_hash: 2640b0bb9e3d0291ee10d6e0b23c7f0b200db19ec90a1079dadbcc4f4bb2abf5 source_path: gateway/protocol.md workflow: 15 --- @@ -18,9 +18,9 @@ Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输层** ## 传输 -- WebSocket，带有 JSON 负载的文本帧。 +- WebSocket，使用带有 JSON 负载的文本帧。 - 第一帧**必须**是一个 `connect` 请求。 -- 连接前帧的上限为 64 KiB。握手成功后，客户端应遵循 `hello-ok.policy.maxPayload` 和 `hello-ok.policy.maxBufferedBytes` 限制。启用诊断后，过大的入站帧和缓慢的出站缓冲区会在 Gateway 网关关闭连接或丢弃受影响帧之前发出 `payload.large` 事件。这些事件会保留大小、限制、表面以及安全原因代码。它们不会保留消息正文、附件内容、原始帧正文、令牌、Cookie 或秘密值。 +- 连接前帧大小上限为 64 KiB。成功握手后，客户端应遵循 `hello-ok.policy.maxPayload` 和 `hello-ok.policy.maxBufferedBytes` 限制。启用诊断时，过大的入站帧和缓慢的出站缓冲区会在 Gateway 网关关闭连接或丢弃受影响帧之前发出 `payload.large` 事件。这些事件会保留大小、限制、表面以及安全原因代码。它们不会保留消息正文、附件内容、原始帧正文、令牌、cookies 或密钥值。 ## 握手（connect） @@ -91,7 +91,7 @@ Gateway 网关 → 客户端： } ``` -`server`、`features`、`snapshot` 和 `policy` 都是 schema（`src/gateway/protocol/schema/frames.ts`）要求的必填项。`canvasHostUrl` 是可选项。`auth` 会在可用时报告协商后的角色/作用域，并在 Gateway 网关签发设备令牌时包含 `deviceToken`。 +`server`、`features`、`snapshot` 和 `policy` 都是 schema（`src/gateway/protocol/schema/frames.ts`）要求的字段。`canvasHostUrl` 是可选的。`auth` 会在可用时报告协商后的角色/作用域，并在 Gateway 网关签发设备令牌时包含 `deviceToken`。 未签发设备令牌时，`hello-ok.auth` 仍然可以报告协商后的权限： @@ -104,7 +104,7 @@ Gateway 网关 → 客户端： } ``` -受信任的同进程后端客户端（`client.id: "gateway-client"`、`client.mode: "backend"`）在使用共享 Gateway 网关 token/password 通过直接 loopback 连接进行身份验证时，可以省略 `device`。此路径保留用于内部控制平面 RPC，可避免过期的 CLI/设备配对基线阻碍本地后端工作，例如子智能体会话更新。远程客户端、浏览器来源客户端、节点客户端以及显式设备令牌/设备身份客户端仍然使用常规配对和作用域升级检查。 +受信任的同进程后端客户端（`client.id: "gateway-client"`、`client.mode: "backend"`）在使用共享 Gateway 网关令牌/密码通过直接 loopback 连接进行身份验证时，可以省略 `device`。该路径保留给内部控制平面 RPC，以避免过期的 CLI/设备配对基线阻碍本地后端工作，例如子智能体会话更新。远程客户端、浏览器来源客户端、节点客户端，以及显式使用设备令牌/设备身份的客户端，仍然使用常规的配对和作用域升级检查。 签发设备令牌时，`hello-ok` 还会包含： @@ -118,7 +118,7 @@ Gateway 网关 → 客户端： } ``` -在受信任的引导交接期间，`hello-ok.auth` 还可能在 `deviceTokens` 中包含额外的有界角色条目： +在受信任的引导移交流程中，`hello-ok.auth` 还可能在 `deviceTokens` 中包含额外的有界角色条目： ```json { @@ -137,7 +137,7 @@ Gateway 网关 → 客户端： } ``` -对于内置的 node/operator 引导流程，主 node 令牌保持 `scopes: []`，而任何交接的 operator 令牌都保持受限于引导 operator 允许列表（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）。引导作用域检查保持按角色前缀区分：operator 条目只满足 operator 请求，而非 operator 角色仍然需要其自身角色前缀下的作用域。 +对于内置的节点/操作员引导流程，主节点令牌保持为 `scopes: []`，任何移交的 operator 令牌都保持受限于引导 operator 允许列表（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）。引导作用域检查仍保持按角色前缀匹配：operator 条目只满足 operator 请求，非 operator 角色仍然需要其自身角色前缀下的作用域。 ### 节点示例 @@ -180,7 +180,7 @@ Gateway 网关 → 客户端： - **响应**：`{type:"res", id, ok, payload|error}` - **事件**：`{type:"event", event, payload, seq?, stateVersion?}` -具有副作用的方法需要 **idempotency keys**（参见 schema）。 +具有副作用的方法需要 **idempotency keys**（见 schema）。 ## 角色 + 作用域 @@ -204,103 +204,103 @@ Gateway 网关 → 客户端： 由插件注册的 Gateway 网关 RPC 方法可以请求它们自己的 operator 作用域，但保留的核心管理前缀（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终解析为 `operator.admin`。 -方法作用域只是第一道关卡。某些通过 `chat.send` 到达的斜杠命令会在此基础上应用更严格的命令级检查。例如，持久化的 `/config set` 和 `/config unset` 写入需要 `operator.admin`。 +方法作用域只是第一道关卡。某些通过 `chat.send` 到达的斜杠命令还会叠加更严格的命令级检查。例如，持久化的 `/config set` 和 `/config unset` 写入需要 `operator.admin`。 -`node.pair.approve` 在基础方法作用域之上还有额外的审批时作用域检查： +`node.pair.approve` 在基础方法作用域之上也有额外的审批时作用域检查： - 无命令请求：`operator.pairing` - 带有非 exec 节点命令的请求：`operator.pairing` + `operator.write` - 包含 `system.run`、`system.run.prepare` 或 `system.which` 的请求： `operator.pairing` + `operator.admin` -### Caps/commands/permissions（node） +### caps/commands/permissions（node） -节点在连接时声明能力声明： +节点在连接时声明其能力主张： - `caps`：高层能力类别。 - `commands`：用于 invoke 的命令允许列表。 - `permissions`：细粒度开关（例如 `screen.record`、`camera.capture`）。 -Gateway 网关将这些视为**声明**，并执行服务端允许列表。 +Gateway 网关将这些视为**声明**，并在服务端实施允许列表。 ## 在线状态 - `system-presence` 返回按设备身份键控的条目。 -- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，因此 UI 即使在设备同时以 **operator** 和 **node** 身份连接时，也能为其显示单独一行。 +- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，这样 UI 即使在设备同时以 **operator** 和 **node** 身份连接时，也能为其显示单独一行。 -## 广播事件作用域限制 +## 广播事件作用域 -服务端推送的 WebSocket 广播事件受作用域门控，因此仅具备配对作用域或仅节点的会话不会被动接收会话内容。 +服务器推送的 WebSocket 广播事件会进行作用域门控，以便仅具备配对作用域或仅节点的会话不会被动接收会话内容。 -- **聊天、智能体和工具结果帧**（包括流式 `agent` 事件和工具调用结果）至少需要 `operator.read`。没有 `operator.read` 的会话会完全跳过这些帧。 -- **插件定义的 `plugin.*` 广播** 会根据插件注册方式，门控到 `operator.write` 或 `operator.admin`。 +- **聊天、智能体和工具结果帧**（包括流式 `agent` 事件和工具调用结果）至少需要 `operator.read`。不具备 `operator.read` 的会话将完全跳过这些帧。 +- **插件定义的 `plugin.*` 广播** 会根据插件注册方式，被门控到 `operator.write` 或 `operator.admin`。 - **Status 和传输事件**（`heartbeat`、`presence`、`tick`、连接/断开生命周期等）保持不受限制，以便每个已认证会话都能观察传输健康状态。 -- **未知广播事件族** 默认受作用域门控（默认关闭，fail-closed），除非注册的处理程序明确放宽它们。 +- **未知广播事件族** 默认进行作用域门控（默认拒绝），除非已注册的处理器显式放宽限制。 -每个客户端连接都保留自己的每客户端序列号，因此即使不同客户端看到的事件流子集因作用域过滤而不同，广播在该 socket 上仍保持单调顺序。 +每个客户端连接都维护自己的每客户端序列号，因此即使不同客户端看到的是经过不同作用域过滤后的事件流子集，广播在该 socket 上仍会保持单调顺序。 ## 常见 RPC 方法族 -公共 WS 表面比上面的握手/认证示例更广。这不是生成的导出——`hello-ok.features.methods` 是一个保守的发现列表，基于 `src/gateway/server-methods-list.ts` 加上已加载插件/渠道方法导出构建。应将其视为功能发现，而不是对 `src/gateway/server-methods/*.ts` 的完整枚举。 +公开的 WS 表面比上面的握手/认证示例更广。这不是生成的导出结果——`hello-ok.features.methods` 是根据 `src/gateway/server-methods-list.ts` 以及已加载的插件/渠道方法导出构建的保守发现列表。应将其视为功能发现，而不是 `src/gateway/server-methods/*.ts` 的完整枚举。 - `health` 返回缓存的或新探测的 Gateway 网关健康快照。 - - `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它会保留操作元数据，例如事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称以及会话 id。它不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie 或秘密值。需要 operator.read 作用域。 - - `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅包含在具有 admin 作用域的 operator 客户端中。 - - `gateway.identity.get` 返回用于 relay 和配对流程的 Gateway 网关设备身份。 + - `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它会保留诸如事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称以及会话 id 等运维元数据。它不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、cookies 或密钥值。需要 operator 读取作用域。 + - `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅对具备 admin 作用域的 operator 客户端包含。 + - `gateway.identity.get` 返回 relay 和配对流程使用的 Gateway 网关设备身份。 - `system-presence` 返回当前已连接 operator/node 设备的在线状态快照。 - - `system-event` 追加一个系统事件，并且可以更新/广播在线状态上下文。 - - `last-heartbeat` 返回最新持久化的心跳事件。 - - `set-heartbeats` 切换 Gateway 网关上的心跳处理。 + - `system-event` 追加一条系统事件，并可更新/广播在线状态上下文。 + - `last-heartbeat` 返回最新持久化的 heartbeat 事件。 + - `set-heartbeats` 切换 Gateway 网关上的 heartbeat 处理。 - `models.list` 返回运行时允许的模型目录。 - `usage.status` 返回提供商用量窗口/剩余额度摘要。 - - `usage.cost` 返回某个日期范围的聚合成本用量摘要。 - - `doctor.memory.status` 返回活动默认智能体工作区的向量内存 / embedding 就绪状态。 - - `sessions.usage` 返回每个会话的用量摘要。 + - `usage.cost` 返回某个日期范围内聚合的成本用量摘要。 + - `doctor.memory.status` 返回活动默认智能体工作区的向量 memory / embedding 就绪状态。 + - `sessions.usage` 返回按会话划分的用量摘要。 - `sessions.usage.timeseries` 返回单个会话的时序用量。 - `sessions.usage.logs` 返回单个会话的用量日志条目。 - `channels.status` 返回内置 + 内置打包渠道/插件的 Status 摘要。 - - `channels.logout` 在渠道支持登出的情况下，登出特定渠道/账户。 - - `web.login.start` 为当前支持 QR/web 登录的 web 渠道提供商启动一个 QR/web 登录流程。 - - `web.login.wait` 等待该 QR/web 登录流程完成，并在成功后启动渠道。 - - `push.test` 向已注册的 iOS 节点发送一个测试 APNs 推送。 + - `channels.logout` 在渠道支持登出的情况下，为特定渠道/账号执行登出。 + - `web.login.start` 为当前支持 QR/web 登录的 web 渠道提供商启动 QR/web 登录流程。 + - `web.login.wait` 等待该 QR/web 登录流程完成，并在成功时启动该渠道。 + - `push.test` 向已注册的 iOS 节点发送测试 APNs 推送。 - `voicewake.get` 返回已存储的唤醒词触发器。 - `voicewake.set` 更新唤醒词触发器并广播更改。 - - `send` 是聊天运行器之外、针对渠道/账户/线程目标发送的直接出站投递 RPC。 + - `send` 是直接的出站投递 RPC，用于在 chat runner 之外按渠道/账号/线程目标发送消息。 - `logs.tail` 返回已配置的 Gateway 网关文件日志尾部，支持 cursor/limit 和最大字节控制。 - - `talk.config` 返回有效的 Talk 配置负载；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。 + - `talk.config` 返回生效中的 Talk 配置负载；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。 - `talk.mode` 为 WebChat/Control UI 客户端设置/广播当前 Talk 模式状态。 - - `talk.speak` 通过活动的 Talk speech 提供商合成语音。 - - `tts.status` 返回 TTS 启用状态、活动提供商、后备提供商以及提供商配置状态。 + - `talk.speak` 通过当前活动的 Talk 语音提供商合成语音。 + - `tts.status` 返回 TTS 启用状态、活动提供商、回退提供商以及提供商配置状态。 - `tts.providers` 返回可见的 TTS 提供商清单。 - `tts.enable` 和 `tts.disable` 切换 TTS 偏好状态。 - `tts.setProvider` 更新首选 TTS 提供商。 - - `tts.convert` 运行一次性文本转语音转换。 + - `tts.convert` 执行一次性 text-to-speech 转换。 - - - `secrets.reload` 重新解析活动 SecretRefs，并且仅在完全成功时替换运行时秘密状态。 - - `secrets.resolve` 为特定命令/目标集合解析面向命令目标的秘密分配。 + + - `secrets.reload` 重新解析活动的 SecretRefs，并且仅在完全成功时才切换运行时密钥状态。 + - `secrets.resolve` 为特定的命令/目标集合解析命令目标密钥分配。 - `config.get` 返回当前配置快照和哈希值。 - `config.set` 写入经过验证的配置负载。 - `config.patch` 合并部分配置更新。 - `config.apply` 验证并替换完整配置负载。 - - `config.schema` 返回 Control UI 和 CLI 工具使用的实时配置 schema 负载：schema、`uiHints`、版本和生成元数据，包括在运行时可以加载时的插件 + 渠道 schema 元数据。该 schema 包含字段 `title` / `description` 元数据，来源于 UI 使用的相同标签和帮助文本；在存在匹配字段文档时，也包括嵌套对象、通配符、数组项以及 `anyOf` / `oneOf` / `allOf` 组合分支。 - - `config.schema.lookup` 为单个配置路径返回路径范围查找负载：规范化路径、浅层 schema 节点、匹配的提示 + `hintPath`，以及供 UI/CLI 逐层钻取的直接子项摘要。查找 schema 节点保留面向用户的文档和常见验证字段（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数值/字符串/数组/对象边界，以及 `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` 等标记）。子项摘要公开 `key`、规范化后的 `path`、`type`、`required`、`hasChildren`，以及匹配的 `hint` / `hintPath`。 - - `update.run` 运行 Gateway 网关更新流程，并且仅在更新本身成功时安排重启。 + - `config.schema` 返回 Control UI 和 CLI 工具使用的实时配置 schema 负载：schema、`uiHints`、版本和生成元数据，包括在运行时可加载时的插件 + 渠道 schema 元数据。该 schema 包含字段 `title` / `description` 元数据，这些元数据源自 UI 使用的相同标签和帮助文本；如果存在匹配的字段文档，也包括嵌套对象、通配符、数组项以及 `anyOf` / `oneOf` / `allOf` 组合分支。 + - `config.schema.lookup` 为单个配置路径返回按路径限定的查找负载：规范化路径、浅层 schema 节点、匹配的 hint + `hintPath`，以及用于 UI/CLI 逐级深入的直接子项摘要。查找 schema 节点保留面向用户的文档和常见验证字段（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数值/字符串/数组/对象边界，以及 `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` 等标记）。子项摘要公开 `key`、规范化后的 `path`、`type`、`required`、`hasChildren`，以及匹配的 `hint` / `hintPath`。 + - `update.run` 运行 Gateway 网关更新流程，并且仅在更新本身成功时才安排重启。 - `wizard.start`、`wizard.next`、`wizard.status` 和 `wizard.cancel` 通过 WS RPC 暴露新手引导向导。 @@ -309,15 +309,15 @@ Gateway 网关将这些视为**声明**，并执行服务端允许列表。 - `agents.create`、`agents.update` 和 `agents.delete` 管理智能体记录和工作区连接。 - `agents.files.list`、`agents.files.get` 和 `agents.files.set` 管理为某个智能体公开的引导工作区文件。 - `agent.identity.get` 返回某个智能体或会话的有效助手身份。 - - `agent.wait` 等待某次运行完成，并在可用时返回终态快照。 + - `agent.wait` 等待某次运行结束，并在可用时返回终态快照。 - `sessions.list` 返回当前会话索引。 - `sessions.subscribe` 和 `sessions.unsubscribe` 为当前 WS 客户端切换会话变更事件订阅。 - - `sessions.messages.subscribe` 和 `sessions.messages.unsubscribe` 为单个会话切换 transcript/消息事件订阅。 - - `sessions.preview` 返回特定会话键的有界 transcript 预览。 - - `sessions.resolve` 解析或规范化会话目标。 + - `sessions.messages.subscribe` 和 `sessions.messages.unsubscribe` 为单个会话切换转录/消息事件订阅。 + - `sessions.preview` 返回特定会话键的有界转录预览。 + - `sessions.resolve` 解析或规范化某个会话目标。 - `sessions.create` 创建新的会话条目。 - `sessions.send` 向现有会话发送消息。 - `sessions.steer` 是活动会话的中断并引导变体。 @@ -325,113 +325,113 @@ Gateway 网关将这些视为**声明**，并执行服务端允许列表。 - `sessions.patch` 更新会话元数据/覆盖项。 - `sessions.reset`、`sessions.delete` 和 `sessions.compact` 执行会话维护。 - `sessions.get` 返回完整存储的会话行。 - - 聊天执行仍然使用 `chat.history`、`chat.send`、`chat.abort` 和 `chat.inject`。对 UI 客户端来说，`chat.history` 已做显示规范化：可见文本中的内联指令标签会被剥离，纯文本工具调用 XML 负载（包括 `...`、`...`、`...`、`...` 以及被截断的工具调用块）和泄露的 ASCII/全角模型控制令牌会被剥离，纯静默令牌的助手行（例如精确的 `NO_REPLY` / `no_reply`）会被省略，过大的行可能会被占位符替换。 + - 聊天执行仍然使用 `chat.history`、`chat.send`、`chat.abort` 和 `chat.inject`。`chat.history` 针对 UI 客户端进行了显示规范化：内联指令标签会从可见文本中移除，纯文本工具调用 XML 负载（包括 `...`、`...`、`...`、`...` 以及被截断的工具调用块）和泄露的 ASCII/全角模型控制令牌会被移除，像精确 `NO_REPLY` / `no_reply` 这样的纯静默令牌助手行会被省略，过大的行可被占位符替换。 - `device.pair.list` 返回待处理和已批准的配对设备。 - `device.pair.approve`、`device.pair.reject` 和 `device.pair.remove` 管理设备配对记录。 - - `device.token.rotate` 在已批准的角色和作用域边界内轮换某个配对设备令牌。 - - `device.token.revoke` 撤销某个配对设备令牌。 + - `device.token.rotate` 在已批准的角色和作用域边界内轮换已配对设备令牌。 + - `device.token.revoke` 撤销已配对设备令牌。 - `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject` 和 `node.pair.verify` 涵盖节点配对和引导验证。 - - `node.list` 和 `node.describe` 返回已知/已连接节点状态。 - - `node.rename` 更新某个已配对节点标签。 + - `node.list` 和 `node.describe` 返回已知/已连接的节点状态。 + - `node.rename` 更新已配对节点标签。 - `node.invoke` 将命令转发到已连接节点。 - - `node.invoke.result` 返回某个 invoke 请求的结果。 - - `node.event` 将节点来源事件携回 Gateway 网关。 - - `node.canvas.capability.refresh` 刷新带作用域的 canvas 能力令牌。 - - `node.pending.pull` 和 `node.pending.ack` 是已连接节点队列 API。 + - `node.invoke.result` 返回调用请求的结果。 + - `node.event` 将源自节点的事件携回 Gateway 网关。 + - `node.canvas.capability.refresh` 刷新按作用域限定的 canvas 能力令牌。 + - `node.pending.pull` 和 `node.pending.ack` 是已连接节点的队列 API。 - `node.pending.enqueue` 和 `node.pending.drain` 管理离线/断开连接节点的持久待处理工作。 - - `exec.approval.request`、`exec.approval.get`、`exec.approval.list` 和 `exec.approval.resolve` 涵盖一次性 exec 审批请求，以及待处理审批的查找/重放。 - - `exec.approval.waitDecision` 等待一个待处理 exec 审批并返回最终决定（或在超时时返回 `null`）。 + - `exec.approval.request`、`exec.approval.get`、`exec.approval.list` 和 `exec.approval.resolve` 涵盖一次性 exec 审批请求以及待处理审批的查找/重放。 + - `exec.approval.waitDecision` 等待一个待处理 exec 审批，并返回最终决定（或在超时时返回 `null`）。 - `exec.approvals.get` 和 `exec.approvals.set` 管理 Gateway 网关 exec 审批策略快照。 - `exec.approvals.node.get` 和 `exec.approvals.node.set` 通过节点 relay 命令管理节点本地 exec 审批策略。 - `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision` 和 `plugin.approval.resolve` 涵盖插件定义的审批流程。 - - 自动化：`wake` 安排立即或下一次心跳时注入唤醒文本；`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` 管理计划工作。 + - 自动化：`wake` 调度立即或下一个 heartbeat 的唤醒文本注入；`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` 管理定时工作。 - Skills 和工具：`commands.list`、`skills.*`、`tools.catalog`、`tools.effective`。 ### 常见事件族 -- `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅 transcript 的聊天事件。 -- `session.message` 和 `session.tool`：已订阅会话的 transcript/事件流更新。 -- `sessions.changed`：会话索引或元数据已变更。 +- `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅转录的聊天事件。 +- `session.message` 和 `session.tool`：已订阅会话的转录/事件流更新。 +- `sessions.changed`：会话索引或元数据已更改。 - `presence`：系统在线状态快照更新。 -- `tick`：周期性 keepalive / 存活性事件。 +- `tick`：周期性 keepalive / 存活事件。 - `health`：Gateway 网关健康快照更新。 -- `heartbeat`：心跳事件流更新。 -- `cron`：cron 运行/任务变更事件。 +- `heartbeat`：heartbeat 事件流更新。 +- `cron`：cron 运行/作业更改事件。 - `shutdown`：Gateway 网关关闭通知。 - `node.pair.requested` / `node.pair.resolved`：节点配对生命周期。 -- `node.invoke.request`：节点 invoke 请求广播。 -- `device.pair.requested` / `device.pair.resolved`：配对设备生命周期。 -- `voicewake.changed`：唤醒词触发器配置已变更。 +- `node.invoke.request`：节点调用请求广播。 +- `device.pair.requested` / `device.pair.resolved`：已配对设备生命周期。 +- `voicewake.changed`：唤醒词触发器配置已更改。 - `exec.approval.requested` / `exec.approval.resolved`：exec 审批生命周期。 - `plugin.approval.requested` / `plugin.approval.resolved`：插件审批生命周期。 ### 节点辅助方法 -- 节点可以调用 `skills.bins` 以获取当前技能可执行文件列表，用于自动允许检查。 +- 节点可以调用 `skills.bins` 来获取当前 Skills 可执行文件列表，以用于自动允许检查。 ### operator 辅助方法 -- operator 可以调用 `commands.list`（`operator.read`）以获取某个智能体的运行时命令清单。 - - `agentId` 是可选项；省略时读取默认智能体工作区。 - - `scope` 控制主 `name` 目标对应哪个表面： +- operator 可以调用 `commands.list`（`operator.read`）来获取某个智能体的运行时命令清单。 + - `agentId` 是可选的；省略它即可读取默认智能体工作区。 + - `scope` 控制主 `name` 针对哪个表面： - `text` 返回不带前导 `/` 的主文本命令令牌 - - `native` 和默认的 `both` 路径会在可用时返回具备 provider 感知的原生命名 + - `native` 和默认的 `both` 路径会在可用时返回提供商感知的原生命名 - `textAliases` 携带精确的斜杠别名，例如 `/model` 和 `/m`。 - - `nativeName` 在存在时携带具备 provider 感知的原生命令名。 - - `provider` 是可选项，只影响原生命名以及原生插件命令可用性。 - - `includeArgs=false` 会从响应中省略序列化参数元数据。 -- operator 可以调用 `tools.catalog`（`operator.read`）以获取某个智能体的运行时工具目录。响应包含分组工具和来源元数据： + - `nativeName` 在存在时携带提供商感知的原生命令名称。 + - `provider` 是可选的，仅影响原生命名以及原生插件命令可用性。 + - `includeArgs=false` 会从响应中省略序列化的参数元数据。 +- operator 可以调用 `tools.catalog`（`operator.read`）来获取某个智能体的运行时工具目录。响应包括分组工具和来源元数据： - `source`：`core` 或 `plugin` - `pluginId`：当 `source="plugin"` 时的插件所有者 - - `optional`：某个插件工具是否为可选 -- operator 可以调用 `tools.effective`（`operator.read`）以获取某个会话的运行时有效工具清单。 - - `sessionKey` 为必填。 - - Gateway 网关从服务端的会话派生受信任运行时上下文，而不是接受调用方提供的 auth 或投递上下文。 - - 响应按会话范围限定，并反映当前活动对话此刻可使用的内容，包括 core、plugin 和渠道工具。 -- operator 可以调用 `skills.status`（`operator.read`）以获取某个智能体的可见技能清单。 - - `agentId` 是可选项；省略时读取默认智能体工作区。 - - 响应包含资格、缺失要求、配置检查和已清理的安装选项，但不会暴露原始秘密值。 -- operator 可以调用 `skills.search` 和 `skills.detail`（`operator.read`）以获取 ClawHub 发现元数据。 -- operator 可以调用 `skills.install`（`operator.admin`），支持两种模式： - - ClawHub 模式：`{ source: "clawhub", slug, version?, force? }` 将某个技能文件夹安装到默认智能体工作区的 `skills/` 目录。 + - `optional`：某个插件工具是否可选 +- operator 可以调用 `tools.effective`（`operator.read`）来获取某个会话的运行时生效工具清单。 + - `sessionKey` 是必需的。 + - Gateway 网关会在服务端从会话中推导受信任的运行时上下文，而不是接受调用方提供的认证或投递上下文。 + - 响应按会话限定，并反映当前活动对话此刻可使用的内容，包括核心、插件和渠道工具。 +- operator 可以调用 `skills.status`（`operator.read`）来获取某个智能体可见的 Skills 清单。 + - `agentId` 是可选的；省略它即可读取默认智能体工作区。 + - 响应包括资格、缺失要求、配置检查和已净化的安装选项，而不会暴露原始密钥值。 +- operator 可以调用 `skills.search` 和 `skills.detail`（`operator.read`）来获取 ClawHub 发现元数据。 +- operator 可以用两种模式调用 `skills.install`（`operator.admin`）： + - ClawHub 模式：`{ source: "clawhub", slug, version?, force? }` 将一个 skill 文件夹安装到默认智能体工作区的 `skills/` 目录中。 - Gateway 网关安装器模式：`{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` 在 Gateway 网关主机上运行声明的 `metadata.openclaw.install` 操作。 -- operator 可以调用 `skills.update`（`operator.admin`），支持两种模式： - - ClawHub 模式更新一个已跟踪 slug，或更新默认智能体工作区中的所有已跟踪 ClawHub 安装项。 - - 配置模式修补 `skills.entries.` 值，例如 `enabled`、`apiKey` 和 `env`。 +- operator 可以用两种模式调用 `skills.update`（`operator.admin`）： + - ClawHub 模式会更新一个已跟踪的 slug，或更新默认智能体工作区中所有已跟踪的 ClawHub 安装项。 + - 配置模式会修补 `skills.entries.` 值，例如 `enabled`、`apiKey` 和 `env`。 ## Exec 审批 - 当某个 exec 请求需要审批时，Gateway 网关会广播 `exec.approval.requested`。 -- operator 客户端通过调用 `exec.approval.resolve` 来处理（需要 `operator.approvals` 作用域）。 +- operator 客户端通过调用 `exec.approval.resolve` 来完成处理（需要 `operator.approvals` 作用域）。 - 对于 `host=node`，`exec.approval.request` 必须包含 `systemRunPlan`（规范的 `argv`/`cwd`/`rawCommand`/会话元数据）。缺少 `systemRunPlan` 的请求会被拒绝。 -- 审批完成后，被转发的 `node.invoke system.run` 调用会复用该规范 `systemRunPlan`，作为权威的命令/cwd/会话上下文。 -- 如果调用方在 prepare 和最终获批的 `system.run` 转发之间修改了 `command`、`rawCommand`、`cwd`、`agentId` 或 `sessionKey`，Gateway 网关会拒绝此次运行，而不是信任被修改的负载。 +- 审批通过后，转发的 `node.invoke system.run` 调用会重用该规范 `systemRunPlan`，作为权威的命令/cwd/会话上下文。 +- 如果调用方在 prepare 和最终获批的 `system.run` 转发之间篡改了 `command`、`rawCommand`、`cwd`、`agentId` 或 `sessionKey`，Gateway 网关会拒绝此次运行，而不是信任被篡改的负载。 ## 智能体投递回退 -- `agent` 请求可以包含 `deliver=true`，以请求出站投递。 -- `bestEffortDeliver=false` 保持严格行为：未解析或仅内部的投递目标会返回 `INVALID_REQUEST`。 -- `bestEffortDeliver=true` 允许在无法解析外部可投递路由时回退到仅会话执行（例如内部/webchat 会话或有歧义的多渠道配置）。 +- `agent` 请求可以包含 `deliver=true` 来请求出站投递。 +- `bestEffortDeliver=false` 保持严格行为：无法解析或仅内部的投递目标会返回 `INVALID_REQUEST`。 +- `bestEffortDeliver=true` 允许在无法解析到外部可投递路径时回退为仅会话执行（例如内部/webchat 会话或含糊的多渠道配置）。 ## 版本控制 - `PROTOCOL_VERSION` 位于 `src/gateway/protocol/schema/protocol-schemas.ts`。 -- 客户端发送 `minProtocol` + `maxProtocol`；服务端会拒绝不匹配情况。 +- 客户端发送 `minProtocol` + `maxProtocol`；服务器会拒绝不匹配的情况。 - Schemas + 模型由 TypeBox 定义生成： - `pnpm protocol:gen` - `pnpm protocol:gen:swift` @@ -439,68 +439,68 @@ Gateway 网关将这些视为**声明**，并执行服务端允许列表。 ### 客户端常量 -`src/gateway/client.ts` 中的参考客户端使用这些默认值。这些值在协议 v3 中保持稳定，也是第三方客户端的预期基线。 +`src/gateway/client.ts` 中的参考客户端使用这些默认值。这些值在协议 v3 中保持稳定，并且是第三方客户端的预期基线。 | 常量 | 默认值 | 来源 | | ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | | `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | | 请求超时（每个 RPC） | `30_000` ms | `src/gateway/client.ts`（`requestTimeoutMs`） | -| 预认证 / 连接质询超时 | `10_000` ms | `src/gateway/handshake-timeouts.ts`（限制为 `250`–`10_000`） | +| 预认证 / connect-challenge 超时 | `10_000` ms | `src/gateway/handshake-timeouts.ts`（限制在 `250`–`10_000`） | | 初始重连退避 | `1_000` ms | `src/gateway/client.ts`（`backoffMs`） | | 最大重连退避 | `30_000` ms | `src/gateway/client.ts`（`scheduleReconnect`） | | 设备令牌关闭后的快速重试限制 | `250` ms | `src/gateway/client.ts` | | `terminate()` 前的强制停止宽限期 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | | `stopAndWait()` 默认超时 | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | -| 默认 tick 间隔（`hello-ok` 之前） | `30_000` ms | `src/gateway/client.ts` | +| 默认 tick 间隔（`hello-ok` 前） | `30_000` ms | `src/gateway/client.ts` | | tick 超时关闭 | 当静默超过 `tickIntervalMs * 2` 时使用代码 `4000` | `src/gateway/client.ts` | | `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024`（25 MB） | `src/gateway/server-constants.ts` | -服务端会在 `hello-ok` 中公布有效的 `policy.tickIntervalMs`、`policy.maxPayload` 和 `policy.maxBufferedBytes`；客户端应遵循这些值，而不是握手前的默认值。 +服务器会在 `hello-ok` 中公布生效的 `policy.tickIntervalMs`、`policy.maxPayload` 和 `policy.maxBufferedBytes`；客户端应遵循这些值，而不是握手前的默认值。 ## 认证 -- 共享密钥 Gateway 网关认证使用 `connect.params.auth.token` 或 `connect.params.auth.password`，取决于已配置的认证模式。 -- 带身份的模式，例如 Tailscale Serve（`gateway.auth.allowTailscale: true`）或非 loopback 的 `gateway.auth.mode: "trusted-proxy"`，会通过请求头而不是 `connect.params.auth.*` 来满足连接认证检查。 -- 私有入口 `gateway.auth.mode: "none"` 会完全跳过共享密钥连接认证；不要在公共/不受信任入口上暴露此模式。 -- 配对后，Gateway 网关会签发一个按连接角色 + 作用域限定的**设备令牌**。它会在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化，以供将来连接使用。 +- 基于共享密钥的 Gateway 网关认证使用 `connect.params.auth.token` 或 `connect.params.auth.password`，具体取决于配置的认证模式。 +- 带身份的模式，例如 Tailscale Serve（`gateway.auth.allowTailscale: true`）或非 loopback 的 `gateway.auth.mode: "trusted-proxy"`，会从请求头而不是 `connect.params.auth.*` 满足连接认证检查。 +- 私有入口的 `gateway.auth.mode: "none"` 会完全跳过基于共享密钥的连接认证；不要在公共/不受信任的入口上暴露该模式。 +- 配对完成后，Gateway 网关会签发一个**设备令牌**，其作用域绑定到该连接的角色 + 作用域。它会在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化用于后续连接。 - 客户端应在任何成功连接后持久化主 `hello-ok.auth.deviceToken`。 -- 使用该**已存储**设备令牌重新连接时，也应复用该令牌已存储的已批准作用域集合。这样可以保留已授予的读取/探测/状态访问权限，并避免静默将重连收缩为更窄的隐式仅 admin 作用域。 +- 使用该**已存储**设备令牌重新连接时，也应重用为该令牌存储的已批准作用域集合。这样可以保留已授予的读取/探测/Status 访问权限，并避免重连时静默收缩为更窄的隐式仅 admin 作用域。 - 客户端侧连接认证组装（`src/gateway/client.ts` 中的 `selectConnectAuth`）： - - `auth.password` 是正交的，设置后总会被转发。 - - `auth.token` 按优先级顺序填充：首先是显式共享令牌，然后是显式 `deviceToken`，再然后是已存储的按设备令牌（按 `deviceId` + `role` 键控）。 - - 仅当以上都未解析出 `auth.token` 时才会发送 `auth.bootstrapToken`。共享令牌或任何已解析的设备令牌都会抑制它。 - - 在一次性 `AUTH_TOKEN_MISMATCH` 重试中自动提升已存储设备令牌的行为，仅对**受信任端点**开放——loopback，或带固定 `tlsFingerprint` 的 `wss://`。未固定的公共 `wss://` 不符合条件。 -- 额外的 `hello-ok.auth.deviceTokens` 条目是引导交接令牌。仅当连接在受信任传输（如 `wss://` 或 loopback/local pairing）上使用引导认证时，才应持久化它们。 -- 如果客户端提供了**显式** `deviceToken` 或显式 `scopes`，则调用方请求的该作用域集合仍然是权威值；仅当客户端复用已存储的按设备令牌时，才会复用缓存作用域。 + - `auth.password` 是正交的，设置时始终会被转发。 + - `auth.token` 按优先级填充：首先是显式共享令牌，然后是显式 `deviceToken`，最后是已存储的按设备令牌（按 `deviceId` + `role` 键控）。 + - `auth.bootstrapToken` 仅在上述方式都未解析出 `auth.token` 时才会发送。共享令牌或任何已解析的设备令牌都会抑制它。 + - 在一次性 `AUTH_TOKEN_MISMATCH` 重试中自动提升已存储设备令牌，只对**受信任端点**开放——loopback，或带固定 `tlsFingerprint` 的 `wss://`。未固定证书的公共 `wss://` 不符合条件。 +- 额外的 `hello-ok.auth.deviceTokens` 条目是引导移交令牌。只有当连接使用了受信任传输（如 `wss://` 或 loopback/本地配对）上的引导认证时，才应持久化它们。 +- 如果客户端提供了**显式** `deviceToken` 或显式 `scopes`，则调用方请求的该作用域集合仍然是权威的；仅当客户端正在重用已存储的按设备令牌时，才会重用缓存作用域。 - 设备令牌可以通过 `device.token.rotate` 和 `device.token.revoke` 轮换/撤销（需要 `operator.pairing` 作用域）。 -- 令牌签发/轮换始终受限于该设备配对条目中记录的已批准角色集合；轮换令牌不能将设备扩展到配对批准从未授予的角色。 +- 令牌签发/轮换始终受限于该设备配对条目中记录的已批准角色集合；轮换令牌不能把设备扩展到配对审批从未授予的角色。 - 对于配对设备令牌会话，除非调用方还具有 `operator.admin`，否则设备管理是自限定的：非 admin 调用方只能移除/撤销/轮换其**自己的**设备条目。 -- `device.token.rotate` 还会根据调用方当前会话作用域检查所请求的 operator 作用域集合。非 admin 调用方不能将令牌轮换为比其当前持有范围更广的 operator 作用域集合。 -- 认证失败会包含 `error.details.code` 和恢复提示： +- `device.token.rotate` 还会根据调用方当前会话作用域检查所请求的 operator 作用域集合。非 admin 调用方不能把令牌轮换到比自己当前持有更宽的 operator 作用域集合。 +- 认证失败会包含 `error.details.code` 以及恢复提示： - `error.details.canRetryWithDeviceToken`（布尔值） - `error.details.recommendedNextStep`（`retry_with_device_token`、`update_auth_configuration`、`update_auth_credentials`、`wait_then_retry`、`review_auth_configuration`） -- `AUTH_TOKEN_MISMATCH` 的客户端行为： +- 客户端对 `AUTH_TOKEN_MISMATCH` 的行为： - 受信任客户端可以尝试使用缓存的按设备令牌进行一次有界重试。 - - 如果该重试失败，客户端应停止自动重连循环，并向 operator 展示操作指引。 + - 如果该重试失败，客户端应停止自动重连循环，并提示 operator 采取操作。 ## 设备身份 + 配对 - 节点应包含稳定的设备身份（`device.id`），该身份派生自密钥对指纹。 -- Gateway 网关按设备 + 角色签发令牌。 -- 新设备 ID 需要配对批准，除非启用了本地自动批准。 -- 配对自动批准以直接本地 local loopback 连接为中心。 -- OpenClaw 还为受信任的共享密钥辅助流程提供了一条狭义的后端/容器本地自连接路径。 -- 同一主机上的 tailnet 或 LAN 连接在配对上仍被视为远程连接，并且需要批准。 -- 所有 WS 客户端都必须在 `connect` 期间包含 `device` 身份（operator + node）。 - 仅在以下模式下，Control UI 才可以省略它： +- Gateway 网关会按设备 + 角色签发令牌。 +- 新设备 ID 需要配对审批，除非启用了本地自动审批。 +- 配对自动审批以直接本地 local loopback 连接为中心。 +- OpenClaw 还提供一条狭窄的后端/容器本地自连接路径，用于受信任的共享密钥辅助流程。 +- 同主机 tailnet 或 LAN 连接在配对上仍被视为远程连接，并且需要审批。 +- WS 客户端通常会在 `connect` 期间包含 `device` 身份（operator + node）。唯一可无设备的 operator 例外是显式信任路径： - `gateway.controlUi.allowInsecureAuth=true`，用于仅 localhost 的不安全 HTTP 兼容性。 - 成功的 `gateway.auth.mode: "trusted-proxy"` operator Control UI 认证。 - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（紧急破玻璃开关，严重降低安全性）。 -- 所有连接都必须对服务端提供的 `connect.challenge` nonce 进行签名。 + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（紧急开关，严重安全降级）。 + - 使用共享 Gateway 网关令牌/密码认证的直接 loopback `gateway-client` 后端 RPC。 +- 所有连接都必须对服务器提供的 `connect.challenge` nonce 进行签名。 ### 设备认证迁移诊断 -对于仍使用质询前签名行为的旧客户端，`connect` 现在会在 `error.details.code` 下返回 `DEVICE_AUTH_*` 详细代码，并附带稳定的 `error.details.reason`。 +对于仍使用挑战前签名行为的旧版客户端，`connect` 现在会在 `error.details.code` 下返回 `DEVICE_AUTH_*` 详细代码，并在 `error.details.reason` 中提供稳定的原因值。 常见迁移失败： @@ -509,26 +509,26 @@ Gateway 网关将这些视为**声明**，并执行服务端允许列表。 | `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | 客户端省略了 `device.nonce`（或发送了空值）。 | | `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | 客户端使用了过期/错误的 nonce 进行签名。 | | `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 签名负载与 v2 负载不匹配。 | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 签名时间戳超出允许的时钟偏差。 | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 已签名时间戳超出允许的时钟偏差范围。 | | `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` 与公钥指纹不匹配。 | | `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | 公钥格式/规范化失败。 | 迁移目标： - 始终等待 `connect.challenge`。 -- 对包含服务端 nonce 的 v2 负载进行签名。 +- 对包含服务器 nonce 的 v2 负载进行签名。 - 在 `connect.params.device.nonce` 中发送相同的 nonce。 -- 首选签名负载是 `v3`，它除了 device/client/role/scopes/token/nonce 字段外，还绑定 `platform` 和 `deviceFamily`。 -- 为了兼容性，旧版 `v2` 签名仍然可接受，但配对设备元数据固定仍会在重连时控制命令策略。 +- 首选签名负载是 `v3`，它除设备/客户端/角色/作用域/令牌/nonce 字段外，还绑定 `platform` 和 `deviceFamily`。 +- 为了兼容性，旧版 `v2` 签名仍然被接受，但配对设备元数据固定仍会在重连时控制命令策略。 ## TLS + 固定 - WS 连接支持 TLS。 -- 客户端可以选择固定 Gateway 网关证书指纹（参见 `gateway.tls` 配置以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。 +- 客户端可以选择固定 Gateway 网关证书指纹（见 `gateway.tls` 配置，以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。 ## 范围 -该协议公开**完整 Gateway 网关 API**（状态、渠道、模型、聊天、智能体、会话、节点、审批等）。确切表面由 `src/gateway/protocol/schema.ts` 中的 TypeBox schemas 定义。 +该协议公开**完整的 Gateway 网关 API**（Status、渠道、模型、聊天、智能体、会话、节点、审批等）。确切表面由 `src/gateway/protocol/schema.ts` 中的 TypeBox schemas 定义。 ## 相关内容 diff --git a/docs/zh-CN/tools/subagents.md b/docs/zh-CN/tools/subagents.md index 6d94087e9..9dc48ad7d 100644 --- a/docs/zh-CN/tools/subagents.md +++ b/docs/zh-CN/tools/subagents.md @@ -1,24 +1,24 @@ --- read_when: - - 你希望通过智能体进行后台 / 并行工作 + - 你希望通过智能体进行后台/并行工作 - 你正在更改 `sessions_spawn` 或子智能体工具策略 - 你正在实现或排查线程绑定的子智能体会话 -summary: 子智能体：生成隔离的智能体运行，并将结果回报到请求者聊天中 +summary: 子智能体：生成独立的智能体运行，并将结果回报给请求者聊天会话 title: 子智能体 x-i18n: - generated_at: "2026-04-25T20:27:28Z" + generated_at: "2026-04-25T23:29:50Z" model: gpt-5.4 provider: openai - source_hash: 23483228f4ab9af27ff1f98c5e3fdbd2032e66f12be819d0d0a1ad5e51e7da11 + source_hash: b7fa747e677795b0e8a79e6c96e91a3ec5b74064c6d9f46149ad90b2d8c71322 source_path: tools/subagents.md workflow: 15 --- -子智能体是从现有智能体运行中生成的后台智能体运行。它们在自己的会话（`agent::subagent:`）中运行，并在完成时将其结果**回报**到请求者聊天渠道。每次子智能体运行都会作为一个[后台任务](/zh-CN/automation/tasks)被跟踪。 +子智能体是从现有智能体运行中生成的后台智能体运行。它们在自己的会话（`agent::subagent:`）中运行，并在完成后将结果**回报**到请求者聊天渠道。每次子智能体运行都会作为一个[后台任务](/zh-CN/automation/tasks)进行跟踪。 ## 斜杠命令 -使用 `/subagents` 检查或控制**当前会话**的子智能体运行： +使用 `/subagents` 来检查或控制**当前会话**的子智能体运行： - `/subagents list` - `/subagents kill ` @@ -30,7 +30,7 @@ x-i18n: 线程绑定控制： -这些命令适用于支持持久线程绑定的渠道。请参阅下方的**支持线程的渠道**。 +这些命令适用于支持持久线程绑定的渠道。请参见下方的**支持线程的渠道**。 - `/focus ` - `/unfocus` @@ -38,42 +38,42 @@ x-i18n: - `/session idle ` - `/session max-age ` -`/subagents info` 会显示运行元数据（状态、时间戳、会话 id、转录路径、清理情况）。 -使用 `sessions_history` 获取有边界、经过安全过滤的回顾视图；当你需要原始完整转录时，请检查磁盘上的转录路径。 +`/subagents info` 会显示运行元数据（状态、时间戳、会话 id、转录路径、清理信息）。 +使用 `sessions_history` 获取有界且经过安全过滤的回顾视图；当你需要原始完整转录时，请检查磁盘上的转录路径。 ### 生成行为 -`/subagents spawn` 会以用户命令而不是内部中继的方式启动一个后台子智能体，并在运行结束时向请求者聊天发送一条最终完成更新。 +`/subagents spawn` 会以用户命令而非内部中继的方式启动一个后台子智能体，并在运行完成时向请求者聊天发送一条最终完成更新。 - 生成命令是非阻塞的；它会立即返回一个运行 id。 -- 完成时，子智能体会向请求者聊天渠道回报一条摘要 / 结果消息。 -- 完成投递采用推送方式。生成后，不要仅仅为了等待它完成而循环轮询 `/subagents list`、`sessions_list` 或 `sessions_history`；仅在调试或干预时按需检查状态。 -- 完成时，OpenClaw 会尽最大努力关闭该子智能体会话打开的已跟踪浏览器标签页 / 进程，然后再继续执行回报清理流程。 -- 对于手动生成，投递具有韧性： - - OpenClaw 会先使用稳定的幂等键尝试直接 `agent` 投递。 - - 如果直接投递失败，它会回退到队列路由。 - - 如果队列路由仍不可用，则会在最终放弃前使用短指数退避重试该回报。 +- 完成后，子智能体会向请求者聊天渠道回报一条摘要/结果消息。 +- 完成通知基于推送。一旦生成，不要仅为了等待完成而循环轮询 `/subagents list`、`sessions_list` 或 `sessions_history`；只在调试或干预时按需检查状态。 +- 完成时，OpenClaw 会尽力关闭该子智能体会话打开并被跟踪的浏览器标签页/进程，然后再继续回报清理流程。 +- 对于手动生成，投递具有弹性： + - OpenClaw 会先尝试使用稳定的幂等键进行直接 `agent` 投递。 + - 如果直接投递失败，则会回退到队列路由。 + - 如果队列路由仍不可用，则会在最终放弃前以较短的指数退避进行重试回报。 - 完成投递会保留已解析的请求者路由： - 可用时，线程绑定或会话绑定的完成路由优先 - - 如果完成来源只提供渠道，OpenClaw 会用请求者会话已解析路由中的缺失目标 / 账户（`lastChannel` / `lastTo` / `lastAccountId`）进行补全，以便直接投递仍然可用 -- 交给请求者会话的完成移交内容是运行时生成的内部上下文（不是用户编写的文本），其中包括： - - `Result`（最新可见的 `assistant` 回复文本；否则为已净化的最新 `tool` / `toolResult` 文本；终态失败运行不会复用已捕获的回复文本） + - 如果完成来源只提供渠道，OpenClaw 会从请求者会话已解析的路由（`lastChannel` / `lastTo` / `lastAccountId`）中补全缺失的 target/account，以便直接投递仍可工作 +- 向请求者会话的完成交接是运行时生成的内部上下文（不是用户撰写的文本），其中包括： + - `Result`（最新可见的 `assistant` 回复文本；否则为已清理的最新 `tool`/`toolResult` 文本；终态失败运行不会复用捕获的回复文本） - `Status`（`completed successfully` / `failed` / `timed out` / `unknown`） - - 紧凑的运行时 / token 统计信息 - - 一条投递指令，告诉请求者智能体以正常助手语气重写内容（而不是转发原始内部元数据） -- `--model` 和 `--thinking` 会覆盖该特定运行的默认值。 -- 完成后使用 `info` / `log` 检查详细信息和输出。 -- `/subagents spawn` 是一次性模式（`mode: "run"`）。对于持久线程绑定会话，请使用 `sessions_spawn` 并设置 `thread: true` 和 `mode: "session"`。 -- 对于 ACP harness 会话（Codex、Claude Code、Gemini CLI、OpenCode），请使用 `sessions_spawn` 并设置 `runtime: "acp"`，同时参阅 [ACP Agents](/zh-CN/tools/acp-agents)，尤其是在调试完成投递或智能体到智能体循环时参考 [ACP delivery model](/zh-CN/tools/acp-agents#delivery-model)。`runtime: "acp"` 期望一个外部 ACP harness id，或一个 `runtime.type="acp"` 的 `agents.list[]` 条目；对于来自 `agents_list` 的普通 OpenClaw 配置智能体，请使用默认子智能体运行时。 + - 紧凑的运行时/token 统计 + - 一条投递指令，告诉请求者智能体用正常的 assistant 口吻重写，而不是转发原始内部元数据 +- `--model` 和 `--thinking` 会覆盖该次特定运行的默认值。 +- 完成后，使用 `info`/`log` 检查详细信息和输出。 +- `/subagents spawn` 是一次性模式（`mode: "run"`）。对于持久的线程绑定会话，请使用 `sessions_spawn` 并设置 `thread: true` 和 `mode: "session"`。 +- 对于 ACP harness 会话（Codex、Claude Code、Gemini CLI、OpenCode），请使用 `sessions_spawn` 并设置 `runtime: "acp"`，并参见 [ACP Agents](/zh-CN/tools/acp-agents)，尤其是在调试完成通知或智能体到智能体循环时参见 [ACP 投递模型](/zh-CN/tools/acp-agents#delivery-model)。`runtime: "acp"` 需要一个外部 ACP harness id，或一个 `agents.list[]` 条目且其 `runtime.type="acp"`；对于来自 `agents_list` 的普通 OpenClaw 配置智能体，请使用默认的子智能体运行时。 主要目标： - 并行化“研究 / 长任务 / 慢工具”工作，而不阻塞主运行。 - 默认保持子智能体隔离（会话分离 + 可选沙箱隔离）。 -- 使工具面更难被误用：子智能体默认**不会**获得会话工具。 -- 支持适用于编排器模式的可配置嵌套深度。 +- 保持工具表面不易被误用：默认情况下，子智能体**不会**获得会话工具。 +- 支持为编排器模式配置嵌套深度。 -成本说明：每个子智能体默认都有其**自己的**上下文和 token 使用量。对于重型或重复性任务，请为子智能体设置更便宜的模型，而让你的主智能体保留更高质量的模型。你可以通过 `agents.defaults.subagents.model` 或按智能体覆盖来配置这一点。当子级确实需要请求者当前的转录时，智能体可以在那一次生成中请求 `context: "fork"`。 +成本说明：默认情况下，每个子智能体都有其**自己的**上下文和 token 使用量。对于重型或重复任务，请为子智能体设置更便宜的模型，并让你的主智能体保留使用更高质量的模型。你可以通过 `agents.defaults.subagents.model` 或按智能体的覆盖项进行配置。当子级确实需要请求者的当前转录时，智能体可以在那一次生成时请求 `context: "fork"`。 ## 上下文模式 @@ -81,79 +81,79 @@ x-i18n: | 模式 | 适用场景 | 行为 | | ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | -| `isolated` | 全新的研究、独立实现、慢工具工作，或任何可以在任务文本中简要说明的工作 | 创建一个干净的子级转录。这是默认值，并可保持较低的 token 使用量。 | -| `fork` | 工作依赖于当前对话、先前工具结果，或请求者转录中已存在的细致说明时 | 在子级启动前，将请求者转录分支到子级会话中。 | +| `isolated` | 全新研究、独立实现、慢工具工作，或任何可以在任务文本中简要说明清楚的工作 | 创建一个干净的子级转录。这是默认值，并能保持较低的 token 使用量。 | +| `fork` | 依赖当前对话、先前工具结果或请求者转录中已有细致指令的工作 | 在子级启动前，将请求者转录分支到子级会话中。 | -谨慎使用 `fork`。它适用于对上下文敏感的委派，而不是用来替代编写清晰任务提示。 +谨慎使用 `fork`。它用于对上下文敏感的委派，而不是替代撰写清晰任务提示词的方法。 ## 工具 使用 `sessions_spawn`： -- 启动一个子智能体运行（`deliver: false`，全局通道：`subagent`） +- 启动一个子智能体运行（`deliver: false`，全局 lane：`subagent`） - 然后执行一个回报步骤，并将回报回复发布到请求者聊天渠道 -- 默认模型：继承调用方，除非你设置了 `agents.defaults.subagents.model`（或按智能体设置 `agents.list[].subagents.model`）；显式提供的 `sessions_spawn.model` 仍然优先。 -- 默认 thinking：继承调用方，除非你设置了 `agents.defaults.subagents.thinking`（或按智能体设置 `agents.list[].subagents.thinking`）；显式提供的 `sessions_spawn.thinking` 仍然优先。 -- 默认运行超时：如果省略 `sessions_spawn.runTimeoutSeconds`，OpenClaw 会在已设置时使用 `agents.defaults.subagents.runTimeoutSeconds`；否则回退为 `0`（无超时）。 +- 默认模型：继承调用方，除非你设置了 `agents.defaults.subagents.model`（或按智能体设置 `agents.list[].subagents.model`）；显式指定的 `sessions_spawn.model` 仍然优先。 +- 默认 thinking：继承调用方，除非你设置了 `agents.defaults.subagents.thinking`（或按智能体设置 `agents.list[].subagents.thinking`）；显式指定的 `sessions_spawn.thinking` 仍然优先。 +- 默认运行超时：如果省略 `sessions_spawn.runTimeoutSeconds`，OpenClaw 会在已设置时使用 `agents.defaults.subagents.runTimeoutSeconds`；否则回退到 `0`（无超时）。 工具参数： -- `task`（必填） +- `task`（必需） - `label?`（可选） -- `agentId?`（可选；如果允许，则在另一个智能体 id 下生成） -- `runtime?`（`subagent|acp`，默认 `subagent`；`acp` 仅用于外部 ACP harness，例如 `codex`、`claude`、`gemini` 或 `opencode`，或用于 `runtime.type` 为 `acp` 的 `agents.list[]` 条目） -- `model?`（可选；覆盖子智能体模型；无效值会被跳过，子智能体会在默认模型上运行，并在工具结果中给出警告） +- `agentId?`（可选；如果被允许，则在另一个智能体 id 下生成） +- `runtime?`（`subagent|acp`，默认 `subagent`；`acp` 仅用于外部 ACP harness，例如 `codex`、`claude`、`gemini` 或 `opencode`，或用于 `agents.list[]` 中其 `runtime.type` 为 `acp` 的条目） +- `model?`（可选；覆盖子智能体模型；无效值会被跳过，子智能体将使用默认模型运行，并在工具结果中附带警告） - `thinking?`（可选；覆盖子智能体运行的 thinking 级别） -- `runTimeoutSeconds?`（默认在已设置时取 `agents.defaults.subagents.runTimeoutSeconds`，否则为 `0`；设置后，子智能体运行会在 N 秒后中止） -- `thread?`（默认 `false`；设为 `true` 时，请求为该子智能体会话启用渠道线程绑定） +- `runTimeoutSeconds?`（设置时默认使用 `agents.defaults.subagents.runTimeoutSeconds`，否则为 `0`；设置后，子智能体运行会在 N 秒后中止） +- `thread?`（默认 `false`；为 `true` 时，请求为该子智能体会话启用渠道线程绑定） - `mode?`（`run|session`） - - 默认值为 `run` - - 如果 `thread: true` 且省略 `mode`，默认值会变为 `session` + - 默认是 `run` + - 如果 `thread: true` 且省略 `mode`，默认会变为 `session` - `mode: "session"` 需要 `thread: true` - `cleanup?`（`delete|keep`，默认 `keep`） -- `sandbox?`（`inherit|require`，默认 `inherit`；`require` 会在目标子级运行时未启用沙箱隔离时拒绝生成） +- `sandbox?`（`inherit|require`，默认 `inherit`；`require` 会在目标子级运行时不是沙箱隔离时拒绝生成） - `context?`（`isolated|fork`，默认 `isolated`；仅适用于原生子智能体） - `isolated` 会创建一个干净的子级转录，并且是默认值。 - - `fork` 会将请求者当前的转录分支到子级会话中，使子级以相同的对话上下文启动。 + - `fork` 会将请求者当前转录分支到子级会话中，使子级以相同的对话上下文启动。 - 仅当子级需要当前转录时才使用 `fork`。对于范围明确的工作，请省略 `context`。 -- `sessions_spawn` **不**接受渠道投递参数（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）。如需投递，请从已生成的运行中使用 `message` / `sessions_send`。 +- `sessions_spawn` **不**接受渠道投递参数（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）。对于投递，请从已生成的运行中使用 `message`/`sessions_send`。 ## 线程绑定会话 -当某个渠道启用了线程绑定时，子智能体可以保持绑定到一个线程，这样该线程中的后续用户消息会继续路由到同一个子智能体会话。 +当某个渠道启用了线程绑定时，子智能体可以保持绑定到某个线程，因此该线程中的后续用户消息会继续路由到同一个子智能体会话。 ### 支持线程的渠道 -- Discord（当前唯一受支持的渠道）：支持持久线程绑定子智能体会话（`sessions_spawn` 配合 `thread: true`）、手动线程控制（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`），以及适配器键 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSubagentSessions`。 +- Discord（当前唯一受支持的渠道）：支持持久线程绑定的子智能体会话（`sessions_spawn` 配合 `thread: true`）、手动线程控制（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`），以及适配器键 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSubagentSessions`。 快速流程： -1. 使用 `sessions_spawn` 生成，并设置 `thread: true`（可选设置 `mode: "session"`）。 -2. OpenClaw 会在当前渠道中创建线程或将线程绑定到该会话目标。 +1. 使用 `sessions_spawn` 并设置 `thread: true` 进行生成（可选设置 `mode: "session"`）。 +2. OpenClaw 会在当前活跃渠道中创建一个线程或将一个线程绑定到该会话目标。 3. 该线程中的回复和后续消息会路由到绑定的会话。 -4. 使用 `/session idle` 检查 / 更新因不活跃而自动取消聚焦的设置，使用 `/session max-age` 控制硬性时长上限。 +4. 使用 `/session idle` 检查/更新不活动自动取消聚焦，并使用 `/session max-age` 控制硬性上限。 5. 使用 `/unfocus` 手动解除绑定。 手动控制： -- `/focus ` 会将当前线程（或创建一个线程）绑定到一个子智能体 / 会话目标。 -- `/unfocus` 会移除当前已绑定线程的绑定。 -- `/agents` 会列出活动运行和绑定状态（`thread:` 或 `unbound`）。 +- `/focus ` 将当前线程（或创建一个线程）绑定到某个子智能体/会话目标。 +- `/unfocus` 移除当前已绑定线程的绑定。 +- `/agents` 列出活动运行和绑定状态（`thread:` 或 `unbound`）。 - `/session idle` 和 `/session max-age` 仅适用于已聚焦的绑定线程。 配置开关： - 全局默认值：`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours` -- 渠道覆盖和生成自动绑定键是适配器特定的。请参阅上文的**支持线程的渠道**。 +- 渠道覆盖和生成自动绑定键是适配器特定的。请参见上方的**支持线程的渠道**。 -当前适配器的详细信息请参阅 [Configuration Reference](/zh-CN/gateway/configuration-reference) 和 [Slash commands](/zh-CN/tools/slash-commands)。 +当前适配器详细信息请参见 [配置参考](/zh-CN/gateway/configuration-reference) 和 [斜杠命令](/zh-CN/tools/slash-commands)。 允许列表： -- `agents.list[].subagents.allowAgents`：可通过 `agentId` 定向的智能体 id 列表（`["*"]` 表示允许任意值）。默认：仅请求者智能体。 +- `agents.list[].subagents.allowAgents`：可通过 `agentId` 作为目标的智能体 id 列表（`["*"]` 表示允许任意）。默认值：仅允许请求者智能体。 - `agents.defaults.subagents.allowAgents`：当请求者智能体未设置自己的 `subagents.allowAgents` 时使用的默认目标智能体允许列表。 -- 沙箱继承保护：如果请求者会话启用了沙箱隔离，`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。 -- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`：设为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件）。默认：false。 +- 沙箱继承保护：如果请求者会话已在沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱隔离方式运行的目标。 +- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件）。默认值：false。 发现： @@ -161,17 +161,17 @@ x-i18n: 自动归档： -- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes` 之后自动归档（默认值：60）。 +- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes` 后自动归档（默认值：60）。 - 归档使用 `sessions.delete`，并将转录重命名为 `*.deleted.`（同一文件夹中）。 - `cleanup: "delete"` 会在回报后立即归档（仍会通过重命名保留转录）。 - 自动归档是尽力而为；如果 Gateway 网关重启，待处理计时器会丢失。 -- `runTimeoutSeconds` **不会**自动归档；它只会停止运行。会话会保留到自动归档发生。 -- 自动归档同样适用于深度 1 和深度 2 的会话。 -- 浏览器清理与归档清理是分开的：即使保留了转录 / 会话记录，在运行结束时也会尽最大努力关闭已跟踪浏览器标签页 / 进程。 +- `runTimeoutSeconds` **不会**自动归档；它只会停止运行。会话会保留到自动归档发生为止。 +- 自动归档同样适用于深度为 1 和深度为 2 的会话。 +- 浏览器清理与归档清理是分开的：运行完成时，被跟踪的浏览器标签页/进程会尽力关闭，即使转录/会话记录被保留也是如此。 ## 嵌套子智能体 -默认情况下，子智能体不能生成自己的子智能体（`maxSpawnDepth: 1`）。你可以通过设置 `maxSpawnDepth: 2` 来启用一层嵌套，这样就允许使用**编排器模式**：主智能体 → 编排器子智能体 → 工作子子智能体。 +默认情况下，子智能体不能生成它们自己的子智能体（`maxSpawnDepth: 1`）。你可以通过设置 `maxSpawnDepth: 2` 来启用一层嵌套，这样就允许使用**编排器模式**：主智能体 → 编排器子智能体 → 工作子子智能体。 ### 如何启用 @@ -180,10 +180,10 @@ x-i18n: agents: { defaults: { subagents: { - maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1) - maxChildrenPerAgent: 5, // max active children per agent session (default: 5) - maxConcurrent: 8, // global concurrency lane cap (default: 8) - runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout) + maxSpawnDepth: 2, // 允许子智能体生成子级（默认：1） + maxChildrenPerAgent: 5, // 每个智能体会话的最大活动子级数（默认：5） + maxConcurrent: 8, // 全局并发 lane 上限（默认：8） + runTimeoutSeconds: 900, // `sessions_spawn` 在省略时使用的默认超时（0 = 无超时） }, }, }, @@ -192,106 +192,106 @@ x-i18n: ### 深度级别 -| 深度 | 会话键形状 | 角色 | 可以生成？ | -| ---- | -------------------------------------------- | --------------------------------------------- | ----------------------------- | -| 0 | `agent::main` | 主智能体 | 始终可以 | -| 1 | `agent::subagent:` | 子智能体（在允许深度 2 时为编排器） | 仅当 `maxSpawnDepth >= 2` 时 | -| 2 | `agent::subagent::subagent:` | 子子智能体（叶子工作器） | 永不可以 | +| 深度 | 会话键形状 | 角色 | 可以生成？ | +| ---- | -------------------------------------------- | --------------------------------------------- | ---------------------------- | +| 0 | `agent::main` | 主智能体 | 始终可以 | +| 1 | `agent::subagent:` | 子智能体（当允许深度 2 时可作为编排器） | 仅当 `maxSpawnDepth >= 2` 时 | +| 2 | `agent::subagent::subagent:` | 子子智能体（叶子工作者） | 永不 | ### 回报链 -结果会沿链路向上回传： +结果会沿链路向上返回： -1. 深度 2 工作器完成 → 向其父级（深度 1 编排器）回报 +1. 深度 2 工作者完成 → 向其父级（深度 1 编排器）回报 2. 深度 1 编排器接收回报、综合结果、完成 → 向主智能体回报 3. 主智能体接收回报并投递给用户 -每一层只会看到其直接子级的回报。 +每一层只能看到其直接子级的回报。 -操作指南： +操作指引： -- 子级工作只启动一次，然后等待完成事件，而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` sleep 命令构建轮询循环。 -- `sessions_list` 和 `/subagents list` 会让子会话关系聚焦于实时工作：仍在运行的子级会保持关联，已结束的子级会在短暂的最近窗口中保持可见，而仅存储中的陈旧子级链接会在其新鲜度窗口后被忽略。这可防止旧的 `spawnedBy` / `parentSessionKey` 元数据在重启后重新唤起“幽灵”子级。 -- 如果子级完成事件在你已经发送最终答案之后才到达，正确的后续操作是精确的静默 token `NO_REPLY` / `no_reply`。 +- 启动一次子级工作后，等待完成事件，而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` sleep 命令构建轮询循环。 +- `sessions_list` 和 `/subagents list` 会让子会话关系聚焦于存活中的工作：存活的子级保持附着，已结束的子级会在短暂的最近窗口内保持可见，而仅存于存储中的过期子级链接会在其新鲜度窗口后被忽略。这样可以防止旧的 `spawnedBy` / `parentSessionKey` 元数据在重启后重新复活“幽灵”子级。 +- 如果子级完成事件在你已经发送最终答案后才到达，正确的后续操作是精确的静默令牌 `NO_REPLY` / `no_reply`。 ### 按深度划分的工具策略 - 角色和控制范围会在生成时写入会话元数据。这可防止扁平化或恢复后的会话键意外重新获得编排器权限。 -- **深度 1（编排器，当 `maxSpawnDepth >= 2` 时）**：获得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子级。其他会话 / 系统工具仍然被拒绝。 +- **深度 1（编排器，当 `maxSpawnDepth >= 2` 时）**：获得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子级。其他会话/系统工具仍会被拒绝。 - **深度 1（叶子节点，当 `maxSpawnDepth == 1` 时）**：没有会话工具（当前默认行为）。 -- **深度 2（叶子工作器）**：没有会话工具 —— 在深度 2 时始终拒绝 `sessions_spawn`。不能再生成更多子级。 +- **深度 2（叶子工作者）**：没有会话工具 —— 在深度 2 时，`sessions_spawn` 始终被拒绝。不能再生成更多子级。 ### 每个智能体的生成上限 -每个智能体会话（任意深度）同时最多只能拥有 `maxChildrenPerAgent`（默认值：5）个活跃子级。这可防止单个编排器失控式扇出。 +每个智能体会话（任何深度）在同一时间最多只能有 `maxChildrenPerAgent`（默认：5）个活动子级。这可防止单个编排器出现失控扇出。 ### 级联停止 停止一个深度 1 编排器会自动停止其所有深度 2 子级： - 在主聊天中使用 `/stop` 会停止所有深度 1 智能体，并级联停止它们的深度 2 子级。 -- `/subagents kill ` 会停止指定子智能体，并级联停止其子级。 -- `/subagents kill all` 会停止该请求者的所有子智能体，并执行级联停止。 +- `/subagents kill ` 会停止特定子智能体，并级联停止其子级。 +- `/subagents kill all` 会停止请求者的所有子智能体，并执行级联停止。 -## 认证 +## 身份验证 -子智能体认证是按**智能体 id**解析的，而不是按会话类型： +子智能体认证按**智能体 id**解析，而不是按会话类型解析： -- 子智能体会话键为 `agent::subagent:`。 -- 认证存储从该智能体的 `agentDir` 加载。 -- 主智能体的认证配置文件会作为**回退**合并进来；发生冲突时，智能体配置文件会覆盖主配置文件。 +- 子智能体会话键是 `agent::subagent:`。 +- 认证存储会从该智能体的 `agentDir` 加载。 +- 主智能体的认证配置文件会作为**后备**合并进来；发生冲突时，智能体配置文件会覆盖主配置文件。 -注意：这种合并是增量式的，因此主配置文件始终可作为回退使用。每个智能体完全隔离的认证目前尚不支持。 +注意：该合并是附加式的，因此主配置文件始终可作为后备使用。当前尚不支持按智能体完全隔离认证。 ## 回报 -子智能体通过回报步骤进行反馈： +子智能体通过一个回报步骤进行反馈： -- 回报步骤在子智能体会话内部运行（而不是在请求者会话中）。 -- 如果子智能体的回复精确等于 `ANNOUNCE_SKIP`，则不会发布任何内容。 -- 如果最新的助手文本是精确的静默 token `NO_REPLY` / `no_reply`，则即使之前存在可见进度，也会抑制回报输出。 -- 否则投递方式取决于请求者深度： - - 顶层请求者会话使用后续 `agent` 调用进行外部投递（`deliver=true`） - - 嵌套的请求者子智能体会话接收内部后续注入（`deliver=false`），以便编排器在会话内综合子级结果 +- 回报步骤在子智能体会话内运行（不是在请求者会话内）。 +- 如果子智能体精确回复 `ANNOUNCE_SKIP`，则不会发布任何内容。 +- 如果最新的 assistant 文本是精确的静默令牌 `NO_REPLY` / `no_reply`，即使之前存在可见进度，也会抑制回报输出。 +- 否则，投递取决于请求者深度： + - 顶层请求者会话使用带外部投递的后续 `agent` 调用（`deliver=true`） + - 嵌套的请求者子智能体会话会接收内部后续注入（`deliver=false`），以便编排器在会话内综合子级结果 - 如果嵌套的请求者子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求者 -- 对于顶层请求者会话，完成模式的直接投递会先解析任何已绑定的会话 / 线程路由和 hook 覆盖，然后用请求者会话存储路由中的字段补全缺失的渠道目标字段。这样即使完成来源只标识了渠道，也能让完成结果发送到正确的聊天 / 主题。 -- 在构建嵌套完成结果时，子级完成聚合会限定在当前请求者运行范围内，防止陈旧的先前运行子级输出泄露到当前回报中。 -- 在渠道适配器可用时，回报回复会保留线程 / 主题路由。 -- 回报上下文会规范化为稳定的内部事件块： +- 对于顶层请求者会话，完成模式的直接投递会先解析任何已绑定的会话/线程路由和 hook 覆盖，然后再从请求者会话存储的路由中补全缺失的渠道目标字段。这样即使完成来源只标识了渠道，也能让完成通知保持在正确的聊天/主题中。 +- 在构建嵌套完成结果时，子级完成聚合会限定在当前请求者运行范围内，从而防止过期的先前运行子级输出泄漏到当前回报中。 +- 回报回复会在渠道适配器可用时保留线程/主题路由。 +- 回报上下文会被规范化为稳定的内部事件块： - 来源（`subagent` 或 `cron`） - - 子级会话键 / id + - 子会话键/id - 回报类型 + 任务标签 - - 基于运行时结果派生的状态行（`success`、`error`、`timeout` 或 `unknown`） - - 从最新可见助手文本中选择的结果内容；否则为已净化的最新 `tool` / `toolResult` 文本；终态失败运行会报告失败状态，而不会回放已捕获的回复文本 - - 一条后续指令，说明何时应回复、何时应保持静默 -- `Status` 不是从模型输出推断出来的；它来自运行时结果信号。 -- 超时时，如果子级只执行到了工具调用，回报可以将那段历史压缩成简短的部分进度摘要，而不是回放原始工具输出。 + - 从运行时结果派生的状态行（`success`、`error`、`timeout` 或 `unknown`） + - 从最新可见 assistant 文本中选取的结果内容；否则为已清理的最新 `tool`/`toolResult` 文本；终态失败运行会报告失败状态，而不会重放已捕获的回复文本 + - 一条后续指令，描述何时回复以及何时保持静默 +- `Status` 不是从模型输出推断的；它来自运行时结果信号。 +- 超时时，如果子级只完成了工具调用，回报可以将该历史压缩为简短的部分进度摘要，而不是重放原始工具输出。 -回报负载在末尾包含一行统计信息（即使被包装也会包含）： +回报负载在末尾包含一行统计信息（即使已包装）： - 运行时长（例如 `runtime 5m12s`） -- Token 使用量（输入 / 输出 / 总计） -- 配置了模型定价时的预估成本（`models.providers.*.models[].cost`） -- `sessionKey`、`sessionId` 和转录路径（因此主智能体可以通过 `sessions_history` 获取历史，或在磁盘上检查文件） -- 内部元数据仅用于编排；面向用户的回复应以正常助手语气重写。 +- token 使用量（输入/输出/总量） +- 配置了模型定价时的估算成本（`models.providers.*.models[].cost`） +- `sessionKey`、`sessionId` 和转录路径（这样主智能体可以通过 `sessions_history` 获取历史，或在磁盘上检查该文件） +- 内部元数据仅用于编排；面向用户的回复应以正常 assistant 口吻重写。 `sessions_history` 是更安全的编排路径： -- 助手回溯会先被标准化： - - 移除 thinking 标签 - - 移除 `` / `` 脚手架块 - - 移除纯文本工具调用 XML 负载块，如 `...`、`...`、`...` 和 `...`，包括那些从未正确闭合的截断负载 - - 移除降级的工具调用 / 结果脚手架和历史上下文标记 - - 移除泄露的模型控制 token，例如 `<|assistant|>`、其他 ASCII `<|...|>` token，以及全角 `<｜...｜>` 变体 - - 移除格式错误的 MiniMax 工具调用 XML -- 类似凭证 / token 的文本会被脱敏 -- 长内容块可能会被截断 -- 非常大的历史记录可能会丢弃较旧的行，或将超大的单行替换为 `[sessions_history omitted: message too large]` -- 当你需要完整的逐字节转录时，回退方式是检查磁盘上的原始转录 +- assistant 回顾会先被规范化： + - 会移除 thinking 标签 + - 会移除 `` / `` 脚手架块 + - 会移除纯文本工具调用 XML 负载块，例如 `...`、`...`、`...` 和 `...`，包括那些从未正常闭合的截断负载 + - 会移除降级后的工具调用/结果脚手架和历史上下文标记 + - 会移除泄漏的模型控制令牌，例如 `<|assistant|>`、其他 ASCII `<|...|>` 令牌，以及全角 `<｜...｜>` 变体 + - 会移除格式错误的 MiniMax 工具调用 XML +- 类凭证/token 的文本会被脱敏 +- 长块可能会被截断 +- 对于非常大的历史，可能会丢弃较旧的行，或将超大的某一行替换为 `[sessions_history omitted: message too large]` +- 当你需要完整的逐字节转录时，回退方式是检查磁盘上的原始转录文件 ## 工具策略（子智能体工具） -子智能体首先使用与父级或目标智能体相同的配置文件和工具策略流程。之后，OpenClaw 会应用子智能体限制层。 +子智能体会先使用与父级或目标智能体相同的配置文件和工具策略管线。之后，OpenClaw 会应用子智能体限制层。 在没有限制性 `tools.profile` 的情况下，子智能体会获得**除会话工具**和系统工具之外的所有工具： @@ -300,7 +300,7 @@ x-i18n: - `sessions_send` - `sessions_spawn` -这里的 `sessions_history` 仍然是有边界、经过净化的回顾视图；它不是原始转录转储。 +这里的 `sessions_history` 仍是有界且已清理的回顾视图；它不是原始转录转储。 当 `maxSpawnDepth >= 2` 时，深度 1 编排器子智能体还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便管理其子级。 @@ -318,9 +318,9 @@ x-i18n: tools: { subagents: { tools: { - // deny wins + // deny 优先 deny: ["gateway", "cron"], - // if allow is set, it becomes allow-only (deny still wins) + // 如果设置了 allow，则变为仅 allow 模式（deny 仍然优先） // allow: ["read", "exec", "process"] }, }, @@ -328,7 +328,7 @@ x-i18n: } ``` -`tools.subagents.tools.allow` 是最终的仅允许过滤器。它可以缩小已解析出的工具集，但不能把已被 `tools.profile` 移除的工具重新加回来。例如，`tools.profile: "coding"` 包含 `web_search` / `web_fetch`，但不包含 `browser` 工具。要让 coding 配置文件的子智能体使用浏览器自动化，请在配置文件阶段加入 browser： +`tools.subagents.tools.allow` 是最终的仅 allow 过滤器。它可以缩小已经解析出的工具集合，但不能重新添加被 `tools.profile` 移除的工具。例如，`tools.profile: "coding"` 包含 `web_search`/`web_fetch`，但不包含 `browser` 工具。要让 coding 配置文件的子智能体使用浏览器自动化，请在配置文件阶段加入 browser： ```json5 { @@ -339,37 +339,39 @@ x-i18n: } ``` -当只有一个智能体需要浏览器自动化时，请使用按智能体配置的 `agents.list[].tools.alsoAllow: ["browser"]`。 +当只有某一个智能体应获得浏览器自动化时，请使用按智能体配置的 `agents.list[].tools.alsoAllow: ["browser"]`。 ## 并发 -子智能体使用一个专用的进程内队列通道： +子智能体使用专用的进程内队列 lane： -- 通道名称：`subagent` -- 并发数：`agents.defaults.subagents.maxConcurrent`（默认值 `8`） +- lane 名称：`subagent` +- 并发数：`agents.defaults.subagents.maxConcurrent`（默认 `8`） ## 存活性与恢复 -OpenClaw 不会把缺少 `endedAt` 永久视为子智能体仍然存活的证明。超过陈旧运行窗口的未结束运行，将不再在 `/subagents list`、状态摘要、后代完成门控以及每会话并发检查中计为活跃 / 待处理。 +OpenClaw 不会将缺少 `endedAt` 永久视为子智能体仍然存活的证明。超过陈旧运行窗口且未结束的运行，将不再在 `/subagents list`、状态摘要、后代完成门控和按会话并发检查中计为活动/待定。 -Gateway 网关重启后，陈旧的未结束恢复运行会被清理，除非它们的子会话被标记为 `abortedLastRun: true`。这些因重启而中止的子会话仍可通过子智能体孤儿恢复流程进行恢复，该流程会先发送一条合成恢复消息，然后清除中止标记。 +Gateway 网关重启后，过期的未结束恢复运行会被清理，除非其子会话被标记为 `abortedLastRun: true`。这些因重启而中止的子会话仍可通过子智能体孤儿恢复流程恢复，该流程会在清除中止标记之前发送一条合成恢复消息。 + +如果子智能体生成因 Gateway 网关 `PAIRING_REQUIRED` / `scope-upgrade` 失败，请在编辑配对状态之前先检查 RPC 调用方。内部 `sessions_spawn` 协调应通过直接 loopback 共享 token/密码认证，以 `client.id: "gateway-client"` 和 `client.mode: "backend"` 连接；该路径不依赖 CLI 的已配对设备 scope 基线。远程调用方、显式 `deviceIdentity`、显式设备 token 路径以及浏览器/node 客户端仍然需要正常的设备批准来进行 scope 升级。 ## 停止 -- 在请求者聊天中发送 `/stop` 会中止请求者会话，并停止由其生成的所有活跃子智能体运行，同时级联到嵌套子级。 -- `/subagents kill ` 会停止指定子智能体，并级联停止其子级。 +- 在请求者聊天中发送 `/stop` 会中止请求者会话，并停止从中生成的任何活动子智能体运行，同时级联到嵌套子级。 +- `/subagents kill ` 会停止特定子智能体，并级联停止其子级。 ## 限制 -- 子智能体回报是**尽力而为**的。如果 Gateway 网关重启，待处理的“回报回来”工作会丢失。 -- 子智能体仍共享同一个 Gateway 网关进程资源；请将 `maxConcurrent` 视为一个安全阀。 +- 子智能体回报是**尽力而为**的。如果 Gateway 网关重启，待处理的“回报给上游”工作会丢失。 +- 子智能体仍共享同一个 Gateway 网关进程资源；请将 `maxConcurrent` 视为安全阀。 - `sessions_spawn` 始终是非阻塞的：它会立即返回 `{ status: "accepted", runId, childSessionKey }`。 -- 子智能体上下文只注入 `AGENTS.md` + `TOOLS.md`（不注入 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。 -- 最大嵌套深度为 5（`maxSpawnDepth` 范围：1–5）。对于大多数使用场景，推荐使用深度 2。 -- `maxChildrenPerAgent` 会限制每个会话的活跃子级数量（默认值：5，范围：1–20）。 +- 子智能体上下文只会注入 `AGENTS.md` + `TOOLS.md`（不包括 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。 +- 最大嵌套深度为 5（`maxSpawnDepth` 范围：1–5）。大多数用例推荐使用深度 2。 +- `maxChildrenPerAgent` 限制每个会话的活动子级数量（默认：5，范围：1–20）。 ## 相关内容 - [ACP 智能体](/zh-CN/tools/acp-agents) - [多智能体沙箱工具](/zh-CN/tools/multi-agent-sandbox-tools) -- [智能体发送](/zh-CN/tools/agent-send) +- [Agent send](/zh-CN/tools/agent-send)