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
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