OpenClaw ACP Harness 系列 03:Subagent 与 Sessions——任务编排与并行执行

一个 AI 一次处理一件事太慢了。OpenClaw 支持同时启动多个子 Agent 并行工作——就像一个技术主管带着多个工程师同时干活。

一、Sessions 基础概念

OpenClaw 中，每个对话上下文都是一个 Session：

二、sessions_spawn：启动子 Agent

// 语法
sessions_spawn({
task: "任务描述",          // 必填：告诉 subagent 做什么
runtime: "subagent",      // subagent（内部）或 acp（外部工具）
mode: "run",              // run（一次性）或 session（持久）
label: "任务标签",         // 可选：方便识别
runTimeoutSeconds: 300,   // 可选：超时时间（秒）
lightContext: true// 可选：减少上下文加载，更快启动
})

实际例子：

// 并行写文章：同时启动两个 subagent
sessions_spawn({
label: "写文章1-5",
task: "写安卓逆向系列01-05篇，保存到 /mnt/d/project/article/",
runtime: "subagent",
mode: "run",
runTimeoutSeconds: 300
})

sessions_spawn({
label: "写文章6-10",
task: "写安卓逆向系列06-10篇，保存到 /mnt/d/project/article/",
runtime: "subagent",
mode: "run",
runTimeoutSeconds: 300
})

// 两个任务同时运行，完成后推送通知给主会话

三、Subagent 的完成通知机制

Subagent 是推送式通知，不需要轮询：

1. 主会话启动 Subagent A 和 B
2. 主会话 yield（让出控制权）
3. A 和 B 在后台独立运行
4. B 先完成 → 自动推送 completion event 给主会话
5. A 完成 → 自动推送 completion event 给主会话
6. 主会话收到两个完成通知后汇总

⚠️ 注意：不要在 spawn 后主动轮询（sessions_list/exec sleep）
          completion 会自动到来，等待就好

四、ACP Harness：接入外部 AI 工具

ACP Harness 让 OpenClaw 能调度真实的编程 Agent：

// 启动 Codex 完成编程任务
sessions_spawn({
runtime: "acp",
agentId: "codex",          // 必须显式指定 harness id
task: "重构 src/auth/ 目录，改为 FastAPI async 风格",
mode: "run"
})

// 启动持久 Claude Code 会话（thread-bound）
sessions_spawn({
runtime: "acp",
agentId: "claude-code",
mode: "session",
thread: true// 绑定到当前 Discord thread
})

支持的 ACP Harness（需要在配置中启用）：

五、Sessions 管理工具

// 列出所有活跃子 Agent
subagents({ action: "list" })

// 查看某个 subagent 的输出
sessions_history({ sessionKey: "agent:main:subagent:xxx" })

// 干预正在运行的 subagent
subagents({ action: "steer", target: "写文章1-5", message: "只写前3篇就好" })

// 终止 subagent
subagents({ action: "kill", target: "写文章6-10" })

// 向另一个会话发送消息
sessions_send({ sessionKey: "agent:main:subagent:xxx", message: "暂停，等我确认" })

六、实战：大型任务的并行编排策略

以”写10篇系列文章”为例：

策略一：2个 Subagent，各写5篇
优点：简单，并发度高
缺点：如果超时，需要重来

策略二：5个 Subagent，各写2篇
优点：每个任务小，不容易超时
缺点：管理复杂度高

策略三：主会话直接写，不用 Subagent
优点：完全可控，不怕超时
缺点：必须串行，慢

推荐：任务量中等时用2-3个 Subagent；
      任务简单或需要精细控制时自己写。

七、最佳实践

下一篇：Skills 系统——给 AI 装上专属技能包