OpenClaw Sub-agent 通信工具：sessions_spawn / sessions_send / sessions_yield

OpenClaw 多 Agent 编排中的三个核心工具，用于主 Agent 与子 Agent 之间的任务分发和通信。

Agent 间通信三种方式

OpenClaw 提供三种语法，本质上是同一功能的不同抽象层：

方式	语法示例	使用场景	执行模式
@<agentId>	@coder 写个函数	快捷临时委托	同步阻塞
/subagents spawn	/subagents spawn coder "任务"	精细控制的异步任务	异步非阻塞
sessions_spawn	工具调用（编程式）	主 Agent 自动决策	灵活控制

底层关系：

@coder 任务
   ↓ (解析器转换)
/subagents spawn coder "任务"  (使用默认参数)
   ↓ (内部调用)
sessions_spawn(agentId="coder", task="任务")

@agentId — 快捷同步语法

@coder 帮我写一个排序算法

• 最轻量的快捷方式，立即在当前对话中召唤子 Agent
• 同步执行，等待结果返回后继续
• 无法传额外参数（model、thinking 等）
• 适合：简单快速的子任务，需要立即看到结果

/subagents spawn — 完整异步命令

/subagents spawn coder "写排序算法" --model gpt-4o --thinking high

• 显式创建独立子会话，异步执行，当前对话继续
• 可指定模型、思考深度等高级参数
• 适合：复杂任务、并行执行、需要独立上下文

选择建议：

需求	推荐方式
快速问答，必须立即得到结果	@agentId
需要指定模型/思考深度	/subagents spawn
并行执行多个子任务	/subagents spawn（多个）
主 Agent 自动决策分解任务	sessions_spawn
不想等待结果	/subagents spawn

sessions_spawn / sessions_send / sessions_yield 工具概览

工具	作用	阻塞？
sessions_spawn	启动一个后台子 Agent 执行任务	否，立即返回 run id
sessions_send	向已运行的子 Agent 发送消息（steer/引导）	否，单向发送
sessions_yield	结束当前 turn，等待子 Agent 完成事件到达	是，挂起当前 turn

注意：sessions_send 不是”同步阻塞等待回复”的工具。它是向子 Agent 发送引导消息（类似 steer），不会返回子 Agent 的回复内容。等待子 Agent 完成应使用 sessions_yield。

sessions_spawn

启动一个后台子 Agent run，完成后将结果 announce（公告） 回请求方的聊天频道。

核心行为：

• 非阻塞，立即返回 run id
• 子 Agent 在独立 session 中运行（agent:<agentId>:subagent:<uuid>）
• 完成后主动推送结果到请求方频道（push-based，不要轮询）
• 子 Agent 默认不继承父 Agent 的 session tools

工具参数：

sessions_spawn({
  task: string,                       // 必需：任务描述
  agentId?: string,                   // 指定子 Agent（需在 allowAgents 白名单内）
  taskName?: string,                  // 稳定句柄，用于后续 steer/kill（如 "review_task"）
  label?: string,                     // 显示标签，出现在日志和 Active Subagents 提示块
  model?: string,                     // 覆盖子 Agent 模型
  thinking?: string,                  // 覆盖思考级别（"none"/"low"/"high"）
  runTimeoutSeconds?: number,         // 超时秒数（0 = 不超时，默认 900）
  context?: "isolated" | "fork",      // 默认 isolated
  thread?: boolean,                   // 是否绑定到频道线程（仅 Discord 支持）
  mode?: "run" | "session",           // thread:true 时默认 session
  cleanup?: "delete" | "keep",        // 完成后是否立即归档
  sandbox?: "inherit" | "require",    // require 时未沙箱化则拒绝 spawn
})

参数详解：

参数	说明
task	子 Agent 收到的第一条”用户消息”。写得越清晰越好，不要依赖父 Agent 上下文（除非用 fork）
agentId	指定执行 Agent，不填则系统选默认 Agent
taskName	稳定句柄，后续可用 /subagents send review_task <msg> 操作，无需记 run id
label	纯展示用标签，不影响行为
model	覆盖模型，可降本（小模型做简单任务）或提质（大模型做复杂推理）
thinking	覆盖 extended thinking 级别
runTimeoutSeconds	最长运行时间，0 表示不超时（慎用）
context	见下方 Context 模式说明
thread	true 时子 Agent 回复在线程里，不刷主频道（仅 Discord）
mode	run=单次执行完即结束；session=保持存活可持续交互
cleanup	delete=完成后立即归档；keep=保留 session 供后续查看日志
sandbox	inherit=继承父 Agent 沙箱设置；require=强制沙箱，未沙箱化则拒绝 spawn

Context 模式：

模式	适用场景	行为
isolated（默认）	独立研究、并行实现、慢工具任务	创建干净的子 transcript，token 消耗低
fork	依赖当前对话上下文的任务	将父 transcript 分支到子 session，token 消耗高

fork 谨慎使用，不是写清楚 task prompt 的替代品。

典型组合示例：

// 安全审查任务：强模型 + 沙箱 + 保留日志
sessions_spawn({
  task: "审查 PR #42，重点检查 SQL 注入和权限校验，输出问题列表",
  agentId: "security-reviewer",
  taskName: "pr42_review",
  model: "claude-opus-4-6",
  runTimeoutSeconds: 600,
  context: "isolated",
  sandbox: "require",
  cleanup: "keep",
})

典型用法（群聊 @ 指令）：

用户 @主Agent 帮我写个排序算法

主 Agent：
1. sessions_spawn({ agentId: "programmer", task: "写冒泡排序算法" })
2. 回复用户："已启动 programmer Agent 处理，完成后会通知你"
3. 继续处理其他请求

programmer Agent 完成后：
→ 在群聊中公告结果（所有人可见）

可用性： coding 和 full profile 默认包含此工具；messaging profile 不包含，需手动添加：

{ "tools": { "alsoAllow": ["sessions_spawn", "sessions_yield", "subagents"] } }

sessions_send（/subagents send）

向已运行的子 Agent 发送引导消息，等同于 /subagents send <id> <message>。

• 用于在子 Agent 运行过程中调整方向（steer）
• 不返回子 Agent 的回复内容
• 需要知道子 Agent 的 id 或 taskName

# 等价的 slash command
/subagents send <id|#|taskName> <message>
/subagents steer <id|#|taskName> <message>

sessions_yield

结束当前 model turn，等待子 Agent 完成事件作为下一条消息到达。

• 在 spawn 了必要的子任务后、主 Agent 无法给出最终答案前使用
• 不要用轮询（subagents list、sessions_history、sleep）替代它
• 只在 effective tool list 包含此工具时使用

主 Agent 流程：
1. sessions_spawn(task_A)
2. sessions_spawn(task_B)
3. sessions_yield()          ← 挂起，等待 A 和 B 完成
4. [收到完成事件] 综合结果回复用户

/subagents 管理命令

/subagents list                          # 列出当前 session 的子 Agent
/subagents info <id|#>                   # 查看运行元数据
/subagents log <id|#> [limit] [tools]    # 查看日志
/subagents send <id|#> <message>         # 发送引导消息
/subagents steer <id|#> <message>        # 引导子 Agent
/subagents kill <id|#|all>               # 终止子 Agent
/subagents spawn <agentId> <task> [--model <m>] [--thinking <l>]

嵌套子 Agent（Orchestrator 模式）

默认 maxSpawnDepth: 1（子 Agent 不能再 spawn）。设为 2 启用一级嵌套：

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxSpawnDepth": 2,
        "maxChildrenPerAgent": 5,
        "maxConcurrent": 8,
        "runTimeoutSeconds": 900
      }
    }
  }
}

编排模式：main → orchestrator sub-agent → worker sub-sub-agents

在 SOUL.md 中配置协作规则

## 协作指令
当被用户 @ 并要求完成任务时：
1. 不要自己直接完成复杂或耗时的任务
2. 使用 sessions_spawn 创建子 Agent 处理具体任务
3. 用 agentId 指定合适的 Agent，task 字段清晰描述需求
4. 调用 sessions_yield 等待结果（如需综合多个子任务）
5. 回复用户："已启动 [子 Agent 名字] 处理，完成后会通知你"

相关概念

• openclaw — OpenClaw 项目整体介绍
• openclaw-multi-agent-timeout — 多 Agent 超时与挂起问题，spawn 的错误隔离特性可缓解
• openclaw-acp-protocol — ACP 协议，用进程隔离解决主循环阻塞的更底层方案