用 sessions_spawn 理解 OpenClaw 的任务分发：subagent负责原生分工，acp负责外部执行体接管。

1 核心模型

1.1 一个入口

sessions_spawn 是 OpenClaw agent 在运行中创建子任务的统一工具。它默认创建一个隔离session，并且总是非阻塞：调用后立即返回 runId 和childSessionKey，子任务在后台执行，完成后再把结果 announce 回请求者会话。

runtime 决定这个子 session 由谁执行。

1.2 参数差异

runtime:“subagent”是默认值；runtime:“acp”必须显式写，否则会按原生 subagent 路径处理。ACP可用 agentId 选择外部harness，mode可为一次性 run 或持久session，streamTo:“parent”可把 ACP 初始运行进度流回父会话。

2 subagent运行时

2.1 概念

subagent 是 OpenClaw 原生后台 agent run。它运行在自己的 session 中，session key 类似：agent::subagent:

完成后，它会把结果发回请求者 chat channel，并作为 background task 被追踪。

它像让 OpenClaw 分身干活：

2.2 原理

subagent 默认继承调用者的模型和thinking；也可以通过 model、thinking 覆盖。它可以设置runTimeoutSeconds，可以用 sandbox:“require”要求子运行必须在沙箱内执行。文档还说明，subagent默认不会获得 session 类工具，避免递归滥用；只有配置 maxSpawnDepth >= 2 时，第一层 orchestrator subagent 才能继续 spawn 子任务。

最小调用：

因为默认就是 subagent。

2.3 应用

适合：

• 1. 多路并行分析

• 2. 长耗时后台研究

• 3. 代码审查、日志分析、测试解释

• 4. 需要 OpenClaw 工具链和沙箱约束

• 5. 不需要外部 Codex / Claude Code runtime

不适合：

• 1. 要接管外部 CLI 原生 session

• 2. 要恢复 Codex / Claude Code 线程

• 3. 要连接独立本地 daemon 的长期状态

3 acp运行时

3.1 概念

runtime:“acp”表示把任务交给外部 ACP harness。OpenClaw 仍负责channel、auth、安全和投递，但真正执行任务的是 ACP backend，例如acpx，再由它启动 Codex、Claude Code、Gemini CLI 或自定义harness。文档明确区分：ACP用于外部 harness runtime，subagent用于 OpenClaw 原生委托运行。

session key 类似：agent::acp:

3.2 原理

ACP 调用链可以理解为：

当使用 mode:“session”时，它可以建立持久 ACP session；后续消息可继续路由到同一个外部session。文档要求 mode:“session”搭配 thread: true，因为持久会话需要绑定对话线程或会话表面。

一次性调用和持久会话：

3.3 应用

适合：

• 1. 让 Codex / Claude Code 深度操作仓库

• 2. 需要外部 agent 自己的 session / resume

• 3. 需要连接本地 daemon、IDE、CLI runtime

• 4. 需要把一个聊天线程绑定到外部 coding agent

不适合：

• 1. 只是简单并行分析

• 2. 需要强制 OpenClaw sandbox

• 3. 外部 harness 未安装或 policy 未放行

4 完整示例

4.1 配置示例

假设你要同时支持：

subagent：原生代码审查acp：调用 codex 修复测试

OpenClaw 配置：

ACP 文档说明 ACP 必须启用，dispatch没被禁用，且目标 agent 需要被 policy 允许；否则 spawn 会被拒绝。

4.2 subagent实现

最简单的 subagent 用法是：让 OpenClaw 自己启动一个后台子agent，去完成一个独立任务。

含义：

runtime:“subagent”使用 OpenClaw 原生子 agentcontext:“fork”复制父会话上下文sandbox:“require”要求在沙箱中执行runTimeoutSeconds 最多运行 300 秒

执行流程：

适合用来做低风险的并行任务，例如代码阅读、日志分析、文档总结、测试失败原因初判。

4.3 acp实现

最简单的 acp 用法是：让 OpenClaw 把任务交给外部agent，例如 Codex、Claude Code、Gemini CLI 或自定义 ACP harness。

含义：

runtime:“acp”使用外部 ACP runtimeagentId:“codex”调用 acpx 中配置的 codex agentmode:“run”一次性执行任务cwd 外部 agent 的工作目录streamTo:“parent”把执行进度流回父会话

执行流程：

适合用来做需要外部执行体深度参与的任务，例如实际修改代码、运行测试、连接本地daemon、恢复外部 coding session。

5 选择原则

要 OpenClaw 自己分身干活 → subagent要外部 Codex/Claude/Gemini 干活 → acp要强制沙箱 → subagent要持久外部开发会话 → acp + mode=session + thread=true要复制当前上下文 → subagent + context=fork要流式回传外部执行进度 → acp + streamTo=parent

实际项目里，推荐用 subagent 做并行、隔离、可控的分析任务，用 acp 做需要外部 runtime 状态和仓库实操的开发任务。