文章目录
- 每个代理拥有完全独立的运行环境： 独立工作空间：每个代理有自己的文件系统和配置文件（AGENTS.md、SOUL.md 等） 独立状态目录：认证信息、模型注册、会话存储都相互隔离 独立会话存储：会话历史存储在各自的目录下 An **agent** is a fully scoped brain with its own: – **Workspace** (files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules). – **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config. – **Session store** (chat history + routing state) under `~/.openclaw/agents/<agentId>/sessions` . Auth profiles are **per-agent** . Each agent reads from its own: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json Main agent credentials are **not** shared automatically. Never reuse `agentDir` across agents (it causes auth/session collisions). If you want to share creds, copy `auth-profiles.json` into the other agent’s `agentDir` . Skills are per-agent via each workspace’s `skills/` folder, with shared skills available from `~/.openclaw/skills`. See [Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills) .
- OpenClaw 提供三种主要的协同模式： A. 代理间直接消息传递（sessions_send） 用于代理之间的点对点通信 支持等待回复模式和即发即忘模式 包含自动的 ping-pong 回复循环和宣告机制 ## sessions_send Send a message into another session. Parameters: – `sessionKey` (required; accepts session key or `sessionId` from `sessions_list`) – `message` (required) – `timeoutSeconds?: number` (default >0; 0 = fire-and-forget) Behavior: – `timeoutSeconds = 0`: enqueue and return `{ runId, status: “accepted” }`. – `timeoutSeconds > 0`: wait up to N seconds for completion, then return `{ runId, status: “ok”, reply }`. – If wait times out: `{ runId, status: “timeout”, error }`. Run continues; call `sessions_history` later. – If the run fails: `{ runId, status: “error”, error }`. – Announce delivery runs after the primary run completes and is best-effort; `status: “ok”` does not guarantee the announce was delivered. – Waits via gateway `agent.wait` (server-side) so reconnects don’t drop the wait. – Agent-to-agent message context is injected for the primary run. – After the primary run completes, OpenClaw runs a **reply-back loop**: – Round 2+ alternates between requester and target agents. – Reply exactly `REPLY_SKIP` to stop the ping‑pong. – Max turns is `session.agentToAgent.maxPingPongTurns` (0–5, default 5). – Once the loop ends, OpenClaw runs the **agent‑to‑agent announce step** (target agent only): – Reply exactly `ANNOUNCE_SKIP` to stay silent. – Any other reply is sent to the target channel. – Announce step includes the original request + round‑1 reply + latest ping‑pong reply. B. 子代理委派（sessions_spawn） 父代理可以生成子代理处理特定任务 子代理在独立会话中运行，完成后自动回报结果 支持跨代理委派（需配置白名单） title: “Sub-Agents” — # Sub-agents Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`agent:<agentId>:subagent:<uuid>`) and, when finished, **announce** their result back to the requester chat channel. ## Slash command Use `/subagents` to inspect or control sub-agent runs for the **current session**: – `/subagents list` – `/subagents stop <id|#|all>` – `/subagents log <id|#> [limit] [tools]` – `/subagents info <id|#>` – `/subagents send <id|#> <message>` `/subagents info` shows run metadata (status, timestamps, session id, transcript path, cleanup). Primary goals: – Parallelize “research / long task / slow tool” work without blocking the main run. – Keep sub-agents isolated by default (session separation + optional sandboxing). – Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default. – Avoid nested fan-out: sub-agents cannot spawn sub-agents. Cost note: each sub-agent has its **own** context and token usage. For heavy or repetitive tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model. You can configure this via `agents.defaults.subagents.model` or per-agent overrides. C. 广播组（Broadcast Groups） 多个代理同时处理同一消息 支持并行或顺序处理策略 适用于专业团队协作场景 Broadcast Groups enable multiple agents to process and respond to the same message simultaneously. This allows you to create specialized agent teams that work together in a single WhatsApp group or DM — all using one phone number. Current scope: **WhatsApp only** (web channel). Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when OpenClaw would normally reply (for example: on mention, depending on your group settings). ## Use Cases ### 1. Specialized Agent Teams Deploy multiple agents with atomic, focused responsibilities: Group: “Development Team” Agents: – CodeReviewer (reviews code snippets) – DocumentationBot (generates docs) – SecurityAuditor (checks for vulnerabilities) – TestGenerator (suggests test cases)
- 在 ~/.openclaw/openclaw.json 中配置多个代理： { agents: { list: [ { id: “commander”, name: “总指挥”, workspace: “~/.openclaw/workspace-commander”, agentDir: “~/.openclaw/agents/commander/agent”, model: “anthropic/claude-opus-4-6” }, { id: “project-manager”, name: “项目经理”, workspace: “~/.openclaw/workspace-pm”, agentDir: “~/.openclaw/agents/project-manager/agent”, model: “anthropic/claude-sonnet-4-5” }, { id: “developer”, name: “开发工程师”, workspace: “~/.openclaw/workspace-dev”, agentDir: “~/.openclaw/agents/developer/agent” }, { id: “tester”, name: “测试工程师”, workspace: “~/.openclaw/workspace-test”, agentDir: “~/.openclaw/agents/tester/agent” } ] } }
- 必须显式启用并配置白名单： { tools: { agentToAgent: { enabled: true, allow: [“commander”, “project-manager”, “developer”, “tester”] } } }
- 允许代理生成和委派子代理： { agents: { list: [ { id: “commander”, subagents: { allowAgents: [“project-manager”] // 总指挥可以委派给项目经理 } }, { id: “project-manager”, subagents: { allowAgents: [“developer”, “tester”] // 项目经理可以委派给开发和测试 } } ] } }
- 为不同代理配置不同的安全级别： { agents: { list: [ { id: “commander”, sandbox: { mode: “off” // 总指挥无沙箱限制 } }, { id: “project-manager”, sandbox: { mode: “all”, scope: “agent” }, tools: { allow: [“read”, “write”, “exec”, “sessions_send”, “sessions_spawn”] } }, { id: “developer”, sandbox: { mode: “all”, scope: “agent”, sessionToolsVisibility: “spawned” // 只能看到自己生成的会话 }, tools: { allow: [“read”, “write”, “exec”] } } ] } }
- 总指挥代理收到需求后，进行分析并生成任务清单： 在自己的工作空间创建项目规划文档 定义各子任务和交付标准 使用 sessions_spawn 委派任务给项目经理代理 工具调用示例： { “tool”: “sessions_spawn”, “task”: “根据以下需求制定详细的项目执行方案：[需求描述]。要求包含：1) 任务分解 2) 资源分配 3) 时间表 4) 质量标准”, “label”: “项目规划会话”, “agentId”: “project-manager”, “cleanup”: “keep” }
- 项目经理代理在独立会话中工作： 接收总指挥的任务描述 进一步拆解为具体的执行单元 使用 sessions_spawn 为每个团队成员创建子任务 连续委派示例： // 委派给开发工程师 { “tool”: “sessions_spawn”, “task”: “实现功能模块 X，要求：[具体技术规格]”, “label”: “开发任务-模块X”, “agentId”: “developer” } // 委派给测试工程师 { “tool”: “sessions_spawn”, “task”: “为模块 X 编写测试用例，覆盖率要求 >80%”, “label”: “测试任务-模块X”, “agentId”: “tester” }
- 开发和测试代理在各自隔离的会话中独立工作： 会话隔离：每个代理使用 agent:<agentId>:subagent:<uuid> 格式的会话键 独立上下文：不会看到其他代理的消息历史 独立工作空间：文件操作在各自的沙箱中进行 11
- 每个子代理完成任务后自动执行宣告步骤： 系统运行宣告步骤（announce step） 子代理总结工作成果 结果自动发送回父代理的聊天频道 包含统计信息：运行时间、token 使用、会话信息等 ## Tool Use `sessions_spawn`: – Starts a sub-agent run (`deliver: false`, global lane: `subagent`) – Then runs an announce step and posts the announce reply to the requester chat channel – Default model: inherits the caller unless you set `agents.defaults.subagents.model` (or per-agent `agents.list[].subagents.model`); an explicit `sessions_spawn.model` still wins. – Default thinking: inherits the caller unless you set `agents.defaults.subagents.thinking` (or per-agent `agents.list[].subagents.thinking`); an explicit `sessions_spawn.thinking` still wins. Tool params: – `task` (required) – `label?` (optional) – `agentId?` (optional; spawn under another agent id if allowed) – `model?` (optional; overrides the sub-agent model; invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result) – `thinking?` (optional; overrides thinking level for the sub-agent run) – `runTimeoutSeconds?` (default `0`; when set, the sub-agent run is aborted after N seconds) – `cleanup?` (`delete|keep`, default `keep`) Allowlist: – `agents.list[].subagents.allowAgents`: list of agent ids that can be targeted via `agentId` (`[“*”]` to allow any). Default: only the requester agent. Discovery: – Use `agents_list` to see which agent ids are currently allowed for `sessions_spawn`. Auto-archive: – Sub-agent sessions are automatically archived after `agents.defaults.subagents.archiveAfterMinutes` (default: 60). – Archive uses `sessions.delete` and renames the transcript to `*.deleted.<timestamp>` (same folder). – `cleanup: “delete”` archives immediately after announce (still keeps the transcript via rename). – Auto-archive is best-effort; pending timers are lost if the gateway restarts. – `runTimeoutSeconds` does **not** auto-archive; it only stops the run. The session remains until auto-archive.
- 项目经理代理收到所有团队成员的回报后： 使用 sessions_history 查看各子任务的详细历史（如需要） 整合所有交付成果 进行质量检查和验证 在自己的宣告步骤中将整合结果回报给总指挥 查看子任务历史示例： { “tool”: “sessions_history”, “sessionKey”: “agent:developer:subagent:abc-123”, “limit”: 50, “includeTools”: true }
- 总指挥代理接收项目经理的整合报告后： 审查所有交付成果 进行最终质量把关 如需补充工作，可再次使用 sessions_send 发送反馈 生成最终完整的项目交付 使用 sessions_send 进行双向沟通： { “tool”: “sessions_send”, “sessionKey”: “agent:project-manager:subagent:xyz-789”, “message”: “开发模块 X 需要补充单元测试，请协调处理”, “timeoutSeconds”: 300 }
- 当需要代理间多轮对话时，sessions_send 自动支持 ping-pong 循环： 最多 5 轮交互（可配置） 任一方回复 REPLY_SKIP 即可终止循环 适用于需要澄清或迭代的场景
- 对于需要严格步骤控制和审批的场景，可以结合 Lobster 工具： 定义多步骤管道 内置审批检查点 可恢复的工作流状态 适合替代复杂的代理间协调 # Lobster Lobster is a workflow shell that lets OpenClaw run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints. ## Hook Your assistant can build the tools that manage itself. Ask for a workflow, and 30 minutes later you have a CLI plus pipelines that run as one call. Lobster is the missing piece: deterministic pipelines, explicit approvals, and resumable state. ## Why Today, complex workflows require many back-and-forth tool calls. Each call costs tokens, and the LLM has to orchestrate every step. Lobster moves that orchestration into a typed runtime: – **One call instead of many**: OpenClaw runs one Lobster tool call and gets a structured result. – **Approvals built in**: Side effects (send email, post comment) halt the workflow until explicitly approved. – **Resumable**: Halted workflows return a token; approve and resume without re-running everything.
- 如果需要多个代理同时评审同一任务： { broadcast: { strategy: “parallel”, “+15555550123”: [“developer”, “tester”, “security-auditor”] } } 所有代理会并行处理相同消息，各自提供专业视角。
目录
- 一、核心架构思路
- 1. 代理完全隔离
- 2. 协同通信机制
- 二、配置方法
- 1. 基础代理配置
- 2. 启用代理间通信
- 3. 配置子代理权限
- 4. 配置沙箱隔离（可选但推荐）
- 三、实现步骤
- 步骤 1：总指挥代理分析和规划
- 步骤 2：项目经理代理细化任务
- 步骤 3：团队成员并行工作
- 步骤 4：子代理自动回报结果
- 步骤 5：项目经理整合子项目
- 步骤 6：总指挥最终整合
- 四、工作流程图示
- 五、高级协同模式
- 1. Ping-Pong 交互模式
- 2. 使用 Lobster 实现确定性工作流
- 3. 广播组用于专业团队
- 六、最佳实践建议
- 1. 隔离性保障
- 2. 协同效率
- 3. 错误处理
- Notes
- Citations
- 总结
OpenClaw 采用 中央网关（Gateway）+ 多代理隔离 的架构模式来实现代理协同：
每个代理拥有完全独立的运行环境：
- 独立工作空间：每个代理有自己的文件系统和配置文件（AGENTS.md、SOUL.md 等）
- 独立状态目录：认证信息、模型注册、会话存储都相互隔离
- 独立会话存储：会话历史存储在各自的目录下
An **agent** is a fully scoped brain with its own: - **Workspace** (files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules). - **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config. - **Session store** (chat history + routing state) under `~/.openclaw/agents/<agentId>/sessions` . Auth profiles are **per-agent** . Each agent reads from its own: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json Main agent credentials are **not** shared automatically. Never reuse `agentDir` across agents (it causes auth/session collisions). If you want to share creds, copy `auth-profiles.json` into the other agent's `agentDir` . Skills are per-agent via each workspace’s `skills/` folder, with shared skills available from `~/.openclaw/skills`. See [Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills) .
OpenClaw 提供三种主要的协同模式：
A. 代理间直接消息传递（sessions_send）
- 用于代理之间的点对点通信
- 支持等待回复模式和即发即忘模式
- 包含自动的 ping-pong 回复循环和宣告机制
## sessions_send
Send a message into another session.
Parameters:
- `sessionKey` (required; accepts session key or `sessionId` from `sessions_list`)
- `message` (required)
- `timeoutSeconds?: number` (default >0; 0 = fire-and-forget)
Behavior:
- `timeoutSeconds = 0`: enqueue and return `{ runId, status: "accepted" }`.
- `timeoutSeconds > 0`: wait up to N seconds for completion, then return `{ runId, status: "ok", reply }`.
- If wait times out: `{ runId, status: "timeout", error }`. Run continues; call `sessions_history` later.
- If the run fails: `{ runId, status: "error", error }`.
- Announce delivery runs after the primary run completes and is best-effort; `status: "ok"` does not guarantee the announce was delivered.
- Waits via gateway `agent.wait` (server-side) so reconnects don't drop the wait.
- Agent-to-agent message context is injected for the primary run.
- After the primary run completes, OpenClaw runs a **reply-back loop**:
- Round 2+ alternates between requester and target agents.
- Reply exactly `REPLY_SKIP` to stop the ping‑pong.
- Max turns is `session.agentToAgent.maxPingPongTurns` (0–5, default 5).
- Once the loop ends, OpenClaw runs the **agent‑to‑agent announce step** (target agent only):
- Reply exactly `ANNOUNCE_SKIP` to stay silent.
- Any other reply is sent to the target channel.
- Announce step includes the original request + round‑1 reply + latest ping‑pong reply.
B. 子代理委派（sessions_spawn）
- 父代理可以生成子代理处理特定任务
- 子代理在独立会话中运行，完成后自动回报结果
- 支持跨代理委派（需配置白名单）
title: "Sub-Agents" --- # Sub-agents Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`agent:<agentId>:subagent:<uuid>`) and, when finished, **announce** their result back to the requester chat channel. ## Slash command Use `/subagents` to inspect or control sub-agent runs for the **current session**: - `/subagents list` - `/subagents stop <id|#|all>` - `/subagents log <id|#> [limit] [tools]` - `/subagents info <id|#>` - `/subagents send <id|#> <message>` `/subagents info` shows run metadata (status, timestamps, session id, transcript path, cleanup). Primary goals: - Parallelize “research / long task / slow tool” work without blocking the main run. - Keep sub-agents isolated by default (session separation + optional sandboxing). - Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default. - Avoid nested fan-out: sub-agents cannot spawn sub-agents. Cost note: each sub-agent has its **own** context and token usage. For heavy or repetitive tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model. You can configure this via `agents.defaults.subagents.model` or per-agent overrides.
C. 广播组（Broadcast Groups）
- 多个代理同时处理同一消息
- 支持并行或顺序处理策略
- 适用于专业团队协作场景
Broadcast Groups enable multiple agents to process and respond to the same message simultaneously. This allows you to create specialized agent teams that work together in a single WhatsApp group or DM — all using one phone number. Current scope: **WhatsApp only** (web channel). Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when OpenClaw would normally reply (for example: on mention, depending on your group settings). ## Use Cases ### 1. Specialized Agent Teams Deploy multiple agents with atomic, focused responsibilities: Group: "Development Team" Agents: - CodeReviewer (reviews code snippets) - DocumentationBot (generates docs) - SecurityAuditor (checks for vulnerabilities) - TestGenerator (suggests test cases)
在 ~/.openclaw/openclaw.json 中配置多个代理：
{
agents: {
list: [
{
id: "commander",
name: "总指挥",
workspace: "~/.openclaw/workspace-commander",
agentDir: "~/.openclaw/agents/commander/agent",
model: "anthropic/claude-opus-4-6"
},
{
id: "project-manager",
name: "项目经理",
workspace: "~/.openclaw/workspace-pm",
agentDir: "~/.openclaw/agents/project-manager/agent",
model: "anthropic/claude-sonnet-4-5"
},
{
id: "developer",
name: "开发工程师",
workspace: "~/.openclaw/workspace-dev",
agentDir: "~/.openclaw/agents/developer/agent"
},
{
id: "tester",
name: "测试工程师",
workspace: "~/.openclaw/workspace-test",
agentDir: "~/.openclaw/agents/tester/agent"
}
]
}
}
必须显式启用并配置白名单：
{
tools: {
agentToAgent: {
enabled: true,
allow: ["commander", "project-manager", "developer", "tester"]
}
}
}
允许代理生成和委派子代理：
{
agents: {
list: [
{
id: "commander",
subagents: {
allowAgents: ["project-manager"] // 总指挥可以委派给项目经理
}
},
{
id: "project-manager",
subagents: {
allowAgents: ["developer", "tester"] // 项目经理可以委派给开发和测试
}
}
]
}
}
为不同代理配置不同的安全级别：
{
agents: {
list: [
{
id: "commander",
sandbox: {
mode: "off" // 总指挥无沙箱限制
}
},
{
id: "project-manager",
sandbox: {
mode: "all",
scope: "agent"
},
tools: {
allow: ["read", "write", "exec", "sessions_send", "sessions_spawn"]
}
},
{
id: "developer",
sandbox: {
mode: "all",
scope: "agent",
sessionToolsVisibility: "spawned" // 只能看到自己生成的会话
},
tools: {
allow: ["read", "write", "exec"]
}
}
]
}
}
总指挥代理收到需求后，进行分析并生成任务清单：
- 在自己的工作空间创建项目规划文档
- 定义各子任务和交付标准
- 使用
sessions_spawn委派任务给项目经理代理
工具调用示例：
{
"tool": "sessions_spawn",
"task": "根据以下需求制定详细的项目执行方案：[需求描述]。要求包含：1) 任务分解 2) 资源分配 3) 时间表 4) 质量标准",
"label": "项目规划会话",
"agentId": "project-manager",
"cleanup": "keep"
}
项目经理代理在独立会话中工作：
- 接收总指挥的任务描述
- 进一步拆解为具体的执行单元
- 使用
sessions_spawn为每个团队成员创建子任务
连续委派示例：
// 委派给开发工程师
{
"tool": "sessions_spawn",
"task": "实现功能模块 X，要求：[具体技术规格]",
"label": "开发任务-模块X",
"agentId": "developer"
}
// 委派给测试工程师
{
"tool": "sessions_spawn",
"task": "为模块 X 编写测试用例，覆盖率要求 >80%",
"label": "测试任务-模块X",
"agentId": "tester"
}
开发和测试代理在各自隔离的会话中独立工作：
- 会话隔离：每个代理使用
agent:<agentId>:subagent:<uuid>格式的会话键 - 独立上下文：不会看到其他代理的消息历史
- 独立工作空间：文件操作在各自的沙箱中进行 11
每个子代理完成任务后自动执行宣告步骤：
- 系统运行宣告步骤（announce step）
- 子代理总结工作成果
- 结果自动发送回父代理的聊天频道
- 包含统计信息：运行时间、token 使用、会话信息等
## Tool Use `sessions_spawn`: - Starts a sub-agent run (`deliver: false`, global lane: `subagent`) - Then runs an announce step and posts the announce reply to the requester chat channel - Default model: inherits the caller unless you set `agents.defaults.subagents.model` (or per-agent `agents.list[].subagents.model`); an explicit `sessions_spawn.model` still wins. - Default thinking: inherits the caller unless you set `agents.defaults.subagents.thinking` (or per-agent `agents.list[].subagents.thinking`); an explicit `sessions_spawn.thinking` still wins. Tool params: - `task` (required) - `label?` (optional) - `agentId?` (optional; spawn under another agent id if allowed) - `model?` (optional; overrides the sub-agent model; invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result) - `thinking?` (optional; overrides thinking level for the sub-agent run) - `runTimeoutSeconds?` (default `0`; when set, the sub-agent run is aborted after N seconds) - `cleanup?` (`delete|keep`, default `keep`) Allowlist: - `agents.list[].subagents.allowAgents`: list of agent ids that can be targeted via `agentId` (`["*"]` to allow any). Default: only the requester agent. Discovery: - Use `agents_list` to see which agent ids are currently allowed for `sessions_spawn`. Auto-archive: - Sub-agent sessions are automatically archived after `agents.defaults.subagents.archiveAfterMinutes` (default: 60). - Archive uses `sessions.delete` and renames the transcript to `*.deleted.<timestamp>` (same folder). - `cleanup: "delete"` archives immediately after announce (still keeps the transcript via rename). - Auto-archive is best-effort; pending timers are lost if the gateway restarts. - `runTimeoutSeconds` does **not** auto-archive; it only stops the run. The session remains until auto-archive.
项目经理代理收到所有团队成员的回报后：
- 使用
sessions_history查看各子任务的详细历史（如需要） - 整合所有交付成果
- 进行质量检查和验证
- 在自己的宣告步骤中将整合结果回报给总指挥
查看子任务历史示例：
{
"tool": "sessions_history",
"sessionKey": "agent:developer:subagent:abc-123",
"limit": 50,
"includeTools": true
}
总指挥代理接收项目经理的整合报告后：
- 审查所有交付成果
- 进行最终质量把关
- 如需补充工作，可再次使用
sessions_send发送反馈 - 生成最终完整的项目交付
使用 sessions_send 进行双向沟通：
{
"tool": "sessions_send",
"sessionKey": "agent:project-manager:subagent:xyz-789",
"message": "开发模块 X 需要补充单元测试，请协调处理",
"timeoutSeconds": 300
}
当需要代理间多轮对话时，sessions_send 自动支持 ping-pong 循环：
- 最多 5 轮交互（可配置）
- 任一方回复
REPLY_SKIP即可终止循环 - 适用于需要澄清或迭代的场景
对于需要严格步骤控制和审批的场景，可以结合 Lobster 工具：
- 定义多步骤管道
- 内置审批检查点
- 可恢复的工作流状态
- 适合替代复杂的代理间协调
# Lobster Lobster is a workflow shell that lets OpenClaw run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints. ## Hook Your assistant can build the tools that manage itself. Ask for a workflow, and 30 minutes later you have a CLI plus pipelines that run as one call. Lobster is the missing piece: deterministic pipelines, explicit approvals, and resumable state. ## Why Today, complex workflows require many back-and-forth tool calls. Each call costs tokens, and the LLM has to orchestrate every step. Lobster moves that orchestration into a typed runtime: - **One call instead of many**: OpenClaw runs one Lobster tool call and gets a structured result. - **Approvals built in**: Side effects (send email, post comment) halt the workflow until explicitly approved. - **Resumable**: Halted workflows return a token; approve and resume without re-running everything.
如果需要多个代理同时评审同一任务：
{
broadcast: {
strategy: "parallel",
"+15555550123": ["developer", "tester", "security-auditor"]
}
}
所有代理会并行处理相同消息，各自提供专业视角。
- ✅ 为每个代理配置独立的工作空间
- ✅ 使用沙箱限制敏感代理的工具访问
- ✅ 配置
sessionToolsVisibility: "spawned" 限制会话可见性
sessionToolsVisibility: "spawned" 限制会话可见性
- ✅ 总指挥和项目经理使用更强大的模型（如 Opus）
- ✅ 执行型代理可使用较快的模型（如 Sonnet）
- ✅ 设置合理的
runTimeoutSeconds 避免长时间挂起
runTimeoutSeconds 避免长时间挂起
- ✅ 检查子代理的
status 字段（success/error/timeout）
- ✅ 使用
sessions_history 查看失败任务的详细日志
- ✅ 配置自动归档清理完成的子代理会话
status 字段（success/error/timeout）sessions_history 查看失败任务的详细日志
关键配置要点：
-
必须显式启用跨代理通信：
tools.agentToAgent.enabled: true是前提条件，否则代理间消息会被拒绝 -
会话键格式：子代理使用
agent:<agentId>:subagent:<uuid>格式，确保完全隔离 -
认证信息隔离：每个代理的认证配置存储在各自的
~/.openclaw/agents/<agentId>/agent/auth-profiles.json -
工具策略是安全关键：通过
agents.list[].tools.allow/deny精确控制每个代理的能力边界 -
宣告机制是异步的：子代理完成后的回报是尽力而为（best-effort），网关重启可能导致宣告丢失
OpenClaw 的这种架构设计使得代理既能保持完全独立（各自的工作空间、会话、权限），又能通过结构化的工具调用实现无缝协同，非常适合您描述的层级化任务委派场景。
File: /concepts/multi-agent.md
An **agent** is a fully scoped brain with its own: - **Workspace** (files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules). - **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config. - **Session store** (chat history + routing state) under `~/.openclaw/agents/<agentId>/sessions`. Auth profiles are **per-agent**. Each agent reads from its own:
~/.openclaw/agents//agent/auth-profiles.json
Main agent credentials are **not** shared automatically. Never reuse `agentDir` across agents (it causes auth/session collisions). If you want to share creds, copy `auth-profiles.json` into the other agent's `agentDir`. Skills are per-agent via each workspace’s `skills/` folder, with shared skills available from `~/.openclaw/skills`. See [Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills).
File: concepts/multi-agent.md
`~/.openclaw/openclaw.json` (JSON5):
```js
{
agents: {
list: [
{
id: "home",
default: true,
name: "Home",
workspace: "~/.openclaw/workspace-home",
agentDir: "~/.openclaw/agents/home/agent",
},
{
id: "work",
name: "Work",
workspace: "~/.openclaw/workspace-work",
agentDir: "~/.openclaw/agents/work/agent",
},
],
},
// Deterministic routing: first match wins (most-specific first).
bindings: [
{ agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
{ agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
// Optional per-peer override (example: send a specific group to work agent).
{
agentId: "work",
match: {
channel: "whatsapp",
accountId: "personal",
peer: { kind: "group", id: "1203630...@g.us" },
},
},
],
// Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
tools: {
agentToAgent: {
enabled: false,
allow: ["home", "work"],
},
},
channels: {
whatsapp: {
accounts: {
personal: {
// Optional override. Default: ~/.openclaw/credentials/whatsapp/personal
// authDir: "~/.openclaw/credentials/whatsapp/personal",
},
biz: {
// Optional override. Default: ~/.openclaw/credentials/whatsapp/biz
// authDir: "~/.openclaw/credentials/whatsapp/biz",
},
},
},
},
}
File: concepts/multi-agent.md
Starting with v2026.1.6, each agent can have its own sandbox and tool restrictions:
```js
{
agents: {
list: [
{
id: "personal",
workspace: "~/.openclaw/workspace-personal",
sandbox: {
mode: "off", // No sandbox for personal agent
},
// No tool restrictions - all tools available
},
{
id: "family",
workspace: "~/.openclaw/workspace-family",
sandbox: {
mode: "all", // Always sandboxed
scope: "agent", // One container per agent
docker: {
// Optional one-time setup after container creation
setupCommand: "apt-get update && apt-get install -y git curl",
},
},
tools: {
allow: ["read"], // Only read tool
deny: ["exec", "write", "edit", "apply_patch"], // Deny others
},
},
],
},
}
Note: `setupCommand` lives under `sandbox.docker` and runs once on container creation.
Per-agent `sandbox.docker.*` overrides are ignored when the resolved scope is `"shared"`.
**Benefits:**
- **Security isolation**: Restrict tools for untrusted agents
- **Resource control**: Sandbox specific agents while keeping others on host
- **Flexible policies**: Different permissions per agent
Note: `tools.elevated` is **global** and sender-based; it is not configurable per agent.
If you need per-agent boundaries, use `agents.list[].tools` to deny `exec`.
For group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent.
See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for detailed examples.
File: concepts/session-tool.md
Fetch transcript for one session. Parameters: - `sessionKey` (required; accepts session key or `sessionId` from `sessions_list`) - `limit?: number` max messages (server clamps) - `includeTools?: boolean` (default false) Behavior: - `includeTools=false` filters `role: "toolResult"` messages. - Returns messages array in the raw transcript format. - When given a `sessionId`, OpenClaw resolves it to the corresponding session key (missing ids error).
File: concepts/session-tool.md
Send a message into another session.
Parameters:
- `sessionKey` (required; accepts session key or `sessionId` from `sessions_list`)
- `message` (required)
- `timeoutSeconds?: number` (default >0; 0 = fire-and-forget)
Behavior:
- `timeoutSeconds = 0`: enqueue and return `{ runId, status: "accepted" }`.
- `timeoutSeconds > 0`: wait up to N seconds for completion, then return `{ runId, status: "ok", reply }`.
- If wait times out: `{ runId, status: "timeout", error }`. Run continues; call `sessions_history` later.
- If the run fails: `{ runId, status: "error", error }`.
- Announce delivery runs after the primary run completes and is best-effort; `status: "ok"` does not guarantee the announce was delivered.
- Waits via gateway `agent.wait` (server-side) so reconnects don't drop the wait.
- Agent-to-agent message context is injected for the primary run.
- After the primary run completes, OpenClaw runs a **reply-back loop**:
- Round 2+ alternates between requester and target agents.
- Reply exactly `REPLY_SKIP` to stop the ping‑pong.
- Max turns is `session.agentToAgent.maxPingPongTurns` (0–5, default 5).
- Once the loop ends, OpenClaw runs the **agent‑to‑agent announce step** (target agent only):
- Reply exactly `ANNOUNCE_SKIP` to stay silent.
- Any other reply is sent to the target channel.
- Announce step includes the original request + round‑1 reply + latest ping‑pong reply.
File: concepts/session-tool.md
Behavior:
- Starts a new `agent:<agentId>:subagent:<uuid>` session with `deliver: false`.
- Sub-agents default to the full tool set **minus session tools** (configurable via `tools.subagents.tools`).
- Sub-agents are not allowed to call `sessions_spawn` (no sub-agent → sub-agent spawning).
- Always non-blocking: returns `{ status: "accepted", runId, childSessionKey }` immediately.
- After completion, OpenClaw runs a sub-agent **announce step** and posts the result to the requester chat channel.
- Reply exactly `ANNOUNCE_SKIP` during the announce step to stay silent.
- Announce replies are normalized to `Status`/`Result`/`Notes`; `Status` comes from runtime outcome (not model text).
- Sub-agent sessions are auto-archived after `agents.defaults.subagents.archiveAfterMinutes` (default: 60).
- Announce replies include a stats line (runtime, tokens, sessionKey/sessionId, transcript path, and optional cost).
File: tools/subagents.md
# Sub-agents Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`agent:<agentId>:subagent:<uuid>`) and, when finished, **announce** their result back to the requester chat channel. ## Slash command Use `/subagents` to inspect or control sub-agent runs for the **current session**: - `/subagents list` - `/subagents stop <id|#|all>` - `/subagents log <id|#> [limit] [tools]` - `/subagents info <id|#>` - `/subagents send <id|#> <message>` `/subagents info` shows run metadata (status, timestamps, session id, transcript path, cleanup). Primary goals: - Parallelize “research / long task / slow tool” work without blocking the main run. - Keep sub-agents isolated by default (session separation + optional sandboxing). - Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default. - Avoid nested fan-out: sub-agents cannot spawn sub-agents. Cost note: each sub-agent has its **own** context and token usage. For heavy or repetitive tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model. You can configure this via `agents.defaults.subagents.model` or per-agent overrides.
File: tools/subagents.md
## Tool Use `sessions_spawn`: - Starts a sub-agent run (`deliver: false`, global lane: `subagent`) - Then runs an announce step and posts the announce reply to the requester chat channel - Default model: inherits the caller unless you set `agents.defaults.subagents.model` (or per-agent `agents.list[].subagents.model`); an explicit `sessions_spawn.model` still wins. - Default thinking: inherits the caller unless you set `agents.defaults.subagents.thinking` (or per-agent `agents.list[].subagents.thinking`); an explicit `sessions_spawn.thinking` still wins. Tool params: - `task` (required) - `label?` (optional) - `agentId?` (optional; spawn under another agent id if allowed) - `model?` (optional; overrides the sub-agent model; invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result) - `thinking?` (optional; overrides thinking level for the sub-agent run) - `runTimeoutSeconds?` (default `0`; when set, the sub-agent run is aborted after N seconds) - `cleanup?` (`delete|keep`, default `keep`)
File: tools/subagents.md
Allowlist: - `agents.list[].subagents.allowAgents`: list of agent ids that can be targeted via `agentId` (`["*"]` to allow any). Default: only the requester agent. Discovery: - Use `agents_list` to see which agent ids are currently allowed for `sessions_spawn`.
File: tools/subagents.md
Auto-archive: - Sub-agent sessions are automatically archived after `agents.defaults.subagents.archiveAfterMinutes` (default: 60). - Archive uses `sessions.delete` and renames the transcript to `*.deleted.<timestamp>` (same folder). - `cleanup: "delete"` archives immediately after announce (still keeps the transcript via rename). - Auto-archive is best-effort; pending timers are lost if the gateway restarts. - `runTimeoutSeconds` does **not** auto-archive; it only stops the run. The session remains until auto-archive.
File: tools/subagents.md
## Announce Sub-agents report back via an announce step: - The announce step runs inside the sub-agent session (not the requester session). - If the sub-agent replies exactly `ANNOUNCE_SKIP`, nothing is posted. - Otherwise the announce reply is posted to the requester chat channel via a follow-up `agent` call (`deliver=true`). - Announce replies preserve thread/topic routing when available (Slack threads, Telegram topics, Matrix threads). - Announce messages are normalized to a stable template: - `Status:` derived from the run outcome (`success`, `error`, `timeout`, or `unknown`). - `Result:` the summary content from the announce step (or `(not available)` if missing). - `Notes:` error details and other useful context. - `Status` is not inferred from model output; it comes from runtime outcome signals.
File: channels/broadcast-groups.md
## Overview Broadcast Groups enable multiple agents to process and respond to the same message simultaneously. This allows you to create specialized agent teams that work together in a single WhatsApp group or DM — all using one phone number. Current scope: **WhatsApp only** (web channel). Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when OpenClaw would normally reply (for example: on mention, depending on your group settings). ## Use Cases ### 1. Specialized Agent Teams Deploy multiple agents with atomic, focused responsibilities: Group: "Development Team" Agents: - CodeReviewer (reviews code snippets) - DocumentationBot (generates docs) - SecurityAuditor (checks for vulnerabilities) - TestGenerator (suggests test cases)
File: channels/broadcast-groups.md
### Basic Setup
Add a top-level `broadcast` section (next to `bindings`). Keys are WhatsApp peer ids:
- group chats: group JID (e.g. `120363403215116621@g.us`)
- DMs: E.164 phone number (e.g. `+15551234567`)
```json
{
"broadcast": {
"120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
}
}
**Result:** When OpenClaw would reply in this chat, it will run all three agents.
File: channels/broadcast-groups.md
### Session Isolation Each agent in a broadcast group maintains completely separate: - **Session keys** (`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`) - **Conversation history** (agent doesn't see other agents' messages) - **Workspace** (separate sandboxes if configured) - **Tool access** (different allow/deny lists) - **Memory/context** (separate IDENTITY.md, SOUL.md, etc.) - **Group context buffer** (recent group messages used for context) is shared per peer, so all broadcast agents see the same context when triggered This allows each agent to have: - Different personalities - Different tool access (e.g., read-only vs. read-write) - Different models (e.g., opus vs. sonnet) - Different skills installed ### Example: Isolated Sessions
File: agents/tools/sessions-send-tool.ts
const SessionsSendToolSchema = Type.Object({
sessionKey: Type.Optional(Type.String()),
label: Type.Optional(Type.String({ minLength: 1, maxLength: SESSION_LABEL_MAX_LENGTH })),
agentId: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
message: Type.String(),
timeoutSeconds: Type.Optional(Type.Number({ minimum: 0 })),
});
File: tools/lobster.md
# Lobster Lobster is a workflow shell that lets OpenClaw run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints. ## Hook Your assistant can build the tools that manage itself. Ask for a workflow, and 30 minutes later you have a CLI plus pipelines that run as one call. Lobster is the missing piece: deterministic pipelines, explicit approvals, and resumable state. ## Why Today, complex workflows require many back-and-forth tool calls. Each call costs tokens, and the LLM has to orchestrate every step. Lobster moves that orchestration into a typed runtime: - **One call instead of many**: OpenClaw runs one Lobster tool call and gets a structured result. - **Approvals built in**: Side effects (send email, post comment) halt the workflow until explicitly approved. - **Resumable**: Halted workflows return a token; approve and resume without re-running everything.
到此这篇关于OpenClaw多代理协同工作模式配置完整指南的文章就介绍到这了,更多相关OpenClaw多代理协同工作模式内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！