OpenClaw Agent 层级与协作完全指南

📚 目录

- Agent 层级结构

- 子 Agent vs 同级 Agent

- 层级间交互

- 协作模式

- 实战演示

- 最佳实践

🏗️ Agent 层级结构

核心概念

OpenClaw 的 Agent 系统是一个树状层级结构：

┌─────────────┐ │用户│ ││ └──────┬──────┘ │ ┌──────▼──────┐ │MainAgent │ ← 根节点（深度 0） ││ └──────┬──────┘ │ sessions_spawn() ┌─────────────────┼─────────────────┐ │││ ┌─────▼─────┐┌──────▼──────┐┌──────▼──────┐ │ Subagent 1││ Subagent 2││ Subagent 3│ ← 深度 1 │ (子 Agent) ││(子 Agent) ││(子 Agent) │ └─────┬─────┘└──────┬──────┘└──────┬──────┘ │││ │ sessions_spawn()│ ┌─────▼─────┐│ │Subagent 1a││ │ (深度 2)││ └───────────┘│

层级深度限制

深度	名称	说明
0	Main Agent	根节点，直接和用户对话
1	Subagent (Level 1)	主 Agent 的子 Agent
2	Subagent (Level 2)	子 Agent 的子 Agent（深度限制）
3+	❌ 禁止	默认最大深度为 2

深度限制配置：

JavaScript // 子 Agent 上下文中标注 [Subagent Context] You are running as a subagent (depth 1/1)

🔄 子 Agent vs 同级 Agent

定义对比

维度	子 Agent	同级 Agent
创建方式	sessions_spawn() 由父 Agent 创建	独立创建，无父子关系
SessionKey	agent:main:subagent:uuid	agent:main:feishu:direct:xxx
上下文继承	继承父 Agent 的部分上下文	独立上下文
生命周期	父 Agent 可管理（查看/终止）	独立生命周期
通信方式	sessions_send() + 自动推送	sessions_send()
深度限制	受深度限制（默认 1-2 层）	无深度限制

SessionKey 格式解析

JavaScript // 子 Agent 的 SessionKey "agent:main:subagent:acd9d5fb-3704-4c3f-97bf-b1abcebbde3d" │││ ││└─ 唯一 UUID │└────────── 标记为 subagent └─────────────── 父 Agent 是 main // 主 Agent 的 SessionKey "agent:main:feishu:direct:ou_5bf6420a9b4ce050f1a87513a7c5783b" ││││ │││└─ 用户 ID ││└────────── 直聊（非群组） │└─────────────── 通道类型 └──────────────────── 根 Agent

实际例子

场景：开发一个网站

子 Agent 方式（推荐）：

用户 └─ Main Agent ├─ 前端 Agent (子 Agent，深度 1) │└─ CSS 优化 Agent (子 Agent，深度 2) ├─ 后端 Agent (子 Agent，深度 1) └─ 测试 Agent (子 Agent，深度 1)

同级 Agent 方式（不推荐）：

用户 ├─ Agent A ├─ 前端 Agent (Agent B，独立) ├─ 后端 Agent (Agent C，独立) └─ 测试 Agent (Agent D，独立)

问题：同级 Agent 之间无法直接通信，需要用户手动协调！

💬 层级间交互

1. 主 Agent → 子 Agent

创建子 Agent

JavaScript const child = await sessions_spawn({ task: "完成这个任务", runtime: "subagent" | "acp", mode: "run" | "session", label: "agent-名称" })

发送指令

JavaScript await sessions_send({ sessionKey: child.sessionKey, message: "请修改这个函数的逻辑" })

等待完成

JavaScript await sessions_yield() // 自动收到完成事件

查看状态

JavaScript const agents = await subagents({ action: "list" }) // 返回：[{sessionKey, label, status, runtime}, ...]

终止子 Agent

JavaScript await subagents({ action: "kill", target: "agent:main:subagent:uuid" })

2. 子 Agent → 主 Agent

自动推送：子 Agent 完成后自动通知主 Agent

JavaScript // 子 Agent 完成任务后 // 主 Agent 自动收到事件： { source: "subagent", session_key: "agent:main:subagent:uuid", type: "subagent task", status: "completed successfully", result: "任务结果..." }

3. 子 Agent → 子 Agent（兄弟之间）

❌ 不能直接通信！需要通过主 Agent 中转：

前端 Agent ──→ 小川 (Main) ──→ 后端 Agent ││ └──── 不能直接发送 ──────────┘

正确方式：

JavaScript // 前端 Agent 完成工作 // 1. 自动推送给小川 // 2. 小川转发给后端 Agent await sessions_send({ sessionKey: "agent:main:subagent:backend-uuid", message: `前端已完成，API 接口如下：${frontendResult}` })

4. 同级 Agent 之间

❌ 无法直接通信！同级 Agent 是独立的，没有父子关系。

解决方案：

1升级为父子关系（推荐）

1通过共享文件系统

1通过外部服务（数据库、消息队列）

🤝 协作模式

模式 1：主从架构（推荐）

Main Agent / 协调者 │ ┌────┼────┐ ▼▼▼ 前端后端测试 (执行者)

适用场景：复杂项目需要协调

代码示例：

JavaScript // 1. Main Agent分析需求，拆解任务 const tasks = analyzeRequirement(userRequest) // 2. 创建子 Agents const frontend = await sessions_spawn({ task: tasks.frontend, label: "frontend-dev" }) const backend = await sessions_spawn({ task: tasks.backend, label: "backend-dev" }) const tester = await sessions_spawn({ task: tasks.test, label: "qa-tester" }) // 3. 等待所有完成 await sessions_yield() // 4. 汇总结果 const result = { frontend: frontend.result, backend: backend.result, test: tester.result } // 5. 交付给用户 deliver(result)

模式 2：流水线架构

需求 → Agent A → Agent B → Agent C → 结果 (分析)(开发)(测试)

适用场景：任务有先后依赖

代码示例：

JavaScript // 1. 需求分析 const analyst = await sessions_spawn({ task: "分析需求，输出功能列表", label: "analyst" }) await sessions_yield() const requirements = analyst.result // 2. 基于分析结果开发 const developer = await sessions_spawn({ task: `根据需求开发：${requirements}`, label: "developer" }) await sessions_yield() const code = developer.result // 3. 测试 const tester = await sessions_spawn({ task: `测试这些代码：${code}`, label: "tester" }) await sessions_yield()

模式 3：并行协作

任务 │ ┌─────┼─────┐ ▼▼▼ ABC(并行执行) │││ └─────┼─────┘ ▼ 汇总结果

适用场景：任务独立，可并行

代码示例：

JavaScript // 并行创建多个子 Agent const agents = await Promise.all([ sessions_spawn({ task: "模块 A", label: "dev-a" }), sessions_spawn({ task: "模块 B", label: "dev-b" }), sessions_spawn({ task: "模块 C", label: "dev-c" }) ]) // 等待所有完成 await sessions_yield() // 汇总 const results = agents.map(a => a.result)

模式 4：递归分解（深度受限）

Main Agent (深度 0) └─ 前端 Agent (深度 1) ├─ HTML Agent (深度 2) ✅ ├─ CSS Agent (深度 2) ✅ └─ JS Agent (深度 2) ✅ └─ 工具函数 Agent (深度 3) ❌ 超出限制

适用场景：大型项目需要多层分解

注意：默认深度限制为 2，需要修改配置才能更深。

🎬 实战演示

场景：开发一个电商网站

步骤 1：主 Agent 分析需求

JavaScript // Main Agent接收用户需求 const userRequest = "开发一个电商网站，包含商品展示、购物车、支付功能" // 分析并拆解任务 const projectPlan = { frontend: { pages: ["首页", "商品列表", "商品详情", "购物车", "结算页"], features: ["响应式设计", "图片懒加载", "搜索功能"] }, backend: { apis: ["商品 API", "订单 API", "支付 API", "用户 API"], database: ["商品表", "订单表", "用户表"] }, test: { unit: "单元测试", integration: "集成测试", e2e: "端到端测试" } }

步骤 2：创建第一层子 Agent

JavaScript // 前端负责人 const frontendLead = await sessions_spawn({ task: `负责前端开发：${JSON.stringify(projectPlan.frontend)}`, runtime: "acp", agentId: "claude-code", label: "frontend-lead", mode: "session"// 持久化会话 }) // 后端负责人 const backendLead = await sessions_spawn({ task: `负责后端开发：${JSON.stringify(projectPlan.backend)}`, runtime: "acp", agentId: "claude-code", label: "backend-lead", mode: "session" }) // 测试负责人 const testLead = await sessions_spawn({ task: `负责测试：${JSON.stringify(projectPlan.test)}`, runtime: "subagent", label: "test-lead", mode: "session" })

步骤 3：子 Agent 创建自己的子 Agent（深度 2）

JavaScript // 前端负责人创建子团队（在 frontendLead 会话中） const htmlDev = await sessions_spawn({ task: "开发 HTML 页面结构", label: "html-dev" }) const cssDev = await sessions_spawn({ task: "开发 CSS 样式", label: "css-dev" }) const jsDev = await sessions_spawn({ task: "开发 JavaScript 交互", label: "js-dev" }) await sessions_yield()

步骤 4：跨团队协作（通过主 Agent 中转）

JavaScript // 后端完成 API 设计 const apiSpec = backendLead.result.apiDesign // 小川转发给前端 await sessions_send({ sessionKey: frontendLead.sessionKey, message: `后端 API 设计已完成，请基于此开发前端：${apiSpec}` }) // 前端完成后通知测试 await sessions_send({ sessionKey: testLead.sessionKey, message: `前端和后端已完成，请开始测试` })

步骤 5：汇总交付

JavaScript // 等待所有团队完成 await Promise.all([ waitForCompletion(frontendLead), waitForCompletion(backendLead), waitForCompletion(testLead) ]) // 汇总结果 const finalResult = { frontend: frontendLead.result, backend: backendLead.result, testReport: testLead.result, deployGuide: generateDeployGuide() } // 交付给用户 deliver(finalResult)

📊 通信方式对比

通信方向	方式	API	说明
主 → 子	直接发送	sessions_send()	随时发送指令
主 → 子	创建时指定	sessions_spawn(task)	初始任务
子 → 主	自动推送	系统自动	完成时自动通知
子 → 子	❌ 不支持	-	需通过主 Agent 中转
同级 → 同级	❌ 不支持	-	需升级为父子关系

⚠️ 常见陷阱

1. 试图让子 Agent 直接通信

JavaScript // ❌ 错误：子 Agent 之间无法直接发送 await sessions_send({ from: "agent:main:subagent:frontend", to: "agent:main:subagent:backend",// 无效！ message: "API 已完成" }) // ✅ 正确：通过主 Agent 中转 // 1. 前端完成，自动推送给小川 // 2. 小川转发给后端 await sessions_send({ sessionKey: "agent:main:subagent:backend", message: "前端已完成，API 接口如下：..." })

2. 创建同级 Agent 而非子 Agent

JavaScript // ❌ 错误：创建独立 Agent（无法管理） const agent1 = sessions_spawn({...})// 独立 const agent2 = sessions_spawn({...})// 独立 // ✅ 正确：创建子 Agent（可管理） const child1 = await sessions_spawn({...})// 子 Agent const child2 = await sessions_spawn({...})// 子 Agent // 主 Agent 可以查看状态、发送指令、终止

3. 忽略深度限制

JavaScript // ❌ 可能失败：超过深度限制 Main (depth 0) └─ Agent A (depth 1) └─ Agent B (depth 2) └─ Agent C (depth 3) ❌ // ✅ 正确：控制深度 Main (depth 0) └─ Agent A (depth 1) ├─ Agent B (depth 2) ✅ └─ Agent C (depth 2) ✅

4. 忘记等待完成

JavaScript // ❌ 错误：创建后不等待 await sessions_spawn({task: "任务"}) // 立即继续，子 Agent 可能还没完成！ // ✅ 正确 await sessions_spawn({task: "任务"}) await sessions_yield()// 等待完成

🔧 高级技巧

1. 动态创建子 Agent

JavaScript // 根据任务复杂度动态决定创建多少子 Agent function createTeam(taskComplexity) { if (taskComplexity === "low") { return [sessions_spawn({task: "简单任务"})] } else if (taskComplexity === "medium") { return [ sessions_spawn({task: "模块 A"}), sessions_spawn({task: "模块 B"}) ] } else { return [ sessions_spawn({task: "前端"}), sessions_spawn({task: "后端"}), sessions_spawn({task: "测试"}), sessions_spawn({task: "文档"}) ] } }

2. 任务链（Chain of Agents）

JavaScript async function processWithChain(input) { // Agent 1: 分析 const analyst = await sessions_spawn({ task: `分析：${input}`, label: "analyst" }) await sessions_yield() // Agent 2: 基于分析结果处理 const processor = await sessions_spawn({ task: `处理：${analyst.result}`, label: "processor" }) await sessions_yield() // Agent 3: 审校 const reviewer = await sessions_spawn({ task: `审校：${processor.result}`, label: "reviewer" }) await sessions_yield() return reviewer.result }

3. 监控和日志

JavaScript // 记录所有子 Agent 的状态 const agentLog = [] async function spawnWithLogging(config) { const agent = await sessions_spawn(config) agentLog.push({ label: config.label, sessionKey: agent.sessionKey, createdAt: new Date(), status: "running" }) return agent } // 定期查看状态 async function monitorAgents() { const agents = await subagents({action: "list"}) agents.forEach(agent => { console.log(`${agent.label}: ${agent.status} (${agent.runtime})`) }) }

4. 错误处理和重试

JavaScript async function spawnWithRetry(task, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { const agent = await sessions_spawn({task, label: `retry-${i}`}) await sessions_yield() if (agent.status === "error") { throw new Error("Agent execution failed") } return agent.result } catch (error) { if (i === maxRetries - 1) throw error console.log(`Retry ${i + 1}/${maxRetries}`) } } }

📝 总结

核心要点

- 层级结构：树状结构，Main Agent 是根，子 Agent 是分支

- 子 Agent：由父 Agent 创建，可管理，自动推送完成

- 同级 Agent：独立创建，无法直接通信，不推荐

- 通信规则：

- 主 → 子：直接发送

- 子 → 主：自动推送

- 子 ↔ 子：通过主 Agent 中转

- 同级 ↔ 同级：❌ 不支持

- 深度限制：默认最大深度 2 层

最佳实践

✅ 使用子 Agent 而非同级 Agent

✅ 明确任务描述，减少沟通成本

✅ 合理控制深度，避免超出限制

✅ 使用 sessions_yield() 等待完成

✅ 通过主 Agent 协调跨团队协作

选择建议

场景	推荐方式
简单任务	主 Agent 直接完成
中等任务	创建 1-2 个子 Agent
复杂项目	多层子 Agent + 主 Agent 协调
长期项目	mode: "session" 持久化会话
一次性任务	mode: "run" 自动清理