[ai/08-2] MCP 整合與多 Agent 工作流：實戰配置指南

cover

先講結論

上篇講了 CLAUDE.md、Skills、Memory 這些「單人模式」的配置。這篇要進入「連線模式」——讓 AI 接上外部工具（MCP）、統一管理多個 AI client（Gateway），以及讓多個 Agent 一起幹活。

三個重點：

MCP — 讓 AI 直接操作 Notion、Gmail 等外部服務，不用再當人肉搬運工
Gateway — 多個 AI client 共用一個 API 入口，集中管理 key 和 rate limit
多 Agent — 把任務拆給不同 Agent 並行處理，適合大型重構或跨模組功能

如果你還沒看上篇，建議先讀 AI 工具最佳配置。

MCP：AI 的外掛系統

MCP（Model Context Protocol）就是 AI 的標準化工具介面。概念不難，但實戰有坑。

# 安裝 mcporter（MCP server 管理工具）
npm i -g mcporter
 
# 列出已配置的 MCP server
mcporter list
 
# 呼叫 Notion API
mcporter call notion notion_search '{"query": "blog"}'
 
# 呼叫 Gmail API
mcporter call gmail gmail_search_messages '{"query": "from:github.com"}'

Notion MCP 常用操作速查：

操作	工具名稱	用途
搜尋	`notion_search`	全域搜尋 page/database
讀取	`notion_get_page`	取得特定 page 內容
查詢	`notion_query_database`	查詢 database 記錄
建立	`notion_create_page`	新建 page

MCP 最大的坑：Context 爆炸

這是我花了一整個下午才搞懂的教訓。Notion API 回傳的 JSON 冗長到離譜，8 次 mcporter 呼叫就能塞滿 2.4MB 的 session context，然後你就會看到美麗的 context_length_exceeded 錯誤。

怎麼解？

❌ 直接把 API response 放 context
   → 呼叫 8 次 → context 爆炸 → 整個對話作廢

✅ 只提取需要的欄位，立即寫入檔案
   1. 呼叫 API
   2. 只取 title + id
   3. 寫入 ~/tmp/notion-results.json
   4. Context 裡只留「已寫入檔案，共 24 筆」

你可能會想「有這麼誇張嗎？」——有，而且不只 Notion。任何會回傳大量 JSON 的 API 都一樣。養成習慣：API response 進檔案，context 留摘要。

Gateway：API 的統一入口

當你有 Claude Code、Discord Bot、自動化腳本同時要呼叫 LLM，讓它們各自管理 API key 是找死的行為。Gateway 解決這個問題：

Claude Code ──┐
Discord Bot ──┼──→ Gateway(:18789) ──→ LLM Provider
自動化腳本 ──┘

好處很直覺：API key 集中管理、模型路由、成本監控、rate limit 統一處理。

配置長這樣：

// openclaw.json（關鍵設定）
{
  "gateway": {
    "port": 18789,
    "model": "openai-codex/gpt-5.2-codex"
  },
  "agents": {
    "defaults": {
      "heartbeat": {
        "interval": "30m",
        "activeHours": "08:00-23:00",
        "timezone": "Asia/Taipei"
      }
    }
  }
}

Gateway 踩坑三連

問題	原因	解法
大量 429 errors	設了 Google model fallback，兩個 provider 互搶配額	統一用同一個 model，不設 fallback
Gateway 無法啟動	Service mode 有 bug	用 `pnpm openclaw gateway`（direct mode）
Session 越來越慢	sessions.json 累積太多舊資料	定期寫入 `{}` 清空

那個 429 的問題我 debug 了快一天。一開始以為是 rate limit 太低，結果是自己設了 fallback model 導致兩個 provider 同時被打爆。~~有時候問題的根源就是你自己的聰明才智。~~

多 Agent：什麼時候該用

先問自己一個問題：這個任務能拆成 3 個以上獨立的子任務嗎？如果不能，用單 Agent 就好，別為了用而用。

場景	為什麼需要多 Agent
大型重構	一個分析、一個修改、一個測試
跨模組功能	前端 + 後端 + 測試並行
內容規劃	一個審計、一個寫文章、一個修 backlink

注意事項——這些是真的會咬你的：

每個 Agent 的 context 獨立，不共享對話歷史
Agent 之間靠 SendMessage 通訊，有延遲
Windows 上 Agent 的檔案編輯需要權限確認（瓶頸）
Team 控制在 3-5 個 Agent，再多協調成本超過收益

Discord Bot 當 AI 介面的眉角

如果你跟我一樣用 Discord Bot 作為 Agent 入口，system prompt 的設計決定了它是「好用的助手」還是「會搞破壞的實習生」。

必須包含的資訊：

執行環境（Windows 11, NOT Docker——這點不寫清楚 Agent 會亂用 Linux 語法）
所有檔案的完整路徑
Shell 規則（禁 bash heredoc、禁 wrapper script）
Context 管理（定期摘要、清理舊 session）

我曾經讓 Bot 的 session 膨脹到 166K tokens，然後它就開始每次 heartbeat 都回覆「一切正常」卻什麼事都不做。~~就跟某些同事一樣。~~

Windows 上的特殊地雷

在 Windows 上用 AI 工具有幾個獨特的坑，不碰不知道，碰了想哭：

問題	說明	解法
Git Bash flag mangling	`/FI` 被轉成 `C:/Program Files/...`	用 `powershell -Command "..."`
路徑分隔符	`\` vs `/` 混用	CLAUDE.md 裡明確指定格式
Shell 語法衝突	Bash heredoc 在 PowerShell 不能用	統一用 PowerShell
taskkill 被 mangle	Git Bash 會破壞 `/PID` flag	`powershell -Command "Stop-Process -Id PID -Force"`

配置同步策略

最後一個實用的表：

配置類型	同步方式	說明
CLAUDE.md	Git	跟著 repo 走，團隊共享
Skills	Git 或本地	通用的放 repo，個人的放 `~/.claude/`
Memory	本地	個人化，不適合共享
settings.json	本地	機器特定的全域設定

Terry Yao's Blog

分類

目錄