如果你已經(jīng)用了一段時(shí)間 OpenClaw，肯定會遇到這樣的需求：我需要一個(gè)專門寫博客的 AI 助手，一個(gè)寫小說的，一個(gè)做代碼開發(fā)的……每個(gè)都有獨(dú)立的角色定位、工作目錄和配置。這就是多 Agent 配置要解決的問題。

本文不是理論教程，而是實(shí)戰(zhàn)踩坑記錄。我會告訴你配置過程中會遇到哪些坑，為什么會踩坑，以及怎么避免和解決。

為什么需要多 Agent

場景隔離。不同的工作場景需要不同的 AI 助手：

• 博客助手：專注于技術(shù)寫作，熟悉你的博客部署流程，有獨(dú)立的文章草稿目錄
• 小說助手：創(chuàng)意寫作風(fēng)格，管理小說章節(jié)和人物設(shè)定，不需要訪問技術(shù)代碼
• 開發(fā)助手：熟悉代碼規(guī)范，可以執(zhí)行敏感命令，但不應(yīng)該訪問私人筆記
• 家庭助手：綁定到家庭 WhatsApp 群，只能訪問受限的工具集，保護(hù)隱私

獨(dú)立配置。每個(gè) Agent 有自己的：

• Workspace：獨(dú)立的工作目錄，互不干擾
• SOUL.md：獨(dú)立的角色定位和性格設(shè)定
• Model：可以給不同 Agent 配置不同模型（Opus 做深度思考，Sonnet 做日常聊天）
• Tool Policy：限制某些 Agent 的工具權(quán)限（比如家庭助手不能執(zhí)行 shell 命令）

賬號路由。多個(gè) Telegram bot 或 WhatsApp 賬號，路由到不同的 Agent，一個(gè) Gateway 管理所有賬號。

舉個(gè)例子，你可能會配置這樣的 Agent：

• main：日常聊天，全功能
• work：工作場景，可以訪問項(xiàng)目文檔
• creative：創(chuàng)作助手，專注于寫作
• coding：開發(fā)助手，執(zhí)行代碼相關(guān)任務(wù)

多 Agent 配置流程

1. 創(chuàng)建 Agent

# 創(chuàng)建一個(gè)新 Agent
openclaw agents add blog --workspace ~/.openclaw/workspace-blog
# 驗(yàn)證創(chuàng)建結(jié)果
openclaw agents list

這會在配置文件中添加：

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        workspace: "~/.openclaw/workspace",
      },
      {
        id: "blog",
        workspace: "~/.openclaw/workspace-blog",
      },
    ],
  },
}

2. 設(shè)置模型

?? 第一個(gè)坑：模型 ID 格式

配置模型時(shí)，要用別名，不要帶日期后綴！

# ? 正確：使用別名
openclaw config patch agents.list.1.model "anthropic/claude-sonnet-4-5"
# ? 錯誤：帶日期后綴的完整 ID
openclaw config patch agents.list.1.model "anthropic/claude-sonnet-4-20250514"

為什么？

帶日期的 ID 會在新版本發(fā)布時(shí)失效。別名（如 claude-sonnet-4-5）會自動指向最新版本。

驗(yàn)證配置：

openclaw config get agents.list.1.model
# 應(yīng)該輸出：anthropic/claude-sonnet-4-5

3. 編寫 SOUL.md 定義角色

每個(gè) Agent 的 workspace 下創(chuàng)建 SOUL.md，定義它的角色：

cd ~/.openclaw/workspace-blog

創(chuàng)建 SOUL.md：

# SOUL.md - 工作助手
你是工作助手，幫助處理日常工作任務(wù)。
## 角色定位
- 專注于工作場景，風(fēng)格專業(yè)高效
- 熟悉常用開發(fā)工具和工作流程
- 所有重要操作需要確認(rèn)后執(zhí)行
## 工作流程
1. 接收任務(wù)需求
2. 分析任務(wù)并制定執(zhí)行計(jì)劃
3. 執(zhí)行任務(wù)
4. 匯報(bào)結(jié)果
## 工作規(guī)范
- 代碼示例要完整可用
- 文檔結(jié)構(gòu)清晰
- 操作前確認(rèn)權(quán)限

?? 第二個(gè)坑：不要創(chuàng)建 BOOTSTRAP.md

如果你手動創(chuàng)建了 BOOTSTRAP.md，Agent 會一直卡在 bootstrapping 狀態(tài)！

為什么？

BOOTSTRAP.md 是 Agent 的"初始化任務(wù)清單"。Agent 啟動后會執(zhí)行里面的指令，執(zhí)行完才會刪除這個(gè)文件。如果你手動創(chuàng)建了這個(gè)文件但內(nèi)容不完整，Agent 會不斷嘗試執(zhí)行，永遠(yuǎn)無法進(jìn)入正常狀態(tài)。

解決方法：

# 如果發(fā)現(xiàn) Agent 卡住了，檢查是否有 BOOTSTRAP.md
ls ~/.openclaw/workspace-blog/BOOTSTRAP.md
# 如果存在，直接刪除
rm ~/.openclaw/workspace-blog/BOOTSTRAP.md
# 重啟 Gateway
openclaw gateway restart

4. 測試 Agent

# 列出所有 Agent
openclaw agents list
# 查看 Agent 詳細(xì)配置
openclaw config get agents.list.1
# 重啟 Gateway 讓配置生效
openclaw gateway restart

Telegram 多賬號配置

多 Agent 的典型用法是配置多個(gè) Telegram bot，每個(gè) bot 路由到不同的 Agent。

1. 創(chuàng)建 Telegram Bot

在 Telegram 找 @BotFather，創(chuàng)建 bot：

/newbot

按提示輸入名稱和用戶名，獲得 token（類似 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz）。

假設(shè)你創(chuàng)建了兩個(gè) bot：

• @MyMainBot → token1
• @MyWorkBot → token2

2. 配置多賬號

編輯 ~/.openclaw/openclaw.json（或用 openclaw config patch）：

{
  channels: {
    telegram: {
      accounts: {
        main: {
          token: "token1",
          dmPolicy: "allowlist",
          allowFrom: ["123456789"], // 你的 Telegram user ID
        },
        blog: {
          token: "token2",
          dmPolicy: "allowlist",
          allowFrom: ["123456789"],
        },
      },
    },
  },
}

?? 第三個(gè)坑：dmPolicy 默認(rèn)值

如果不設(shè)置 dmPolicy，默認(rèn)是 pairing，這意味著用戶必須先執(zhí)行 /pair 命令才能聊天。但如果配置有問題，/pair 可能也不會響應(yīng)，消息會被靜默丟棄！

解決方法：

明確設(shè)置 dmPolicy: "allowlist"，并配置 allowFrom 列表：

{
  dmPolicy: "allowlist",
  allowFrom: ["123456789", "987654321"], // 允許的 user ID 列表
}

獲取你的 Telegram user ID：給 @userinfobot 發(fā)消息。

3. 配置路由規(guī)則

添加 bindings 將不同的 Telegram 賬號路由到不同的 Agent：

{
  bindings: [
    {
      agentId: "main",
      match: { channel: "telegram", accountId: "main" },
    },
    {
      agentId: "blog",
      match: { channel: "telegram", accountId: "blog" },
    },
  ],
}

路由規(guī)則優(yōu)先級：

1. peer 精確匹配（具體的 DM 或群組 ID）
2. accountId 匹配（哪個(gè) Telegram 賬號）
3. channel 匹配（哪個(gè)平臺）
4. 默認(rèn) Agent（default: true 或列表中第一個(gè)）

4. 重啟 Gateway

openclaw gateway restart --reason "添加新 Telegram bot"

測試：給兩個(gè) bot 發(fā) /start，應(yīng)該分別收到來自不同 Agent 的回復(fù)。

常見問題與解決

問題 1：config.patch 把配置沖掉了

現(xiàn)象：

我想給 telegram.accounts 添加一個(gè)新賬號，執(zhí)行：

openclaw config patch channels.telegram.accounts.blog '{"token":"xxx"}'

結(jié)果其他賬號的配置全沒了！

原因：

config.patch 對嵌套對象是整體替換，不是增量修改！

如果配置是：

{
  channels: {
    telegram: {
      accounts: {
        main: {...},
        novel: {...},
      },
    },
  },
}

執(zhí)行 patch channels.telegram.accounts.blog {...} 會導(dǎo)致：

{
  channels: {
    telegram: {
      accounts: {
        blog: {...}, // 只剩這一個(gè)！
      },
    },
  },
}

解決方法：

patch 時(shí)帶上完整的對象：

# ? 錯誤：只 patch 一個(gè)子項(xiàng)
openclaw config patch channels.telegram.accounts.blog '{"token":"xxx"}'
# ? 正確：patch 整個(gè) accounts 對象
openclaw config patch channels.telegram.accounts '{
  "main": {"token":"token1", "dmPolicy":"allowlist", "allowFrom":["123456789"]},
  "blog": {"token":"token2", "dmPolicy":"allowlist", "allowFrom":["123456789"]}
}'

同樣適用于 bindings、agents.list 等數(shù)組或?qū)ο蟆?/p>

最佳實(shí)踐：

配置變更前，先導(dǎo)出當(dāng)前配置：

# 導(dǎo)出當(dāng)前配置
openclaw config get channels.telegram.accounts > telegram-accounts-backup.json
# 編輯后再 patch 回去
openclaw config patch channels.telegram.accounts "$(cat telegram-accounts-edited.json)"

問題 2：Telegram bot 不響應(yīng)消息

現(xiàn)象：

給 bot 發(fā) /start 或任何消息，都沒有回復(fù)。

可能的原因 1：dmPolicy 配置問題

檢查配置：

openclaw config get channels.telegram.accounts.blog.dmPolicy

如果是 pairing 或未設(shè)置，改成 allowlist：

openclaw config patch channels.telegram.accounts.blog.dmPolicy '"allowlist"'
openclaw config patch channels.telegram.accounts.blog.allowFrom '["123456789"]'
openclaw gateway restart

可能的原因 2：Telegram 409 沖突

癥狀： 日志中有 getUpdates conflict (409) 錯誤。

原因： 同一個(gè) bot token 被多個(gè)實(shí)例同時(shí)使用！常見場景：

• OpenClaw.app (GUI) 和 CLI gateway 同時(shí)運(yùn)行
• 兩個(gè) terminal 同時(shí)啟動了 gateway

檢查：

ps aux | grep -i openclaw

如果看到多個(gè)進(jìn)程（GUI app 和 CLI gateway），說明沖突了。

解決方法：

1. 退出 OpenClaw.app (GUI)
2. 重啟 CLI gateway：

openclaw gateway restart --reason "清除 Telegram bot 沖突"

教訓(xùn)：

同一個(gè) Telegram bot token 只能被一個(gè) Gateway 實(shí)例使用。如果要切換 GUI/CLI，必須先停掉其中一個(gè)。

問題 3：綁定規(guī)則不生效

現(xiàn)象：

配置了 bindings，但消息還是路由到了錯誤的 Agent。

檢查綁定：

openclaw agents list --bindings

常見錯誤：

1. 順序錯誤：更具體的規(guī)則要放在前面

// ? 錯誤：通配規(guī)則在前，精確規(guī)則在后
bindings: [
  { agentId: "main", match: { channel: "telegram" } }, // 會匹配所有 telegram 消息
  { agentId: "blog", match: { channel: "telegram", accountId: "blog" } }, // 永遠(yuǎn)不會執(zhí)行
]
// ? 正確：精確規(guī)則在前
bindings: [
  { agentId: "blog", match: { channel: "telegram", accountId: "blog" } },
  { agentId: "main", match: { channel: "telegram", accountId: "main" } },
]

2. accountId 拼寫錯誤：檢查是否與 channels.telegram.accounts 中的 key 一致

# 列出所有配置的賬號
openclaw config get channels.telegram.accounts | jq 'keys'

問題 4：Agent 配置變更后不生效

解決方法：

Gateway 需要重啟才能加載新配置：

openclaw gateway restart --reason "更新 Agent 配置"

檢查 Agent 是否正常啟動：

openclaw status --deep

如果看到某個(gè) Agent 狀態(tài)異常，查看日志：

tail -n 100 ~/.openclaw/gateway.err.log

問題 5：配置了嵌套對象，但只有部分生效

現(xiàn)象：

我在頂層配置了 channels.telegram.dmPolicy，為什么某個(gè)賬號還是用了不同的策略？

原因：

配置有繼承關(guān)系，account 級別的配置會覆蓋頂層配置：

{
  channels: {
    telegram: {
      dmPolicy: "allowlist", // 頂層默認(rèn)
      allowFrom: ["123456789"],
      accounts: {
        main: {
          token: "token1",
          // 繼承頂層的 dmPolicy 和 allowFrom
        },
        public: {
          token: "token2",
          dmPolicy: "pairing", // 覆蓋頂層配置
        },
      },
    },
  },
}

最佳實(shí)踐：

• 如果所有賬號都用相同策略，配置在頂層
• 如果某個(gè)賬號需要不同策略，在 account 級別覆蓋
• 明確寫出每個(gè) account 的 dmPolicy，避免繼承混淆

最佳實(shí)踐

1. 配置變更前先審查

教訓(xùn)： 我曾因?yàn)闆]仔細(xì)審查 patch 命令，把所有 Telegram 賬號配置沖掉，導(dǎo)致所有 bot 連接中斷。

規(guī)則：

• 任何 config.patch、gateway restart、模型變更等操作，先審查一遍
• 嵌套對象（bindings、accounts）必須帶完整列表
• 有疑問先導(dǎo)出當(dāng)前配置對比

# 變更前備份
openclaw config get > openclaw-config-backup.json
# 變更后對比
openclaw config get > openclaw-config-new.json
diff openclaw-config-backup.json openclaw-config-new.json

2. 使用 status --deep 診斷

openclaw status --deep

輸出包括：

• 每個(gè) Agent 的狀態(tài)
• Channel 連接狀態(tài)
• 最近的錯誤日志

如果某個(gè) Agent 或 Channel 異常，會直接顯示。

3. 查看錯誤日志

# 實(shí)時(shí)查看日志
tail -f ~/.openclaw/gateway.err.log
# 搜索特定錯誤
grep -i "error\|conflict\|fail" ~/.openclaw/gateway.err.log | tail -n 50

常見錯誤關(guān)鍵詞：

• 409 conflict：Telegram bot 沖突
• unauthorized：token 錯誤或過期
• dmPolicy：消息被訪問控制策略攔截
• binding：路由規(guī)則問題

4. 分階段配置

不要一次性配置所有 Agent 和 Channel，容易出錯且難以排查。

推薦流程：

1. 先配置一個(gè)新 Agent（不配置 Telegram），本地測試
2. Agent 正常后，添加一個(gè) Telegram bot，測試路由
3. 驗(yàn)證通過后，再添加其他 Agent 和 bot
4. 每次變更后，驗(yàn)證所有已有功能正常

5. 文檔化你的配置

在 workspace 下創(chuàng)建 SETUP.md，記錄：

• 每個(gè) Agent 的用途和配置
• Telegram bot 對應(yīng)關(guān)系
• 特殊配置的原因

# SETUP.md
## Agents
- main: 日常聊天，全功能，Telegram @MyMainBot
- blog: 技術(shù)寫作，workspace-blog，Telegram @MyWorkBot
- novel: 小說創(chuàng)作，workspace-novel，僅本地使用
## Telegram Bots
- @MyMainBot (123456789): main agent
- @MyWorkBot (987654321): work agent
## 特殊配置
- work agent 的 dmPolicy 設(shè)為 allowlist，只允許授權(quán)用戶訪問
- main agent 啟用了 heartbeat，定期檢查日程

總結(jié)

OpenClaw 多 Agent 配置不復(fù)雜，但有幾個(gè)容易踩的坑：

1. config.patch 陷阱：嵌套對象是整體替換，不是增量修改
2. 模型 ID：用別名（claude-sonnet-4-5），不要帶日期
3. BOOTSTRAP.md：不要手動創(chuàng)建，會導(dǎo)致 Agent 卡住
4. dmPolicy：默認(rèn)是 pairing，建議改成 allowlist
5. Telegram 409：同一個(gè) bot token 只能被一個(gè) Gateway 使用
6. 配置繼承：account 級別配置會覆蓋頂層配置

核心原則：

• 配置前先備份
• 變更后先驗(yàn)證
• 出問題先看日志
• 分階段逐步配置

到此這篇關(guān)于OpenClaw多Agent配置實(shí)戰(zhàn)及踩坑指南的文章就介紹到這了,更多相關(guān)OpenClaw多Agent配置內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評論