OpenClaw 多Agent软件开发最佳实践指南

OpenClaw 多Agent软件开发最佳实践指南

---

核心洞察：为什么需要多Agent协作？

单一智能体的局限性在复杂软件开发中日益明显：

• 上下文污染：代码、设计、测试信息混杂，响应质量下降
• 人设混乱：同一智能体需切换产品经理、程序员、测试员角色，导致行为不一致
• Token浪费：每次请求都加载无关记忆，成本激增
• 职责不清：缺乏专业化分工，难以保证输出质量

OpenClaw通过"角色拆分、身份隔离、协作分工"的多Agent架构，彻底解决了这些痛点。

---

一、架构设计原则

1.1 三层隔离架构

OpenClaw的每个Agent是完全独立的"虚拟员工"，理解这一点至关重要：

~/.openclaw/agents/<agentId>/
├── agent/                    # 身份层 - 员工牌
│   ├── auth-profiles.json    # 认证配置（API Key）
│   └── models.json           # 模型配置（用哪个LLM）
├── sessions/                 # 状态层 - 工作日志
│   ├── <session-id>.jsonl   # 独立聊天记录
│   └── sessions.json        # 会话索引
└── workspace/               # 工作层 - 办公桌面
    ├── SOUL.md             # 灵魂/人格定义
    ├── AGENTS.md           # 行为规范
    ├── USER.md             # 用户信息
    ├── TOOLS.md            # 工具使用指南
    ├── IDENTITY.md         # 身份定义
    └── memory/            # 记忆存储
        └── YYYY-MM-DD.md  # 每日日志

关键原则：永远不要让两个Agent共享agentDir或workspace——这会导致认证碰撞、会话冲突、文件覆盖。

1.2 两种部署流派

维度	分身术（推荐）	独立团
实现方式	一个Bot，通过Bindings路由到不同Agent	每个Agent对应独立Bot
用户体验	同一机器人，但"换脑"工作	每个机器人有独立头像/名字
管理成本	低，配置简单	高，需管理多个Bot
适合场景	个人使用，追求效率	团队协作，需要角色感

对于个人开发者，强烈推荐分身术——用最少的配置获得最大的灵活性。

---

二、Agent角色设计

2.1 推荐的软件开发团队角色

Main (大蔡/统筹)
├── 职责：任务拆解、进度坚控、结果聚合
├── 模型：经济型（如qwen3-max-2026）
└── 工具：sessions_send、sessions_receive、planning

Coder (蔡农/编码)
├── 职责：代码编写、系统调试、单元测试
├── 模型：代码专用（如qwen3-coder-2026）
└── 工具：exec、write、edit、git

Reviewer (审核员)
├── 职责：代码审查、安全检查、性能分析
├── 模型：顶级模型（如GPT-4.5/Sonnet 4.6）
└── 工具：read、exec、test

Architect (架构师)
├── 职责：技术选型、架构设计、方案评审
├── 模型：顶级模型
└── 工具：browser、read、write

DevOps (运维工程师)
├── 职责：部署配置、CI/CD编排、坚控告警
├── 模型：经济型
└── 工具：exec、git、cloud-tools

2.2 SOUL.md 设计原则

反面示例（过长，浪费token）：

你是一位经验丰富的软件工程师，拥有10年Java开发经验，
擅长微服务架构设计，对Spring Boot有深入研究，
在项目中你总是注重代码质量，遵循SOLID原则...
（500字+）

正面示例（简洁高效）：

# SOUL.md - Coder Agent

角色：后端开发工程师
专长：Java、微服务、Spring Boot
原则：
- 代码可测试性 > 简洁性
- 遵循SOLID原则
- API文档先行
- 3行以上逻辑必须写注释

典型工作流：
1. 理解需求 → 2. 编写测试 → 3. 实现代码 → 4. 自测验证

黄金法则：SOUL.md保持在1-2KB以内。超过5KB会导致每次请求浪费大量token。

2.3 模型混搭策略

不要无脑用最贵的模型，也不要为了省钱全用最便宜的：

Agent类型	推荐模型	理由
统筹/调度	Haiku/Nano	简单任务分配，不需要深度推理
编码	CodeLLaMA/Coder	代码专用，性价比最高
审核/架构	GPT-4.5/Sonnet 4.6	需要深度思考和复杂推理
日常问答	Qwen-Max	中文能力强，价格适中

实战数据：某开发者从"全用Sonnet（$90\mathrm{/}\text{月）}\mathrm{"}\text{优化为}\mathrm{"}\text{模型混搭}\mathrm{"}\text{后，成本降至}\ast \ast$45/月**，且质量无损失。

---

三、协作模式

3.1 四种主流模式

模式1：Supervisor（监督者模式）

适用场景：需要统一入口、跨领域协作、质量监督

OpenClaw实现：

{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["main", "coder", "reviewer", "architect"]
    }
  }
}

实战案例：开发一个用户认证模块

1. Main接收需求 → 调用Architect设计方案
2. Main根据架构 → 调用Coder实现代码
3. Main触发Reviewer → 代码审查
4. Main聚合所有反馈 → 生成最终报告

模式2：Router（路由模式）

手绘示意图：Router模式

用户请求
    ↓
Router（分类器）
    ├→ Agent A（专业领域1）
    ├→ Agent B（专业领域2）
    └→ Agent C（专业领域3）

适用场景：不同渠道需要不同风格、不同用户群需要不同专业度

OpenClaw实现：利用Bindings的确定性路由

{
  "bindings": [
    {
      "agentId": "coder",
      "match": {
        "channel": "discord",
        "peer": { "kind": "channel", "id": "coding-team" }
      }
    },
    {
      "agentId": "architect",
      "match": {
        "channel": "discord",
        "peer": { "kind": "channel", "id": "architecture-team" }
      }
    }
  ]
}

模式3：Pipeline（流水线模式）

任务像流水线一样在Agent之间传递：
调研Agent → 写作Agent → 校审Agent → 排版Agent
   ↓            ↓            ↓            ↓
 (资料收集)  (初稿撰写)  (质量把关)  (最终输出)

适用场景：内容创作、代码开发、数据处理

OpenClaw实现：通过sessions_send编排执行链

# Main Agent的工作流
research_result = sessions_send({
    "agent": "researcher",
    "task": "调研OpenClaw最新功能"
})

draft = sessions_send({
    "agent": "writer",
    "task": f"基于调研结果撰写文档：{research_result}"
})

final_doc = sessions_send({
    "agent": "reviewer",
    "task": f"审核并优化文档：{draft}"
})

模式4：Parallel（并行协作模式）

Main Agent 同时触发多个独立任务：
    ├→ Coder（后端开发）
    ├→ Frontend-Dev（前端开发）
    └→ QA（测试用例编写）
    ↓
Main Agent 收集所有结果 → 整合联调

适用场景：多模块并行开发、数据分片处理

OpenClaw实现（使用sessions_spawn）：

# 并行执行三个任务
results = await Promise.all([
    sessions_spawn({
        "label": "后端开发",
        "task": "实现用户认证API",
        "runTimeoutSeconds": 300
    }),
    sessions_spawn({
        "label": "前端开发",
        "task": "设计登录页面UI",
        "runTimeoutSeconds": 300
    }),
    sessions_spawn({
        "label": "测试编写",
        "task": "编写认证模块测试用例",
        "runTimeoutSeconds": 180
    })
])

3.2 最新特性：Agent Teams（2026年2月新增）

️ 注意：此功能在RFC阶段，可能尚未正式发布，使用前请确认版本支持。

OpenClaw新增了更高级的协作模式——Agent Teams，支持：

• 共享任务列表（Task List with Dependencies）
• Agent间直接通信（Mailbox）
• 动态任务认领（Task Claiming）

适用场景：复杂项目需要多个Agent长期协作

{
  "tool": "team_create",
  "params": {
    "teamName": "feature-auth-refactor",
    "coordinationMode": "normal"
  }
}

协调模式对比：

模式	Lead行为	适用场景
normal	Lead可以claim任务	Lead参与实现+协调
delegate	Lead不能claim任务	Lead纯协调，不参与实现

---

四、通信机制

4.1 Agent间通信工具

sessions_send（点对点通信）

sessions_send({
    "agent": "coder",        # 目标Agent ID
    "task": "实现用户登录API",  # 任务描述
    "timeoutSeconds": 300          # 超时时间（秒），timeoutSeconds>0时等待完成
})

特点：

• 定向通信，精准派单
• 结果回传，支持状态追踪
• 记录独立，不污染用户会话

sessions_spawn（子代理生成）

️ 常见误区（经官方文档验证）：

错误表述	正确说明
mode: "run" / mode: "session"	sessions_spawn没有mode参数，不存在
runtimeoutseconds	正确参数名是runTimeoutSeconds
用mode控制一次性/持久	通过cleanup和thread参数控制

正确用法：

# 一次性子代理（完成后自动归档）
sessions_spawn({
    "label": "代码审查",
    "task": "审查当前分支代码",
    "cleanup": "delete",  # announce完立即归档（默认就是delete）
    "runTimeoutSeconds": 300
})

# 持久子代理（需手动管理）
sessions_spawn({
    "label": "长期助手",
    "task": "在这个线程中长期协助用户",
    "cleanup": "keep",  # 交给统一的auto-archive
    "thread": true,       # 启用线程绑定（Discord专用）
    "runTimeoutSeconds": 600
})

**关键参数说明 **：

• task：必填，子代理要完成的自然语言任务
• label：可选，用于给子代理打易读标签
• runTimeoutSeconds：超时后会中止运行（注意参数名是runTimeoutSeconds）
• cleanup："delete"（announce完立即归档）或"keep"（交给统一的auto-archive）
• thread：布尔值，启用线程绑定（Discord等渠道支持，持久化子代理专用）
• agentId：可选，如果配置了allowAgents，可以指定用另一个Agent运行
• thinking：可选，覆盖默认思考级别（off/low/medium/high）

线程绑定（Thread Binding）：

• 支持的渠道：Discord
• 特点：子代理绑定到当前线程，后续消息直接路由到该子代理
• 管理命令：/focus、/unfocus、/agents、/sessionIdle、/sessionMaxAge
• 适用场景：Discord群机器人，每个讨论线程一个专属子代理

agentToAgent（批量通信）

{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["main", "coder", "reviewer"],
      "maxPingPongTurns": 0  # 防止Agent无限互怼
    }
  }
}

关键配置：

• enabled: true - 开启Agent间通信
• allow - 通信白名单（仅允许main调度其他Agent）
• maxPingPongTurns: 0 - 禁止自动互相回复

maxPingPongTurns说明（️ 重要）：

• maxPingPongTurns: 0：表示完全禁止agentToAgent的ping-pong循环
• 这是sessions_send的机制，不是sessions_spawn
• 当设置为0时，主Agent调用sessions_send后，目标Agent执行任务并返回结果，不会继续对话
• 如果设置为1-5，则允许指定轮数的来回对话（用于需要澄清的场景）

4.2 避坑指南

问题1：Agent间无限客套循环

Agent A: "你好，我准备好了"
Agent B: "你好，我也准备好了"
Agent A: "那我们开始吧"
Agent B: "好的，我听你的"
...（无限循环）

解决方案：

{
  "session": {
    "agentToAgent": {
      "maxPingPongTurns": 0  # 禁止自动互怼
    }
  }
}

问题2：工作区文件互相覆盖

• 原因：多个Agent共用同一个workspace
• 解决：为每个Agent创建独立workspace

问题3：路由对了但身份错了

• 原因：未配置多Bot Token，所有Agent共用一个身份
• 解决：为每个Agent创建独立的Bot Token

---

五、成本优化策略

5.1 Token消耗的真相

OpenClaw的token消耗有90%是可以避免的：

消耗来源	占比	优化方案	节省
Bootstrap文件注入（AGENTS/SOUL）	30%	控制在5KB以内	60%
工具调用Schema（如browser）	20%	使用轻量工具	40%
无关记忆加载	15%	记忆分层管理	70%
心跳检查用昂贵模型	10%	改用Nano模型	95%

5.2 实战优化技巧

技巧1：子代理处理大任务

错误做法：

让Main Agent直接做深度研究、写大量代码
→ 所有中间结果留在主会话上下文
→ 每条消息都带着这些垃圾

正确做法：

Main创建临时代理执行重活
→ 子代理完成工作后，只返回关键摘要（10%）
→ 主会话保持轻量

# 在AGENTS.md中添加
"对于复杂任务（研究、编程、数据分析），创建临时子代理完成。
子代理完成后，只返回最终结果给主会话。"

技巧2：记忆分层管理

MEMORY.md (长期记忆)
├── 核心原则、关键决策
├── 项目架构、技术选型
└── 最佳实践、踩坑记录

memory/YYYY-MM-DD.md (每日日志)
├── 当天执行的任务
├── 遇到的临时问题
└── 快速笔记

优化命令：

每周执行一次"记忆压缩"：
"请总结memory/过去7天的文件，保留10条最重要的信息，
删除重复和过时内容，将文件压缩到5KB以内"

技巧3：心跳检查优化

错误配置：

{
  "cron": "*/30 * * * *",  // 每30分钟
  "agent": "main",
  "model": "sonnet-4.6"     // 用顶级模型做简单检查
}

→ 每月成本：$45

优化配置：

{
  "cron": "*/30 * * * *",
  "agent": "heartbeat-coordinator",
  "model": "haiku-3.5"      // 用廉价模型做初步检查
}

当haiku发现问题后，再触发sonnet处理 → 每月成本：$2.25（节省95%）

技巧4：上下文管理

启用自动剪枝：

{
  "agents": {
    "defaults": {
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "5m",
        "keepLastAssistants": 3,
        "softTrim": { "maxChars": 4000 },
        "hardClear": { "enabled": true }
      }
    }
  }
}

启用记忆刷新（️ 关键配置）：

{
  "compaction": {
    "reserveTokensFloor": 20000,
    "memoryFlush": {
      "enabled": true,
      "softThresholdTokens": 4000,
      "prompt": "Write durable notes to memory/YYYY-MM-DD.md"
    }
  }
}

memoryFlush触发时机公式（经官方文档验证）：

flush触发点 = contextWindow - reserveTokensFloor - softThresholdTokens

举例（假设contextWindow=200000）：

200000 - 20000 - 4000 = 176000 tokens

当会话接近176000 tokens时，会触发memory flush，将关键信息写入长期记忆，避免压缩后丢失。

技巧5：本地LLM的激进上下文管理

对于本地LLM（prefill速度慢，如4.5 tokens/sec），需要更激进的配置：

{
  "models": {
    "providers": {
      "local-qwen": {
        "models": [{
          "id": "mlx-community/Qwen3.5-397B-A17B-4bit",
          "contextWindow": 50000  // 强制设置较小的窗口
        }]
      }
    }
  },
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "default",
        "reserveTokensFloor": 10000,  // 本地模型需要更多保留空间
        "memoryFlush": { "enabled": true }
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "10m",  // 更频繁的剪枝
        "keepLastAssistants": 2,
        "minPrunableToolChars": 20000  // 工具输出超过2万字符才剪枝
      }
    }
  }
}

为什么需要：

• System prompt + skills + tool schemas可能占用18k+ tokens
• 本地模型prefill慢，80k tokens需要~300秒处理
• 用户感知到Bot"死机"

技巧6：记忆搜索的时间衰减（temporal decay）

为避免6个月前的记忆排名高于今天的记忆，启用时间衰减：

{
  "memorySearch": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "temporalDecay": {
      "enabled": true,
      "halfLifeDays": 30  // 30天半衰期
    }
  }
}

计算公式（官方文档提供）：

decayedScore = score × e^(-λ × ageInDays)
其中 λ = ln(2) / halfLifeDays

效果：

• 今天的记忆：100%原始分
• 7天前：84%
• 30天前：50%
• 90天前：12.5%
• 180天前：~1.6%

例外：

• MEMORY.md（根记忆文件）不衰减
• memory/projects.md等非日期文件不衰减
• 只有memory/YYYY-MM-DD.md按日期衰减

---

六、安全治理

6.1 沙箱隔离策略

{
  "agents": {
    "list": [
      {
        "id": "main",
        "sandbox": { "mode": "off" }  // 完全信任，无隔离
      },
      {
        "id": "public-agent",
        "sandbox": {
          "mode": "all",       // 始终沙箱隔离
          "scope": "agent"      // 每Agent一个容器
        }
      },
      {
        "id": "semi-trusted",
        "sandbox": {
          "mode": "non-main",  // 非主会话才隔离
          "scope": "session"    // 每会话一个容器
        }
      }
    ]
  }
}

6.2 工具权限控制

{
  "agents": {
    "list": [
      {
        "id": "family-bot",
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "browser", "process"]
        }
      },
      {
        "id": "coding-bot",
        "tools": {
          "allow": ["read", "write", "edit", "exec", "git"],
          "deny": ["browser"]  // 禁止访问互联网
        }
      }
    ]
  }
}

6.3 批准工作流

对于敏感操作（如exec、删除文件），启用批准机制：

{
  "tools": {
    "execApproval": {
      "enabled": true,
      "commands": ["rm -rf", "docker exec", "kubectl delete"],
      "approvalMode": "human"  // 需要人工批准
    }
  }
}

6.4 最新安全加固（2026年2月更新）

OpenClaw 2026.2.23版本引入了多项安全加固措施：

{
  "tools": {
    "ssrf": {
      "policy": "trusted-network"  // 新默认：仅信任网络（防止SSRF攻击）
    },
    "execApproval": {
      "enabled": true,
      "commands": ["rm -rf", "docker exec", "kubectl delete"],
      "approvalMode": "human"
    }
  }
}

其他安全措施：

• 配置快照时自动redact敏感密钥（env.*、skills.env.*）
• 检测并阻止混淆命令（obfuscated commands）
• Skills打包时拒绝symlink逃逸和XSS漏洞提示
• OTEL诊断日志中自动redact API密钥

---

七、实战案例：端到端软件开发

案例1：开发一个用户认证模块

任务分解：

1. Architect设计技术方案（JWT + Redis）
2. Coder实现后端API
3. Frontend-Dev实现登录页面
4. QA编写测试用例
5. Reviewer进行代码审查

Main Agent的执行流程：

# 步骤1：任务拆解
plan = break_down_task("开发用户认证模块")

# 步骤2：架构设计（串行）
architecture = sessions_send({
    "agent": "architect",
    "task": f"设计用户认证方案：{plan}",
    "timeoutSeconds": 180
})

# 步骤3：并行开发（后端+前端+测试）
results = await Promise.all([
    sessions_spawn({
        "label": "后端API",
        "task": f"实现认证API：{architecture}",
        "runTimeoutSeconds": 600
    }),
    sessions_spawn({
        "label": "前端页面",
        "task": f"实现登录UI：{architecture}",
        "runTimeoutSeconds": 600
    }),
    sessions_spawn({
        "label": "测试用例",
        "task": "编写认证模块测试",
        "runTimeoutSeconds": 300
    })
])

# 步骤4：代码审查（串行）
review = sessions_send({
    "agent": "reviewer",
    "task": f"审查代码：{results}",
    "timeoutSeconds": 300
})

# 步骤5：整合输出
final_report = synthesize_results(architecture, results, review)

案例2：自动化PR工作流

场景：开发者提交代码后，自动触发代码审查

Cron配置：

{
  "cron": "*/15 * * * *",  // 每15分钟检查一次
  "agent": "pr-bot",
  "task": "检查开放的PR，自动进行代码审查"
}

PR Bot的工作流：

1. 检查是否有开放的PR
2. 如有PR，触发Reviewer进行代码审查
3. 生成审查报告（问题清单、改进建议）
4. 通过T@elegrimm通知开发者

---

八、坚控与调试

8.1 可观测性设计

日志追踪：

• 为每次协作生成唯一trace_id
• 记录每个Agent的思考过程和行动
• 保存所有inter-agent通信

可视化仪表盘：

• 任务执行状态（pending/in-progress/completed/failed）
• Agent响应时间
• Token消耗统计
• 成本分析

8.2 常见问题诊断

问题	可能原因	解决方案
Agent不响应	模型超时/限流	检查API配额，设置重试机制
输出质量差	Bootstrap文件过大	压缩SOUL.md/AGENTS.md
成本激增	心跳检查用昂贵模型	改用Nano模型
Agent互相冲突	职责边界不清	重新定义Agent角色

---

九、从单Agent迁移到多Agent

迁移步骤

阶段1：准备（1天）

• 识别当前Agent的职责（产品经理+程序员+测试员）
• 设计新的Agent角色拆分方案

阶段2：配置（2-3天）

• 创建独立workspace
• 配置bindings路由
• 编写SOUL.md和AGENTS.md

阶段3：测试（3-5天）

• 并行运行新旧Agent
• 对比输出质量和响应时间
• 收集反馈，调整配置

阶段4：切换（1天）

• 将流量切换到新Agent
• 坚控一周，优化配置

迁移检查清单

• 每个Agent有独立workspace
• SOUL.md/AGENTS.md控制在5KB以内
• 启用contextPruning
• 配置agentToAgent通信
• 设置模型混搭策略
• 启用沙箱隔离（针对非信任Agent）
• 配置坚控告警

---

十、进阶模式

10.1 动态子Agent（sessions_spawn）

无需预配置，按需创建临时助手：

# 动态创建代码审查助手（一次性）
reviewer = sessions_spawn({
    "label": "代码审查助手",
    "task": "审查当前分支的代码变更",
    "cleanup": "delete",  # 完成后立即归档
    "runTimeoutSeconds": 300
})

# 动态创建性能分析助手（持久会话，需手动管理）
profiler = sessions_spawn({
    "label": "性能分析助手",
    "task": "分析API响应时间瓶颈",
    "thread": true,  # 启用线程绑定（Discord专用，持久化子代理）
    "runTimeoutSeconds": 600
})

适用场景：

• 临时性、一次性的专门任务
• 不需要长期维护的辅助Agent
• Discord线程绑定：需要子代理长期驻留在某个讨论线程中

10.2 共享沙箱

多个Agent共享同一个沙箱容器：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "scope": "shared",
        "workspaceRoot": "/tmp/work-sandboxes"
      }
    }
  }
}

适用场景：

• 需要共享文件系统的相关任务
• 节省资源，减少容器数量

10.3 跨Agent Spawning

默认情况下，子代理只能在创建它的Agent下运行。允许跨Agent spawning：

{
  "agents": {
    "list": [
      {
        "id": "orchestrator",
        "subagents": {
          "allowAgents": ["researcher", "coder"],  // 允许orchestrator创建researcher和coder的子代理
          // 或者用 ["*"] 允许任何Agent
        }
      }
    ]
  }
}

用途：

• Orchestrator可以按需创建不同专业子代理
• 避免每个Agent都预配置大量子代理
• 灵活的团队组合

10.4 内容路由（实验性特性）

️ 注意：这是2026年2月提出的RFC，可能尚未正式发布。

OpenClaw支持基于消息内容的路由：

{
  "bindings": [
    {
      "agentId": "chef",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "group", "id": "123@g.us" },
        "content": {          // 新增：内容匹配
          "pattern": "^@chef\b",
          "stripMatch": true  // 移除匹配的前缀
        }
      }
    }
  ]
}

适用场景：

• 同一群组根据@提及路由到不同Agent
• 无需中间Agent充当调度器

---

十一、性能基准

实战数据（来自OpenClaw Production Guide）

优化前（2026年1月）：

• 成本：~$90/月（全用Sonnet）
• Bootstrap：85KB（21,400 tokens）
• Embeddings：禁用
• 任务管理：手动
• 架构：单体Agent

优化后（2026年2月）：

• 成本：~$45/月（降低50%）
• Bootstrap：27KB（6,472 tokens，降低69.8%）
• Embeddings：启用（382个chunks，0失败）
• 任务管理：自动化（Opus 4.6 cron @ 05:30 AM）
• 架构：多Agent架构

关键洞察：

• 上下文优化是最大赢家——仅记忆归档就节省$135/月
• 策略性模型选择 > 盲目降级——Haiku在67%的任务中失败
• 多Agent架构——Haiku + 5KB上下文 ≈ Sonnet + 27KB上下文（便宜4倍）

---

十二、工具与模板

12.1 快速初始化脚本

#!/bin/bash
# create_agents.sh - 创建多Agent工作区

# 创建5个Agent的独立工作区
mkdir -p ~/.openclaw/workspaces/{main,coder,reviewer,architect,devops}

# 设置权限
chmod 755 ~/.openclaw/workspaces/*

# 复制基础模板
for workspace in ~/.openclaw/workspaces/*; do
    cp templates/SOUL.md "$workspace/"
    cp templates/AGENTS.md "$workspace/"
    cp templates/IDENTITY.md "$workspace/"
    mkdir -p "$workspace/memory"
done

echo " Agent工作区创建完成"

12.2 配置文件模板

// openclaw.json - 多Agent配置模板
{
  "agents": {
    "defaults": {
      "llm": {
        "provider": "dashscope",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
      },
      "session": {
        "agentToAgent": {
          "maxPingPongTurns": 0,
          "enabled": true
        }
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "5m",
        "keepLastAssistants": 3,
        "softTrim": { "maxChars": 4000 },
        "hardClear": { "enabled": true }
      },
      "compaction": {
        "mode": "default",
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "prompt": "Write durable notes to memory/YYYY-MM-DD.md"
        }
      }
    },
    "list": [
      {
        "id": "main",
        "name": "统筹助手",
        "workspace": "~/.openclaw/workspaces/main",
        "llm": { "model": "qwen3-max-2026" },
        "sandbox": { "mode": "off" }
      },
      {
        "id": "coder",
        "name": "编码专家",
        "workspace": "~/.openclaw/workspaces/coder",
        "llm": { "model": "qwen3-coder-2026" },
        "sandbox": { "mode": "all", "scope": "agent" }
      },
      {
        "id": "reviewer",
        "name": "代码审核",
        "workspace": "~/.openclaw/workspaces/reviewer",
        "llm": { "model": "gpt-4.5" },
        "sandbox": { "mode": "all", "scope": "session" }
      }
    ]
  },
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["main", "coder", "reviewer"]
    }
  },
  "bindings": [
    {
      "agentId": "main",
      "match": { "channel": "discord", "peer": { "kind": "channel", "id": "general" } }
    },
    {
      "agentId": "coder",
      "match": { "channel": "discord", "peer": { "kind": "channel", "id": "coding" } }
    }
  ]
}

---

十三、总结：核心要点速查

必做事项

1. 一个Agent一个workspace——永不共享
2. Bootstrap文件控制在5KB内——AGENTS.md、SOUL.md
3. 启用contextPruning——减少token浪费
4. 模型混搭——统筹用廉价、编码用专用、审核用顶级
5. 配置agentToAgent——设置maxPingPongTurns=0
6. 启用沙箱隔离——非信任Agent必须隔离
7. 记忆分层管理——MEMORY.md长期 + memory/YYYY-MM-DD.md日志
8. 启用memoryFlush——压缩前保存关键信息（️ 防止记忆丢失）
9. 参数名准确——runTimeoutSeconds而非runtimeoutseconds（️ 常见误区）
10. 本地LLM激进配置——设置较小的contextWindow和更频繁的pruning

禁忌事项

1. 不要让Agent互相无限客套（设置maxPingPongTurns=0）
2. 不要在主会话做重活（用子代理）
3. 不要无脑降级模型（Haiku失败率67%）
4. 不要共享agentDir
5. 不要心跳检查用昂贵模型
6. 不要使用不存在的sessions_spawn参数：mode: "run"/mode: "session"不存在
7. 不要用错参数名：runtimeoutseconds应为runTimeoutSeconds

推荐架构

个人用户：分身术（单Bot多路由）
团队协作：独立团（多Bot独立身份）
复杂项目：Agent Teams（️ RFC阶段，需确认版本支持）
临时任务：sessions_spawn（动态子代理）

---

参考资源

• OpenClaw官方文档：docs.openclaw.ai
• OpenClaw架构文档：github.com/mudrii/open…
• OpenClaw生产实践：github.com/ctala/openc…
• 多Agent RFC（Agent Teams）：github.com/openclaw/op…
• 编排系统指南：github.com/happycastle…
• sessions_spawn官方文档：github.com/openclaw/op…
• 上下文治理详解：mp.weixin.qq.com/s?__biz=MzI…

---

最后的话：

多Agent架构不是"更炫酷"的选择，而是应对复杂软件开发的必然演化。当你的任务涉及跨领域协作、需要专业化分工、追求可控的质量和成本时，多Agent就是答案。

OpenClaw的核心价值在于"专业分工"——让每个Agent专注自己的领域，避免上下文污染、人设混乱、token浪费，真正实现"1+1>2"的协作效果。

开始时，从2-Agent系统（Supervisor + Worker）入手，逐步扩展。渐进式迭代，是避免混乱的最佳策略。

祝你的AI团队协作愉快！