跳轉到內容
最近更新

OpenClaw 多代理（Multi-Agent）YAML 設定教學（config.yaml / agents.yaml）

本文面向已經跑通 OpenClaw 基礎安裝的使用者，講解如何用 YAML 設定“單實例多代理”（推薦方案）：
通過一個 OpenClaw gateway 同時管理多個 agent，每個 agent 擁有獨立的工作區、persona、模型、權限、記憶，並支持按通道/使用者/關鍵詞路由。

⚠️ 注意：多代理 YAML 支持在不同版本中可能存在字段差異。寫完後務必用：
openclaw gateway restart --verbose + openclaw logs 驗證是否加載成功。

目錄

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 裡覆蓋的部分用這裡）
YAML
# ~/.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

Command
mkdir -p ~/.openclawnano ~/.openclaw/config.yaml# 或用你熟悉的編輯器

5.2 創建 workspace 與 agentDir

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

5.3 把密鑰放到 .env（推薦）

Command
nano ~/.openclaw/.env

示例：

Command
ANTHROPIC_API_KEY=sk-REPLACE_MEAPIYI_KEY=sk-REPLACE_MEMINIMAX_API_KEY=REDACTED_MINIMAX_API_KEYTELEGRAM_TOKEN=REDACTED_TELEGRAM_BOT_TOKENFEISHU_APP_ID=cli_REPLACE_MEFEISHU_APP_SECRET=REDACTED_FEISHU_APP_SECRET

5.4 重啟並確認加載成功

Command
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/隔離環境測試，別在主力機裸奔跑滿權限。