From ade1dc47ac0a2ca03e705a724372c976ee718169 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 3 May 2026 21:43:19 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/tools/slash-commands.md | 291 ++++++++++++------------ docs/zh-CN/tools/subagents.md | 353 +++++++++++++++-------------- 2 files changed, 331 insertions(+), 313 deletions(-) diff --git a/docs/zh-CN/tools/slash-commands.md b/docs/zh-CN/tools/slash-commands.md index 08b8590e0..a15ff4397 100644 --- a/docs/zh-CN/tools/slash-commands.md +++ b/docs/zh-CN/tools/slash-commands.md @@ -3,40 +3,40 @@ read_when: - 使用或配置聊天命令 - 调试命令路由或权限 sidebarTitle: Slash commands -summary: 斜杠命令：文本与原生命令、配置和支持的命令 +summary: 斜杠命令：文本与原生、配置和支持的命令 title: 斜杠命令 x-i18n: - generated_at: "2026-05-03T18:10:24Z" + generated_at: "2026-05-03T21:41:51Z" model: gpt-5.5 provider: openai - source_hash: 9fbdd76ccd43159cabfbc3f15f7bddd2a7ada07fcd6eea2e169d2d88df18f28c + source_hash: b95b98f84fd26b706cc38d93935be509033e5df30e00b2f581e326e68b256043 source_path: tools/slash-commands.md workflow: 16 --- 命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! `（`/bash ` 作为别名）。 -当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍保持本地处理：`/acp ...` 始终会到达 OpenClaw ACP 命令处理程序，并且只要该表面启用了命令处理，`/status` 和 `/unfocus` 就会保持本地处理。 +当对话或话题绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍然保留在本地：`/acp ...` 始终会到达 OpenClaw ACP 命令处理程序，并且只要该界面启用了命令处理，`/status` 和 `/unfocus` 也会保留在本地。 有两个相关系统： - + 独立的 `/...` 消息。 - + `/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。 - 指令会在模型看到消息之前从消息中剥离。 - - 在普通聊天消息中（非仅指令消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 - - 在仅指令消息中（消息只包含指令），它们会持久化到会话，并回复确认。 - - 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则，授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被当作纯文本处理。 + - 在普通聊天消息中（不是仅含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 + - 在仅含指令的消息中（消息只包含指令），它们会持久化到会话并回复确认。 + - 指令只会应用于**已授权的发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对加上 `commands.useAccessGroups`。未授权的发送者会看到指令被当作纯文本处理。 - - 仅允许列表内/已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 + + 仅限允许列表内/已授权的发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - 它们会立即运行，在模型看到消息之前被剥离，剩余文本会继续按正常流程处理。 + 它们会立即运行，在模型看到消息之前被剥离，剩余文本会继续进入正常流程。 @@ -69,20 +69,20 @@ x-i18n: ``` - 启用在聊天消息中解析 `/...`。在没有原生命令的表面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将它设置为 `false`，文本命令仍然可用。 + 在聊天消息中启用 `/...` 解析。在没有原生命令的界面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将它设为 `false`，文本命令仍然可用。 - 注册原生命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对没有原生支持的提供商忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。在 Discord 上，`false` 会跳过启动期间的斜杠命令注册和清理；之前注册的命令可能会保持可见，直到你从 Discord 应用中移除它们。Slack 命令在 Slack 应用中管理，不会自动移除。 + 注册原生命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对没有原生支持的提供商会被忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。在 Discord 上，`false` 会在启动期间跳过斜杠命令注册和清理；先前注册的命令可能会保持可见，直到你从 Discord 应用中移除它们。Slack 命令在 Slack 应用中管理，不会自动移除。 -在 Discord 上，原生命令规范可以包含 `descriptionLocalizations`，OpenClaw 会将其发布为 Discord `description_localizations`，并纳入对账比较。 +在 Discord 上，原生命令规范可以包含 `descriptionLocalizations`，OpenClaw 会将其发布为 Discord `description_localizations`，并包含在协调比较中。 - 在支持时以原生方式注册 **skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 要求为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 + 在支持时原生注册 **skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 - 启用 `! ` 以运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` 允许列表）。 + 启用 `! ` 来运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` 允许列表）。 - 控制 bash 在切换到后台模式前等待的时长（`0` 表示立即进入后台）。 + 控制 bash 在切换到后台模式之前等待多长时间（`0` 表示立即进入后台）。 启用 `/config`（读取/写入 `openclaw.json`）。 @@ -91,7 +91,7 @@ x-i18n: 启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。 - 启用 `/plugins`（插件发现/Status，以及安装和启用/禁用控制）。 + 启用 `/plugins`（插件发现/状态，以及安装 + 启用/禁用控件）。 启用 `/debug`（仅运行时覆盖）。 @@ -100,19 +100,19 @@ x-i18n: 启用 `/restart` 以及 Gateway 网关重启工具操作。 - 为仅所有者命令/工具表面设置显式所有者允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账户。它独立于 `commands.allowFrom`，也独立于私信配对访问。 + 设置仅所有者命令/工具界面的显式所有者允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom` 和私信配对访问。 - 按渠道：让仅所有者命令在该表面运行时要求**所有者身份**。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` scope。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求——仅所有者命令会在该渠道上默认关闭失败。如果你希望仅所有者命令只受 `ownerAllowFrom` 和标准命令允许列表控制，请保持关闭。 + 按渠道设置：使仅所有者命令在该界面上必须具备**所有者身份**才能运行。当为 `true` 时，发送者必须匹配一个已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` 范围。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求——仅所有者命令会在该渠道上默认失败关闭。如果你希望仅所有者命令只由 `ownerAllowFrom` 和标准命令允许列表门控，请保持关闭。 控制所有者 ID 在系统提示中的显示方式。 - 可选设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC secret。 + 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。 - 用于命令授权的按提供商允许列表。配置后，它就是命令和指令的唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。 + 用于命令授权的按提供商允许列表。配置后，它就是命令和指令的唯一授权来源（渠道允许列表/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商专用键会覆盖它。 当未设置 `commands.allowFrom` 时，为命令强制执行允许列表/策略。 @@ -120,54 +120,55 @@ x-i18n: ## 命令列表 -当前事实来源： +当前可信来源： - 核心内置项来自 `src/auto-reply/commands-registry.shared.ts` -- 生成的停靠命令来自 `src/auto-reply/commands-registry.data.ts` -- 插件命令来自插件 `registerCommand()` 调用 -- 在你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道表面以及已安装/已启用的插件 +- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts` +- 插件命令来自插件的 `registerCommand()` 调用 +- 你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道界面，以及已安装/已启用的插件 ### 核心内置命令 - + - `/new [model]` 启动新会话；`/reset` 是重置别名。 - - Control UI 会拦截键入的 `/new`，以创建并切换到新的仪表板会话；键入的 `/reset` 仍会运行 Gateway 网关的原地重置。 - - `/reset soft [message]` 保留当前转录，丢弃已复用的 CLI 后端会话 ID，并原地重新运行启动/系统提示加载。 - - `/compact [instructions]` 压缩会话上下文。参见[压缩](/zh-CN/concepts/compaction)。 + - Control UI 会拦截键入的 `/new`，以创建并切换到全新的仪表盘会话；键入的 `/reset` 仍会运行 Gateway 网关的原地重置。 + - `/reset soft [message]` 保留当前转录，丢弃复用的 CLI 后端会话 ID，并在原地重新运行启动/系统提示加载。 + - `/compact [instructions]` 压缩会话上下文。参见 [Compaction](/zh-CN/concepts/compaction)。 - `/stop` 中止当前运行。 - - `/session idle ` 和 `/session max-age ` 管理线程绑定过期时间。 + - `/session idle ` 和 `/session max-age ` 管理话题绑定过期时间。 - `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。 - - `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。 + - `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出一个 JSONL [trajectory bundle](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。 - - - `/think ` 设置思考级别。选项来自活动模型的提供商配置文件；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，而 `xhigh`、`adaptive`、`max` 或二进制 `on` 等自定义级别仅在支持的位置可用。别名：`/thinking`、`/t`。 + + - `/think ` 设置思考级别。选项来自活动模型的提供商配置档案；常见级别是 `off`、`minimal`、`low`、`medium` 和 `high`，自定义级别如 `xhigh`、`adaptive`、`max`，或二进制 `on` 仅在受支持处可用。别名：`/thinking`、`/t`。 - `/verbose on|off|full` 切换详细输出。别名：`/v`。 - - `/trace on|off` 为当前会话切换插件 trace 输出。 + - `/trace on|off` 切换当前会话的插件跟踪输出。 - `/fast [status|on|off]` 显示或设置快速模式。 - - `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。 - - `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。 + - `/reasoning [on|off|stream]` 切换 reasoning 可见性。别名：`/reason`。 + - `/elevated [on|off|ask|full]` 切换提权模式。别名：`/elev`。 - `/exec host= security= ask= node=` 显示或设置 exec 默认值。 - `/model [name|#|status]` 显示或设置模型。 - - `/models [provider] [page] [limit=|size=|all]` 列出已配置/可用认证的提供商，或某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。 - - `/queue ` 管理队列行为（`steer`、旧版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见[命令队列](/zh-CN/concepts/queue)和 [Steering queue](/zh-CN/concepts/queue-steering)。 + - `/models [provider] [page] [limit=|size=|all]` 列出已配置/有可用身份验证的提供商，或某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。 + - `/queue ` 管理队列行为（`steer`、旧版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见 [Command queue](/zh-CN/concepts/queue) 和 [Steering queue](/zh-CN/concepts/queue-steering)。 + - `/steer ` 将指导注入当前会话的活动运行中，独立于 `/queue` 模式。当会话空闲时，它不会启动新的运行。别名：`/tell`。 - + - `/help` 显示简短帮助摘要。 - `/commands` 显示生成的命令目录。 - - `/tools [compact|verbose]` 显示当前智能体现在可以使用什么。 - - `/status` 显示执行/运行时 Status，包括 `Execution`/`Runtime` 标签，以及可用时的提供商用量/配额。 - - `/diagnostics [note]` 是用于 Gateway 网关 bug 和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 前请求显式 exec 批准；不要使用 allow-all 规则批准诊断。批准后，它会发送一份可粘贴报告，其中包含本地包路径、清单摘要、隐私说明和相关会话 ID。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一批准还会将相关 Codex 反馈发送到 OpenAI 服务器，完成后的回复会列出 OpenClaw 会话 ID、Codex 线程 ID 和 `codex resume ` 命令。参见[诊断导出](/zh-CN/gateway/diagnostics)。 + - `/tools [compact|verbose]` 显示当前智能体现在可以使用的内容。 + - `/status` 显示执行/运行时状态，包括 `Execution`/`Runtime` 标签，以及可用时的提供商用量/配额。 + - `/diagnostics [note]` 是针对 Gateway 网关 bug 和 Codex harness 运行的仅所有者支持报告流程。它在每次运行 `openclaw gateway diagnostics export --json` 前都会请求显式 exec 批准；不要用允许全部规则批准诊断。批准后，它会发送一份可粘贴报告，包含本地 bundle 路径、清单摘要、隐私说明和相关会话 ID。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一次批准还会将相关 Codex 反馈发送到 OpenAI 服务器，并且完成后的回复会列出 OpenClaw 会话 ID、Codex 话题 ID 和 `codex resume ` 命令。参见 [Diagnostics Export](/zh-CN/gateway/diagnostics)。 - `/crestodian ` 从所有者私信运行 Crestodian 设置和修复助手。 - - `/tasks` 列出当前会话的活动/最近后台任务。 - - `/context [list|detail|json]` 解释上下文如何组装。 + - `/tasks` 列出当前会话的活动/近期后台任务。 + - `/context [list|detail|json]` 说明上下文如何组装。 - `/whoami` 显示你的发送者 ID。别名：`/id`。 - `/usage off|tokens|full|cost` 控制每条回复的用量页脚，或打印本地成本摘要。 - + - `/skill [input]` 按名称运行一个 skill。 - `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。 - `/approve ` 解决 exec 批准提示。 @@ -177,48 +178,48 @@ x-i18n: - `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。 - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。 - - `/focus ` 将当前 Discord 线程或 Telegram 话题/对话绑定到一个会话目标。 + - `/focus ` 将当前 Discord 线程或 Telegram 主题/对话绑定到一个会话目标。 - `/unfocus` 移除当前绑定。 - `/agents` 列出当前会话中绑定到线程的智能体。 - `/kill ` 中止一个或所有正在运行的子智能体。 - - `/steer ` 向正在运行的子智能体发送引导。别名：`/tell`。 + - `/subagents steer ` 向正在运行的子智能体发送引导。 - - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅所有者。需要 `commands.config: true`。 - - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅所有者。需要 `commands.mcp: true`。 - - `/plugins list|inspect|show|get|install|enable|disable` 检查或修改插件状态。`/plugin` 是别名。写入仅限所有者。需要 `commands.plugins: true`。 - - `/debug show|set|unset|reset` 管理仅运行时生效的配置覆盖项。仅所有者。需要 `commands.debug: true`。 + - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅所有者可用。需要 `commands.config: true`。 + - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅所有者可用。需要 `commands.mcp: true`。 + - `/plugins list|inspect|show|get|install|enable|disable` 检查或变更插件状态。`/plugin` 是别名。写入仅所有者可用。需要 `commands.plugins: true`。 + - `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅所有者可用。需要 `commands.debug: true`。 - `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用它。 - - `/send on|off|inherit` 设置发送策略。仅所有者。 + - `/send on|off|inherit` 设置发送策略。仅所有者可用。 - + - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。参见 [TTS](/zh-CN/tools/tts)。 - `/activation mention|always` 设置群组激活模式。 - - `/bash ` 运行主机 shell 命令。仅文本。别名：`! `。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。 + - `/bash ` 运行主机 shell 命令。仅文本。别名：`! `。需要 `commands.bash: true` 加上 `tools.elevated` 允许列表。 - `!poll [sessionId]` 检查后台 bash 任务。 - `!stop [sessionId]` 停止后台 bash 任务。 -### 生成的停靠命令 +### 生成的 dock 命令 -停靠命令会将当前会话的回复路由切换到另一个已链接的渠道。有关设置、示例和故障排除，请参见[渠道停靠](/zh-CN/concepts/channel-docking)。 +Dock 命令会将当前会话的回复路由切换到另一个已链接的渠道。设置、示例和故障排除见[渠道停靠](/zh-CN/concepts/channel-docking)。 -停靠命令由支持原生命令的渠道插件生成。当前内置集合： +Dock 命令由支持原生命令的渠道插件生成。当前内置集合： - `/dock-discord`（别名：`/dock_discord`） - `/dock-mattermost`（别名：`/dock_mattermost`） - `/dock-slack`（别名：`/dock_slack`） - `/dock-telegram`（别名：`/dock_telegram`） -在直接聊天中使用停靠命令，可将当前会话的回复路由切换到另一个已链接的渠道。智能体会保留相同的会话上下文，但该会话之后的回复会发送到所选渠道对端。 +在直接聊天中使用 dock 命令，可将当前会话的回复路由切换到另一个已链接渠道。智能体会保留同一个会话上下文，但该会话之后的回复会投递到所选渠道对端。 -停靠命令需要 `session.identityLinks`。源发送者和目标对端必须位于同一身份组，例如 `["telegram:123", "discord:456"]`。如果 ID 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活跃会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未链接到 Discord 对端，该命令会回复设置提示，而不会落入普通聊天流程。 +Dock 命令需要 `session.identityLinks`。源发送者和目标对端必须在同一个身份组中，例如 `["telegram:123", "discord:456"]`。如果 ID 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未链接到 Discord 对端，该命令会回复设置提示，而不是落入普通聊天流程。 -停靠只会更改活跃会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，也不会将对话历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的停靠命令可再次切换路由。 +停靠只会更改活动会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，或将转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的 dock 命令可再次切换路由。 ### 内置插件命令 @@ -230,97 +231,97 @@ x-i18n: - `/voice status|list [limit]|set ` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。 - `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。 - `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 检查并控制内置 Codex 应用服务器 harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。 -- 仅 QQBot 的命令： +- 仅 QQBot 可用的命令： - `/bot-ping` - `/bot-version` - `/bot-help` - `/bot-upgrade` - `/bot-logs` -### 动态 Skill 命令 +### 动态 Skills 命令 -用户可调用的 Skills 也会作为斜杠命令公开： +用户可调用的 Skills 也会作为斜杠命令暴露： - `/skill [input]` 始终可作为通用入口点使用。 -- 当 Skill/插件注册直接命令时，Skills 也可能以 `/prose` 这样的直接命令出现。 -- 原生 Skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 +- 当 skill/插件注册后，Skills 也可能显示为 `/prose` 这样的直接命令。 +- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 - 命令规格可以为支持本地化描述的原生界面提供 `descriptionLocalizations`，包括 Discord。 - - 命令允许在命令和参数之间使用可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 - - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，文本会被视为消息正文。 - - 如需完整的提供商用量细分，请使用 `openclaw status --usage`。 - - `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。 - - 在多账号渠道中，面向配置的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账号的 `configWrites`。 - - `/usage` 控制每条回复的用量页脚；`/usage cost` 会根据 OpenClaw 会话日志打印本地费用汇总。 + - 命令在命令和参数之间接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 + - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。 + - 要查看完整的提供商用量明细，请使用 `openclaw status --usage`。 + - `/allowlist add|remove` 需要 `commands.config=true`，并遵守渠道 `configWrites`。 + - 在多账号渠道中，面向配置目标的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵守目标账号的 `configWrites`。 + - `/usage` 控制每条回复的用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地成本摘要。 - `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。 - - `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包、`git:` 或 `clawhub:`，然后由于插件源码模块已更改而请求重启 Gateway 网关。 + - `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包、`git:` 或 `clawhub:`，然后因为插件源模块已更改而请求重启 Gateway 网关。 - `/plugins enable|disable` 更新插件配置，并为新的智能体轮次触发 Gateway 网关插件重新加载。 - - - 仅 Discord 原生命令：`/vc join|leave|status` 控制语音渠道（不能作为文本使用）。`join` 需要一个服务器和所选的语音/舞台渠道。需要 `channels.discord.voice` 和原生命令。 - - Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 + + - 仅 Discord 可用的原生命令：`/vc join|leave|status` 控制语音频道（不能作为文本使用）。`join` 需要一个服务器和已选择的语音/舞台频道。需要 `channels.discord.voice` 和原生命令。 + - Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要有效线程绑定已启用（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 - ACP 命令参考和运行时行为：[ACP 智能体](/zh-CN/tools/acp-agents)。 - - - `/verbose` 用于调试和额外可见性；日常使用时保持**关闭**。 - - `/trace` 比 `/verbose` 范围更窄：它只显示插件拥有的跟踪/调试行，并保持常规详细工具输出关闭。 - - `/fast on|off` 会持久保存一个会话覆盖项。使用会话 UI 的 `inherit` 选项可清除它，并回退到配置默认值。 - - `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射为 `service_tier=priority`，而直接的公共 Anthropic 请求（包括发送到 `api.anthropic.com` 的 OAuth 认证流量）会将其映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 + + - `/verbose` 用于调试和提供额外可见性；正常使用时保持**关闭**。 + - `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具噪声关闭。 + - `/fast on|off` 会持久化会话覆盖。使用会话 UI 的 `inherit` 选项清除它，并回退到配置默认值。 + - `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将它映射到 `service_tier=priority`，而直接的公开 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会将它映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 - 相关时仍会显示工具失败摘要，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。 - - `/reasoning`、`/verbose` 和 `/trace` 在群组环境中有风险：它们可能暴露你不想公开的内部推理、工具输出或插件诊断信息。最好保持关闭，尤其是在群聊中。 + - `/reasoning`、`/verbose` 和 `/trace` 在群组环境中有风险：它们可能泄露你并不打算暴露的内部推理、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。 - - `/model` 会立即持久保存新的会话模型。 + - `/model` 会立即持久化新的会话模型。 - 如果智能体处于空闲状态，下一次运行会立刻使用它。 - - 如果已有运行处于活跃状态，OpenClaw 会将实时切换标记为待处理，并且只会在干净的重试点重启到新模型。 - - 如果工具活动或回复输出已经开始，待处理的切换可能会一直排队到之后的重试机会或下一个用户轮次。 - - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这独立于消息渠道救援模式，也不会授予远程配置权限。 + - 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在干净的重试点重启到新模型。 + - 如果工具活动或回复输出已经开始，待处理的切换可能会一直排队，直到之后的重试机会或下一次用户轮次。 + - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这与消息渠道救援模式分离，并且不会授予远程配置权限。 - - - **快速路径：** 来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。 - - **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。 - - **行内快捷方式（仅允许列表发送者）：** 某些命令嵌入普通消息时也可工作，并会在模型看到剩余文本前被移除。 - - 示例：`hey /status` 触发状态回复，剩余文本继续进入普通流程。 + + - **快速路径：**来自允许列表发送者的仅命令消息会立即处理（绕过队列 + 模型）。 + - **群组提及门控：**来自允许列表发送者的仅命令消息会绕过提及要求。 + - **内联快捷方式（仅允许列表发送者）：**某些命令嵌入普通消息时也会生效，并会在模型看到剩余文本之前被剥离。 + - 示例：`hey /status` 会触发状态回复，剩余文本继续走普通流程。 - 当前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - - 未授权的纯命令消息会被静默忽略，行内 `/...` 片段会被视为普通文本。 + - 未授权的仅命令消息会被静默忽略，内联 `/...` 标记会被视为纯文本。 - - **Skill 命令：** `user-invocable` Skills 会作为斜杠命令公开。名称会清理为 `a-z0-9_`（最多 32 个字符）；冲突时会添加数字后缀（例如 `_2`）。 - - `/skill [input]` 按名称运行一个 Skill（当原生命令限制无法为每个 Skill 创建命令时很有用）。 - - 默认情况下，Skill 命令会作为普通请求转发给模型。 - - Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性、无模型）。 + - **Skill 命令：**`user-invocable` Skills 会作为斜杠命令暴露。名称会被清洗为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。 + - `/skill [input]` 按名称运行一个 skill（当原生命令限制阻止为每个 skill 提供命令时很有用）。 + - 默认情况下，skill 命令会作为普通请求转发给模型。 + - Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，无模型）。 - 示例：`/prose`（OpenProse 插件）— 参见 [OpenProse](/zh-CN/prose)。 - - **原生命令参数：** Discord 对动态选项使用自动补全（缺少必需参数时使用按钮菜单）。当命令支持选项且你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选项会根据目标会话模型解析，因此 `/think` 级别等模型特定选项会遵循该会话的 `/model` 覆盖项。 + - **原生命令参数：**Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。动态选项会根据目标会话模型解析，因此 `/think` 级别等模型特定选项会跟随该会话的 `/model` 覆盖。 ## `/tools` -`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体在当前对话中现在可以使用什么**。 +`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体现在在这次对话中可以使用什么**。 -- 默认的 `/tools` 简洁，并针对快速扫描优化。 -- `/tools verbose` 会添加简短描述。 -- 支持参数的原生命令界面会公开相同的模式切换，即 `compact|verbose`。 -- 结果按会话限定，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。 -- `/tools` 包括运行时实际可达的工具，包括核心工具、已连接的插件工具以及渠道拥有的工具。 +- 默认 `/tools` 很紧凑，并针对快速浏览优化。 +- `/tools verbose` 添加简短描述。 +- 支持参数的原生命令界面会暴露相同的模式切换：`compact|verbose`。 +- 结果是会话作用域的，因此更改智能体、渠道、线程、发送者授权或模型可能会改变输出。 +- `/tools` 包含运行时实际可达的工具，包括核心工具、已连接插件工具以及渠道拥有的工具。 -如需编辑配置文件和覆盖项，请使用 Control UI Tools 面板或配置/目录界面，而不要把 `/tools` 当作静态目录。 +要编辑配置文件和覆盖，请使用 Control UI Tools 面板或配置/目录界面，而不是把 `/tools` 当作静态目录。 ## 用量界面（哪里显示什么） -- **提供商用量/配额**（示例：“Claude 剩余 80%”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余百分比”；对于 MiniMax，仅表示剩余的百分比字段会在显示前取反，并且 `model_remains` 响应会优先使用聊天模型条目以及带模型标记的套餐标签。 -- **Token/缓存行** 在 `/status` 中可以在实时会话快照信息稀疏时回退到最新的转录用量条目。已有的非零实时值仍然优先，并且在已存总量缺失或更小时，转录回退还可以恢复当前运行时模型标签以及更大的、面向提示词的总量。 -- **执行与运行时：** `/status` 会为有效的沙箱路径报告 `Execution`，并为实际运行会话的对象报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。 -- **每次响应的 token/成本** 由 `/usage off|tokens|full` 控制（附加到普通回复中）。 -- `/model status` 关注的是 **模型/凭证/端点**，而不是用量。 +- **提供商用量/配额**（示例：“Claude 80% left”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会把提供商窗口规范化为 `% left`；对于 MiniMax，仅剩余百分比字段会在显示前反转，`model_remains` 响应优先使用聊天模型条目以及带模型标记的方案标签。 +- **Token/缓存行** 在 `/status` 中可以在实时会话快照稀疏时回退到最新的转录用量条目。已有的非零实时值仍然优先，转录回退也可以在存储的总量缺失或更小时恢复活动运行时模型标签，以及更大的面向提示词的总量。 +- **执行与运行时：** `/status` 会为有效沙箱路径报告 `Execution`，并为实际运行会话的一方报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、某个 CLI 后端，或某个 ACP 后端。 +- **每次响应的 token/费用** 由 `/usage off|tokens|full` 控制（追加到正常回复）。 +- `/model status` 关注的是**模型/凭证/端点**，不是用量。 ## 模型选择（`/model`） @@ -337,16 +338,16 @@ x-i18n: /model status ``` -注意： +说明： -- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型家族 + 可用提供商）。 -- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单以及提交步骤。 -- `/model <#>` 会从该选择器中选择（并在可能时优先使用当前提供商）。 -- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用。 +- `/model` 和 `/model list` 会显示紧凑的编号选择器（模型系列 + 可用提供商）。 +- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个 Submit 步骤。 +- `/model <#>` 会从该选择器中选择（并尽可能优先使用当前提供商）。 +- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`，如果可用）。 -## 调试覆盖 +## 调试覆盖项 -`/debug` 让你设置**仅运行时**配置覆盖（内存中，而不是磁盘）。仅限所有者。默认禁用；使用 `commands.debug: true` 启用。 +`/debug` 允许你设置**仅运行时**配置覆盖项（内存中，不写入磁盘）。仅限所有者。默认禁用；使用 `commands.debug: true` 启用。 示例： @@ -359,12 +360,12 @@ x-i18n: ``` -覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并返回磁盘上的配置。 +覆盖项会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖项并返回磁盘上的配置。 ## 插件跟踪输出 -`/trace` 让你切换**会话范围内的插件跟踪/调试行**，无需开启完整详细模式。 +`/trace` 允许你切换**会话作用域的插件跟踪/调试行**，无需开启完整详细模式。 示例： @@ -374,14 +375,14 @@ x-i18n: /trace off ``` -注意： +说明： -- 不带参数的 `/trace` 会显示当前会话跟踪状态。 +- 不带参数的 `/trace` 会显示当前会话的跟踪状态。 - `/trace on` 会为当前会话启用插件跟踪行。 - `/trace off` 会再次禁用它们。 -- 插件跟踪行可能出现在 `/status` 中，也可能在普通助手回复之后作为后续诊断消息出现。 -- `/trace` 不会替代 `/debug`；`/debug` 仍然管理仅运行时配置覆盖。 -- `/trace` 不会替代 `/verbose`；普通的详细工具/Status 输出仍然属于 `/verbose`。 +- 插件跟踪行可以出现在 `/status` 中，也可以在正常 assistant 回复后作为后续诊断消息出现。 +- `/trace` 不会替代 `/debug`；`/debug` 仍然管理仅运行时配置覆盖项。 +- `/trace` 不会替代 `/verbose`；正常的详细工具/状态输出仍然归 `/verbose` 管理。 ## 配置更新 @@ -398,7 +399,7 @@ x-i18n: ``` -配置会在写入前进行验证；无效更改会被拒绝。`/config` 更新会在重启后保留。 +写入前会验证配置；无效更改会被拒绝。`/config` 更新会在重启后保留。 ## MCP 更新 @@ -415,12 +416,12 @@ x-i18n: ``` -`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定哪些传输协议实际可执行。 +`/mcp` 会把配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器会决定哪些传输协议实际可执行。 ## 插件更新 -`/plugins` 让操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。 +`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。 示例： @@ -433,29 +434,29 @@ x-i18n: ``` -- `/plugins list` 和 `/plugins show` 会基于当前工作区以及磁盘上的配置执行真实插件发现。 -- `/plugins install` 会从 ClawHub、npm、git、本地目录和归档安装。 -- `/plugins enable|disable` 仅更新插件配置；它不会安装或卸载插件。 -- 启用和禁用更改会为新的智能体轮次热重载 Gateway 网关插件运行时表面；安装会请求 Gateway 网关重启，因为插件源模块发生了变化。 +- `/plugins list` 和 `/plugins show` 会针对当前工作区以及磁盘配置使用真实插件发现。 +- `/plugins install` 会从 ClawHub、npm、git、本地目录和归档文件安装。 +- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。 +- 启用和禁用更改会为新的智能体轮次热重载 Gateway 网关插件运行时界面；安装会请求重启 Gateway 网关，因为插件源模块已发生变化。 -## 表面说明 +## 界面说明 - - - **文本命令** 在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。 + + - **文本命令** 在正常聊天会话中运行（私信共享 `main`，群组有自己的会话）。 - **原生命令** 使用隔离会话： - Discord：`agent::discord:slash:` - Slack：`agent::slack:slash:`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置） - - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位聊天会话） - - **`/stop`** 定位当前聊天会话，因此它可以中止当前运行。 + - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位到聊天会话） + - **`/stop`** 定位到活动聊天会话，因此它可以中止当前运行。 - - `channels.slack.slashCommand` 仍然支持单个 `/openclaw` 风格的命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack slash command（名称与 `/help` 相同）。Slack 的命令参数菜单会作为临时的 Block Kit 按钮发送。 + + 仍然支持 `channels.slack.slashCommand` 用于单个 `/openclaw` 风格命令。如果启用 `commands.native`，你必须为每个内置命令创建一个 Slack slash command（名称与 `/help` 相同）。Slack 的命令参数菜单会作为临时 Block Kit 按钮送达。 - Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 仍可在 Slack 消息中使用。 + Slack 原生例外：注册 `/agentstatus`（不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。 @@ -464,15 +465,15 @@ x-i18n: `/btw` 是关于当前会话的快速**附带问题**。`/side` 是别名。 -与普通聊天不同： +与正常聊天不同： - 它使用当前会话作为背景上下文， - 它作为单独的**无工具**一次性调用运行， -- 它不会改变未来的会话上下文， +- 它不会改变未来会话上下文， - 它不会写入转录历史， -- 它作为实时附带结果发送，而不是普通助手消息。 +- 它会作为实时附带结果送达，而不是正常 assistant 消息。 -这使得 `/btw` 在你希望主任务继续进行时获得临时说明很有用。 +当你希望在主任务继续进行时临时澄清问题，`/btw` 会很有用。 示例： @@ -481,9 +482,9 @@ x-i18n: /side what changed while the main run continued? ``` -查看 [BTW 附带问题](/zh-CN/tools/btw)，了解完整行为和客户端 UX 细节。 +完整行为和客户端 UX 详情见 [BTW 附带问题](/zh-CN/tools/btw)。 -## 相关 +## 相关内容 - [创建 Skills](/zh-CN/tools/creating-skills) - [Skills](/zh-CN/tools/skills) diff --git a/docs/zh-CN/tools/subagents.md b/docs/zh-CN/tools/subagents.md index bb8176910..480bc3358 100644 --- a/docs/zh-CN/tools/subagents.md +++ b/docs/zh-CN/tools/subagents.md @@ -1,37 +1,48 @@ --- read_when: - - 你想通过智能体进行后台或并行工作 + - 你想通过智能体执行后台或并行工作 - 你正在更改 sessions_spawn 或子智能体工具策略 - - 你正在实现线程绑定的子智能体会话，或对其进行故障排除 + - 你正在实现或排查线程绑定的子智能体会话 sidebarTitle: Sub-agents -summary: 启动隔离的后台智能体运行任务，并将结果回报到请求者聊天 +summary: 启动隔离的后台智能体运行，并将结果回告到请求者聊天 title: 子智能体 x-i18n: - generated_at: "2026-05-02T06:10:58Z" + generated_at: "2026-05-03T21:42:01Z" model: gpt-5.5 provider: openai - source_hash: 0e964df543bd19435daf94f2c85a34b9d32e07662405d2eac7635935f1e7bf64 + source_hash: e09370a96c3af4752a774aba5db62e38b0afd78bc5e105597d977cb130597daf source_path: tools/subagents.md workflow: 16 --- -子智能体是从现有智能体运行中派生出的后台智能体运行。 -它们在自己的会话（`agent::subagent:`）中运行，并在完成后将结果**通知**回请求者聊天渠道。每个子智能体运行都会作为一个[后台任务](/zh-CN/automation/tasks)进行跟踪。 +子智能体是从现有智能体运行中生成的后台智能体运行。 +它们在自己的会话（`agent::subagent:`）中运行， +完成后会将结果**告知**回请求方聊天 +渠道。每次子智能体运行都会作为 +[后台任务](/zh-CN/automation/tasks)进行跟踪。 主要目标： - 并行处理“研究 / 长任务 / 慢工具”工作，而不阻塞主运行。 - 默认保持子智能体隔离（会话分离 + 可选沙箱隔离）。 -- 保持工具表面难以误用：子智能体默认不会获得会话工具。 +- 让工具表面难以误用：子智能体默认**不会**获得会话工具。 - 支持可配置的嵌套深度，用于编排器模式。 -**成本注意事项：**默认情况下，每个子智能体都有自己的上下文和 token 用量。对于繁重或重复的任务，可以为子智能体设置更便宜的模型，并让你的主智能体使用更高质量的模型。通过 `agents.defaults.subagents.model` 或按智能体覆盖项进行配置。当子级确实需要请求者当前转录时，智能体可以在那次派生中请求 `context: "fork"`。线程绑定的子智能体会话默认使用 `context: "fork"`，因为它们会把当前对话分支到一个后续线程中。 +**成本注意事项：**默认情况下，每个子智能体都有自己的上下文和 token 用量。 +对于繁重或重复的任务，请为子智能体设置更便宜的模型， +并让你的主智能体使用质量更高的模型。通过 +`agents.defaults.subagents.model` 或按智能体覆盖项进行配置。当子级 + 确实需要请求方的当前转录时，智能体可以在该次生成中请求 + `context: "fork"`。线程绑定的子智能体会话默认使用 + `context: "fork"`，因为它们会将当前对话分支到一个 + 后续线程。 -## Slash 命令 +## 斜杠命令 -使用 `/subagents` 检查或控制**当前会话**的子智能体运行： +使用 `/subagents` 检查或控制**当前 +会话**的子智能体运行： ```text /subagents list @@ -43,12 +54,17 @@ x-i18n: /subagents spawn [--model ] [--thinking ] ``` -`/subagents info` 会显示运行元数据（状态、时间戳、会话 ID、转录路径、清理）。使用 `sessions_history` 获取有界、经过安全过滤的回忆视图；当你需要原始完整转录时，检查磁盘上的转录路径。 +使用顶层 `/steer ` 来引导当前请求方会话的活跃运行。当目标是子运行时，使用 `/subagents steer `。 + +`/subagents info` 显示运行元数据（状态、时间戳、会话 id、 +转录路径、清理）。使用 `sessions_history` 获取有界、 +经过安全过滤的回忆视图；当你需要原始完整转录时， +检查磁盘上的转录路径。 ### 线程绑定控制 这些命令适用于支持持久线程绑定的渠道。 -参见下方的[支持线程的渠道](#thread-supporting-channels)。 +请参见下方的[支持线程的渠道](#thread-supporting-channels)。 ```text /focus @@ -58,60 +74,72 @@ x-i18n: /session max-age ``` -### 派生行为 +### 生成行为 -`/subagents spawn` 会作为用户命令启动一个后台子智能体（而不是内部中继），并在运行完成时向请求者聊天发送一次最终完成更新。 +`/subagents spawn` 作为用户命令（不是内部中继）启动一个后台子智能体， +并在运行完成时向请求方聊天发送一条最终完成更新。 - - 派生命令是非阻塞的；它会立即返回一个运行 ID。 - - 完成时，子智能体会向请求者聊天渠道通知一条摘要/结果消息。 - - 完成是基于推送的。派生后，不要为了等待它完成而循环轮询 `/subagents list`、`sessions_list` 或 `sessions_history`；只在按需调试或干预时检查状态。 - - 完成时，OpenClaw 会在通知清理流程继续之前，尽力关闭该子智能体会话打开的已跟踪浏览器标签页/进程。 + - 生成命令是非阻塞的；它会立即返回一个运行 id。 + - 完成时，子智能体会向请求方聊天渠道告知一条摘要/结果消息。 + - 完成是基于推送的。生成后，**不要**为了等待它结束而循环轮询 `/subagents list`、`sessions_list` 或 `sessions_history`；仅在调试或干预时按需检查状态。 + - 完成时，OpenClaw 会尽力关闭该子智能体会话打开并跟踪的浏览器标签页/进程，然后继续执行告知清理流程。 - - - OpenClaw 会先尝试使用稳定的幂等键进行直接 `agent` 投递。 - - 如果直接投递失败，它会回退到队列路由。 - - 如果队列路由仍不可用，通知会在最终放弃前使用短暂的指数退避进行重试。 - - 完成投递会保留已解析的请求者路由：当线程绑定或对话绑定的完成路由可用时优先使用；如果完成来源只提供渠道，OpenClaw 会从请求者会话的已解析路由（`lastChannel` / `lastTo` / `lastAccountId`）补齐缺失的目标/账号，使直接投递仍然可用。 + + - OpenClaw 首先尝试使用稳定幂等键进行直接 `agent` 交付。 + - 如果直接交付失败，它会回退到队列路由。 + - 如果队列路由仍然不可用，告知会先用短指数退避重试，然后才最终放弃。 + - 完成交付会保留已解析的请求方路由：可用时，线程绑定或对话绑定的完成路由优先；如果完成来源只提供渠道，OpenClaw 会从请求方会话的已解析路由（`lastChannel` / `lastTo` / `lastAccountId`）补齐缺失的目标/账户，这样直接交付仍可工作。 - 向请求者会话的完成交接是运行时生成的内部上下文（不是用户编写的文本），并包含： + 发送给请求方会话的完成交接是运行时生成的 + 内部上下文（不是用户撰写的文本），包含： - - `Result` — 最新可见的 `assistant` 回复文本，否则为经过清理的最新 tool/toolResult 文本。终态失败的运行不会复用捕获的回复文本。 + - `Result` — 最新可见的 `assistant` 回复文本；否则为经过清理的最新工具/toolResult 文本。终止失败的运行不会复用已捕获的回复文本。 - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`。 - - 紧凑的运行时/token 统计。 - - 一条投递指令，要求请求者智能体用普通助手语气改写（而不是转发原始内部元数据）。 + - 紧凑的运行时/token 统计信息。 + - 一条交付指令，告诉请求方智能体用普通助手语气重写（而不是转发原始内部元数据）。 - `--model` 和 `--thinking` 会覆盖该特定运行的默认值。 - - 使用 `info`/`log` 在完成后检查详细信息和输出。 - - `/subagents spawn` 是一次性模式（`mode: "run"`）。对于持久的线程绑定会话，请使用带有 `thread: true` 和 `mode: "session"` 的 `sessions_spawn`。 - - 对于 ACP harness 会话（Claude Code、Gemini CLI、OpenCode，或显式的 Codex ACP/acpx），当工具声明该运行时时，请使用带有 `runtime: "acp"` 的 `sessions_spawn`。调试完成或智能体到智能体循环时，参见 [ACP 投递模型](/zh-CN/tools/acp-agents#delivery-model)。当启用 `codex` 插件时，Codex 聊天/线程控制应优先使用 `/codex ...`，除非用户明确要求 ACP/acpx。 - - 在启用 ACP、请求者未被沙箱隔离，并且加载了 `acpx` 等后端插件之前，OpenClaw 会隐藏 `runtime: "acp"`。`runtime: "acp"` 需要外部 ACP harness ID，或一个 `runtime.type="acp"` 的 `agents.list[]` 条目；对于来自 `agents_list` 的普通 OpenClaw 配置智能体，请使用默认子智能体运行时。 + - 使用 `info`/`log` 在完成后检查详情和输出。 + - `/subagents spawn` 是一次性模式（`mode: "run"`）。对于持久线程绑定会话，请使用 `sessions_spawn`，并设置 `thread: true` 和 `mode: "session"`。 + - 对于 ACP harness 会话（Claude Code、Gemini CLI、OpenCode，或显式的 Codex ACP/acpx），当工具声明该运行时时，使用 `sessions_spawn` 并设置 `runtime: "acp"`。调试完成或智能体到智能体循环时，请参见 [ACP 交付模型](/zh-CN/tools/acp-agents#delivery-model)。启用 `codex` 插件时，除非用户明确要求 ACP/acpx，否则 Codex 聊天/线程控制应优先使用 `/codex ...` 而不是 ACP。 + - 在 ACP 启用、请求方未被沙箱隔离，并且已加载 `acpx` 等后端插件之前，OpenClaw 会隐藏 `runtime: "acp"`。`runtime: "acp"` 需要一个外部 ACP harness id，或者一个 `runtime.type="acp"` 的 `agents.list[]` 条目；对于来自 `agents_list` 的普通 OpenClaw 配置智能体，请使用默认子智能体运行时。 ## 上下文模式 -原生子智能体默认以隔离方式启动，除非调用方明确要求 fork 当前转录。 +原生子智能体会以隔离状态启动，除非调用方明确要求 fork +当前转录。 -| 模式 | 何时使用 | 行为 | +| 模式 | 使用场景 | 行为 | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| `isolated` | 全新研究、独立实现、慢工具工作，或任何可以在任务文本中简要说明的内容 | 创建一个干净的子转录。这是默认值，并会降低 token 用量。 | -| `fork` | 依赖当前对话、先前工具结果，或请求者转录中已有的细致指令的工作 | 在子级启动前，将请求者转录分支到子会话。 | +| `isolated` | 全新研究、独立实现、慢工具工作，或任何可以在任务文本中简要说明的事项 | 创建干净的子转录。这是默认值，并且会降低 token 用量。 | +| `fork` | 依赖当前对话、先前工具结果，或请求方转录中已有细微指令的工作 | 在子级启动前，将请求方转录分支到子会话中。 | -请谨慎使用 `fork`。它用于上下文敏感的委派，而不是替代编写清晰的任务提示。 +谨慎使用 `fork`。它用于上下文敏感的委派， +而不是替代清晰任务提示的方式。 ## 工具：`sessions_spawn` -在全局 `subagent` 通道上以 `deliver: false` 启动子智能体运行，然后执行通知步骤，并将通知回复发布到请求者聊天渠道。 +在全局 `subagent` lane 上以 `deliver: false` 启动子智能体运行， +随后运行告知步骤，并将告知回复发布到请求方 +聊天渠道。 -可用性取决于调用方的有效工具策略。`coding` 和 `full` 配置文件默认公开 `sessions_spawn`。`messaging` 配置文件不会；对于应委派工作的智能体，请添加 `tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"]` 或使用 `tools.profile: "coding"`。渠道/群组、提供商、沙箱以及按智能体的允许/拒绝策略仍可能在配置文件阶段后移除该工具。使用同一会话中的 `/tools` 确认有效工具列表。 +可用性取决于调用方的有效工具策略。`coding` 和 +`full` 配置文件默认公开 `sessions_spawn`。`messaging` 配置文件 +不会公开；对于应委派工作的智能体，请添加 `tools.alsoAllow: ["sessions_spawn", "sessions_yield", +"subagents"]`，或使用 `tools.profile: "coding"`。 +渠道/群组、提供商、沙箱，以及按智能体允许/拒绝策略仍可 +在配置文件阶段后移除该工具。从同一个 +会话使用 `/tools` 来确认有效工具列表。 **默认值：** @@ -128,68 +156,80 @@ x-i18n: 可选的人类可读标签。 - 在 `subagents.allowAgents` 允许时，在另一个智能体 ID 下派生。 + 在 `subagents.allowAgents` 允许时，在另一个智能体 id 下生成。 `acp` 仅用于外部 ACP harness（`claude`、`droid`、`gemini`、`opencode`，或明确请求的 Codex ACP/acpx），以及 `runtime.type` 为 `acp` 的 `agents.list[]` 条目。 - 仅 ACP。在 `runtime: "acp"` 时恢复现有 ACP harness 会话；对原生子智能体派生会被忽略。 + 仅限 ACP。`runtime: "acp"` 时恢复现有 ACP harness 会话；对原生子智能体生成会被忽略。 - 仅 ACP。在 `runtime: "acp"` 时将 ACP 运行输出流式传输到父会话；原生子智能体派生时省略。 + 仅限 ACP。`runtime: "acp"` 时将 ACP 运行输出流式传输到父会话；原生子智能体生成时省略。 - 覆盖子智能体模型。无效值会被跳过，子智能体会在默认模型上运行，并在工具结果中给出警告。 + 覆盖子智能体模型。无效值会被跳过，子智能体将使用默认模型运行，并在工具结果中给出警告。 覆盖子智能体运行的 thinking 级别。 - 已设置时默认为 `agents.defaults.subagents.runTimeoutSeconds`，否则为 `0`。设置后，子智能体运行会在 N 秒后中止。 + 设置时默认使用 `agents.defaults.subagents.runTimeoutSeconds`，否则为 `0`。设置后，子智能体运行会在 N 秒后中止。 - 当为 `true` 时，为此子智能体会话请求渠道线程绑定。 + 当为 `true` 时，为该子智能体会话请求渠道线程绑定。 - 如果 `thread: true` 且省略 `mode`，默认值会变为 `session`。`mode: "session"` 需要 `thread: true`。 + 如果 `thread: true` 且省略 `mode`，默认值变为 `session`。`mode: "session"` 需要 `thread: true`。 - `"delete"` 会在通知后立即归档（仍通过重命名保留转录）。 + `"delete"` 会在告知后立即归档（仍通过重命名保留转录）。 - `require` 会在目标子级运行时未被沙箱隔离时拒绝派生。 + `require` 会拒绝生成，除非目标子运行时已被沙箱隔离。 - `fork` 会把请求者的当前转录分支到子会话。仅限原生子智能体。线程绑定的派生默认使用 `fork`；非线程派生默认使用 `isolated`。 + `fork` 会将请求方的当前转录分支到子会话。仅限原生子智能体。线程绑定生成默认使用 `fork`；非线程生成默认使用 `isolated`。 -`sessions_spawn` 不接受渠道投递参数（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）。投递请从派生运行中使用 `message`/`sessions_send`。 +`sessions_spawn` **不**接受渠道交付参数（`target`、 +`channel`、`to`、`threadId`、`replyTo`、`transport`）。交付时，请从生成的运行使用 +`message`/`sessions_send`。 ## 线程绑定会话 -当某个渠道启用线程绑定时，子智能体可以保持绑定到某个线程，使该线程中的后续用户消息继续路由到同一子智能体会话。 +为某个渠道启用线程绑定后，子智能体可以持续绑定到 +某个线程，使该线程中的后续用户消息继续路由到 +同一个子智能体会话。 ### 支持线程的渠道 -**Discord** 目前是唯一受支持的渠道。它支持持久的线程绑定子智能体会话（带有 `thread: true` 的 `sessions_spawn`）、手动线程控制（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`），以及适配器键 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSessions`。 +**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.spawnSessions`。 ### 快速流程 - - 带有 `thread: true` 的 `sessions_spawn`（并可选使用 `mode: "session"`）。 + + 使用 `sessions_spawn` 并设置 `thread: true`（以及可选的 `mode: "session"`）。 - OpenClaw 会在活跃渠道中创建一个线程，或将线程绑定到该会话目标。 + OpenClaw 在活跃渠道中创建一个线程，或将线程绑定到该会话目标。 - 该线程中的回复和后续消息会路由到已绑定会话。 + 该线程中的回复和后续消息会路由到绑定的会话。 - 使用 `/session idle` 检查/更新不活跃自动取消聚焦，并使用 `/session max-age` 控制硬性上限。 + 使用 `/session idle` 检查/更新非活动自动取消聚焦，并 + 使用 `/session max-age` 控制硬上限。 使用 `/unfocus` 手动分离。 @@ -198,55 +238,53 @@ x-i18n: ### 手动控制 -| 命令 | 作用 | -| ------------------ | --------------------------------------------------------------------- | -| `/focus ` | 将当前线程（或新建一个线程）绑定到子智能体/会话目标 | -| `/unfocus` | 移除当前已绑定线程的绑定 | -| `/agents` | 列出活跃运行和绑定状态（`thread:` 或 `unbound`） | -| `/session idle` | 查看/更新空闲自动取消聚焦（仅限已聚焦的绑定线程） | -| `/session max-age` | 查看/更新硬性上限（仅限已聚焦的绑定线程） | +| 命令 | 效果 | +| ------------------ | -------------------------------------------------------------------- | +| `/focus ` | 将当前线程（或创建一个线程）绑定到子智能体/会话目标 | +| `/unfocus` | 移除当前已绑定线程的绑定 | +| `/agents` | 列出活跃运行和绑定状态（`thread:` 或 `unbound`） | +| `/session idle` | 查看/更新空闲自动取消聚焦（仅限已聚焦的绑定线程） | +| `/session max-age` | 查看/更新硬性上限（仅限已聚焦的绑定线程） | ### 配置开关 -- **全局默认值：** `session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 -- **渠道覆盖和生成自动绑定键** 是适配器特定的。请参阅上面的 [支持线程的渠道](#thread-supporting-channels)。 +- **全局默认值：**`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 +- **渠道覆盖和生成时自动绑定键**特定于适配器。参见上方的[支持线程的渠道](#thread-supporting-channels)。 -有关当前适配器详情，请参阅 [配置参考](/zh-CN/gateway/configuration-reference) 和 +有关当前适配器的详细信息，请参见[配置参考](/zh-CN/gateway/configuration-reference)和 [斜杠命令](/zh-CN/tools/slash-commands)。 ### 允许列表 - 可通过显式 `agentId` 作为目标的智能体 id 列表（`["*"]` 允许任意智能体）。默认值：仅请求方智能体。如果你设置了列表，并且仍希望请求方使用 `agentId` 生成自身，请在列表中包含请求方 id。 + 可通过显式 `agentId` 指定为目标的智能体 ID 列表（`["*"]` 允许任意智能体）。默认值：仅请求方智能体。如果你设置了列表，并且仍希望请求方通过 `agentId` 生成自身，请将请求方 ID 包含在列表中。 当请求方智能体未设置自己的 `subagents.allowAgents` 时使用的默认目标智能体允许列表。 - 阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件）。按智能体覆盖：`agents.list[].subagents.requireAgentId`。 + 阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置档案）。单智能体覆盖：`agents.list[].subagents.requireAgentId`。 -如果请求方会话已沙箱隔离，`sessions_spawn` 会拒绝以非沙箱隔离方式运行的目标。 +如果请求方会话处于沙箱隔离状态，`sessions_spawn` 会拒绝那些将以非沙箱隔离方式运行的目标。 ### 设备发现 -使用 `agents_list` 查看当前允许用于 `sessions_spawn` 的智能体 id。响应包含每个已列出智能体的有效模型和嵌入式运行时元数据，因此调用方可以区分 PI、Codex 应用服务器以及其他已配置的原生运行时。 +使用 `agents_list` 查看当前允许 `sessions_spawn` 指向哪些智能体 ID。响应包含每个列出智能体的有效模型和嵌入式运行时元数据，因此调用方可以区分 Pi、Codex 应用服务器以及其他已配置的原生运行时。 ### 自动归档 -- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes` 之后自动归档（默认值 `60`）。 +- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes` 后自动归档（默认 `60`）。 - 归档使用 `sessions.delete`，并将转录重命名为 `*.deleted.`（同一文件夹）。 -- `cleanup: "delete"` 会在通知后立即归档（仍通过重命名保留转录）。 -- 自动归档是尽力而为；如果 Gateway 网关重启，待处理计时器会丢失。 -- `runTimeoutSeconds` **不会**自动归档；它只会停止运行。会话会保留到自动归档发生。 +- `cleanup: "delete"` 会在 announce 后立即归档（仍通过重命名保留转录）。 +- 自动归档是尽力而为；如果 Gateway 网关重启，挂起的计时器会丢失。 +- `runTimeoutSeconds` **不会**自动归档；它只会停止运行。会话会一直保留到自动归档。 - 自动归档同样适用于深度 1 和深度 2 会话。 -- 浏览器清理与归档清理分离：跟踪的浏览器标签页/进程会在运行结束时尽力关闭，即使转录/会话记录被保留。 +- 浏览器清理与归档清理分开：即使保留转录/会话记录，也会在运行结束时尽力关闭已跟踪的浏览器标签页/进程。 ## 嵌套子智能体 -默认情况下，子智能体不能生成自己的子智能体 -（`maxSpawnDepth: 1`）。设置 `maxSpawnDepth: 2` 可启用一层嵌套，即**编排器模式**：主智能体 → 编排器子智能体 → -工作子智能体。 +默认情况下，子智能体不能生成自己的子智能体（`maxSpawnDepth: 1`）。设置 `maxSpawnDepth: 2` 可启用一层嵌套，即**编排器模式**：主智能体 → 编排器子智能体 → 工作子子智能体。 ```json5 { @@ -265,39 +303,36 @@ 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:` | 子子智能体（叶子工作者） | 永远不能 | -### 通知链 +### Announce 链 -结果会沿链路向上传回： +结果沿链向上流动： -1. 深度 2 工作器完成 → 通知其父级（深度 1 编排器）。 -2. 深度 1 编排器收到通知，综合结果，完成 → 通知主智能体。 -3. 主智能体收到通知并交付给用户。 +1. 深度 2 工作者完成 → announce 给其父级（深度 1 编排器）。 +2. 深度 1 编排器接收 announce，综合结果并完成 → announce 给主智能体。 +3. 主智能体接收 announce 并交付给用户。 -每一级只会看到来自其直接子级的通知。 +每一级只能看到其直接子级发来的 announce。 -**操作指导：** 启动子任务一次，然后等待完成事件，而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` 睡眠命令构建轮询循环。`sessions_list` 和 `/subagents list` 会让子会话关系聚焦于实时工作：实时子级保持附加，已结束子级会在较短的最近窗口内保持可见，过时的仅存储子级链接会在其新鲜度窗口后被忽略。这可以防止旧的 `spawnedBy` / -`parentSessionKey` 元数据在重启后复活幽灵子级。如果子级完成事件在你已经发送最终答案之后到达，正确的后续响应是完全静默令牌 -`NO_REPLY` / `no_reply`。 +**操作指南：**启动一次子任务，然后等待完成事件，而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` 睡眠命令构建轮询循环。`sessions_list` 和 `/subagents list` 让子会话关系专注于实时工作：实时子级保持附加，已结束子级会在短暂的近期窗口中保持可见，而陈旧的仅存储子级链接会在其新鲜度窗口后被忽略。这可以防止旧的 `spawnedBy` / `parentSessionKey` 元数据在重启后重新唤起幽灵子级。如果子级完成事件在你已经发送最终回答后到达，正确的后续响应是精确的静默令牌 `NO_REPLY` / `no_reply`。 ### 按深度划分的工具策略 -- 角色和控制范围会在生成时写入会话元数据。这样可以防止扁平或恢复后的会话键意外重新获得编排器权限。 -- **深度 1（编排器，当 `maxSpawnDepth >= 2` 时）：** 获得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，因此它可以管理其子级。其他会话/系统工具仍会被拒绝。 -- **深度 1（叶子，当 `maxSpawnDepth == 1` 时）：** 没有会话工具（当前默认行为）。 -- **深度 2（叶子工作器）：** 没有会话工具，`sessions_spawn` 在深度 2 始终被拒绝。无法继续生成子级。 +- 角色和控制范围会在生成时写入会话元数据。这可以防止扁平化或恢复后的会话键意外重新获得编排器权限。 +- **深度 1（编排器，当 `maxSpawnDepth >= 2` 时）：**获得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子级。其他会话/系统工具仍被拒绝。 +- **深度 1（叶子，当 `maxSpawnDepth == 1` 时）：**没有会话工具（当前默认行为）。 +- **深度 2（叶子工作者）：**没有会话工具，`sessions_spawn` 在深度 2 始终被拒绝。不能继续生成子级。 -### 按智能体的生成限制 +### 单智能体生成限制 -每个智能体会话（任意深度）同一时间最多可以有 `maxChildrenPerAgent` -（默认值 `5`）个活跃子级。这可以防止单个编排器失控式扇出。 +每个智能体会话（任意深度）同一时间最多可以有 `maxChildrenPerAgent` 个活跃子级（默认 `5`）。这可以防止单个编排器失控扇出。 ### 级联停止 @@ -307,85 +342,84 @@ x-i18n: - `/subagents kill ` 会停止指定子智能体，并级联到其子级。 - `/subagents kill all` 会停止请求方的所有子智能体并级联。 -## 身份验证 +## 认证 -子智能体身份验证按**智能体 id** 解析，而不是按会话类型解析： +子智能体认证按**智能体 ID**解析，而不是按会话类型解析： -- 子智能体会话键为 `agent::subagent:`。 -- 身份验证存储从该智能体的 `agentDir` 加载。 -- 主智能体的身份验证配置文件会作为**回退**合并进来；发生冲突时，智能体配置文件会覆盖主配置文件。 +- 子智能体会话键是 `agent::subagent:`。 +- 认证存储从该智能体的 `agentDir` 加载。 +- 主智能体的认证配置档案会作为**回退**合并进来；发生冲突时，智能体配置档案会覆盖主配置档案。 -合并是增量的，因此主配置文件始终可作为回退使用。尚不支持按智能体完全隔离身份验证。 +合并是追加式的，因此主配置档案始终可作为回退使用。尚不支持每个智能体完全隔离的认证。 -## 通知 +## Announce -子智能体通过通知步骤回报： +子智能体通过 announce 步骤回报： -- 通知步骤在子智能体会话内运行（不是请求方会话）。 -- 如果子智能体准确回复 `ANNOUNCE_SKIP`，则不会发布任何内容。 -- 如果最新助手文本是完全静默令牌 `NO_REPLY` / `no_reply`，即使之前存在可见进度，也会抑制通知输出。 +- announce 步骤在子智能体会话内运行（不是请求方会话）。 +- 如果子智能体精确回复 `ANNOUNCE_SKIP`，则不会发布任何内容。 +- 如果最新助手文本是精确的静默令牌 `NO_REPLY` / `no_reply`，即使之前存在可见进度，announce 输出也会被抑制。 交付取决于请求方深度： - 顶层请求方会话使用带外部交付的后续 `agent` 调用（`deliver=true`）。 -- 嵌套请求方子智能体会话会接收内部后续注入（`deliver=false`），以便编排器可以在会话内综合子级结果。 +- 嵌套请求方子智能体会话接收内部后续注入（`deliver=false`），以便编排器在会话内综合子级结果。 - 如果嵌套请求方子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求方。 -对于顶层请求方会话，完成模式的直接交付会先解析任何已绑定的对话/线程路由和钩子覆盖，然后从请求方会话存储的路由中填充缺失的渠道目标字段。这样即使完成来源只标识了渠道，也能将完成内容保留在正确的聊天/主题中。 +对于顶层请求方会话，完成模式的直接交付会先解析任何已绑定的对话/线程路由和钩子覆盖，然后从请求方会话的已存储路由中填充缺失的渠道目标字段。这样即使完成来源只标识了渠道，也能让完成内容进入正确的聊天/话题。 -构建嵌套完成发现时，子级完成聚合限定在当前请求方运行范围内，防止陈旧的先前运行子级输出泄漏到当前通知中。渠道适配器可用时，通知回复会保留线程/主题路由。 +构建嵌套完成 findings 时，子级完成聚合会限定在当前请求方运行范围内，防止陈旧的上一次运行子级输出泄漏到当前 announce 中。当渠道适配器可用时，announce 回复会保留线程/话题路由。 -### 通知上下文 +### Announce 上下文 -通知上下文会规范化为稳定的内部事件块： +Announce 上下文会规范化为稳定的内部事件块： -| 字段 | 来源 | -| -------------- | ------------------------------------------------------------------------------------------------------------- | +| 字段 | 来源 | +| ------------ | ------------------------------------------------------------------------------------------------------------- | | 来源 | `subagent` 或 `cron` | -| 会话 id | 子会话键/id | -| 类型 | 通知类型 + 任务标签 | -| Status | 从运行时结果派生（`success`、`error`、`timeout` 或 `unknown`），**不是**从模型文本推断 | -| 结果内容 | 最新可见助手文本，否则为已清理的最新工具/toolResult 文本 | -| 后续操作 | 描述何时回复与何时保持静默的指令 | +| 会话 ID | 子会话键/ID | +| 类型 | Announce 类型 + 任务标签 | +| Status | 从运行时结果派生（`success`、`error`、`timeout` 或 `unknown`），**不是**从模型文本推断 | +| 结果内容 | 最新可见助手文本；否则为经过净化的最新工具/toolResult 文本 | +| 后续 | 描述何时回复与何时保持静默的指令 | -终止失败的运行会报告失败状态，而不会重放已捕获的回复文本。超时时，如果子级只执行到工具调用，通知可以将该历史折叠成简短的部分进度摘要，而不是重放原始工具输出。 +终端失败运行会报告失败状态，而不会重放捕获的回复文本。超时时，如果子级只执行到了工具调用，announce 可以将该历史折叠成简短的部分进度摘要，而不是重放原始工具输出。 ### 统计行 -通知载荷会在末尾包含统计行（即使被换行包装）： +Announce 载荷会在末尾包含统计行（即使被换行包裹）： -- 运行时（例如 `runtime 5m12s`）。 -- 令牌用量（输入/输出/总计）。 +- 运行时长（例如 `runtime 5m12s`）。 +- 令牌使用量（输入/输出/总计）。 - 配置了模型定价时的估算成本（`models.providers.*.models[].cost`）。 -- `sessionKey`、`sessionId` 和转录路径，以便主智能体可以通过 `sessions_history` 获取历史，或检查磁盘上的文件。 +- `sessionKey`、`sessionId` 和转录路径，以便主智能体可以通过 `sessions_history` 获取历史记录，或检查磁盘上的文件。 -内部元数据仅用于编排；面向用户的回复应改写为普通助手语气。 +内部元数据仅用于编排；面向用户的回复应改写为正常的助手语气。 ### 为什么优先使用 `sessions_history` `sessions_history` 是更安全的编排路径： -- 助手回忆会先被规范化：移除思考标签；移除 `` / `` 脚手架；移除纯文本工具调用 XML 载荷块（``、``、``、``），包括从未干净闭合的截断载荷；移除降级后的工具调用/结果脚手架和历史上下文标记；移除泄漏的模型控制令牌（`<|assistant|>`、其他 ASCII `<|...|>`、全角 `<｜...｜>`）；移除格式错误的 MiniMax 工具调用 XML。 -- 类似凭证/令牌的文本会被遮盖。 +- 助手回忆会先被规范化：移除 thinking 标签；移除 `` / `` 脚手架；移除纯文本工具调用 XML 载荷块（``、``、``、``），包括从未正常闭合的截断载荷；移除降级的工具调用/结果脚手架和历史上下文标记；移除泄漏的模型控制令牌（`<|assistant|>`、其他 ASCII `<|...|>`、全角 `<｜...｜>`）；移除格式错误的 MiniMax 工具调用 XML。 +- 凭证/类似令牌的文本会被遮盖。 - 长块可能会被截断。 -- 非常大的历史可能会丢弃较旧的行，或用 `[sessions_history omitted: message too large]` 替换过大的行。 -- 当你需要完整逐字节转录时，回退方案是检查磁盘上的原始转录。 +- 非常大的历史记录可能会丢弃较旧行，或用 `[sessions_history omitted: message too large]` 替换过大的行。 +- 当你需要完整逐字节转录时，原始磁盘转录检查是回退方案。 ## 工具策略 -子智能体首先使用与父级或目标智能体相同的配置文件和工具策略流水线。之后，OpenClaw 会应用子智能体限制层。 +子智能体首先使用与父智能体或目标智能体相同的配置档案和工具策略流水线。之后，OpenClaw 会应用子智能体限制层。 -如果没有限制性的 `tools.profile`，子智能体会获得**除会话工具**和系统工具之外的所有工具： +在没有限制性 `tools.profile` 的情况下，子智能体会获得**除会话工具和系统工具之外的所有工具**： - `sessions_list` - `sessions_history` - `sessions_send` - `sessions_spawn` -这里的 `sessions_history` 仍是有界且已清理的回忆视图，不是原始转录转储。 +这里的 `sessions_history` 仍是有界且经过净化的回忆视图，不是原始转录转储。 -当 `maxSpawnDepth >= 2` 时，深度 1 编排器子智能体还会获得 `sessions_spawn`、`subagents`、`sessions_list` 和 -`sessions_history`，以便它们可以管理其子级。 +当 `maxSpawnDepth >= 2` 时，深度 1 编排器子智能体还会获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便管理其子级。 ### 通过配置覆盖 @@ -411,11 +445,7 @@ x-i18n: } ``` -`tools.subagents.tools.allow` 是最终的仅允许过滤器。它可以收窄 -已经解析出的工具集，但无法**重新添加**被 `tools.profile` 移除的工具。 -例如，`tools.profile: "coding"` 包含 `web_search`/`web_fetch`，但不包含 -`browser` 工具。要让 coding-profile 子智能体使用浏览器自动化，请在 -profile 阶段添加 browser： +`tools.subagents.tools.allow` 是最终的仅允许过滤器。它可以收窄已经解析出的工具集，但不能**加回**已被 `tools.profile` 移除的工具。例如，`tools.profile: "coding"` 包含 `web_search`/`web_fetch`，但不包含 `browser` 工具。若要让 coding-profile 子智能体使用浏览器自动化，请在 profile 阶段添加 browser： ```json5 { @@ -426,53 +456,40 @@ profile 阶段添加 browser： } ``` -当只有一个智能体需要获得浏览器自动化时，请使用每智能体 -`agents.list[].tools.alsoAllow: ["browser"]`。 +当只有一个智能体应获得浏览器自动化能力时，使用每智能体的 `agents.list[].tools.alsoAllow: ["browser"]`。 ## 并发 子智能体使用专用的进程内队列通道： - **通道名称：** `subagent` -- **并发数：** `agents.defaults.subagents.maxConcurrent`（默认值 `8`） +- **并发数：** `agents.defaults.subagents.maxConcurrent`（默认 `8`） -## 存活性和恢复 +## 存活性与恢复 -OpenClaw 不会把缺少 `endedAt` 视为子智能体仍然存活的永久证明。 -超过陈旧运行窗口且未结束的运行，在 `/subagents list`、Status 摘要、 -后代完成门控以及每会话并发检查中，不再计为 active/pending。 +OpenClaw 不会把缺少 `endedAt` 视为子智能体仍然存活的永久证明。早于 stale-run 窗口且未结束的运行，在 `/subagents list`、Status 摘要、后代完成门控以及每会话并发检查中不再计为 active/pending。 -Gateway 网关重启后，陈旧且未结束的已恢复运行会被清理，除非其子会话被标记为 -`abortedLastRun: true`。这些因重启而中止的子会话仍可通过子智能体孤儿恢复流程恢复， -该流程会先发送一条合成的继续消息，然后清除中止标记。 +Gateway 网关重启后，过期且未结束的已恢复运行会被清理，除非其子会话标记为 `abortedLastRun: true`。这些因重启而中止的子会话仍可通过子智能体孤儿恢复流程恢复，该流程会先发送一条合成的恢复消息，然后清除中止标记。 -自动重启恢复按每个子会话设有边界。如果同一个子智能体子会话在快速重新卡住窗口内反复被接受进入孤儿恢复， -OpenClaw 会在该会话上持久化一个恢复墓碑，并在后续重启时停止自动继续它。 -运行 `openclaw tasks maintenance --apply` 来协调任务记录，或运行 -`openclaw doctor --fix` 来清除已加墓碑会话上的陈旧中止恢复标记。 +自动重启恢复按子会话设有边界。如果同一个子智能体子会话在 rapid re-wedge 窗口内反复被接受用于孤儿恢复，OpenClaw 会在该会话上持久化一个恢复墓碑，并在后续重启时停止自动恢复它。运行 `openclaw tasks maintenance --apply` 来协调任务记录，或运行 `openclaw doctor --fix` 来清除墓碑会话上的过期中止恢复标志。 -如果子智能体 spawn 因 Gateway 网关 `PAIRING_REQUIRED` / -`scope-upgrade` 失败，请先检查 RPC 调用方，再编辑配对状态。 -内部 `sessions_spawn` 协调应通过直接 loopback 共享 token/密码认证， -以 `client.id: "gateway-client"` 和 `client.mode: "backend"` 连接； -该路径不依赖 CLI 的已配对设备 scope 基线。远程调用方、显式 -`deviceIdentity`、显式设备 token 路径以及浏览器/node 客户端，仍需要正常的设备批准才能进行 scope 升级。 +如果子智能体生成失败并出现 Gateway 网关 `PAIRING_REQUIRED` / `scope-upgrade`，请先检查 RPC 调用方，再编辑配对状态。内部 `sessions_spawn` 协调应通过 direct loopback 共享令牌/密码认证，以 `client.id: "gateway-client"` 和 `client.mode: "backend"` 连接；该路径不依赖 CLI 的已配对设备 scope 基线。远程调用方、显式 `deviceIdentity`、显式设备令牌路径以及 browser/node 客户端仍需要正常设备批准才能进行 scope 升级。 ## 停止 -- 在请求方聊天中发送 `/stop` 会中止请求方会话，并停止从该会话生成的所有活动子智能体运行，同时级联到嵌套子项。 -- `/subagents kill ` 会停止指定的子智能体，并级联到其子项。 +- 在请求方聊天中发送 `/stop` 会中止请求方会话，并停止从该会话生成的任何活跃子智能体运行，同时级联到嵌套子级。 +- `/subagents kill ` 会停止指定子智能体，并级联到其子级。 ## 限制 -- 子智能体公告是**尽力而为**的。如果 Gateway 网关重启，待处理的“回传公告”工作会丢失。 +- 子智能体通知是**尽力而为**。如果 Gateway 网关重启，待处理的 “announce back” 工作会丢失。 - 子智能体仍共享同一个 Gateway 网关进程资源；请将 `maxConcurrent` 视为安全阀。 - `sessions_spawn` 始终是非阻塞的：它会立即返回 `{ status: "accepted", runId, childSessionKey }`。 -- 子智能体上下文只注入 `AGENTS.md` + `TOOLS.md`（不包含 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。 +- 子智能体上下文只注入 `AGENTS.md` + `TOOLS.md`（不含 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。 - 最大嵌套深度为 5（`maxSpawnDepth` 范围：1–5）。大多数用例建议使用深度 2。 -- `maxChildrenPerAgent` 限制每个会话的活动子项数量（默认值 `5`，范围 `1–20`）。 +- `maxChildrenPerAgent` 限制每个会话的活跃子级数量（默认 `5`，范围 `1–20`）。 ## 相关