ACP vs Subagent 运行时指南
# ACP vs Subagent 运行时指南
_最后更新：2026-03-10_
_作者：小笔 ✍️_
—
## 📋 快速对比表
| 特性 | Subagent (默认) | ACP Runtime |
|——|—————–|————-|
| **runtime 参数** | `”subagent”` 或省略 | `”acp”` |
| **用途** | OpenClaw 内部任务委托 | 外部 coding harness (Pi, Claude Code, Codex 等) |
| **配置要求** | `allowAgents: [“*”]` | ACP harness 配置 |
| **通信方式** | 内部 push-based | 外部 ACP 协议 |
| **典型场景** | 文档处理、数据收集、内部任务 | 代码生成、外部 IDE 集成 |
—
## 1️⃣ 两种 Runtime 的区别和用途
### Subagent Runtime (默认)
**定义：** OpenClaw 原生的子代理系统，用于在主代理会话内部分解任务。
**特点：**
– 内置于 OpenClaw 框架
– 使用 `subagents` 工具进行创建和管理
– 结果通过 push-based 自动汇报
– 轻量级，适合快速任务委托
**适用场景：**
– 文档编写和编辑
– 数据收集和整理
– 内部任务分解
– 需要独立上下文的子任务
### ACP Runtime
**定义：** 外部 Agent Communication Protocol 运行时，用于与外部 coding harness 集成。
**特点：**
– 连接外部 AI 编码工具 (Pi, Claude Code, Codex, OpenCode, Gemini CLI 等)
– 使用 `sessions_spawn` 创建会话
– 需要 ACP harness 配置
– 适合复杂代码生成任务
**适用场景：**
– 需要外部 IDE 集成的任务
– 复杂代码生成和重构
– 与特定 coding harness 配合工作
—
## 2️⃣ 何时使用 Subagent（默认）
**✅ 使用 Subagent 的情况：**
“`javascript
// 场景 1: 文档处理任务
await subagents.spawn({
label: “小笔 – 文档专家”,
// runtime 省略或使用 “subagent”
message: “请编写这份文档…”
});
// 场景 2: 数据收集
await subagents.spawn({
label: “采儿 – 数据收集”,
message: “请收集相关数据…”
});
// 场景 3: 内部任务委托
await subagents.spawn({
label: “任务助手”,
message: “帮我完成这个子任务…”
});
“`
**最佳实践：**
– 默认使用 subagent，除非明确需要 ACP
– 给 subagent 清晰的标签和任务描述
– 信任 push-based 完成通知，不要轮询状态
—
## 3️⃣ 何时使用 ACP（外部 Coding Harness）
**✅ 使用 ACP 的情况：**
“`javascript
// 场景 1: 需要 Pi 编码助手
await sessions_spawn({
runtime: “acp”,
harness: “pi”,
message: “请生成这个模块的代码…”
});
// 场景 2: Claude Code 集成
await sessions_spawn({
runtime: “acp”,
harness: “claude-code”,
message: “请重构这个文件…”
});
// 场景 3: 其他外部 coding harness
await sessions_spawn({
runtime: “acp”,
harness: “codex”, // 或 “opencode”, “gemini-cli”
message: “请完成这个功能…”
});
“`
**注意：** 使用 ACP 前需确保：
1. 对应 harness 已配置
2. ACP 协议正确设置
3. 明确知道需要外部工具的能力
—
## 4️⃣ 配置要求
### Subagent 配置
**必需配置：**
“`json
{
“agents”: {
“list”: [
{
“name”: “xiaobi”,
“subagents”: {
“allowAgents”: [“*”] // ⭐ 关键配置！
}
}
]
}
}
“`
**配置说明：**
– `allowAgents: [“*”]` – 允许创建任意 subagent
– 也可以指定具体允许的 agent 列表：`[“xiaobi”, “caier”, …]`
– 此配置缺失会导致 `sessions_spawn` 失败
### ACP 配置
**必需配置：**
“`json
{
“agents”: {
“list”: [
{
“name”: “xiaobi”,
“acp”: {
“enabled”: true,
“harnesses”: [“pi”, “claude-code”, “codex”]
}
}
]
}
}
“`
**额外要求：**
– ACP harness 服务需运行
– 网络连通性正常
– 认证凭据配置正确
—
## 5️⃣ 常见错误和解决方法
### ❌ 错误 1: sessions_spawn 失败，提示权限不足
**错误信息：**
“`
Error: sessions_spawn failed: subagents not allowed
“`
**原因：** 缺少 `allowAgents` 配置
**解决方法：**
“`json
// 在 agents.list[].subagents 中添加
“allowAgents”: [“*”]
“`
—
### ❌ 错误 2: 混淆 runtime=”acp” 和 runtime=”subagent”
**错误信息：**
“`
Error: Unknown runtime “subagent” for sessions_spawn
“`
**原因：** `sessions_spawn` 专用于 ACP，subagent 应使用 `subagents.spawn`
**解决方法：**
“`javascript
// ❌ 错误
await sessions_spawn({
runtime: “subagent”, // sessions_spawn 不支持此 runtime
message: “…”
});
// ✅ 正确 – 使用 subagent
await subagents.spawn({
label: “任务助手”,
message: “…”
});
// ✅ 正确 – 使用 ACP
await sessions_spawn({
runtime: “acp”,
harness: “pi”,
message: “…”
});
“`
—
### ❌ 错误 3: ACP harness 未找到
**错误信息：**
“`
Error: Harness “pi” not found or not configured
“`
**原因：** ACP harness 未正确配置或服务未运行
**解决方法：**
1. 检查 harness 配置是否存在
2. 确认 harness 服务正在运行
3. 验证网络连接和认证
—
### ❌ 错误 4: Subagent 创建后无响应
**原因：** 可能在轮询状态，但 subagent 使用 push-based 完成通知
**解决方法：**
“`javascript
// ❌ 错误 – 不要轮询
while (true) {
const status = await subagents.list();
// …
}
// ✅ 正确 – 等待自动通知
await subagents.spawn({
label: “任务”,
message: “请完成…”
});
// subagent 完成后会自动汇报结果
“`
—
## 6️⃣ 今天的实际案例 (2026-03-10)
### 📖 问题背景
在主会话中尝试创建一个 subagent 来处理文档任务，但 `sessions_spawn` 调用失败。
### 🔍 问题诊断
**初始尝试：**
“`javascript
await sessions_spawn({
runtime: “subagent”, // ❌ 错误用法
label: “小笔 – 文档化 ACP vs Subagent 经验”,
message: “请创建文档…”
});
“`
**错误现象：** 调用失败，提示配置问题
**根本原因：**
1. 混淆了 `sessions_spawn` 和 `subagents.spawn` 的用途
2. `sessions_spawn` 专用于 ACP runtime
3. Subagent 应该使用 `subagents` 工具
4. 缺少 `allowAgents` 配置
### ✅ 解决方案
**步骤 1: 添加配置**
“`json
{
“agents”: {
“list”: [
{
“name”: “xiaobi”,
“subagents”: {
“allowAgents”: [“*”] // ⭐ 添加此配置
}
}
]
}
}
“`
**步骤 2: 使用正确的工具**
“`javascript
// ✅ 正确方式
await subagents.spawn({
label: “小笔 – 文档专家”,
message: “请创建文档：acp-vs-subagent-guide.md”
});
“`
**步骤 3: 验证成功**
– Subagent 成功创建
– 任务正常执行
– 结果自动汇报到主会话
### 📝 经验教训
| 教训 | 说明 |
|——|——|
| 🎯 **明确工具用途** | `sessions_spawn` = ACP, `subagents.spawn` = Subagent |
| ⚙️ **检查配置** | 确保 `allowAgents` 已配置 |
| 📌 **默认使用 Subagent** | 除非明确需要外部 harness |
| 🔔 **信任 Push-based** | 不要轮询 subagent 状态 |
—
## 🧭 决策流程图
“`
需要创建新 Agent？
│
▼
是否需要外部 coding harness？
(Pi, Claude Code, Codex 等)
│
├── 是 ──→ 使用 sessions_spawn({ runtime: “acp”, harness: “…” })
│
└── 否 ──→ 使用 subagents.spawn({ label: “…”, message: “…” })
│
▼
检查 allowAgents 配置
│
▼
完成！等待自动汇报
“`
—
## 📚 相关文档
– [OpenClaw Subagent 文档](../README.md)
– [ACP Router Skill]（OpenClaw ACP路由技能文档）
– [AGENTS.md – 工作区规范]（Agent工作区配置文档）
—
_此文档由小笔 ✍️ 创建，用于记录 ACP vs Subagent 的使用经验。_
