Codex 多智能體實戰：從架構設計到高階落地策略

在多智能體（Multi-Agent）開發逐漸成為主流的情境下，許多開發者一開始會直覺認為：只要把任務拆分、同時執行，就能大幅提升效率。

但真正落地後，很快會發現問題並不在「並行能力」，而是在系統可控性。

常見的失控現象包含：

• Token 使用量急遽上升，成本難以預測
• 上下文快速膨脹，模型回應品質下降
• 任務狀態分散，各 Agent 輸出無法整合
• 多個 Agent 各自修改同一批檔案，最後難以 merge

因此，多智能體系統的真正核心並非「速度」，而是三個關鍵能力：

• 控制成本
• 控制狀態
• 控制依賴關係

本文整理自 X@BTCqzy1，有興趣可以前往觀看原文

一、核心架構：多 Agent 是一個 DAG 調度問題

多智能體系統本質上不是多個 AI 同時聊天，而是一個任務 DAG（Directed Acyclic Graph，有向無環圖）調度系統。每一個任務節點都有明確的依賴關係，只有前置任務完成後，後續任務才應該開始。

若沒有設計成 DAG，而是讓任務彼此互相依賴，就容易出現循環依賴、任務卡死、狀態無法收斂等問題。

Manager（指揮官）

Manager 是整個系統的核心控制點，負責拆解任務、安排順序、控管依賴關係，以及在最後整合成果。

它的重點不是親自寫所有程式碼，而是像調度器一樣決定：

• 哪些任務可以並行
• 哪些任務必須等待
• 哪些輸出可以被合併
• 哪些結果需要退回重做

也就是說：

Manager 本質是調度器，不是聊天機器人。

Subagent（執行器）

Subagent 是負責實際執行任務的角色，通常會依照專業領域拆分，例如：

• 前端 Agent：負責 UI、互動、頁面整合
• 後端 Agent：負責 API、資料庫、服務邏輯
• 測試 Agent：負責測試、驗證、品質控管

每個 Subagent 應該在獨立的環境中執行，並且只專注於自己的任務範圍。這樣才能避免彼此互相覆蓋程式碼，或因為共享太多上下文而導致狀態污染。

Harness（執行環境）

Harness 可以理解為多智能體系統的基礎設施層，負責讓 Agent 能安全、穩定、可控地執行任務。

它通常需要處理：

• 執行環境隔離
• 自動壓縮上下文
• 同步必要狀態
• 管控工具權限
• 記錄任務執行狀況

如果沒有 Harness，多 Agent 很容易變成「多個 AI 同時亂改專案」。因此 Harness 的角色，是把 Agent 從單純對話模型，變成可管理的執行單元。

二、正確的 config.toml 配置：穩定比高併發更重要

Codex 支援全域與專案級兩層配置：

• 全域配置：~/.codex/config.toml
• 專案配置：.codex/config.toml

一般來說，專案級配置優先於全域配置，這樣可以針對不同專案設定不同的 Agent 策略。

以下是一個基礎範例：

# ~/.codex/config.toml
model = "gpt-5.4"
model_reasoning_effort = "high"

model_auto_compact_token_limit = 80000

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[agents]
max_threads = 4
max_depth = 3
job_max_runtime_seconds = 600

[agents.backend]
description = "後端專家（API / DB）"
config_file = "./agents/backend.toml"

[agents.frontend]
description = "前端專家（UI / 互動）"
config_file = "./agents/frontend.toml"

[agents.tester]
description = "測試專家（品質控制）"
config_file = "./agents/tester.toml"

[mcp_servers.security-auditor]
command = "python3"
args = ["/path/to/audit_tool.py"]

這份配置的重點不在於「開最多 Agent」，而在於限制系統的執行邊界。

並發數：max_threads

[agents]
max_threads = 4

max_threads 決定同時能執行多少個 Agent 任務。

很多人會想把它開到很高，但實務上並發越高，不代表效率越好。當 Agent 數量增加時，Token 消耗、上下文同步成本、錯誤合併難度都會同步上升。

一般建議從 3～4 開始，這通常是比較穩定的甜點區間。

任務深度：max_depth

max_depth = 3

max_depth 用來限制任務可以被拆分的層級。

如果設得太高，Agent 可能會不斷把任務再拆成子任務，導致任務樹過深，最後變得難以管理。
如果設得太低，則可能無法處理稍微複雜的專案。

多數專案可以從 2～3 開始。

執行時間限制：job_max_runtime_seconds

job_max_runtime_seconds = 600

這個設定可以避免單一任務無限執行。

尤其在多 Agent 系統中，如果某個 Agent 卡住，可能會持續消耗 token、佔用 thread，甚至拖慢整個任務流程。因此每個 job 都應該設定最大執行時間。

MCP Server 設定

[mcp_servers.security-auditor]
command = "python3"
args = ["/path/to/audit_tool.py"]

MCP Server 讓 Agent 可以呼叫外部工具，例如安全掃描、測試執行、資料庫查詢或 API 驗證。

不過一旦開放工具能力，就必須特別注意權限控管。工具不是越多越好，而是要明確限制每個工具能做什麼、不能做什麼。

三、Master Prompt 模板：系統規格書，而不是一般提示詞

在多 Agent 系統中，Master Prompt 的角色不是單純告訴模型「請幫我完成任務」，而是要定義整個系統的運作規則。

Manager 的品質，基本上會決定整個多 Agent 系統的上限。

以下是範例：

### [PROJECT_NAME]

目標：[一句話說明問題]

技術棧：[React / FastAPI / PostgreSQL]

執行規則：
1. 必須用 git worktree 做物理隔離
2. 先完成 DB schema，再並行開發前後端
3. 所有模組通過 shared_schema.json 作為唯一契約
4. 子任務完成後必須 git commit，由 Manager 決策合併

輸出：
agent | branch | task

這份 Prompt 的重點是，它不是只描述需求，而是明確定義：

• 執行順序
• 隔離方式
• 共同契約
• 完成條件
• 輸出格式

如果 Prompt 寫不清楚，多 Agent 很容易各寫各的，最後變成三個看似完成、但完全無法整合的結果。

建議補充：加入衝突處理規則

可以在 Master Prompt 中加上：

衝突處理：
1. 若前後端 API 定義不一致，以 shared_schema.json 為準
2. 若資料表欄位與 API 回傳格式衝突，先停止並回報 Manager
3. 不允許 Subagent 自行修改 shared_schema.json，除非 Manager 指派

這樣可以避免每個 Agent 自行定義自己的版本。

四、Worktree 並行隔離：真正的關鍵不是模型，而是 Git

多智能體最核心的一步，其實不是模型選擇，而是隔離方式。

在同一個工作目錄中讓多個 Agent 同時修改檔案，很容易發生：

• 前端 Agent 改到後端檔案
• 後端 Agent 覆蓋前端修改
• 測試 Agent 還沒等功能完成就改測試
• 最後 merge 時衝突爆炸

因此建議用 git worktree 為每個 Agent 建立獨立工作區。

範例：

git worktree add -b feature/frontend-ui ../wt-frontend
git worktree add -b feature/backend-api ../wt-backend
git worktree add -b feature/auto-test ../wt-tester

這樣會建立三個獨立的 worktree：

../wt-frontend   # 前端 Agent 使用
../wt-backend    # 後端 Agent 使用
../wt-tester     # 測試 Agent 使用

為什麼用 Git 做物理隔離？

因為物理隔離比 prompt 約束可靠。

你可以在 prompt 裡要求 Agent「不要修改某些檔案」，但只要上下文理解錯誤，還是可能發生誤改。
而 worktree 則是從檔案系統與 Git 分支層面把任務隔開。

合併流程建議

每個 Agent 完成任務後，應先各自 commit：

cd ../wt-frontend
git add .
git commit -m "feat: implement frontend UI"

cd ../wt-backend
git add .
git commit -m "feat: implement backend API"

cd ../wt-tester
git add .
git commit -m "test: add integration tests"

最後由 Manager 決定合併順序：

git checkout main
git merge feature/backend-api
git merge feature/frontend-ui
git merge feature/auto-test

通常建議先合併底層契約與後端，再合併前端，最後合併測試。

五、MCP 工具實戰：工具鏈決定 Agent 是否真的能做事

Agent 是否真的能幹活，取決於工具鏈，而不是單純的模型能力。

如果 Agent 只能聊天，它只是顧問。
如果 Agent 能安全地執行測試、掃描程式碼、檢查 API、操作檔案，它才是真正的執行者。

以下是一個簡化的安全掃描工具範例：

import subprocess

def audit_code(path: str) -> str:
    if ".." in path or not path.startswith("./"):
        return "Error: Access Denied"

    result = subprocess.run(
        ["bandit", "-r", path],
        capture_output=True,
        text=True
    )

    return result.stdout

為什麼要做輸入過濾？

這段判斷很重要：

if ".." in path or not path.startswith("./"):
    return "Error: Access Denied"

它可以避免 Agent 傳入危險路徑，例如：

../../etc/passwd
/home/user/.ssh
/

更完整一點的安全寫法

可以再加上路徑正規化：

import subprocess
from pathlib import Path

BASE_DIR = Path("./").resolve()

def audit_code(path: str) -> str:
    target = (BASE_DIR / path).resolve()

    if not str(target).startswith(str(BASE_DIR)):
        return "Error: Access Denied"

    if not target.exists():
        return "Error: Path Not Found"

    result = subprocess.run(
        ["bandit", "-r", str(target)],
        capture_output=True,
        text=True,
        timeout=120
    )

    return result.stdout or result.stderr

這樣會比單純檢查 .. 更安全，因為有些路徑可以透過符號連結或特殊寫法繞過簡單判斷。

六、Token 優化：多 Agent 的真正瓶頸

大多數場景下，多 Agent 的主要瓶頸不是模型能力，而是上下文管理與成本控制。

當多個 Agent 同時執行時，每個 Agent 都需要自己的上下文。如果沒有管理好，很快就會遇到：

• 同一份程式碼被重複讀取
• 每個 Agent 都帶入過多無關資訊
• Token 成本成倍增加
• 模型開始忽略重要細節

增量上下文：只載入相關程式碼

不要把整個專案丟給 Agent，而是用搜尋工具定位相關檔案。

例如：

grep -R "userService" ./src
grep -R "createUser" ./app
grep -R "shared_schema" .

讓 Agent 先定位，再讀取必要片段，會比一次塞入整個專案更穩定。

文件切片：只讀必要區段

可以用 sed 讀取指定行數：

sed -n '1,200p' app/Http/Controllers/UserController.php
sed -n '200,400p' app/Http/Controllers/UserController.php

或用 grep -n 找到行號：

grep -n "function store" app/Http/Controllers/UserController.php

再讀取附近片段：

sed -n '80,160p' app/Http/Controllers/UserController.php

這樣可以降低上下文污染，也能讓 Agent 更專注。

自動壓縮：超出閾值後摘要

原本配置中這行：

model_auto_compact_token_limit = 80000

代表當上下文接近指定 token 閾值時，系統應該自動進行壓縮或摘要。

但摘要不能只是單純縮短文字，而應保留：

• 已完成任務
• 尚未完成任務
• 已做出的技術決策
• 目前分支與 commit 狀態
• 已知風險與阻塞點

建議摘要格式

[STATE SUMMARY]

已完成：
- backend API branch 已完成 user CRUD
- frontend UI branch 已完成列表與表單

目前契約：
- shared_schema.json 為唯一 API 契約
- User 欄位包含 id, name, email, created_at

待處理：
- tester branch 需補 integration test
- Manager 需合併 backend 後再合併 frontend

風險：
- frontend 目前假設 email 必填，需確認 schema

這種摘要可以讓狀態更容易收斂。

七、高階策略：讓多 Agent 系統真正可控

除了基本架構，實務上還需要額外設計幾個保護機制，避免系統在長時間執行後失控。

狀態收斂：每輪結束都要重新整理狀態

每次子任務完成後，Manager 應產出最新狀態摘要，而不是讓每個 Agent 繼續攜帶過長的歷史對話。

建議格式：

[ROUND CHECKPOINT]

Round: 2

完成任務：
- backend API 已 commit
- frontend UI 已 commit

下一步：
1. merge backend
2. 執行 migration
3. merge frontend
4. 執行測試 Agent

阻塞：
- 無

決策：
- shared_schema.json 不允許 Subagent 直接修改

這可以避免狀態越跑越亂。

任務快照：每個穩定階段都要保留回滾點

建議在重要階段建立 Git tag：

git tag checkpoint/schema-ready
git tag checkpoint/backend-ready
git tag checkpoint/frontend-ready

若後續合併失敗，可以快速回到已知穩定狀態：

git checkout checkpoint/backend-ready

成本護欄：Token 超標就停止

可以在規則中明確寫入：

成本限制：
1. 單一 Agent 不得讀取超過 10 個檔案，除非 Manager 批准
2. 若上下文超過限制，必須先輸出摘要再繼續
3. 若任務需要大量重寫，必須先回報原因

這類規則能有效避免 Agent 一路消耗 token 卻沒有產出。

結語：單 Agent 拼 Prompt，多 Agent 拼架構

多 Agent 開發的本質不是模型能力競賽，而是系統工程。

成熟的 Codex 多智能體系統應該具備：

• 清楚的 DAG 任務結構
• 明確的 Manager / Subagent / Harness 分工
• 使用 git worktree 做物理隔離
• 使用 shared schema 作為唯一契約
• MCP 工具要有嚴格輸入驗證
• Token 與上下文必須可控
• 每一輪都要有 checkpoint 與狀態摘要

最後可以用一句話總結：

單 Agent 拼的是 Prompt，多 Agent 拼的是架構與治理能力。