OpenClaw 單伺服器多 Agent 架構 + Telegram 多對話分工最佳實踐

適用版本：OpenClaw 2026.2.x+
前提：使用 OpenRouter API（不跑本地模型）
最後更新：2026 年 3 月

一、核心概念：什麼是「一個 Agent」？

在 OpenClaw 裡，一個 Agent 是一個完全隔離的「大腦」，擁有：

Workspace（獨立的 SOUL.md / AGENTS.md / USER.md / skills/）
State Directory（agentDir，存放 auth-profiles.json、模型設定）
Session Store（聊天歷史和路由狀態）

路徑結構：

~/.openclaw/
├── openclaw.json                          # 全局設定（所有 Agent 共用）
├── workspace-main/                        # 主 Agent 的 Workspace
├── workspace-marketing/                   # 行銷 Agent 的 Workspace
├── workspace-dev/                         # 開發 Agent 的 Workspace
├── agents/
│   ├── main/
│   │   ├── agent/                         # auth-profiles, model registry
│   │   └── sessions/                      # 聊天記錄
│   ├── marketing/
│   │   ├── agent/
│   │   └── sessions/
│   └── dev/
│       ├── agent/
│       └── sessions/
└── skills/                                # 全局共用 skills（所有 Agent 可見）

關鍵隔離原則：Auth profiles 是 per-agent 的，主 Agent 的帳號不會自動共用給其他 Agent。如果要共用，需手動複製 auth-profiles.json。

二、建立多 Agent 的兩種模式

模式 A：持久型 Agent（Persistent Agents）— 最常用

這些 Agent「永遠活著」，各自綁定到不同的通訊頻道或 bot 帳號。一個 Gateway 進程內可以跑多個隔離 Agent。

# 用精靈建立 Agent
openclaw agents add marketing
openclaw agents add developer
openclaw agents add support

# 確認
openclaw agents list --bindings

模式 B：Sub-Agent（子代理）— 任務型

由主 Agent 動態產生，執行完特定任務後自動歸檔。適合平行研究、批次處理等。

# 在對話中由 Agent 自行 spawn
/subagents spawn
# 或透過 sessions_spawn tool 由 orchestrator 自動觸發

實務建議：大多數場景用模式 A 就夠了。只有在需要平行處理（例如同時研究三個不同題目）時才考慮 Sub-Agent。

三、完整 openclaw.json 多 Agent 設定範例

{
  "env": {
    "OPENROUTER_API_KEY": "sk-or-v1-你的金鑰"
  },

  "gateway": {
    "bind": "127.0.0.1",     // 安全：永遠綁 localhost
    "port": 18789
  },

  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4-5",
        "fallbacks": ["openrouter/anthropic/claude-haiku-4-5"]
      },
      "maxConcurrent": 10    // 允許多個 session 同時處理（預設 main lane = 4）
    },

    "list": [
      {
        "id": "main",
        "default": true,
        "name": "主助理",
        "workspace": "~/.openclaw/workspace-main"
      },
      {
        "id": "marketing",
        "name": "行銷 Agent",
        "workspace": "~/.openclaw/workspace-marketing",
        "model": {
          "primary": "openrouter/anthropic/claude-sonnet-4-5"
        }
      },
      {
        "id": "developer",
        "name": "開發 Agent",
        "workspace": "~/.openclaw/workspace-dev",
        "model": {
          "primary": "openrouter/anthropic/claude-sonnet-4-5"
        }
      },
      {
        "id": "support",
        "name": "客服 Agent",
        "workspace": "~/.openclaw/workspace-support",
        "model": {
          "primary": "openrouter/anthropic/claude-haiku-4-5"
        },
        "tools": {
          "allow": ["read", "web_search"],
          "deny": ["exec", "write", "browser"]
        }
      },
      {
        "id": "researcher",
        "name": "研究 Agent",
        "workspace": "~/.openclaw/workspace-research",
        "model": {
          "primary": "openrouter/anthropic/claude-opus-4-6"
        }
      }
    ]
  }
}

四、Telegram 多 Bot 分工：核心架構

方法一：一個 Bot 對應一個 Agent（推薦）

這是官方文件和社群最推薦的做法。每個 Agent 透過 BotFather 建立一個獨立的 Telegram Bot。

步驟：

在 openclaw.json 設定 channels + bindings

到 BotFather 建立多個 Bot在 Telegram 搜尋 @BotFather，為每個 Agent 各建一個 bot：

/newbot → TentenMainBot      → 取得 token A
/newbot → TentenMarketingBot → 取得 token B
/newbot → TentenDevBot       → 取得 token C
/newbot → TentenSupportBot   → 取得 token D
/newbot → TentenResearchBot  → 取得 token E

{
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "main_bot": {
          "botToken": "TOKEN_A",
          "dmPolicy": "pairing"       // 首次需配對
        },
        "marketing_bot": {
          "botToken": "TOKEN_B",
          "dmPolicy": "pairing"
        },
        "dev_bot": {
          "botToken": "TOKEN_C",
          "dmPolicy": "pairing"
        },
        "support_bot": {
          "botToken": "TOKEN_D",
          "dmPolicy": "pairing"
        },
        "research_bot": {
          "botToken": "TOKEN_E",
          "dmPolicy": "pairing"
        }
      }
    }
  },

  "bindings": [
    {
      "agentId": "main",
      "match": { "channel": "telegram", "accountId": "main_bot" }
    },
    {
      "agentId": "marketing",
      "match": { "channel": "telegram", "accountId": "marketing_bot" }
    },
    {
      "agentId": "developer",
      "match": { "channel": "telegram", "accountId": "dev_bot" }
    },
    {
      "agentId": "support",
      "match": { "channel": "telegram", "accountId": "support_bot" }
    },
    {
      "agentId": "researcher",
      "match": { "channel": "telegram", "accountId": "research_bot" }
    }
  ]
}

重啟並驗證

openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

配對

首次使用時，向每個 bot 發送一條訊息，它會回傳一個 pairing code：

openclaw pair <CODE>

配對完成後，建議把 dmPolicy 改為 "allowlist" 並加入你的 Telegram 數字 ID，防止他人使用。

方法二：一個 Bot + 多 Group 分流

如果不想建太多 bot，可以用一個 bot 但透過不同的 Telegram Group 來路由到不同 Agent：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "main_bot": {
          "botToken": "YOUR_SINGLE_BOT_TOKEN",
          "dmPolicy": "pairing"
        }
      },
      // Group 專屬設定
      "groups": {
        "*": { "requireMention": true },               // 預設需要 @mention
        "-100XXXXXXXXX1": { "requireMention": false },  // 行銷群組免 @
        "-100XXXXXXXXX2": { "requireMention": false }   // 開發群組免 @
      }
    }
  },

  "bindings": [
    {
      "agentId": "marketing",
      "match": {
        "channel": "telegram",
        "accountId": "main_bot",
        "peer": { "kind": "group", "id": "-100XXXXXXXXX1" }
      }
    },
    {
      // ⚠️ Telegram 的群組可能被識別為 "group" 或 "channel"，兩者都要設定
      "agentId": "marketing",
      "match": {
        "channel": "telegram",
        "accountId": "main_bot",
        "peer": { "kind": "channel", "id": "-100XXXXXXXXX1" }
      }
    },
    {
      "agentId": "developer",
      "match": {
        "channel": "telegram",
        "accountId": "main_bot",
        "peer": { "kind": "group", "id": "-100XXXXXXXXX2" }
      }
    },
    {
      "agentId": "developer",
      "match": {
        "channel": "telegram",
        "accountId": "main_bot",
        "peer": { "kind": "channel", "id": "-100XXXXXXXXX2" }
      }
    },
    {
      // DM 預設走主 Agent
      "agentId": "main",
      "match": { "channel": "telegram", "accountId": "main_bot" }
    }
  ]
}

取得 Group ID 的方法：把 bot 加入群組，發一條訊息，然後 openclaw logs --follow 看日誌裡的 chat ID。

方法��：混合式（DM + Group 同時用）

最靈活的做法，結合方法一和方法二：

DM 各個 Bot → 做為私人對話頻道，一對一和特定 Agent 互動
共用群組 → 多個 Agent 共存，靠 @mention 或 group binding 來路由

五、Binding 路由規則（優先順序）

OpenClaw 的路由是確定性的，最具體的規則優先：

優先順序	匹配條件	說明
1（最高）	`peer`（精確 DM/群組/頻道 ID）	特定對話 → 特定 Agent
2	`parentPeer`（Thread 繼承）	Discord/Telegram thread
3	`guildId + roles`	Discord 角色路由
4	`guildId`	Discord server
5	`teamId`	Slack workspace
6	`accountId`（精確匹配）	特定 bot 帳號
7	`accountId: "*"`	該 channel 的所有帳號
8（最低）	fallback	預設 Agent（`default: true`）

注意：同一層級有多個匹配時，config 裡先出現的優先。多個 match 欄位同時設定時是 AND 邏輯。

六、每個 Agent 的 Workspace 設定

每個 Agent 的 workspace 目錄結構：

~/.openclaw/workspace-marketing/
├── SOUL.md        # 人設：誰、個性、行為準則
├── AGENTS.md      # 能力定義：能做什麼、不能做什麼
├── USER.md        # 使用者資訊：偏好、常用指令
├── TOOLS.md       # 工具設定：允許/禁止的工具
├── MEMORY.md      # 長期記憶：重要知識和歷史決策
├── HEARTBEAT.md   # 排程任務：定期自動執行的事項
├── IDENTITY.md    # 對外名稱、emoji、語氣
└── skills/        # Agent 專屬 skills

範例 — 行銷 Agent 的 SOUL.md：

# Soul

## 核心身份
你是 Tenten 工作室的資深數位行銷專家，專精 Meta Ads、Google Ads、SEO 內容策略。

## 語言規則
- 客戶面向：繁體中文
- 內部技術討論：英文可接受
- 數據報告：中英混合

## 行為準則
- 所有建議基於數據，引用具體指標
- 先分析再建議，避免空泛意見
- 了解台灣市場特性和消費者行為
- 熟悉 Shopify 電商生態

## 工具使用
- 可以搜尋網頁取得最新廣告政策
- 可以查詢 GA4 數據（透過 MCP）
- 不得擅自修改廣告設定，需先回報

七、已知問題與解決方案

問題 1：多 Telegram Bot 只有預設帳號收到訊息

這是 2026 年 2 月回報的已知 Bug（GitHub Issue #19000）。第二個 bot 帳號雖然收到 Telegram API 的更新，但訊息沒有被正確路由到綁定的 Agent。

暫時解決方案：

方案 A：用方法二（一個 bot + 多 group 分流）替代多 bot
方案 B：跑多個 Gateway 進程，每個綁一個 bot（犧牲一點資源但穩定）
持續追蹤：關注 Issue #19000 的修復進度

問題 2：多 Agent 同時收訊息的串行瓶頸

GitHub Issue #16055 指出，所有訊息預設走同一個 main lane 佇列，即使設了 maxConcurrent: 100，main lane 預設只處理 4 個同時連線。

解決方案：

{
  "agents": {
    "defaults": {
      "maxConcurrent": 20,      // 提高主佇列並行上限
      "subagents": {
        "maxConcurrent": 20
      }
    }
  }
}

若瓶頸仍在，考慮跑 2 個 Gateway 進程分擔負載。

問題 3：BotFather Group Privacy 導致群組訊息消失

Telegram Bot 預設開啟 Privacy Mode，在群組裡只能看到被 @mention 的訊息。

修復：BotFather → /mybots → Bot Settings → Group Privacy → OFF

問題 4：Telegram 群組的 peer.kind 不一致

同一個群組可能被識別為 "group" 或 "channel"，所以 binding 要同時設定兩種：

[
  { "agentId": "dev", "match": { "peer": { "kind": "group", "id": "-100XXX" } } },
  { "agentId": "dev", "match": { "peer": { "kind": "channel", "id": "-100XXX" } } }
]

八、安全最佳實踐

Gateway 永遠綁 127.0.0.1：遠端存取用 Tailscale VPN，不要 0.0.0.0
dmPolicy 用 allowlist：配對完成後立即切換，只允許你的 Telegram ID
Agent 權限最小化：客服 Agent 不給 exec/write，開發 Agent 才給完整權限
不要共用 agentDir：會造成 auth/session 衝突
審核第三方 Skills：2026 初有惡意 Skills 進入公開 registry 的案例，安裝前務必檢查 SKILL.md 和腳本內容
Bot Token 安全：不要 commit 到 git，不要放在公開文件裡

# 鎖定權限
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/agents/*/agent/

九、模型分層策略（成本最佳化）

Agent 角色	推薦模型	原因
日常對話 / 客服	Claude Haiku 4.5	便宜快速，簡單任務足夠
行銷 / 企劃	Claude Sonnet 4.5	品質與成本平衡
開發 / 架構	Claude Sonnet 4.5	程式碼品質好，延遲可接受
深度研究 / 分析	Claude Opus 4.6	最強推理，用於重要決策
批量處理	GLM-4.7-Flash / MiniMax M2.5	極低成本，適合大量簡單任務

十、資源需求（API 模式）

在純 API 模式下（不跑本地模型），OpenClaw 本身非常輕量：

指標	單 Agent	5 Agent	10 Agent
RAM	~50-80MB	~250-400MB	~500-800MB
CPU	極低	低	低
磁碟	~50MB	~250MB	~500MB

Mac Mini M4 16GB 跑 10-20 個 API Agent 完全沒問題。真正的瓶頸在 OpenRouter 的 rate limit 和 API 費用。

十一、快速啟動檢查清單

[ ] 1. 安裝 OpenClaw：npm install -g openclaw@latest && openclaw onboard
[ ] 2. 設定 OpenRouter API Key
[ ] 3. 到 BotFather 為每個 Agent 建立 Telegram Bot
[ ] 4. 執行 openclaw agents add <name> 建立各 Agent
[ ] 5. 為每個 Agent 建立 SOUL.md + AGENTS.md
[ ] 6. 在 openclaw.json 設定 channels.telegram.accounts（每個 bot token）
[ ] 7. 在 openclaw.json 設定 bindings（accountId → agentId 對應）
[ ] 8. openclaw gateway restart
[ ] 9. openclaw agents list --bindings（確認路由正確）
[ ] 10. openclaw channels status --probe（確認 bot 連線正常）
[ ] 11. 向每個 bot 發訊息 → 完成配對（openclaw pair <CODE>）
[ ] 12. 切換 dmPolicy 為 allowlist + 你的 Telegram ID
[ ] 13. 鎖定檔案權限（chmod 600/700）
[ ] 14. 開始使用！

十二、參考資源

官方多 Agent 文件：https://docs.openclaw.ai/concepts/multi-agent
官方 Telegram 設定：https://docs.openclaw.ai/channels/telegram
社群多 Agent 教學：https://lumadock.com/tutorials/openclaw-multi-agent-setup
社群一鍵多 Agent 套件（9 Agent）：https://github.com/shenhao-stu/openclaw-agents
多 Telegram Bot 實戰：https://dev.to/onin/one-openclaw-gateway-multiple-isolated-ai-assistants-one-telegram-bot-per-worker-3k97
Telegram 群組路由實戰（中文影片）：https://zerofuturetech.substack.com/p/build-a-multi-agent-openclaw-team
已知 Bug — 多帳號路由：https://github.com/openclaw/openclaw/issues/19000
已知 Bug — 並行瓶頸：https://github.com/openclaw/openclaw/issues/16055

延伸閱讀：

I'm a Full Stack Developer with expertise in building modern web applications that fast, secure, and scalable. Crafting seamless user experiences with a passion for headless CMS, Vercel and Cloudflare