# 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