docs: 重整文件結構，移除 v2/v3 舊文檔，新增實作指南
- 刪除 v2/v3 所有舊規格文件 - 將 v4 規格文件移至 spec/ 目錄 - 新增 guides/ 目錄，包含： - guide_openclaw_config.md：openclaw.json 設定、Discord 接入、Gateway 管理 - guide_workspace_files.md：8 個 Workspace 設定檔正確用途 - guide_sessions_tools.md：sessions_spawn/send 參數與 Agents vs Sub-agent run 說明 - 更新 spec_v4_rollout_and_risks.md：加入 Phase 0/1 實際進度 - 新增 INDEX.md 文件索引 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Chris
182
docs/guides/guide_openclaw_config.md
Normal file
182
docs/guides/guide_openclaw_config.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# OpenClaw 實際設定指南
|
||||
|
||||
> 適用版本：OpenClaw v2026.4.x
|
||||
> 更新日期：2026-04-09
|
||||
|
||||
---
|
||||
|
||||
## openclaw.json 結構
|
||||
|
||||
設定檔位置：`~/.openclaw/openclaw.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"workspace": "~/.openclaw/workspace",
|
||||
"model": { "primary": "openai-codex/gpt-5.4-mini" }
|
||||
},
|
||||
"list": [
|
||||
{
|
||||
"id": "main"
|
||||
},
|
||||
{
|
||||
"id": "ceo_coo",
|
||||
"name": "ceo_coo",
|
||||
"workspace": "~/.openclaw/workspaces/ceo_coo",
|
||||
"agentDir": "~/.openclaw/agents/ceo_coo/agent",
|
||||
"model": "openai-codex/gpt-5.4"
|
||||
}
|
||||
]
|
||||
},
|
||||
"channels": {
|
||||
"discord": {
|
||||
"enabled": true,
|
||||
"token": "<BOT_TOKEN>",
|
||||
"guilds": {
|
||||
"<GUILD_ID>": {
|
||||
"channels": {
|
||||
"<CHANNEL_ID>": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"bindings": [
|
||||
{
|
||||
"type": "route",
|
||||
"agentId": "ceo_coo",
|
||||
"match": {
|
||||
"channel": "discord",
|
||||
"peer": {
|
||||
"kind": "channel",
|
||||
"id": "<CHANNEL_ID>"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 新增 Agent
|
||||
|
||||
```bash
|
||||
openclaw agents add <agent_id> \
|
||||
--workspace ~/.openclaw/workspaces/<agent_id> \
|
||||
--model <model_id> \
|
||||
--non-interactive
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Discord 設定
|
||||
|
||||
### 1. 接入 Discord Bot
|
||||
|
||||
```bash
|
||||
openclaw channels add --channel discord --token <BOT_TOKEN>
|
||||
```
|
||||
|
||||
### 2. Discord Developer Portal 必開設定
|
||||
|
||||
Bot → Privileged Gateway Intents：
|
||||
- Message Content Intent ✅
|
||||
- Server Members Intent ✅
|
||||
|
||||
### 3. 設定 Guild 頻道白名單
|
||||
|
||||
在 `openclaw.json` 的 `channels.discord.guilds` 下新增：
|
||||
|
||||
```json
|
||||
"guilds": {
|
||||
"<GUILD_ID>": {
|
||||
"channels": {
|
||||
"<CHANNEL_ID>": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 設定 Agent 路由 Binding
|
||||
|
||||
```json
|
||||
"bindings": [
|
||||
{
|
||||
"type": "route",
|
||||
"agentId": "<agent_id>",
|
||||
"match": {
|
||||
"channel": "discord",
|
||||
"peer": {
|
||||
"kind": "channel",
|
||||
"id": "<CHANNEL_ID>"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 5. 授權 Discord 用戶
|
||||
|
||||
Bot 初次收到 DM 時會顯示 pairing code：
|
||||
|
||||
```bash
|
||||
openclaw pairing approve discord <PAIRING_CODE>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Gateway 管理
|
||||
|
||||
Gateway 以 systemd user service 常駐：
|
||||
|
||||
```bash
|
||||
# 啟動
|
||||
systemctl --user start openclaw-gateway.service
|
||||
|
||||
# 重啟
|
||||
systemctl --user restart openclaw-gateway.service
|
||||
|
||||
# 狀態
|
||||
systemctl --user status openclaw-gateway.service
|
||||
|
||||
# 查 log
|
||||
journalctl --user -u openclaw-gateway.service -f
|
||||
```
|
||||
|
||||
設定異動通常不需重啟（熱重載）。
|
||||
以下異動需要重啟：Discord token、Channel 設定、Plugin 設定。
|
||||
|
||||
---
|
||||
|
||||
## 常用指令
|
||||
|
||||
```bash
|
||||
# 查 agent 清單與路由
|
||||
openclaw agents list --json
|
||||
|
||||
# 查 channel 連線狀態
|
||||
openclaw channels status --probe
|
||||
|
||||
# 查 binding 清單
|
||||
openclaw agents bindings
|
||||
|
||||
# 設定 agent 路由
|
||||
openclaw agents bind --agent <id> --bind "discord:<channel_id>"
|
||||
|
||||
# 移除 binding
|
||||
openclaw agents unbind --agent <id> --all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## King Claw 實際設定
|
||||
|
||||
| 項目 | 值 |
|
||||
|---|---|
|
||||
| Guild ID | `1486353934594342924` |
|
||||
| #總機 Channel ID | `1486739757957644319` |
|
||||
| CEO Agent ID | `ceo_coo` |
|
||||
| CEO 模型 | `openai-codex/gpt-5.4` |
|
||||
| 預設模型 | `openai-codex/gpt-5.4-mini` |
|
||||
87
docs/guides/guide_sessions_tools.md
Normal file
87
docs/guides/guide_sessions_tools.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# sessions_spawn / sessions_send 使用指南
|
||||
|
||||
> 適用版本：OpenClaw v2026.4.x
|
||||
> 更新日期：2026-04-09
|
||||
|
||||
---
|
||||
|
||||
## Agents vs Sub-agent Runs
|
||||
|
||||
**Agent** = 有自己 workspace、設定檔、記憶的持久實體。在 `openclaw.json` 的 `agents.list` 裡定義。
|
||||
|
||||
**Sub-agent run** = 當一個 Agent 被 `sessions_spawn` 呼叫時，那次在隔離 session 裡的執行。Session key 格式：`agent:<agentId>:subagent:<uuid>`。
|
||||
|
||||
兩者不是不同等級，只是存在方式不同：同一個 Agent 可以被 spawn 成 sub-agent run 來執行任務，完成後 announce 結果回去。
|
||||
|
||||
---
|
||||
|
||||
## sessions_spawn — 派工（非阻塞）
|
||||
|
||||
**行為：** 立即返回 `runId` 和 `childSessionKey`，不等待結果。對方 Agent 在獨立 session 執行，完成後 announce 結果。
|
||||
|
||||
**使用場景：** 獨立任務，不需要即時來回溝通。
|
||||
|
||||
```json
|
||||
{
|
||||
"agentId": "finance_researcher",
|
||||
"task": "蒐集今日盤前財經資訊，輸出 Finance_Research_Brief.json",
|
||||
"thread": true,
|
||||
"runtime": "subagent"
|
||||
}
|
||||
```
|
||||
|
||||
**關鍵參數：**
|
||||
|
||||
| 參數 | 說明 |
|
||||
|---|---|
|
||||
| `agentId` | 目標 Agent ID |
|
||||
| `task` | 給對方的任務提示 |
|
||||
| `runtime` | `subagent`（預設）或 `acp` |
|
||||
| `thread: true` | 綁定到 Discord 執行緒 |
|
||||
| `sandbox: "require"` | 強制沙箱隔離 |
|
||||
| `model` | 覆蓋模型設定 |
|
||||
|
||||
**限制：**
|
||||
- 最多 5 層深（spawn 的 spawn 的 spawn...）
|
||||
- 最多 5 個並行
|
||||
- 預設葉層 sub-agent 不具備 sessions 工具（無法再 spawn）
|
||||
|
||||
---
|
||||
|
||||
## sessions_send — 同步溝通（可等待回覆）
|
||||
|
||||
**行為：** 向另一個 session 傳訊，可設定是否等待回覆。支援最多 5 輪來回。
|
||||
|
||||
**使用場景：** 追問細節、審查來回、交叉確認。
|
||||
|
||||
```json
|
||||
{
|
||||
"sessionKey": "agent:reviewer:subagent:xxxx",
|
||||
"message": "請審查以下量化策略內容：[...]",
|
||||
"timeoutSeconds": 60
|
||||
}
|
||||
```
|
||||
|
||||
**操作模式：**
|
||||
|
||||
| 模式 | 設定 | 用途 |
|
||||
|---|---|---|
|
||||
| 等待回覆 | `timeoutSeconds > 0` | 需要立即得到回應 |
|
||||
| 即發即忘 | `timeoutSeconds: 0` | 不需等回覆 |
|
||||
| 多輪來回 | 自動支援，最多 5 輪 | 審查、追問 |
|
||||
|
||||
對方可回覆 `REPLY_SKIP` 提早結束來回。
|
||||
|
||||
---
|
||||
|
||||
## 使用情境對照
|
||||
|
||||
| 情境 | 工具 | 原因 |
|
||||
|---|---|---|
|
||||
| 蒐集資料 | spawn | 獨立任務，不需互動 |
|
||||
| 寫回測程式 | spawn | 獨立任務 |
|
||||
| 多空平行研究 | spawn（兩個） | 並行執行 |
|
||||
| 追問研究員細節 | send | 兩個 agent 直接對話 |
|
||||
| 審查員來回審查 | send | 需要 ping-pong |
|
||||
| 請秘書做摘要 | spawn 或 send | 依是否需要等待 |
|
||||
| Coordinator 討論 | send（逐一收集） | 整合多方觀點 |
|
||||
157
docs/guides/guide_workspace_files.md
Normal file
157
docs/guides/guide_workspace_files.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# OpenClaw Workspace 設定檔指南
|
||||
|
||||
> 適用版本：OpenClaw v2026.4.x
|
||||
> 更新日期：2026-04-09
|
||||
|
||||
---
|
||||
|
||||
## 總覽
|
||||
|
||||
每個 Agent 的 workspace 資料夾下有固定的 8 個設定檔，OpenClaw 在 session 啟動時自動讀取並組合成 Agent 的身份、行為規則、記憶與任務排程。
|
||||
|
||||
```
|
||||
~/.openclaw/workspaces/<agent_id>/
|
||||
├── SOUL.md ← 性格與邊界
|
||||
├── AGENTS.md ← 操作程序手冊
|
||||
├── IDENTITY.md ← 公開元數據
|
||||
├── USER.md ← 關於人類用戶
|
||||
├── TOOLS.md ← 工具使用指南
|
||||
├── HEARTBEAT.md ← 定期任務清單
|
||||
├── BOOTSTRAP.md ← 首次啟動引導（用完刪）
|
||||
├── MEMORY.md ← 長期記憶
|
||||
└── memory/
|
||||
└── YYYY-MM-DD.md ← 每日工作記錄
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 各檔案詳細說明
|
||||
|
||||
### SOUL.md — 性格與邊界
|
||||
|
||||
**誰讀：** Agent 自己，每個 session 開始時注入
|
||||
**用途：** 定義 Agent 是誰、核心使命、禁止行為
|
||||
|
||||
**應放內容：**
|
||||
- 語氣與個性（簡潔、果斷、有主見）
|
||||
- 職權範圍與使命
|
||||
- 嚴格禁止事項
|
||||
- 高風險動作清單
|
||||
|
||||
**原則：短勝於長，銳利勝於模糊。不放生平故事、不堆安全政策。**
|
||||
|
||||
---
|
||||
|
||||
### AGENTS.md — 操作程序手冊
|
||||
|
||||
**誰讀：** Agent 自己，每個 session 開始時讀取
|
||||
**用途：** 最重要的大文件，記錄「怎麼做」的程序
|
||||
|
||||
**應放內容：**
|
||||
- Session 啟動流程（依序讀哪些檔案）
|
||||
- 記憶記錄規則
|
||||
- 任務執行流程
|
||||
- Multi-agent 移交協議（spawn/send 哪個 agent）
|
||||
- Review Gate 觸發條件
|
||||
- HITL 審批節點
|
||||
- Discord 發言規範
|
||||
- 紅線（絕對不能做的事）
|
||||
|
||||
**這是複雜 Agent 最大的檔案。**
|
||||
|
||||
---
|
||||
|
||||
### IDENTITY.md — 公開元數據
|
||||
|
||||
**誰讀：** 系統初始化、`openclaw agents set-identity` 指令
|
||||
**用途：** 輕量級的公開身份卡片，**要很短**
|
||||
|
||||
**應放內容：**
|
||||
- 名字（Name）
|
||||
- 角色標籤（Creature/Role）
|
||||
- 語言
|
||||
- Emoji（簽名）
|
||||
- Avatar 路徑（可選）
|
||||
|
||||
**不要放行為邏輯，那屬於 SOUL.md 和 AGENTS.md。**
|
||||
|
||||
---
|
||||
|
||||
### USER.md — 關於人類用戶
|
||||
|
||||
**誰讀：** Agent 自己，每個 session 讀取
|
||||
**用途：** 靜態的用戶資訊，讓 Agent 有個性化的互動
|
||||
|
||||
**應放內容：**
|
||||
- 姓名與稱呼
|
||||
- 時區
|
||||
- 語言偏好
|
||||
- 溝通偏好
|
||||
- 決策權限說明
|
||||
|
||||
**不要放機密資訊。手動更新，不常變動。**
|
||||
|
||||
---
|
||||
|
||||
### TOOLS.md — 工具使用指南
|
||||
|
||||
**誰讀：** Agent 自己，參考用
|
||||
**用途：** 記錄 Agent 可以使用哪些工具以及如何正確使用
|
||||
|
||||
**應放內容：**
|
||||
- 可用工具清單與參數說明
|
||||
- 使用場景與注意事項
|
||||
- 環境特定設定（SSH hosts、API endpoints 等）
|
||||
|
||||
**不要存放 API Key 或機密，用環境變數。**
|
||||
**不控制工具可用性，只是使用指南。**
|
||||
|
||||
---
|
||||
|
||||
### HEARTBEAT.md — 定期任務清單
|
||||
|
||||
**誰讀：** Agent 自己，收到 heartbeat poll 時讀取
|
||||
**用途：** 定義 Agent 需要定期檢查或執行的任務
|
||||
|
||||
**應放內容：**
|
||||
- 簡短的檢查清單（要小，避免 token 浪費）
|
||||
- 定期任務說明
|
||||
|
||||
**空檔案 = 跳過 heartbeat API call。**
|
||||
|
||||
---
|
||||
|
||||
### BOOTSTRAP.md — 首次啟動引導
|
||||
|
||||
**誰讀：** Agent 自己，首次啟動時
|
||||
**用途：** 引導 Agent 建立身份，完成後自行刪除
|
||||
|
||||
**應放內容：**
|
||||
- 引導 Agent 詢問用戶並填寫 IDENTITY.md、USER.md、SOUL.md
|
||||
- 完成後刪除自身
|
||||
|
||||
**用完就刪，不需要永久保留。**
|
||||
|
||||
---
|
||||
|
||||
### MEMORY.md — 長期記憶
|
||||
|
||||
**誰讀：** Agent 自己，**只在主 session（直接對話）載入，Discord 等群組場合不載入**
|
||||
**用途：** 跨 session 的長期記憶，由 Agent 自己維護
|
||||
|
||||
**應放內容：**
|
||||
- 重要決策記錄
|
||||
- 總司令偏好
|
||||
- 長期策略方向
|
||||
- 需要跨 session 記住的關鍵事項
|
||||
|
||||
**每日工作記錄放 `memory/YYYY-MM-DD.md`，MEMORY.md 是精煉過的長期記憶。**
|
||||
|
||||
---
|
||||
|
||||
## 系統行為注意事項
|
||||
|
||||
- 缺失檔案：系統注入「缺失檔案」標記後繼續執行
|
||||
- 大型檔案截斷：單檔上限約 20,000 字元，總計 150,000 字元
|
||||
- `openclaw setup` 可重建預設值，不會覆蓋現有檔案
|
||||
- 每日筆記系統：`memory/YYYY-MM-DD.md` 自動讀取今日+昨日
|
||||
Reference in New Issue
Block a user