460 lines
12 KiB
Markdown
460 lines
12 KiB
Markdown
# OpenClaw 多代理 Config 草案（2026-04-07）
|
||
|
||
本文件是把前面確認過的流程設計，轉成可實際落地的 OpenClaw 設定草案。
|
||
|
||
目標不是立刻套用，而是先把：
|
||
- agent 名單
|
||
- workspace 規劃
|
||
- 權限邊界
|
||
- agent-to-agent 允許圖
|
||
- session 可見性
|
||
- 模型配置
|
||
|
||
整理成一份可審、可再修的正式草案。
|
||
|
||
---
|
||
|
||
## 1. 設計原則
|
||
|
||
### 1.1 唯一入口
|
||
- Eric 總管只對 **Eve / coder 主會話** 下旨
|
||
- 不直接與下游功能型 agent 對話
|
||
|
||
### 1.2 下游只對 Eve 回報
|
||
- `prompt-optimizer`
|
||
- `reviewer`
|
||
- `research`
|
||
- `engineering`
|
||
- `ops`
|
||
|
||
以上 5 個 agent 都只接受 Eve 派工，並只向 Eve 回報。
|
||
|
||
### 1.3 不做過重 routing
|
||
第一版不做複雜朝廷式多層 routing，也不讓 Telegram 直接綁到其他 agent。
|
||
|
||
### 1.4 強調防失聯
|
||
- 任務可失敗，但不可失聯
|
||
- 任務可中斷，但不可無聲中斷
|
||
- Eve 必須是持續追蹤與回報者
|
||
|
||
---
|
||
|
||
## 2. Agent 清單草案
|
||
|
||
建議第一版 agent list：
|
||
|
||
1. `coder`（Eve 主會話）
|
||
2. `prompt-optimizer`
|
||
3. `reviewer`
|
||
4. `research`
|
||
5. `engineering`
|
||
6. `ops`
|
||
|
||
### 2.1 各 agent 定位
|
||
- `coder`：Eve，本體／總調度
|
||
- `prompt-optimizer`：整理執行版任務單
|
||
- `reviewer`：驗收與複核
|
||
- `research`：查找、比較、整理研究資訊
|
||
- `engineering`：程式、除錯、測試、技術實作
|
||
- `ops`：部署、設定、服務、容器、log、系統診斷
|
||
|
||
---
|
||
|
||
## 3. Workspace 規劃
|
||
|
||
建議在 `~/.openclaw/` 下建立獨立工作區：
|
||
|
||
- `/home/alice/.openclaw/workspace` → `coder`（Eve，沿用現有主工作區）
|
||
- `/home/alice/.openclaw/workspace-prompt-optimizer`
|
||
- `/home/alice/.openclaw/workspace-reviewer`
|
||
- `/home/alice/.openclaw/workspace-research`
|
||
- `/home/alice/.openclaw/workspace-engineering`
|
||
- `/home/alice/.openclaw/workspace-ops`
|
||
|
||
### 3.1 工作區原則
|
||
- Eve 使用主工作區
|
||
- 每個功能型 agent **必須擁有自己獨立的 workspace**
|
||
- **禁止多個 agent 共用同一個工作目錄**
|
||
- 獨立工作區的目的，是避免互相污染上下文、memory、tasks、logs 與操作痕跡
|
||
- 若需要共享規格文件，可用明確同步方式，不靠隱晦 prompt 假設
|
||
- config 草案中應盡量為每個 agent 明確寫出 `workspace`，不要依賴共享 default workspace
|
||
|
||
---
|
||
|
||
## 4. Session / Tool 邊界建議
|
||
|
||
### 4.1 `tools.sessions.visibility`
|
||
Schema 核對後，可選值重點如下：
|
||
|
||
#### 選項比較
|
||
- `self`：只看當前 session，太窄
|
||
- `tree`：**預設值**；可看當前 session + 自己 spawn 出來的 subagent sessions
|
||
- `agent`：可看同一個 agent id 下的 sessions，但仍不等於跨 agent 調度
|
||
- `all`：可看所有 sessions；若要跨 agent，仍需搭配 `tools.agentToAgent`
|
||
|
||
### 建議
|
||
**本架構第一版仍建議用 `all`**，但搭配嚴格 `tools.agentToAgent.allow`。
|
||
原因：
|
||
- Eve 需要查其他 agent 的 session / history / send
|
||
- `tree` 雖然較保守，但只涵蓋當前 session 與其下游，不足以支撐完整多代理中樞協調
|
||
- `all` 不是單獨放行；跨 agent 仍受 `tools.agentToAgent` 約束
|
||
|
||
---
|
||
|
||
## 5. Agent-to-Agent 草案
|
||
|
||
### 5.1 是否啟用
|
||
建議：`enabled: true`
|
||
|
||
因為如果 Eve 要穩定派工與收件，多代理之間需要正式的 agent-to-agent 能力。
|
||
|
||
### 5.2 Allowlist 設計
|
||
第一版建議 allowlist 只放：
|
||
- `coder`
|
||
- `prompt-optimizer`
|
||
- `reviewer`
|
||
- `research`
|
||
- `engineering`
|
||
- `ops`
|
||
|
||
### 5.3 關係規則
|
||
雖然 allowlist 會包含全部 6 個 agent，但實際制度規則應限定為：
|
||
|
||
- `coder` 可派給全部其他 agent
|
||
- `prompt-optimizer` 只回 Eve，不再往下派
|
||
- `reviewer` 只回 Eve，不再往下派
|
||
- `research` 原則上只回 Eve
|
||
- `engineering` 原則上只回 Eve
|
||
- `ops` 原則上只回 Eve
|
||
|
||
### 注意
|
||
OpenClaw schema 對 `tools.agentToAgent` 目前只確認有：
|
||
- `enabled`
|
||
- `allow`
|
||
|
||
也就是說，config 層目前只能做「名單放行」，無法細緻表達「誰可以找誰」的單向圖。
|
||
所以真正的單向制度，必須再由 prompt / workflow 規則約束。
|
||
|
||
---
|
||
|
||
## 6. 模型配置建議
|
||
|
||
### 6.1 Eve / coder
|
||
建議沿用：
|
||
- `cowbay/gpt-5.4`
|
||
|
||
理由：
|
||
- 要做總調度、驗收、判斷、整合
|
||
- 需要較穩定的理解與管理能力
|
||
|
||
### 6.2 prompt-optimizer
|
||
建議：
|
||
- `cowbay/gpt-5.4`
|
||
或較便宜但仍穩的型號
|
||
|
||
理由：
|
||
- 需要理解模糊需求與整理結構
|
||
- 若品質差，後面整條鏈都會歪
|
||
|
||
### 6.3 reviewer
|
||
建議：
|
||
- `cowbay/gpt-5.4`
|
||
|
||
理由：
|
||
- reviewer 的價值在嚴格判斷，不宜太弱
|
||
|
||
### 6.4 research / engineering / ops
|
||
可先統一：
|
||
- `cowbay/gpt-5.4`
|
||
|
||
之後再視成本與品質，分別調整。
|
||
|
||
### 第一版建議
|
||
**先全部用同一個穩定主模型，確認流程正確後再分模型。**
|
||
|
||
---
|
||
|
||
## 7. Agent 草案結構（schema 已確認）
|
||
|
||
Schema 核對後，每個 `agents.list[]` entry：
|
||
|
||
### 必要欄位
|
||
- `id`
|
||
|
||
### 第一版建議明確寫出的欄位
|
||
- `name`
|
||
- `workspace`
|
||
- `model`
|
||
|
||
### Schema 另有支援、可留待第二版評估的欄位
|
||
- `default`
|
||
- `agentDir`
|
||
- `skills`
|
||
- `identity`
|
||
- `tools`
|
||
- `subagents`
|
||
- `runtime`
|
||
- `thinkingDefault`
|
||
- `reasoningDefault`
|
||
- `fastModeDefault`
|
||
|
||
### 已額外核對到的可用欄位細節
|
||
- `identity`：目前可放 `name` / `theme` / `emoji` / `avatar`
|
||
- `skills`：是字串陣列，可作 agent skill allowlist
|
||
- `tools`：可做 per-agent 工具限制（如 `allow` / `alsoAllow` / `deny` / `profile` 等）
|
||
- `subagents`：目前至少確認可放 `allowAgents` / `model` / `thinking`
|
||
- `runtime`：schema 有保留，但這次 lookup 沒展開出更細子欄位，暫不建議先寫死
|
||
|
||
因此，第一版 ready draft 先聚焦在：
|
||
- 穩定 agent id
|
||
- 明確 workspace
|
||
- 明確 model
|
||
- 先不把 prompt 制度細節誤塞進 config schema 不保證的欄位
|
||
|
||
### 概念草案
|
||
|
||
```json
|
||
{
|
||
"agents": {
|
||
"defaults": {
|
||
"model": {
|
||
"primary": "cowbay/gpt-5.4"
|
||
}
|
||
},
|
||
"list": [
|
||
{
|
||
"id": "coder",
|
||
"name": "Eve"
|
||
},
|
||
{
|
||
"id": "prompt-optimizer",
|
||
"name": "Prompt Optimizer",
|
||
"workspace": "/home/alice/.openclaw/workspace-prompt-optimizer"
|
||
},
|
||
{
|
||
"id": "reviewer",
|
||
"name": "Reviewer",
|
||
"workspace": "/home/alice/.openclaw/workspace-reviewer"
|
||
},
|
||
{
|
||
"id": "research",
|
||
"name": "Research",
|
||
"workspace": "/home/alice/.openclaw/workspace-research"
|
||
},
|
||
{
|
||
"id": "engineering",
|
||
"name": "Engineering",
|
||
"workspace": "/home/alice/.openclaw/workspace-engineering"
|
||
},
|
||
{
|
||
"id": "ops",
|
||
"name": "Ops",
|
||
"workspace": "/home/alice/.openclaw/workspace-ops"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 權限與制度邊界
|
||
|
||
### 8.1 Eve 的權限定位
|
||
- 可接旨
|
||
- 可派工
|
||
- 可追蹤
|
||
- 可驗收
|
||
- 可整合回報
|
||
|
||
### 8.2 子代理共通限制
|
||
- 不直接對總管發話
|
||
- 不自行宣告正式完成
|
||
- 高風險動作未授權前不可自行執行
|
||
- 必須如實回報卡點、錯誤與風險
|
||
|
||
### 8.3 Reviewer 特別定位
|
||
- 不是對上窗口
|
||
- 不是第二個 Eve
|
||
- 是 Eve 的驗收輔助與嚴格審查者
|
||
|
||
---
|
||
|
||
## 9. 第一版最小可行配置建議
|
||
|
||
若要先求穩，不必一次裝滿全部能力。
|
||
|
||
### Phase 1
|
||
先開：
|
||
- `coder`
|
||
- `prompt-optimizer`
|
||
- `reviewer`
|
||
- `engineering`
|
||
|
||
用這組先驗證：
|
||
- 接旨
|
||
- prompt 優化
|
||
- 單線技術任務
|
||
- 驗收／退件
|
||
- 正式回報
|
||
|
||
### Phase 2
|
||
再加：
|
||
- `research`
|
||
- `ops`
|
||
|
||
驗證：
|
||
- 研究支線
|
||
- 運維支線
|
||
- 並行任務
|
||
|
||
這樣比一次全開更穩。
|
||
|
||
---
|
||
|
||
## 10. 建議下一步
|
||
|
||
下一步建議分三件事做：
|
||
|
||
### A. 保持「說明文件」與「ready draft JSON」分離
|
||
- `openclaw-config-ready-draft.json` 應只保留 schema-backed config 欄位
|
||
- `meta`、`phase`、`implementationNotes` 這類設計說明，應留在 markdown，不要混進可套用 JSON
|
||
|
||
### B. 第二輪優先決定哪些進階欄位要進第一版 config
|
||
建議優先順序：
|
||
1. `identity`（可讀性高、風險低）
|
||
2. `skills`（可限制每個 agent 看到的 skill 範圍）
|
||
3. `subagents.allowAgents`（若要進一步約束誰能派誰，值得優先研究）
|
||
4. `tools`（高價值，但需非常小心別把 agent 卡死）
|
||
5. `runtime` / `agentDir`（先保守）
|
||
|
||
### C. 真正的制度邊界，分清楚哪裡該放 config、哪裡該放 prompt
|
||
適合放 config：
|
||
- workspace
|
||
- model
|
||
- sessions visibility
|
||
- agentToAgent allowlist
|
||
- per-agent tool policy
|
||
- skill allowlist
|
||
|
||
不適合假裝只靠 config 解決：
|
||
- 只准 Eve 對總管回話
|
||
- 子代理只能回 Eve
|
||
- reviewer 不可越權判定完成
|
||
- 失聯超時後的回報責任
|
||
|
||
### D. 再建立各 agent 工作區與 prompt 檔案布局草案
|
||
例如：
|
||
- `SOUL.md`
|
||
- `AGENTS.md`
|
||
- 是否共用某些規格文件
|
||
|
||
---
|
||
|
||
## 11. 結論
|
||
|
||
這份 config 草案的核心不是「多加幾個 agent」，而是把制度落地成一個穩定的中樞模式：
|
||
|
||
- 總管只對 Eve 下旨
|
||
- Eve 再決定是否走 optimizer
|
||
- Eve 派給對應功能 agent
|
||
- 所有結果先回 Eve
|
||
- Eve 驗收後才正式回報
|
||
|
||
如果照這份草案走，後續實作時就不會再回到那種多層朝廷式、難控、容易失聯的狀態。
|
||
|
||
|
||
## 12. 下一輪收斂建議（往 config.patch 靠攏）
|
||
|
||
若要再往前一步，我建議下一輪直接產出兩份：
|
||
|
||
### 12.1 `config.patch` 候選版本
|
||
只包含：
|
||
- `agents.defaults`
|
||
- `agents.list`
|
||
- `tools.sessions.visibility`
|
||
- `tools.agentToAgent`
|
||
|
||
### 12.2 `policy-notes.md` 或沿用本檔
|
||
專門保存：
|
||
- Eve 才是唯一對上窗口
|
||
- 子代理只能回 Eve
|
||
- reviewer 的角色界線
|
||
- 失聯 / 超時 / 重派的程序正義
|
||
|
||
這樣可避免把制度描述誤塞進 schema 不保證存在的欄位，之後真的套用 config 時也較不容易踩坑。
|
||
|
||
|
||
## 13. 已產出的候選 patch 檔
|
||
|
||
本輪已另外落出兩份審查用文件：
|
||
|
||
1. `docs/plans/2026-04-07-openclaw-config-candidate-patch.json`
|
||
2. `docs/plans/2026-04-07-openclaw-config-candidate-patch-notes.md`
|
||
|
||
### 13.1 候選 patch 的策略
|
||
- 以 live config 為基準做**最小必要變更**
|
||
- 使用 JSON Merge Patch 語義
|
||
- 明確以 `agents.defaults.workspace: null` 刪除共享 default workspace
|
||
- 以完整 `agents.list` 替換現有單一 `coder` list
|
||
|
||
### 13.2 為什麼這份是 candidate patch，不是直接套用版
|
||
因為在真正送進 `gateway config.patch` 前，仍需先確認：
|
||
- 各工作區是否先建好
|
||
- 是否加入 `identity`
|
||
- 是否加入 `skills`
|
||
- 是否加入 per-agent `tools`
|
||
- 是否另外用 prompt / workflow 檔補足制度邊界
|
||
|
||
## 14. Near-Apply Candidate Patch（2026-04-08）
|
||
|
||
本輪已進一步產出：
|
||
|
||
1. `docs/plans/2026-04-08-openclaw-config-near-apply-candidate-patch.json`
|
||
2. `docs/plans/2026-04-08-openclaw-config-near-apply-candidate-patch-notes.md`
|
||
|
||
### 14.1 相較前一版 candidate patch 的新增內容
|
||
- 每個 agent 補 `identity`
|
||
- 每個 agent 補最小 `skills` allowlist
|
||
- 每個下游 agent 補保守的 `tools.deny`
|
||
- 用 `subagents.allowAgents` 進一步表達派工邊界
|
||
|
||
### 14.2 這版仍然不是直接套用版
|
||
雖然已接近可套用，但仍需先審查：
|
||
- `skills` 是否過窄
|
||
- `tools.deny` 是否卡住實際流程
|
||
- `subagents.allowAgents: []` 只代表不能跨 agent 派工，不等於完全禁用 `sessions_spawn`
|
||
- 若要真正禁止下游 agent 再往下派，需搭配 per-agent `tools.deny: ["sessions_spawn"]`
|
||
- 是否還要細化 per-agent tool policy
|
||
|
||
## 15. Final Review Checklist（2026-04-08）
|
||
|
||
本輪已再產出：
|
||
|
||
1. `docs/plans/2026-04-08-openclaw-multi-agent-final-review-checklist.md`
|
||
|
||
### 15.1 用途
|
||
這份文件不是再發散設計，而是把 near-apply 版進入真正套用前，還需要人工確認的點壓成 checklist。
|
||
|
||
### 15.2 焦點
|
||
- skill allowlist 是否過窄
|
||
- per-agent `tools.deny` 是否合理
|
||
- `coder` 與下游 agent 的 delegation 邊界是否符合預期
|
||
- 套用後需要用哪些驗證動作確認 policy 真的生效
|
||
|
||
## 16. Apply-Ready Patch（2026-04-08）
|
||
|
||
本輪已再產出：
|
||
|
||
1. `docs/plans/2026-04-08-openclaw-config-apply-ready-patch.json`
|
||
2. `docs/plans/2026-04-08-openclaw-config-apply-ready-runbook.md`
|
||
|
||
### 16.1 用途
|
||
- `apply-ready-patch.json`：純 `gateway config.patch` payload 候選版
|
||
- `apply-ready-runbook.md`：套用前後的操作順序與驗證清單
|
||
|
||
### 16.2 邊界
|
||
這份 apply-ready patch 仍然**沒有被套用**。
|
||
它的意義是：設計與文件已收斂到可以進入「等待總管批准後再 patch」的階段。
|
||
|