diff --git a/docs/zh-CN/tools/acp-agents.md b/docs/zh-CN/tools/acp-agents.md index 5b26ea2bd..d6c3768fe 100644 --- a/docs/zh-CN/tools/acp-agents.md +++ b/docs/zh-CN/tools/acp-agents.md @@ -1,94 +1,112 @@ --- read_when: - - 通过 ACP 运行编码 harness - - 在消息渠道上设置与会话绑定的 ACP 会话 - - 将消息渠道中的会话绑定到持久化 ACP 会话 - - 排查 ACP 后端和插件连接问题 - - 调试 ACP 完成结果传递或智能体到智能体循环 + - 通过 ACP 运行编码框架 + - 在消息渠道上设置与对话绑定的 ACP 会话 + - 将消息渠道中的对话绑定到持久化 ACP 会话 + - 排查 ACP 后端和插件接线问题 + - 调试 ACP 完成结果投递或智能体到智能体循环 - 从聊天中操作 /acp 命令 -summary: 对 Claude Code、Cursor、Gemini CLI 使用 ACP 运行时会话，以及显式的 Codex ACP 回退、OpenClaw ACP 和其他 harness 智能体 +summary: 对 Claude Code、Cursor、Gemini CLI、显式 Codex ACP 回退、OpenClaw ACP 和其他代理框架智能体使用 ACP 运行时会话 title: ACP 智能体 x-i18n: - generated_at: "2026-04-25T19:10:47Z" + generated_at: "2026-04-25T20:27:34Z" model: gpt-5.4 provider: openai - source_hash: d9149ed31e85b7caadd465e69dc3b8c694c50275b3e2ef8bd82d88ecf833e1a6 + source_hash: 2db23f98e0ab2e9c7292333fb2e9486a69c3b2d71754a1db6d53554e9d05f762 source_path: tools/acp-agents.md workflow: 15 --- -[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI 以及其他受支持的 ACPX harness）。 +[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码框架（例如 Pi、Claude Code、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI 以及其他受支持的 ACPX 框架）。 -如果你用自然语言要求 OpenClaw 在当前会话中绑定或控制 Codex，OpenClaw 应该使用原生 Codex app-server 插件（`/codex bind`、`/codex threads`、`/codex resume`）。如果你要求使用 `/acp`、ACP、acpx，或 Codex 后台子会话，OpenClaw 仍然可以通过 ACP 路由 Codex。每个 ACP 会话生成都会作为一个[后台任务](/zh-CN/automation/tasks)进行跟踪。 +如果你用自然语言要求 OpenClaw 在当前对话中绑定或控制 Codex，OpenClaw 应该使用原生 Codex app-server 插件（`/codex bind`、`/codex threads`、`/codex resume`）。如果你要求使用 `/acp`、ACP、acpx，或 Codex 后台子会话，OpenClaw 仍然可以通过 ACP 路由 Codex。每个 ACP 会话启动都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。 -如果你用自然语言要求 OpenClaw “在线程中启动 Claude Code” 或使用其他外部 harness，OpenClaw 应该将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。 +如果你用自然语言要求 OpenClaw “在线程中启动 Claude Code” 或使用其他外部框架，OpenClaw 应该将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。 -如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的 OpenClaw 渠道会话，请使用 [`openclaw mcp serve`](/zh-CN/cli/mcp) 而不是 ACP。 +如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的 OpenClaw 渠道对话， +请使用 [`openclaw mcp serve`](/zh-CN/cli/mcp) +而不是 ACP。 -## 你想看哪个页面？ +## 我想看哪个页面？ -这里有三个相近的功能界面，容易混淆： +这里有三个很接近、也很容易混淆的入口： | 你想要…… | 使用这个 | 说明 | | ----------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 在当前会话中绑定或控制 Codex | `/codex bind`、`/codex threads` | 原生 Codex app-server 路径；包括绑定聊天回复、图片转发、模型/快速/权限、停止和引导控制。ACP 是显式回退 | -| 通过 OpenClaw 运行 Claude Code、Gemini CLI、显式 Codex ACP 或其他外部 harness | 本页：ACP 智能体 | 聊天绑定会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 | -| 将 OpenClaw Gateway 网关会话作为 ACP 服务器提供给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端通过 stdio/WebSocket 向 OpenClaw 发送 ACP | -| 将本地 AI CLI 复用为纯文本回退模型 | [CLI 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有 harness 运行时 | +| 在当前对话中绑定或控制 Codex | `/codex bind`、`/codex threads` | 原生 Codex app-server 路径；包括绑定聊天回复、图片转发、模型/快速/权限、停止和引导控制。ACP 是显式回退方案 | +| _通过_ OpenClaw 运行 Claude Code、Gemini CLI、显式 Codex ACP 或其他外部框架 | 本页：ACP 智能体 | 与聊天绑定的会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 | +| 将 OpenClaw Gateway 网关会话_作为_ ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端通过 stdio/WebSocket 使用 ACP 与 OpenClaw 通信 | +| 将本地 AI CLI 复用为仅文本的回退模型 | [CLI 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有框架运行时 | -## 这是否开箱即用？ +## 这是开箱即用的吗？ -通常是的。全新安装默认启用了内置的 `acpx` 运行时插件，并带有一个插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自动修复它。运行 `/acp doctor` 可进行就绪性检查。 +通常是的。全新安装默认启用内置的 `acpx` 运行时插件，并带有一个插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自修复它。运行 `/acp doctor` 可执行就绪性检查。 首次运行的注意事项： -- 目标 harness 适配器（Codex、Claude 等）可能会在你首次使用时通过 `npx` 按需获取。 -- 该 harness 对应的供应商认证仍然必须存在于主机上。 -- 如果主机没有 npm 或网络访问权限，则首次运行的适配器获取会失败，直到缓存被预热或适配器通过其他方式安装。 +- 目标框架适配器（Codex、Claude 等）可能会在你第一次使用时通过 `npx` 按需获取。 +- 该框架对应的供应商认证仍然必须已存在于宿主机上。 +- 如果宿主机没有 npm 或网络访问能力，首次运行的适配器获取会失败，直到缓存被预热或适配器通过其他方式安装。 ## 操作手册 -从聊天中快速使用 `/acp` 的流程： +从聊天中进行快速 `/acp` 流程： -1. **生成** —— `/acp spawn claude --bind here`、`/acp spawn gemini --mode persistent --thread auto`，或显式使用 `/acp spawn codex --bind here` -2. 在绑定的会话或线程中**工作**（或者显式指定会话键）。 -3. **检查状态** —— `/acp status` -4. **调优** —— `/acp model `、`/acp permissions `、`/acp timeout ` -5. 在不替换上下文的情况下进行**引导** —— `/acp steer tighten logging and continue` -6. **停止** —— `/acp cancel`（当前轮次）或 `/acp close`（会话 + 绑定） +1. **启动** — `/acp spawn claude --bind here`、`/acp spawn gemini --mode persistent --thread auto`，或显式执行 `/acp spawn codex --bind here` +2. 在已绑定的对话或线程中**工作**（或者显式指定会话键）。 +3. **检查状态** — `/acp status` +4. **调优** — `/acp model `、`/acp permissions `、`/acp timeout ` +5. **引导**且不替换上下文 — `/acp steer tighten logging and continue` +6. **停止** — `/acp cancel`（当前轮次）或 `/acp close`（会话 + 绑定） -应当路由到原生 Codex 插件的自然语言触发词： +应当路由到原生 Codex 插件的自然语言触发示例： -- “将这个 Discord 渠道绑定到 Codex。” -- “将这个聊天附加到 Codex 线程 ``。” +- “把这个 Discord 渠道绑定到 Codex。” +- “把这个聊天附加到 Codex 线程 ``。” - “显示 Codex 线程，然后绑定这一个。” -原生 Codex 会话绑定是默认的聊天控制路径。OpenClaw 动态工具仍通过 OpenClaw 执行，而 Codex 原生工具（例如 shell/apply-patch）则在 Codex 内部执行。对于 Codex 原生工具事件，OpenClaw 会注入一个按轮次生效的原生 hook relay，这样插件钩子就可以阻止 `before_tool_call`、观察 `after_tool_call`，并通过 OpenClaw 审批来路由 Codex 的 `PermissionRequest` 事件。v1 relay 有意保持保守：它不会修改 Codex 原生工具参数、不会重写 Codex 线程记录，也不会拦截最终答案/Stop hooks。只有当你需要 ACP 运行时/会话模型时，才使用显式 ACP。嵌入式 Codex 支持边界记录在 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract) 中。 +原生 Codex 对话绑定是默认的聊天控制路径。OpenClaw +动态工具仍然通过 OpenClaw 执行，而 Codex 原生工具（例如 +shell/apply-patch）则在 Codex 内部执行。对于 Codex 原生工具事件，OpenClaw +会按轮次注入一个原生钩子中继，使插件钩子能够阻止 +`before_tool_call`、观察 `after_tool_call`，并通过 OpenClaw 审批来路由 Codex +的 `PermissionRequest` 事件。v1 中继有意保持保守：它不会修改 Codex 原生工具参数、 +重写 Codex 线程记录，也不会拦截最终答案/Stop 钩子。只有当你确实需要 ACP +运行时/会话模型时，才应使用显式 ACP。嵌入式 Codex 支持边界记录在 +[Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract) +中。 -应当路由到 ACP 运行时的自然语言触发词： +应当路由到 ACP 运行时的自然语言触发示例： -- “把这个作为一次性 Claude Code ACP 会话运行，并总结结果。” -- “对此任务使用 Gemini CLI 在线程中执行，然后在同一个线程中继续后续跟进。” -- “通过 ACP 在线程后台运行 Codex。” +- “把这个作为一次性的 Claude Code ACP 会话运行，并总结结果。” +- “针对这个任务使用 Gemini CLI 在线程中运行，然后后续继续沿用同一个线程。” +- “通过 ACP 在后台线程中运行 Codex。” -OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑定到当前会话或线程，并将后续跟进路由到该会话，直到关闭/过期。只有在明确要求 ACP，或请求的后台运行时仍需要 ACP 时，Codex 才会走这一路径。 +OpenClaw 会选择 `runtime: "acp"`，解析框架 `agentId`，在支持时绑定到当前对话或线程，并将后续消息路由到该会话，直到关闭或过期。只有在明确指定 ACP，或者所请求的后台运行时仍然需要 ACP 时，Codex 才会走这一路径。 + +对于 `sessions_spawn`，`runtime: "acp"` 指向 ACP 框架 id，例如 `codex`、 +`claude`、`gemini` 或 `opencode`。不要传入来自 `agents_list` 的普通 OpenClaw 配置智能体 +id，除非该条目已显式配置为 +`agents.list[].runtime.type="acp"`；否则应使用默认子智能体运行时。 +当某个 OpenClaw 智能体被配置为 `runtime.type="acp"` 时，OpenClaw 会使用 +`runtime.acp.agent` 作为底层框架 id。 ## ACP 与子智能体 -当你需要外部 harness 运行时时，请使用 ACP。对于 Codex 会话绑定/控制，请使用原生 Codex app-server。若你需要 OpenClaw 原生委派运行，请使用子智能体。 +当你需要外部框架运行时时，使用 ACP。对于 Codex 对话绑定/控制，使用原生 Codex app-server。若你需要 OpenClaw 原生委派运行，则使用子智能体。 | 区域 | ACP 会话 | 子智能体运行 | | ------------- | ------------------------------------- | ---------------------------------- | | 运行时 | ACP 后端插件（例如 acpx） | OpenClaw 原生子智能体运行时 | | 会话键 | `agent::acp:` | `agent::subagent:` | | 主要命令 | `/acp ...` | `/subagents ...` | -| 生成工具 | `sessions_spawn` 配合 `runtime:"acp"` | `sessions_spawn`（默认运行时） | +| 启动工具 | `sessions_spawn` 配合 `runtime:"acp"` | `sessions_spawn`（默认运行时） | -另请参见 [子智能体](/zh-CN/tools/subagents)。 +另见 [子智能体](/zh-CN/tools/subagents)。 ## ACP 如何运行 Claude Code -对于通过 ACP 运行的 Claude Code，其栈如下： +对于通过 ACP 运行的 Claude Code，其栈结构如下： 1. OpenClaw ACP 会话控制平面 2. 内置 `acpx` 运行时插件 @@ -97,59 +115,59 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑 重要区别： -- ACP Claude 是一种 harness 会话，带有 ACP 控制、会话恢复、后台任务跟踪，以及可选的会话/线程绑定。 -- CLI 后端是单独的纯文本本地回退运行时。参见 [CLI 后端](/zh-CN/gateway/cli-backends)。 +- ACP Claude 是一个带有 ACP 控制、会话恢复、后台任务跟踪以及可选对话/线程绑定的框架会话。 +- CLI 后端是独立的仅文本本地回退运行时。参见 [CLI 后端](/zh-CN/gateway/cli-backends)。 对于操作人员，实际规则是： -- 想要 `/acp spawn`、可绑定会话、运行时控制或持久化 harness 工作：使用 ACP -- 想要通过原始 CLI 使用简单的本地文本回退：使用 CLI 后端 +- 想要 `/acp spawn`、可绑定会话、运行时控制或持久化框架工作：使用 ACP +- 想要通过原始 CLI 获得简单的本地文本回退：使用 CLI 后端 -## 绑定的会话 +## 已绑定会话 -### 当前会话绑定 +### 当前对话绑定 -`/acp spawn --bind here` 会将当前会话固定绑定到生成的 ACP 会话 —— 不创建子线程，仍在同一个聊天界面。OpenClaw 继续负责传输、认证、安全和消息投递；该会话中的后续消息会路由到同一个会话；`/new` 和 `/reset` 会在原地重置该会话；`/acp close` 会移除绑定。 +`/acp spawn --bind here` 会把当前对话固定绑定到新启动的 ACP 会话——不创建子线程，仍使用同一个聊天界面。OpenClaw 继续负责传输、认证、安全和消息投递；该对话中的后续消息会路由到同一个会话；`/new` 和 `/reset` 会就地重置该会话；`/acp close` 会移除该绑定。 -可将其理解为： +理解模型： - **聊天界面** —— 人们持续交流的地方（Discord 渠道、Telegram 话题、iMessage 聊天）。 -- **ACP 会话** —— OpenClaw 路由到的持久化 Codex/Claude/Gemini 运行时状态。 -- **子线程/话题** —— 仅由 `--thread ...` 创建的可选额外消息界面。 -- **运行时工作区** —— harness 运行所在的文件系统位置（`cwd`、仓库检出目录、后端工作区）。它独立于聊天界面。 +- **ACP 会话** —— OpenClaw 路由到的持久 Codex/Claude/Gemini 运行时状态。 +- **子线程/话题** —— 仅在使用 `--thread ...` 时创建的可选附加消息界面。 +- **运行时工作区** —— 框架运行所在的文件系统位置（`cwd`、仓库检出目录、后端工作区）。它独立于聊天界面。 示例： -- `/codex bind` —— 保持当前聊天，生成或附加原生 Codex app-server，并将后续消息路由到这里。 -- `/codex model gpt-5.4`、`/codex fast on`、`/codex permissions yolo` —— 从聊天中调优绑定的原生 Codex 线程。 +- `/codex bind` —— 保持当前聊天，启动或附加原生 Codex app-server，并将未来消息路由到这里。 +- `/codex model gpt-5.4`、`/codex fast on`、`/codex permissions yolo` —— 从聊天中调优已绑定的原生 Codex 线程。 - `/codex stop` 或 `/codex steer focus on the failing tests first` —— 控制当前活跃的原生 Codex 轮次。 - `/acp spawn codex --bind here` —— 为 Codex 使用显式 ACP 回退。 -- `/acp spawn codex --thread auto` —— OpenClaw 可以创建一个子线程/话题并在其中绑定。 -- `/acp spawn codex --bind here --cwd /workspace/repo` —— 仍绑定当前聊天，但 Codex 在 `/workspace/repo` 中运行。 +- `/acp spawn codex --thread auto` —— OpenClaw 可能会创建一个子线程/话题并绑定到那里。 +- `/acp spawn codex --bind here --cwd /workspace/repo` —— 同样绑定当前聊天，但 Codex 在 `/workspace/repo` 中运行。 说明： - `--bind here` 和 `--thread ...` 互斥。 -- `--bind here` 仅适用于声明支持当前会话绑定的渠道；否则 OpenClaw 会返回清晰的“不支持”消息。绑定在 Gateway 网关重启后仍会保留。 +- `--bind here` 仅在声明支持当前对话绑定的渠道上可用；否则 OpenClaw 会返回清晰的不支持消息。绑定会在 Gateway 网关重启后继续保留。 - 在 Discord 上，只有当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions` —— 对 `--bind here` 不需要。 -- 如果你在未指定 `--cwd` 的情况下生成到另一个 ACP 智能体，OpenClaw 默认会继承**目标智能体的**工作区。若继承路径缺失（`ENOENT`/`ENOTDIR`），则回退到后端默认值；其他访问错误（例如 `EACCES`）会作为生成错误直接显示。 +- 如果你在未指定 `--cwd` 的情况下启动到不同的 ACP 智能体，OpenClaw 默认会继承**目标智能体的**工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误直接返回。 ### 线程绑定会话 -当渠道适配器启用了线程绑定时，ACP 会话可以绑定到线程： +当某个渠道适配器启用了线程绑定时，ACP 会话可以绑定到线程： -- OpenClaw 将一个线程绑定到目标 ACP 会话。 -- 该线程中的后续消息会路由到绑定的 ACP 会话。 -- ACP 输出会回传到同一个线程。 -- 取消聚焦/关闭/归档/空闲超时或最大生命周期过期时，绑定会被移除。 +- OpenClaw 将线程绑定到目标 ACP 会话。 +- 该线程中的后续消息会路由到已绑定的 ACP 会话。 +- ACP 输出会回传到同一线程。 +- 取消聚焦/关闭/归档/空闲超时或最大存活时间到期后，会移除该绑定。 -线程绑定支持取决于适配器。如果当前渠道适配器不支持线程绑定，OpenClaw 会返回清晰的“不支持/不可用”消息。 +线程绑定支持取决于适配器。如果当前活跃的渠道适配器不支持线程绑定，OpenClaw 会返回清晰的“不支持/不可用”消息。 -线程绑定 ACP 所需的功能开关： +线程绑定 ACP 所需的功能标志： - `acp.enabled=true` - `acp.dispatch.enabled` 默认开启（设为 `false` 可暂停 ACP 分发） -- 启用渠道适配器的 ACP 线程生成开关（因适配器而异） +- 启用渠道适配器的 ACP 线程启动标志（适配器专属） - Discord：`channels.discord.threadBindings.spawnAcpSessions=true` - Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true` @@ -158,24 +176,24 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑 - 任何暴露会话/线程绑定能力的渠道适配器。 - 当前内置支持： - Discord 线程/渠道 - - Telegram 话题（群组/超级群组中的论坛话题，以及私信话题） + - Telegram 话题（群组/超级群组中的论坛话题以及私信话题） - 插件渠道也可以通过同一绑定接口添加支持。 -## 渠道特定设置 +## 渠道专属设置 -对于非临时性工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。 +对于非临时工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。 ### 绑定模型 -- `bindings[].type="acp"` 表示持久化 ACP 会话绑定。 -- `bindings[].match` 用于标识目标会话： +- `bindings[].type="acp"` 表示一个持久化 ACP 对话绑定。 +- `bindings[].match` 用于标识目标对话： - Discord 渠道或线程：`match.channel="discord"` + `match.peer.id=""` - Telegram 论坛话题：`match.channel="telegram"` + `match.peer.id=":topic:"` - BlueBubbles 私信/群聊：`match.channel="bluebubbles"` + `match.peer.id=""` 对于稳定的群组绑定，优先使用 `chat_id:*` 或 `chat_identifier:*`。 - iMessage 私信/群聊：`match.channel="imessage"` + `match.peer.id=""` 对于稳定的群组绑定，优先使用 `chat_id:*`。 -- `bindings[].agentId` 是所属 OpenClaw 智能体 id。 +- `bindings[].agentId` 是所属的 OpenClaw 智能体 id。 - 可选的 ACP 覆盖项位于 `bindings[].acp` 下： - `mode`（`persistent` 或 `oneshot`） - `label` @@ -184,10 +202,10 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑 ### 每个智能体的运行时默认值 -使用 `agents.list[].runtime` 为每个智能体统一定义 ACP 默认值： +使用 `agents.list[].runtime` 为每个智能体一次性定义 ACP 默认值： - `agents.list[].runtime.type="acp"` -- `agents.list[].runtime.acp.agent`（harness id，例如 `codex` 或 `claude`） +- `agents.list[].runtime.acp.agent`（框架 id，例如 `codex` 或 `claude`） - `agents.list[].runtime.acp.backend` - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` @@ -280,12 +298,12 @@ ACP 绑定会话的覆盖优先级： 行为： -- OpenClaw 会确保已配置的 ACP 会话在使用前已经存在。 +- OpenClaw 会在使用前确保已配置的 ACP 会话存在。 - 该渠道或话题中的消息会路由到已配置的 ACP 会话。 -- 在已绑定的会话中，`/new` 和 `/reset` 会在原位置重置同一个 ACP 会话键。 -- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍会生效。 -- 对于未显式指定 `cwd` 的跨智能体 ACP 生成，OpenClaw 会从智能体配置中继承目标智能体的工作区。 -- 缺失的继承工作区路径会回退到后端默认 `cwd`；非缺失类访问失败则会作为生成错误直接显示。 +- 在已绑定的对话中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话键。 +- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍然适用。 +- 对于未显式指定 `cwd` 的跨智能体 ACP 启动，OpenClaw 会从智能体配置中继承目标智能体工作区。 +- 缺失的继承工作区路径会回退到后端默认 `cwd`；非缺失的访问失败则会作为启动错误直接返回。 ## 启动 ACP 会话（接口） @@ -305,69 +323,69 @@ ACP 绑定会话的覆盖优先级： 说明： -- `runtime` 默认为 `subagent`，因此对于 ACP 会话需要显式设置 `runtime: "acp"`。 -- 如果省略 `agentId`，OpenClaw 会在配置存在时使用 `acp.defaultAgent`。 -- `mode: "session"` 需要 `thread: true` 才能保持持久化的绑定会话。 +- `runtime` 默认是 `subagent`，因此对于 ACP 会话需要显式设置 `runtime: "acp"`。 +- 如果省略 `agentId`，在已配置时 OpenClaw 会使用 `acp.defaultAgent`。 +- `mode: "session"` 需要 `thread: true` 才能保持持久化绑定对话。 接口详情： - `task`（必填）：发送到 ACP 会话的初始提示。 - `runtime`（ACP 必填）：必须为 `"acp"`。 -- `agentId`（可选）：ACP 目标 harness id。如果已设置，则回退到 `acp.defaultAgent`。 +- `agentId`（可选）：ACP 目标框架 id。如已设置，则回退到 `acp.defaultAgent`。 - `thread`（可选，默认 `false`）：在支持时请求线程绑定流程。 - `mode`（可选）：`run`（一次性）或 `session`（持久化）。 - 默认值为 `run` - - 如果 `thread: true` 且未指定 mode，OpenClaw 可能会根据运行时路径默认采用持久化行为 + - 如果 `thread: true` 且省略 `mode`，OpenClaw 可能会根据运行时路径默认采用持久化行为 - `mode: "session"` 需要 `thread: true` -- `cwd`（可选）：请求的运行时工作目录（由后端/运行时策略验证）。如果省略，ACP 生成会在配置存在时继承目标智能体工作区；缺失的继承路径会回退到后端默认值，而真实访问错误会直接返回。 -- `label`（可选）：面向操作人员的标签，用于会话/banner 文本。 -- `resumeSessionId`（可选）：恢复现有 ACP 会话而不是创建新会话。智能体会通过 `session/load` 回放其会话历史。需要 `runtime: "acp"`。 -- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式回传给请求方会话。 - - 在可用时，接受到的响应会包含 `streamLogPath`，指向一个按会话划分的 JSONL 日志（`.acp-stream.jsonl`），你可以对其进行 tail 以查看完整 relay 历史。 -- `model`（可选）：ACP 子会话的显式模型覆盖。对于 `runtime: "acp"` 会生效，因此子会话会使用请求的模型，而不是静默回退到目标智能体默认模型。Codex ACP 生成会在 `session/new` 之前，将 OpenClaw Codex 引用（例如 `openai-codex/gpt-5.4`）规范化为 Codex ACP 启动配置；带斜杠的形式（例如 `openai-codex/gpt-5.4/high`）还会设置 Codex ACP 的推理强度。 -- `thinking`（可选）：ACP 子会话的显式 thinking/推理强度。对于 Codex ACP，`minimal` 映射为低强度，`low`/`medium`/`high`/`xhigh` 直接映射，`off` 则会省略 reasoning-effort 启动覆盖项。 +- `cwd`（可选）：请求的运行时工作目录（由后端/运行时策略验证）。如果省略，并且已配置，ACP 启动会继承目标智能体工作区；缺失的继承路径会回退到后端默认值，而真实访问错误会直接返回。 +- `label`（可选）：用于会话/横幅文本中的面向操作人员的标签。 +- `resumeSessionId`（可选）：恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load` 重放其对话历史。需要 `runtime: "acp"`。 +- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式返回给请求方会话。 + - 当可用时，接受响应中会包含指向会话范围 JSONL 日志的 `streamLogPath`（`.acp-stream.jsonl`），你可以对其执行 tail 以查看完整中继历史。 +- `model`（可选）：ACP 子会话的显式模型覆盖。对 `runtime: "acp"` 生效，因此子会话会使用请求的模型，而不是静默回退到目标智能体默认模型。Codex ACP 启动会在 `session/new` 之前，将 OpenClaw Codex 引用（如 `openai-codex/gpt-5.4`）规范化为 Codex ACP 启动配置；像 `openai-codex/gpt-5.4/high` 这样的斜杠形式还会设置 Codex ACP 推理强度。 +- `thinking`（可选）：ACP 子会话的显式 thinking/推理强度。对于 Codex ACP，`minimal` 映射为低强度，`low`/`medium`/`high`/`xhigh` 直接映射，`off` 则省略推理强度启动覆盖。 ## 投递模型 -ACP 会话既可以是交互式工作区，也可以是由父级持有的后台工作。投递路径取决于其形态。 +ACP 会话既可以是交互式工作区，也可以是由父级拥有的后台工作。投递路径取决于其形态。 ### 交互式 ACP 会话 交互式会话旨在持续在可见聊天界面中对话： -- `/acp spawn ... --bind here` 会将当前会话绑定到 ACP 会话。 -- `/acp spawn ... --thread ...` 会将渠道线程/话题绑定到 ACP 会话。 -- 持久化配置的 `bindings[].type="acp"` 会将匹配的会话路由到同一个 ACP 会话。 +- `/acp spawn ... --bind here` 将当前对话绑定到 ACP 会话。 +- `/acp spawn ... --thread ...` 将渠道线程/话题绑定到 ACP 会话。 +- 持久化配置的 `bindings[].type="acp"` 会将匹配的对话路由到同一个 ACP 会话。 -已绑定会话中的后续消息会直接路由到 ACP 会话，而 ACP 输出会回传到同一个渠道/线程/话题。 +已绑定对话中的后续消息会直接路由到 ACP 会话，ACP 输出也会回传到同一渠道/线程/话题。 -### 父级持有的一次性 ACP 会话 +### 父级拥有的一次性 ACP 会话 -由另一个智能体运行生成的一次性 ACP 会话属于后台子会话，类似子智能体： +由另一个智能体运行启动的一次性 ACP 会话是后台子级，类似子智能体： -- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求执行工作。 -- 子级在其自己的 ACP harness 会话中运行。 +- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。 +- 子级在其自己的 ACP 框架会话中运行。 - 完成结果通过内部任务完成通知路径回报。 -- 当需要面向用户的回复时，父级会用正常助手语气重写子级结果。 +- 当需要面向用户的回复时，父级会用普通助手语气重写子级结果。 -不要将此路径视为父级与子级之间的点对点聊天。子级已经有返回给父级的完成通道。 +不要将这一路径视为父级与子级之间的点对点聊天。子级已经有一个返回父级的完成通道。 -### `sessions_send` 与 A2A 投递 +### `sessions_send` 和 A2A 投递 -`sessions_send` 可以在生成后将目标指向另一个会话。对于普通对等会话，OpenClaw 会在注入消息后使用智能体到智能体（A2A）的后续跟进路径： +`sessions_send` 可以在启动后指向另一个会话。对于普通对等会话，OpenClaw 会在注入消息后使用智能体到智能体（A2A）的后续路径： - 等待目标会话的回复 -- 可选地让请求方与目标交换有限数量的后续轮次 +- 可选地允许请求方与目标交换有限轮数的后续消息 - 要求目标生成一条通知消息 - 将该通知投递到可见渠道或线程 -该 A2A 路径是对等发送场景下的一种回退机制，适用于发送方需要可见后续回复的情况。当一个无关会话可以看到并向 ACP 目标发送消息时，这一路径仍然保持启用，例如在较宽泛的 `tools.sessions.visibility` 设置下。 +这条 A2A 路径是对等发送场景下的回退机制，适用于发送方需要一个可见后续回复的情况。当某个无关会话能够看到并向 ACP 目标发送消息时，该机制仍会保持启用，例如在宽泛的 `tools.sessions.visibility` 设置下。 -仅当请求方是其自身父级持有的一次性 ACP 子会话的父级时，OpenClaw 才会跳过 A2A 后续跟进。在这种情况下，如果在任务完成之上再运行 A2A，可能会因子级结果唤醒父级，再把父级回复转发回子级，从而造成父级/子级回声循环。对于这种自有子会话情形，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为结果已经由完成路径负责处理。 +只有当请求方是其自己父级拥有的一次性 ACP 子级的父级时，OpenClaw 才会跳过 A2A 后续处理。在这种情况下，如果在任务完成的基础上再运行 A2A，可能会用子级结果唤醒父级，再把父级回复转发回子级，从而形成父级/子级回声循环。对于这种自有子级场景，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为结果已经由完成路径负责处理。 ### 恢复现有会话 -使用 `resumeSessionId` 可继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 回放其会话历史，因此它能带着之前的完整上下文继续工作。 +使用 `resumeSessionId` 来继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其对话历史，因此它能够带着此前的完整上下文继续执行。 ```json { @@ -380,43 +398,43 @@ ACP 会话既可以是交互式工作区，也可以是由父级持有的后台 常见用例： -- 将 Codex 会话从你的笔记本电脑切换到手机 —— 告诉你的智能体从你上次中断的地方继续 -- 继续你之前在 CLI 中以交互方式开始的编码会话，现在通过智能体以无头方式继续 -- 继续因 Gateway 网关重启或空闲超时而中断的工作 +- 将 Codex 会话从笔记本电脑切换到手机——让你的智能体接着你上次停下的位置继续 +- 继续一个你之前在 CLI 中交互式启动、现在希望通过智能体无头继续的编码会话 +- 接续因 Gateway 网关重启或空闲超时而中断的工作 说明： -- `resumeSessionId` 需要 `runtime: "acp"` —— 如果与子智能体运行时一起使用，会返回错误。 -- `resumeSessionId` 会恢复上游 ACP 会话历史；`thread` 和 `mode` 仍会正常应用到你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然需要 `thread: true`。 -- 目标智能体必须支持 `session/load`（Codex 和 Claude Code 都支持）。 -- 如果找不到该会话 ID，生成会以清晰错误失败 —— 不会静默回退到新会话。 +- `resumeSessionId` 需要 `runtime: "acp"`——如果与子智能体运行时一起使用，会返回错误。 +- `resumeSessionId` 会恢复上游 ACP 对话历史；`thread` 和 `mode` 仍会正常应用到你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然需要 `thread: true`。 +- 目标智能体必须支持 `session/load`（Codex 和 Claude Code 支持）。 +- 如果找不到该会话 ID，启动会以清晰错误失败——不会静默回退到新会话。 - + -在 Gateway 网关部署之后，请运行一次真实的端到端检查，而不是仅仅相信单元测试： +在 Gateway 网关部署后，执行一次真实的端到端检查，而不是只依赖单元测试： -1. 验证目标主机上的已部署 Gateway 网关版本和提交。 -2. 打开一个指向在线智能体的临时 ACPX 桥接会话。 -3. 要求该智能体调用 `sessions_spawn`，并设置 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，任务内容为 `Reply with exactly LIVE-ACP-SPAWN-OK`。 -4. 验证 `accepted=yes`、存在真实的 `childSessionKey`，并且没有校验器错误。 -5. 清理这个临时桥接会话。 +1. 验证目标宿主机上的已部署 Gateway 网关版本和提交。 +2. 打开一个到在线智能体的临时 ACPX 桥接会话。 +3. 要求该智能体调用 `sessions_spawn`，并设置 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，以及任务 `Reply with exactly LIVE-ACP-SPAWN-OK`。 +4. 验证 `accepted=yes`、真实的 `childSessionKey`，并且没有验证器错误。 +5. 清理该临时桥接会话。 -将检查门槛保持在 `mode: "run"`，并跳过 `streamTo: "parent"` —— 线程绑定的 `mode: "session"` 和 stream relay 路径属于单独的、更丰富的集成验证步骤。 +将门禁保持在 `mode: "run"`，并跳过 `streamTo: "parent"`——线程绑定的 `mode: "session"` 和流式中继路径属于独立且更丰富的集成测试阶段。 ## 沙箱兼容性 -ACP 会话当前运行在主机运行时上，而不是 OpenClaw 沙箱内。 +ACP 会话当前运行在宿主运行时上，而不是 OpenClaw 沙箱内部。 当前限制： -- 如果请求方会话处于沙箱隔离中，则 ACP 生成会被阻止，对于 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 都是如此。 +- 如果请求方会话处于沙箱隔离中，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 启动都会被阻止。 - 错误：`Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.` -- 使用 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。 +- `sessions_spawn` 配合 `runtime: "acp"` 不支持 `sandbox: "require"`。 - 错误：`sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".` -当你需要由沙箱强制执行的运行方式时，请使用 `runtime: "subagent"`。 +当你需要强制沙箱执行时，请使用 `runtime: "subagent"`。 ### 从 `/acp` 命令启动 @@ -437,58 +455,58 @@ ACP 会话当前运行在主机运行时上，而不是 OpenClaw 沙箱内。 - `--cwd ` - `--label ` -参见[斜杠命令](/zh-CN/tools/slash-commands)。 +参见 [斜杠命令](/zh-CN/tools/slash-commands)。 ## 会话目标解析 -大多数 `/acp` 操作都接受一个可选的会话目标（`session-key`、`session-id` 或 `session-label`）。 +大多数 `/acp` 操作都接受一个可选会话目标（`session-key`、`session-id` 或 `session-label`）。 解析顺序： 1. 显式目标参数（或 `/acp steer` 的 `--session`） - 先尝试 key - - 再尝试 UUID 形式的 session id - - 然后尝试 label -2. 当前线程绑定（如果当前会话/线程已绑定到某个 ACP 会话） + - 然后尝试 UUID 形状的 session id + - 再尝试 label +2. 当前线程绑定（如果当前对话/线程绑定到了某个 ACP 会话） 3. 当前请求方会话回退 -当前会话绑定和线程绑定都会参与第 2 步。 +当前对话绑定和线程绑定都会参与第 2 步。 -如果无法解析任何目标，OpenClaw 会返回清晰错误（`Unable to resolve session target: ...`）。 +如果无法解析出目标，OpenClaw 会返回清晰错误（`Unable to resolve session target: ...`）。 -## 生成绑定模式 +## 启动绑定模式 `/acp spawn` 支持 `--bind here|off`。 | 模式 | 行为 | | ------ | ---------------------------------------------------------------------- | -| `here` | 在原地绑定当前活跃会话；如果没有活跃会话则失败。 | -| `off` | 不创建当前会话绑定。 | +| `here` | 就地绑定当前活跃对话；如果没有活跃对话则失败。 | +| `off` | 不创建当前对话绑定。 | 说明： - `--bind here` 是“让这个渠道或聊天由 Codex 提供支持”的最简单操作路径。 - `--bind here` 不会创建子线程。 -- `--bind here` 仅在暴露当前会话绑定支持的渠道上可用。 +- `--bind here` 仅在暴露当前对话绑定支持的渠道上可用。 - `--bind` 和 `--thread` 不能在同一次 `/acp spawn` 调用中组合使用。 -## 生成线程模式 +## 启动线程模式 `/acp spawn` 支持 `--thread auto|here|off`。 | 模式 | 行为 | | ------ | --------------------------------------------------------------------------------------------------- | -| `auto` | 在活跃线程中：绑定该线程。在线程外：在支持时创建/绑定子线程。 | +| `auto` | 在线程中活跃时：绑定该线程。在线程外：在支持时创建并绑定一个子线程。 | | `here` | 要求当前处于活跃线程中；否则失败。 | -| `off` | 不进行绑定。会话以未绑定状态启动。 | +| `off` | 不进行绑定。会话以未绑定状态启动。 | 说明： -- 在不支持线程绑定的界面上，默认行为实际上等同于 `off`。 -- 线程绑定生成需要渠道策略支持： +- 在非线程绑定界面上，默认行为实际上等同于 `off`。 +- 线程绑定启动需要渠道策略支持： - Discord：`channels.discord.threadBindings.spawnAcpSessions=true` - Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true` -- 当你想固定当前会话而不创建子线程时，请使用 `--bind here`。 +- 如果你希望固定当前对话且不创建子线程，请使用 `--bind here`。 ## ACP 控制 @@ -497,20 +515,20 @@ ACP 会话当前运行在主机运行时上，而不是 OpenClaw 沙箱内。 | `/acp spawn` | 创建 ACP 会话；可选择当前绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` | | `/acp cancel` | 取消目标会话当前进行中的轮次。 | `/acp cancel agent:codex:acp:` | | `/acp steer` | 向运行中的会话发送引导指令。 | `/acp steer --session support inbox prioritize failing tests` | -| `/acp close` | 关闭会话并解绑线程目标。 | `/acp close` | -| `/acp status` | 显示后端、模式、状态、运行时选项、能力。 | `/acp status` | -| `/acp set-mode` | 为目标会话设置运行时模式。 | `/acp set-mode plan` | -| `/acp set` | 通用运行时配置选项写入。 | `/acp set model openai/gpt-5.4` | -| `/acp cwd` | 设置运行时工作目录覆盖项。 | `/acp cwd /Users/user/Projects/repo` | +| `/acp close` | 关闭会话并解除线程目标绑定。 | `/acp close` | +| `/acp status` | 显示后端、模式、状态、运行时选项和能力。 | `/acp status` | +| `/acp set-mode` | 设置目标会话的运行时模式。 | `/acp set-mode plan` | +| `/acp set` | 写入通用运行时配置选项。 | `/acp set model openai/gpt-5.4` | +| `/acp cwd` | 设置运行时工作目录覆盖值。 | `/acp cwd /Users/user/Projects/repo` | | `/acp permissions` | 设置审批策略配置文件。 | `/acp permissions strict` | | `/acp timeout` | 设置运行时超时（秒）。 | `/acp timeout 120` | -| `/acp model` | 设置运行时模型覆盖项。 | `/acp model anthropic/claude-opus-4-6` | -| `/acp reset-options` | 移除会话运行时选项覆盖项。 | `/acp reset-options` | -| `/acp sessions` | 列出存储中的最近 ACP 会话。 | `/acp sessions` | -| `/acp doctor` | 检查后端健康状况、能力和可执行修复。 | `/acp doctor` | -| `/acp install` | 打印确定性的安装与启用步骤。 | `/acp install` | +| `/acp model` | 设置运行时模型覆盖值。 | `/acp model anthropic/claude-opus-4-6` | +| `/acp reset-options` | 移除会话运行时选项覆盖值。 | `/acp reset-options` | +| `/acp sessions` | 从存储中列出最近的 ACP 会话。 | `/acp sessions` | +| `/acp doctor` | 检查后端健康状态、能力和可执行修复。 | `/acp doctor` | +| `/acp install` | 打印确定性的安装和启用步骤。 | `/acp install` | -`/acp status` 会显示生效中的运行时选项，以及运行时级别和后端级别的会话标识符。当某个后端缺少某项能力时，不支持的控制错误会清晰显示。`/acp sessions` 会读取当前已绑定会话或请求方会话的存储；目标标记（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括自定义的按智能体划分的 `session.store` 根目录。 +`/acp status` 会显示生效中的运行时选项，以及运行时级别和后端级别的会话标识符。当某个后端缺少某项能力时，不支持控制的错误会被清晰呈现。`/acp sessions` 会读取当前已绑定会话或请求方会话的存储；目标令牌（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括每个智能体自定义的 `session.store` 根目录。 ## 运行时选项映射 @@ -518,43 +536,44 @@ ACP 会话当前运行在主机运行时上，而不是 OpenClaw 沙箱内。 等价操作： -- `/acp model ` 映射到运行时配置键 `model`。对于 Codex ACP，OpenClaw 会将 `openai-codex/` 规范化为适配器模型 id，并将带斜杠的推理后缀（例如 `openai-codex/gpt-5.4/high`）映射为 Codex ACP 的 `reasoning_effort`。 -- `/acp set thinking ` 映射到运行时配置键 `thinking`。对于 Codex ACP，在适配器支持时，OpenClaw 会发送相应的 `reasoning_effort`。 +- `/acp model ` 映射到运行时配置键 `model`。对于 Codex ACP，OpenClaw 会将 `openai-codex/` 规范化为适配器模型 id，并将斜杠推理后缀（例如 `openai-codex/gpt-5.4/high`）映射为 Codex ACP 的 `reasoning_effort`。 +- `/acp set thinking ` 映射到运行时配置键 `thinking`。对于 Codex ACP，在适配器支持时，OpenClaw 会发送对应的 `reasoning_effort`。 - `/acp permissions ` 映射到运行时配置键 `approval_policy`。 - `/acp timeout ` 映射到运行时配置键 `timeout`。 -- `/acp cwd ` 直接更新运行时 `cwd` 覆盖项。 +- `/acp cwd ` 会直接更新运行时 `cwd` 覆盖值。 - `/acp set ` 是通用路径。 - 特殊情况：`key=cwd` 使用 `cwd` 覆盖路径。 -- `/acp reset-options` 会清除目标会话的所有运行时覆盖项。 +- `/acp reset-options` 会清除目标会话的所有运行时覆盖值。 -## acpx harness、插件设置和权限 +## acpx 框架、插件设置和权限 -有关 acpx harness 配置（Claude Code / Codex / Gemini CLI 别名）、plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP 权限模式，请参见 -[ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)。 +关于 acpx 框架配置（Claude Code / Codex / Gemini CLI 别名）、 +plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP 权限模式，请参见 +[ACP 智能体——设置](/zh-CN/tools/acp-agents-setup)。 ## 故障排除 | 症状 | 可能原因 | 修复方法 | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ACP runtime backend is not configured` | 后端插件缺失或已禁用。 | 安装并启用后端插件，然后运行 `/acp doctor`。 | -| `ACP is disabled by policy (acp.enabled=false)` | ACP 已被全局禁用。 | 设置 `acp.enabled=true`。 | +| `ACP is disabled by policy (acp.enabled=false)` | ACP 被全局禁用。 | 设置 `acp.enabled=true`。 | | `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 来自普通线程消息的分发已禁用。 | 设置 `acp.dispatch.enabled=true`。 | | `ACP agent "" is not allowed by policy` | 智能体不在允许列表中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 | -| `Unable to resolve session target: ...` | key/id/label 标记错误。 | 运行 `/acp sessions`，复制精确的 key/label，然后重试。 | -| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活跃可绑定会话时使用了 `--bind here`。 | 移动到目标聊天/渠道后重试，或使用未绑定生成。 | -| `Conversation bindings are unavailable for .` | 适配器缺少当前会话 ACP 绑定能力。 | 在支持时使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或切换到受支持的渠道。 | -| `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文之外使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 | -| `Only can rebind this channel/conversation/thread.` | 当前活跃绑定目标由其他用户拥有。 | 由拥有者重新绑定，或使用其他会话或线程。 | +| `Unable to resolve session target: ...` | key/id/label 令牌错误。 | 运行 `/acp sessions`，复制精确的 key/label，然后重试。 | +| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活跃可绑定对话的情况下使用了 `--bind here`。 | 移动到目标聊天/渠道后重试，或使用未绑定启动。 | +| `Conversation bindings are unavailable for .` | 适配器缺少当前对话 ACP 绑定能力。 | 在支持时使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或切换到受支持的渠道。 | +| `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文外使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 | +| `Only can rebind this channel/conversation/thread.` | 另一个用户拥有当前活跃绑定目标。 | 由所有者重新绑定，或使用其他对话或线程。 | | `Thread bindings are unavailable for .` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或切换到受支持的适配器/渠道。 | -| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时在主机侧运行；请求方会话处于沙箱隔离中。 | 从沙箱隔离会话中使用 `runtime="subagent"`，或从非沙箱隔离会话中运行 ACP 生成。 | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对需要沙箱隔离的情况使用 `runtime="subagent"`，或从非沙箱隔离会话中使用带 `sandbox="inherit"` 的 ACP。 | +| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于宿主侧；请求方会话处于沙箱隔离中。 | 从沙箱隔离会话中使用 `runtime="subagent"`，或从非沙箱隔离会话中启动 ACP。 | +| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对需要沙箱隔离的场景使用 `runtime="subagent"`，或从非沙箱隔离会话中使用 ACP 配合 `sandbox="inherit"`。 | | 绑定会话缺少 ACP 元数据 | ACP 会话元数据已过期/被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 | -| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互式 ACP 会话中阻止了写入/执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设为 `approve-all` 并重启 Gateway 网关。参见[权限配置](/zh-CN/tools/acp-agents-setup#permission-configuration)。 | +| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互 ACP 会话中阻止写入/执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见[权限配置](/zh-CN/tools/acp-agents-setup#permission-configuration)。 | | ACP 会话很早失败且输出很少 | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。若需完整权限，设置 `permissionMode=approve-all`；若需优雅降级，设置 `nonInteractivePermissions=deny`。 | -| ACP 会话在完成工作后无限期卡住 | harness 进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动杀掉陈旧进程。 | +| ACP 会话在完成工作后无限期卡住 | 框架进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动终止陈旧进程。 | ## 相关内容 - [子智能体](/zh-CN/tools/subagents) - [多智能体沙箱工具](/zh-CN/tools/multi-agent-sandbox-tools) -- [智能体发送](/zh-CN/tools/agent-send) +- [Agent send](/zh-CN/tools/agent-send) diff --git a/docs/zh-CN/tools/subagents.md b/docs/zh-CN/tools/subagents.md index 7e9537673..6d94087e9 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-25T17:03:05Z" + generated_at: "2026-04-25T20:27:28Z" model: gpt-5.4 provider: openai - source_hash: 70195000c4326baba38a9a096dc8d6db178f754f345ad05d122902ee1216ab1c + source_hash: 23483228f4ab9af27ff1f98c5e3fdbd2032e66f12be819d0d0a1ad5e51e7da11 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,121 +38,122 @@ 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` 投递。 +- 生成命令是非阻塞的；它会立即返回一个运行 id。 +- 完成时，子智能体会向请求者聊天渠道回报一条摘要 / 结果消息。 +- 完成投递采用推送方式。生成后，不要仅仅为了等待它完成而循环轮询 `/subagents list`、`sessions_list` 或 `sessions_history`；仅在调试或干预时按需检查状态。 +- 完成时，OpenClaw 会尽最大努力关闭该子智能体会话打开的已跟踪浏览器标签页 / 进程，然后再继续执行回报清理流程。 +- 对于手动生成，投递具有韧性： + - OpenClaw 会先使用稳定的幂等键尝试直接 `agent` 投递。 - 如果直接投递失败，它会回退到队列路由。 - - 如果队列路由仍不可用，则会在最终放弃前采用短时间指数退避重试通告。 + - 如果队列路由仍不可用，则会在最终放弃前使用短指数退避重试该回报。 - 完成投递会保留已解析的请求者路由： - - 如果可用，线程绑定或会话绑定的完成路由优先 - - 如果完成来源仅提供渠道，OpenClaw 会从请求者会话的已解析路由（`lastChannel` / `lastTo` / `lastAccountId`）中补全缺失的 target/account，以便直接投递仍然可用 -- 向请求者会话移交完成结果时，使用的是运行时生成的内部上下文（不是用户编写的文本），其中包括： - - `Result`（最新可见的 `assistant` 回复文本；否则为经过净化的最新 tool/toolResult 文本；终止且失败的运行不会复用已捕获的回复文本） + - 可用时，线程绑定或会话绑定的完成路由优先 + - 如果完成来源只提供渠道，OpenClaw 会用请求者会话已解析路由中的缺失目标 / 账户（`lastChannel` / `lastTo` / `lastAccountId`）进行补全，以便直接投递仍然可用 +- 交给请求者会话的完成移交内容是运行时生成的内部上下文（不是用户编写的文本），其中包括： + - `Result`（最新可见的 `assistant` 回复文本；否则为已净化的最新 `tool` / `toolResult` 文本；终态失败运行不会复用已捕获的回复文本） - `Status`（`completed successfully` / `failed` / `timed out` / `unknown`） - - 精简的运行时/Token 统计 - - 一条投递指令，告知请求者智能体用正常的助手语气改写（而不是转发原始内部元数据） -- `--model` 和 `--thinking` 会覆盖该次运行的默认值。 -- 完成后使用 `info`/`log` 检查详情和输出。 -- `/subagents spawn` 是一次性模式（`mode: "run"`）。对于持久的线程绑定会话，请使用带有 `thread: true` 和 `mode: "session"` 的 `sessions_spawn`。 -- 对于 ACP harness 会话（Codex、Claude Code、Gemini CLI），请使用带有 `runtime: "acp"` 的 `sessions_spawn`，并参见 [ACP Agents](/zh-CN/tools/acp-agents)，尤其是在调试完成投递或智能体到智能体循环时的 [ACP delivery model](/zh-CN/tools/acp-agents#delivery-model)。 + - 紧凑的运行时 / 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 用量。对于高负载或重复性任务，请为子智能体设置更便宜的模型，并让你的主智能体继续使用质量更高的模型。你可以通过 `agents.defaults.subagents.model` 或按智能体的覆盖配置来实现。当某个子级确实需要请求者当前的转录时，智能体可以在该次派生时请求 `context: "fork"`。 +成本说明：每个子智能体默认都有其**自己的**上下文和 token 使用量。对于重型或重复性任务，请为子智能体设置更便宜的模型，而让你的主智能体保留更高质量的模型。你可以通过 `agents.defaults.subagents.model` 或按智能体覆盖来配置这一点。当子级确实需要请求者当前的转录时，智能体可以在那一次生成中请求 `context: "fork"`。 ## 上下文模式 -原生子智能体默认以隔离方式启动，除非调用者明确请求分叉当前转录。 +原生子智能体默认以隔离方式启动，除非调用方明确要求分叉当前转录。 -| 模式 | 适用场景 | 行为 | -| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | -| `isolated` | 全新研究、独立实现、慢工具工作，或任何可以在任务文本中简要说明的事情 | 创建一个干净的子级转录。这是默认值，并且可以保持较低的 Token 用量。 | -| `fork` | 依赖当前对话、先前工具结果或请求者转录中已有细致指令的工作 | 在子级启动前，将请求者转录分支到子级会话中。 | +| 模式 | 适用场景 | 行为 | +| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | +| `isolated` | 全新的研究、独立实现、慢工具工作，或任何可以在任务文本中简要说明的工作 | 创建一个干净的子级转录。这是默认值，并可保持较低的 token 使用量。 | +| `fork` | 工作依赖于当前对话、先前工具结果，或请求者转录中已存在的细致说明时 | 在子级启动前，将请求者转录分支到子级会话中。 | -谨慎使用 `fork`。它用于对上下文敏感的委派，而不是用来替代编写清晰的任务提示。 +谨慎使用 `fork`。它适用于对上下文敏感的委派，而不是用来替代编写清晰任务提示。 ## 工具 使用 `sessions_spawn`： - 启动一个子智能体运行（`deliver: false`，全局通道：`subagent`） -- 然后执行一个通告步骤，并将通告回复发布到请求者聊天渠道 -- 默认模型：继承调用者，除非你设置了 `agents.defaults.subagents.model`（或按智能体设置 `agents.list[].subagents.model`）；显式指定的 `sessions_spawn.model` 仍然优先。 -- 默认 thinking：继承调用者，除非你设置了 `agents.defaults.subagents.thinking`（或按智能体设置 `agents.list[].subagents.thinking`）；显式指定的 `sessions_spawn.thinking` 仍然优先。 +- 然后执行一个回报步骤，并将回报回复发布到请求者聊天渠道 +- 默认模型：继承调用方，除非你设置了 `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`（必填） - `label?`（可选） -- `agentId?`（可选；如果允许，可在另一个智能体 id 下派生） -- `model?`（可选；覆盖子智能体模型；无效值会被跳过，子智能体将使用默认模型运行，并在工具结果中给出警告） +- `agentId?`（可选；如果允许，则在另一个智能体 id 下生成） +- `runtime?`（`subagent|acp`，默认 `subagent`；`acp` 仅用于外部 ACP harness，例如 `codex`、`claude`、`gemini` 或 `opencode`，或用于 `runtime.type` 为 `acp` 的 `agents.list[]` 条目） +- `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` + - 默认值为 `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 会在当前活跃渠道中为该会话目标创建线程或绑定现有线程。 -3. 该线程中的回复和后续消息会路由到已绑定的会话。 -4. 使用 `/session idle` 检查/更新因不活跃而自动取消聚焦的设置，并使用 `/session max-age` 控制硬性时长上限。 +1. 使用 `sessions_spawn` 生成，并设置 `thread: true`（可选设置 `mode: "session"`）。 +2. OpenClaw 会在当前渠道中创建线程或将线程绑定到该会话目标。 +3. 该线程中的回复和后续消息会路由到绑定的会话。 +4. 使用 `/session idle` 检查 / 更新因不活跃而自动取消聚焦的设置，使用 `/session max-age` 控制硬性时长上限。 5. 使用 `/unfocus` 手动解除绑定。 手动控制： -- `/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` -- 渠道覆盖和派生自动绑定键是适配器特定的。请参见上方的**支持线程的渠道**。 +- 渠道覆盖和生成自动绑定键是适配器特定的。请参阅上文的**支持线程的渠道**。 -有关当前适配器详情，请参见[配置参考](/zh-CN/gateway/configuration-reference)和[斜杠命令](/zh-CN/tools/slash-commands)。 +当前适配器的详细信息请参阅 [Configuration Reference](/zh-CN/gateway/configuration-reference) 和 [Slash commands](/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。 发现： @@ -160,17 +161,17 @@ x-i18n: 自动归档： -- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes`（默认：60）之后自动归档。 +- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes` 之后自动归档（默认值：60）。 - 归档使用 `sessions.delete`，并将转录重命名为 `*.deleted.`（同一文件夹中）。 -- `cleanup: "delete"` 会在通告后立即归档（仍会通过重命名保留转录）。 +- `cleanup: "delete"` 会在回报后立即归档（仍会通过重命名保留转录）。 - 自动归档是尽力而为；如果 Gateway 网关重启，待处理计时器会丢失。 -- `runTimeoutSeconds` **不会**触发自动归档；它只会停止运行。会话会保留到自动归档发生。 -- 自动归档同样适用于深度 1 和深度 2 会话。 -- 浏览器清理与归档清理是分开的：当运行结束时，即使保留转录/会话记录，被跟踪的浏览器标签页/进程也会尽最大努力关闭。 +- `runTimeoutSeconds` **不会**自动归档；它只会停止运行。会话会保留到自动归档发生。 +- 自动归档同样适用于深度 1 和深度 2 的会话。 +- 浏览器清理与归档清理是分开的：即使保留了转录 / 会话记录，在运行结束时也会尽最大努力关闭已跟踪浏览器标签页 / 进程。 ## 嵌套子智能体 -默认情况下，子智能体不能再派生自己的子智能体（`maxSpawnDepth: 1`）。你可以通过设置 `maxSpawnDepth: 2` 来启用一层嵌套，即允许**编排器模式**：主智能体 → 编排器子智能体 → 工作子子智能体。 +默认情况下，子智能体不能生成自己的子智能体（`maxSpawnDepth: 1`）。你可以通过设置 `maxSpawnDepth: 2` 来启用一层嵌套，这样就允许使用**编排器模式**：主智能体 → 编排器子智能体 → 工作子子智能体。 ### 如何启用 @@ -179,10 +180,10 @@ x-i18n: agents: { defaults: { subagents: { - maxSpawnDepth: 2, // 允许子智能体派生子级（默认：1） - maxChildrenPerAgent: 5, // 每个智能体会话的最大活跃子级数（默认：5） - maxConcurrent: 8, // 全局并发通道上限（默认：8） - runTimeoutSeconds: 900, // 为省略该项的 sessions_spawn 设置默认超时（0 = 无超时） + 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) }, }, }, @@ -191,115 +192,115 @@ x-i18n: ### 深度级别 -| 深度 | 会话键形态 | 角色 | 可以派生？ | +| 深度 | 会话键形状 | 角色 | 可以生成？ | | ---- | -------------------------------------------- | --------------------------------------------- | ----------------------------- | | 0 | `agent::main` | 主智能体 | 始终可以 | -| 1 | `agent::subagent:` | 子智能体（当允许深度 2 时为编排器） | 仅当 `maxSpawnDepth >= 2` 时 | -| 2 | `agent::subagent::subagent:` | 子子智能体（叶子工作节点） | 永远不可以 | +| 1 | `agent::subagent:` | 子智能体（在允许深度 2 时为编排器） | 仅当 `maxSpawnDepth >= 2` 时 | +| 2 | `agent::subagent::subagent:` | 子子智能体（叶子工作器） | 永不可以 | -### 通告链 +### 回报链 -结果会沿链路逐级回传： +结果会沿链路向上回传： -1. 深度 2 的工作节点完成 → 向其父级（深度 1 编排器）通告 -2. 深度 1 编排器接收通告、综合结果、完成 → 向主智能体通告 -3. 主智能体接收通告并投递给用户 +1. 深度 2 工作器完成 → 向其父级（深度 1 编排器）回报 +2. 深度 1 编排器接收回报、综合结果、完成 → 向主智能体回报 +3. 主智能体接收回报并投递给用户 -每一层只能看到来自其直接子级的通告。 +每一层只会看到其直接子级的回报。 操作指南： -- 子级工作启动一次后，等待完成事件，而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` sleep 命令构建轮询循环。 -- `sessions_list` 和 `/subagents list` 会让子会话关系聚焦于正在进行的工作：活跃子级保持附着，已结束子级会在一个较短的最近窗口内继续可见，而仅存储中的过期子级链接会在其新鲜度窗口过后被忽略。这可以防止旧的 `spawnedBy` / `parentSessionKey` 元数据在重启后“复活”幽灵子级。 -- 如果某个子级完成事件在你已经发送最终答案之后才到达，正确的后续处理是精确的静默令牌 `NO_REPLY` / `no_reply`。 +- 子级工作只启动一次，然后等待完成事件，而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` sleep 命令构建轮询循环。 +- `sessions_list` 和 `/subagents list` 会让子会话关系聚焦于实时工作：仍在运行的子级会保持关联，已结束的子级会在短暂的最近窗口中保持可见，而仅存储中的陈旧子级链接会在其新鲜度窗口后被忽略。这可防止旧的 `spawnedBy` / `parentSessionKey` 元数据在重启后重新唤起“幽灵”子级。 +- 如果子级完成事件在你已经发送最终答案之后才到达，正确的后续操作是精确的静默 token `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 ` 会停止特定子智能体，并级联停止其子级。 +- 在主聊天中使用 `/stop` 会停止所有深度 1 智能体，并级联停止它们的深度 2 子级。 +- `/subagents kill ` 会停止指定子智能体，并级联停止其子级。 - `/subagents kill all` 会停止该请求者的所有子智能体，并执行级联停止。 -## 身份验证 +## 认证 -子智能体身份验证按**智能体 id**解析，而不是按会话类型解析： +子智能体认证是按**智能体 id**解析的，而不是按会话类型： -- 子智能体会话键是 `agent::subagent:`。 -- 身份验证存储从该智能体的 `agentDir` 加载。 -- 主智能体的身份验证配置档案会作为**回退**合并进来；在发生冲突时，智能体配置档案会覆盖主配置档案。 +- 子智能体会话键为 `agent::subagent:`。 +- 认证存储从该智能体的 `agentDir` 加载。 +- 主智能体的认证配置文件会作为**回退**合并进来；发生冲突时，智能体配置文件会覆盖主配置文件。 -注意：这种合并是追加式的，因此主配置档案始终可作为回退使用。当前尚不支持每个智能体完全隔离的身份验证。 +注意：这种合并是增量式的，因此主配置文件始终可作为回退使用。每个智能体完全隔离的认证目前尚不支持。 -## 通告 +## 回报 -子智能体通过一个通告步骤回报结果： +子智能体通过回报步骤进行反馈： -- 通告步骤在子智能体会话内运行（而不是请求者会话）。 -- 如果子智能体精确回复 `ANNOUNCE_SKIP`，则不会发布任何内容。 -- 如果最新的 assistant 文本是精确的静默令牌 `NO_REPLY` / `no_reply`，即使之前存在可见进度，也会抑制通告输出。 -- 否则，投递取决于请求者深度： - - 顶层请求者会话使用带有外部投递（`deliver=true`）的后续 `agent` 调用 +- 回报步骤在子智能体会话内部运行（而不是在请求者会话中）。 +- 如果子智能体的回复精确等于 `ANNOUNCE_SKIP`，则不会发布任何内容。 +- 如果最新的助手文本是精确的静默 token `NO_REPLY` / `no_reply`，则即使之前存在可见进度，也会抑制回报输出。 +- 否则投递方式取决于请求者深度： + - 顶层请求者会话使用后续 `agent` 调用进行外部投递（`deliver=true`） - 嵌套的请求者子智能体会话接收内部后续注入（`deliver=false`），以便编排器在会话内综合子级结果 - - 如果某个嵌套的请求者子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求者 -- 对于顶层请求者会话，完成模式的直接投递会先解析任何已绑定的对话/线程路由和 hook 覆盖，然后从请求者会话存储的路由中补全缺失的渠道目标字段。这样即使完成来源只标识了渠道，也能确保完成结果发送到正确的聊天/主题。 -- 在构建嵌套完成结果时，子级完成聚合会限定在当前请求者运行范围内，防止旧的先前运行子级输出泄漏到当前通告中。 -- 在渠道适配器支持时，通告回复会保留线程/主题路由。 -- 通告上下文会规范化为稳定的内部事件块： + - 如果嵌套的请求者子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求者 +- 对于顶层请求者会话，完成模式的直接投递会先解析任何已绑定的会话 / 线程路由和 hook 覆盖，然后用请求者会话存储路由中的字段补全缺失的渠道目标字段。这样即使完成来源只标识了渠道，也能让完成结果发送到正确的聊天 / 主题。 +- 在构建嵌套完成结果时，子级完成聚合会限定在当前请求者运行范围内，防止陈旧的先前运行子级输出泄露到当前回报中。 +- 在渠道适配器可用时，回报回复会保留线程 / 主题路由。 +- 回报上下文会规范化为稳定的内部事件块： - 来源（`subagent` 或 `cron`） - - 子级会话键/id - - 通告类型 + 任务标签 - - 从运行时结果派生出的状态行（`success`、`error`、`timeout` 或 `unknown`） - - 从最新可见 assistant 文本中选取的结果内容；否则使用经过净化的最新 tool/toolResult 文本；终止且失败的运行会报告失败状态，而不会重放已捕获的回复文本 - - 一条后续指令，用于说明何时回复、何时保持静默 -- `Status` 不是根据模型输出推断的；它来自运行时结果信号。 -- 超时时，如果子级只执行到了工具调用阶段，通告可以将该历史折叠为一段简短的部分进展摘要，而不是重放原始工具输出。 + - 子级会话键 / id + - 回报类型 + 任务标签 + - 基于运行时结果派生的状态行（`success`、`error`、`timeout` 或 `unknown`） + - 从最新可见助手文本中选择的结果内容；否则为已净化的最新 `tool` / `toolResult` 文本；终态失败运行会报告失败状态，而不会回放已捕获的回复文本 + - 一条后续指令，说明何时应回复、何时应保持静默 +- `Status` 不是从模型输出推断出来的；它来自运行时结果信号。 +- 超时时，如果子级只执行到了工具调用，回报可以将那段历史压缩成简短的部分进度摘要，而不是回放原始工具输出。 -通告负载在末尾包含一行统计信息（即使被包裹时也是如此）： +回报负载在末尾包含一行统计信息（即使被包装也会包含）： - 运行时长（例如 `runtime 5m12s`） -- Token 用量（输入/输出/总计） -- 当配置了模型定价时的预估成本（`models.providers.*.models[].cost`） -- `sessionKey`、`sessionId` 和转录路径（这样主智能体可以通过 `sessions_history` 获取历史，或在磁盘上检查该文件） +- Token 使用量（输入 / 输出 / 总计） +- 配置了模型定价时的预估成本（`models.providers.*.models[].cost`） +- `sessionKey`、`sessionId` 和转录路径（因此主智能体可以通过 `sessions_history` 获取历史，或在磁盘上检查文件） - 内部元数据仅用于编排；面向用户的回复应以正常助手语气重写。 `sessions_history` 是更安全的编排路径： -- assistant 回顾会先被规范化： - - 去除 thinking 标签 - - 去除 `` / `` 脚手架块 - - 去除纯文本工具调用 XML 负载块，例如 `...`、`...`、`...` 和 `...`，包括那些从未正确闭合的截断负载 - - 去除降级后的工具调用/结果脚手架和历史上下文标记 - - 去除泄漏的模型控制令牌，例如 `<|assistant|>`、其他 ASCII `<|...|>` 令牌，以及全角 `<｜...｜>` 变体 - - 去除格式错误的 MiniMax 工具调用 XML -- 凭证/Token 类文本会被脱敏 +- 助手回溯会先被标准化： + - 移除 thinking 标签 + - 移除 `` / `` 脚手架块 + - 移除纯文本工具调用 XML 负载块，如 `...`、`...`、`...` 和 `...`，包括那些从未正确闭合的截断负载 + - 移除降级的工具调用 / 结果脚手架和历史上下文标记 + - 移除泄露的模型控制 token，例如 `<|assistant|>`、其他 ASCII `<|...|>` token，以及全角 `<｜...｜>` 变体 + - 移除格式错误的 MiniMax 工具调用 XML +- 类似凭证 / token 的文本会被脱敏 - 长内容块可能会被截断 -- 对于非常大的历史记录，可能会丢弃较早的行，或将过大的单行替换为 `[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`，以便管理其子级。 @@ -317,9 +318,9 @@ x-i18n: tools: { subagents: { tools: { - // deny 优先 + // deny wins deny: ["gateway", "cron"], - // 如果设置了 allow，它会变成仅允许列表（deny 仍然优先） + // if allow is set, it becomes allow-only (deny still wins) // allow: ["read", "exec", "process"] }, }, @@ -327,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` 是最终的仅允许过滤器。它可以缩小已解析出的工具集，但不能把已被 `tools.profile` 移除的工具重新加回来。例如，`tools.profile: "coding"` 包含 `web_search` / `web_fetch`，但不包含 `browser` 工具。要让 coding 配置文件的子智能体使用浏览器自动化，请在配置文件阶段加入 browser： ```json5 { @@ -342,33 +343,33 @@ x-i18n: ## 并发 -子智能体使用专用的进程内队列通道： +子智能体使用一个专用的进程内队列通道： - 通道名称：`subagent` -- 并发数：`agents.defaults.subagents.maxConcurrent`（默认 `8`） +- 并发数：`agents.defaults.subagents.maxConcurrent`（默认值 `8`） ## 存活性与恢复 -OpenClaw 不会将缺少 `endedAt` 永久视为某个子智能体仍然存活的证据。超过过期运行窗口的未结束运行，在 `/subagents list`、状态摘要、后代完成门控以及每会话并发检查中，将不再计为活跃/待处理。 +OpenClaw 不会把缺少 `endedAt` 永久视为子智能体仍然存活的证明。超过陈旧运行窗口的未结束运行，将不再在 `/subagents list`、状态摘要、后代完成门控以及每会话并发检查中计为活跃 / 待处理。 -在 Gateway 网关重启后，过期且未结束的已恢复运行会被清理，除非其子会话被标记为 `abortedLastRun: true`。这些因重启而中止的子会话仍可通过子智能体孤儿恢复流程恢复，该流程会先发送一条合成的恢复消息，然后清除中止标记。 +Gateway 网关重启后，陈旧的未结束恢复运行会被清理，除非它们的子会话被标记为 `abortedLastRun: true`。这些因重启而中止的子会话仍可通过子智能体孤儿恢复流程进行恢复，该流程会先发送一条合成恢复消息，然后清除中止标记。 ## 停止 -- 在请求者聊天中发送 `/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`）。 +- 子智能体上下文只注入 `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）。 ## 相关内容 -- [ACP agents](/zh-CN/tools/acp-agents) -- [Multi-agent sandbox tools](/zh-CN/tools/multi-agent-sandbox-tools) -- [Agent send](/zh-CN/tools/agent-send) +- [ACP 智能体](/zh-CN/tools/acp-agents) +- [多智能体沙箱工具](/zh-CN/tools/multi-agent-sandbox-tools) +- [智能体发送](/zh-CN/tools/agent-send)