OpenClaw 多代理（Multi-Agent）YAML 配置教程（config.yaml / agents.yaml）

本文面向已经跑通 OpenClaw 基础安装的用户，讲解如何用 YAML 配置“单实例多代理”（推荐方案）：
通过一个 OpenClaw gateway 同时管理多个 agent，每个 agent 拥有独立的工作区、persona、模型、权限、记忆，并支持按通道/用户/关键词路由。

⚠️ 注意：多代理 YAML 支持在不同版本中可能存在字段差异。写完后务必用：
openclaw gateway restart --verbose + openclaw logs 验证是否加载成功。

目录

• 1. 两种多代理实现方式
• 2. YAML 为什么比 JSON 更适合多代理
• 3. 文件与目录约定
• 4. 推荐 config.yaml 示例（可直接复制）
• 5. 应用步骤（从 0 到跑通）
• 6. 路由规则设计技巧
• 7. AgentDir 三件套（SOUL/USER/AGENTS）
• 8. 进阶：Agent 间协作与工作流
• 9. 常见踩坑排查
• 10. 安全建议（必须保留）

1. 两种多代理实现方式

方式 A：单实例多代理（推荐、最原生）

• 一个 gateway 进程
• YAML 定义多个 agent
• 根据 通道/用户/群组/关键词 路由到不同 agent
• 好处：维护简单、资源占用低、配置集中

方式 B：多实例协作（更强隔离、配置更复杂）

• 跑多个 OpenClaw 进程（不同端口/不同 workspace）
• 通过 webhook / shared DB / 外部 orchestrator 协作
• 适合：你要“物理隔离”不同工作域（例如生产/开发/个人完全隔离）

2. YAML 为什么比 JSON 更适合多代理

• 多代理会产生大量重复结构（persona、model、permissions、memory、bindings）
• YAML 层级更清晰，适合维护路由规则
• 适合在教程站点直接展示并让用户复制

3. 文件与目录约定

推荐文件

• ~/.openclaw/config.yaml（存在时通常优先于 json）
• ~/.openclaw/openclaw.json（可以并存；不确定优先级时以日志为准）
• ~/.openclaw/.env（放密钥）

推荐目录

• ~/openclaw-workspaces/<agent>：每个 agent 独立工作区（代码、缓存、记忆、向量库等建议隔离）
• ~/.openclaw/agents/<agent>：每个 agent 的 persona/规则文件

4. 推荐 config.yaml 示例（可直接复制）

说明：

• agents.list 定义所有 agent
• agents.bindings 定义路由规则（从上到下，第一条匹配即生效）
• agents.defaults 定义全局默认（未在 agent 里覆盖的部分用这里）

# ~/.openclaw/config.yaml agents:  list:    - id: home-personal      name: Home Assistant      default: true      description: 你的私人生活助手，管理日程、购物、娱乐      workspace: ~/openclaw-workspaces/home      agentDir: ~/.openclaw/agents/home      model:        primary: anthropic/claude-3-5-sonnet-20241022        fallback: apiyi/claude-sonnet-4-20250514      persona:        role: "温暖、幽默的家庭管家，像 Jarvis 但更接地气"        rules: "永远用中文回复；优先考虑隐私；别主动执行 rm/sudo"      permissions:        allowedCommands: [ls, cat, echo, open, git status]        blockedCommands: ["rm -rf", sudo, "curl --upload"]      memory:        vectorStore: local        proactive: true     - id: work-coding      name: Code Master      description: 专注编程、debug、架构设计      workspace: ~/openclaw-workspaces/work      agentDir: ~/.openclaw/agents/work      model:        primary: anthropic/claude-opus-4-5        reasoning: anthropic/claude-opus-4-5      persona:        role: "严谨的专业工程师，代码优先，少废话"        rules: "用英文写代码注释；总是先规划再执行；输出 diff 格式"      permissions:        allowedCommands: [code, git, npm, pytest, docker]        sandbox:          mode: strict          workspaceAccess: read-write     - id: research-deep      name: Research Agent      description: 深度调研、文献阅读、数据分析      workspace: ~/openclaw-workspaces/research      agentDir: ~/.openclaw/agents/research      model:        primary: minimax/MiniMax-M2.1      persona:        role: "学术派研究员，引用来源，逻辑严密"        rules: "每条结论附来源链接；避免 hallucination"   bindings:    - agentId: home-personal      match:        channel: whatsapp        accountId: "+861xxxxxxxxxx"     - agentId: work-coding      match:        channel: telegram        keywords: ["code", "debug", "fix bug", "写代码"]     - agentId: research-deep      match:        channel: feishu        groups: ["research-group"]     - agentId: home-personal      match: {} agents.defaults:  heartbeat:    every: 45m    activeHours:      start: "07:00"      end: "23:00"  sandbox:    mode: non-main    scope: session models:  providers:    apiyi:      baseUrl: https://api.apiyi.com/v1      apiKey: ${APIYI_KEY}

5. 应用步骤（从 0 到跑通）

5.1 写入 config.yaml

mkdir -p ~/.openclawnano ~/.openclaw/config.yaml# 或用你熟悉的编辑器

5.2 创建 workspace 与 agentDir

mkdir -p ~/openclaw-workspaces/{home,work,research}mkdir -p ~/.openclaw/agents/{home,work,research}

5.3 把密钥放到 .env（推荐）

nano ~/.openclaw/.env

示例：

ANTHROPIC_API_KEY=sk-REPLACE_MEAPIYI_KEY=sk-REPLACE_MEMINIMAX_API_KEY=YOUR_MINIMAX_KEYTELEGRAM_TOKEN=YOUR_TELEGRAM_BOT_TOKENFEISHU_APP_ID=cli_REPLACE_MEFEISHU_APP_SECRET=YOUR_FEISHU_APP_SECRET

5.4 重启并确认加载成功

openclaw gateway restart --verbose# 或openclaw restart --verbose

看日志里是否出现类似：

• loaded config.yaml
• registered agents: home-personal, work-coding, research-deep
• bindings loaded ...

5.5 测试路由

• WhatsApp 发消息 → 应命中 home-personal
• Telegram 发 “帮我 debug 这个 bug” → 应命中 work-coding
• 飞书 research-group 群里发消息 → 应命中 research-deep

6. 路由规则设计技巧

6.1 顺序非常重要：最具体的放前面

例如：

1. 指定通道 + 指定账号
2. 指定通道 + 指定群
3. 指定通道 + 关键词
4. 兜底 match:

6.2 关键词路由建议

• 不要太宽泛（例如只写 “help” 会误触）
• 同时覆盖中文/英文（如 debug/修复/报错）
• 对高风险 agent（能写文件/能跑 docker）尽量加账号限制

7. AgentDir 三件套（SOUL/USER/AGENTS）

在每个 agentDir 下建议放：

7.1 SOUL.md（人格与目标）

• 决定 agent 的语气、偏好、边界

7.2 USER.md（你的个人偏好）

• 例如你的工作习惯、语言偏好、时区、工具等

7.3 AGENTS.md（跨 agent 协作规则）

• 例如：
  • “涉及代码修改 → 转交给 work-coding”
  • “需要调研引用 → 先交给 research-deep”

8. 进阶：Agent 间协作与工作流

如果你的版本支持 workflow/编排（例如 lobster/workflow 类插件思路），可以做：

• research-deep：先检索/整理信息
• work-coding：根据整理结果写代码/出 patch
• home-personal：把结果用更友好方式总结给你

实践建议：

• 先把单 agent 跑稳，再上多 agent 协作
• 对“自动串联”要加权限限制（避免自动执行危险操作）

9. 常见踩坑排查

9.1 路由不生效

• bindings 顺序错误（最常见）
• keywords 匹配不到（大小写/分词/中文标点）
• channel 名称与你实际通道标识不同（以日志显示为准）

9.2 内存/向量库冲突

• 不同 agent 共享同一个 vectorStore path 可能互相污染
  ✅ 建议每个 workspace 独立存储（或在 memory 配置里指定不同路径）

9.3 成本爆炸

• primary 太贵、没有 fallback
• research agent 长上下文频繁调用昂贵模型
  ✅ 用便宜模型做主力，强模型只在 reasoning/关键任务使用

9.4 权限泄露

• 某个 agent 允许的命令太宽
  ✅ 每个 agent 单独 allowedCommands，默认尽量只读

10. 安全建议（必须保留）

• 多代理 = 更多入口点。每个 agent 都要做权限最小化。
• 群聊默认 requireMention，避免误触。
• 对能写文件/能执行命令的 agent：一定加 allowFrom 白名单。
• 不要把 gateway 管理端口暴露公网；需要暴露时必须加 token + 防火墙白名单 + 反代认证。
• 优先在 VPS/Docker/隔离环境测试，别在主力机裸奔跑满权限。