06 · Workspace：Agent 的工作空間和身份容器

前兩篇分別講 Memory 和 Context。這一篇講它們共同依賴的物理位置：Agent workspace。

一句話先記住：

把這句話吃透，後面才不會把“檔案規則”“執行配置”“會話歷史”“安全隔離”混在一起。

1. Workspace 是什麼

官方 Agent workspace 文件的定義是：

The workspace is the agent's home. It is the only working directory used for file tools and for workspace context.

預設位置：

~/.openclaw/workspace

如果設定了 OPENCLAW_PROFILE 且不是 default，預設會變成：

~/.openclaw/workspace-<profile>

也可以在 ~/.openclaw/openclaw.json 裡覆蓋：

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  }
}

openclaw onboard、openclaw configure、openclaw setup 會在缺檔案時建立 workspace 並 seed bootstrap files。

2. Workspace 不是 ~/.openclaw/

這個邊界很重要。

flowchart TD
  A[~/.openclaw/] --> B[openclaw.json]
  A --> C[credentials]
  A --> D[agents/<agentId>/sessions]
  A --> E[managed skills]
  A --> F[workspace]

  F --> G[AGENTS.md]
  F --> H[SOUL.md]
  F --> I[TOOLS.md]
  F --> J[MEMORY.md]
  F --> K[memory/YYYY-MM-DD.md]
  F --> L[skills/]

Workspace 裡是 Agent 的可見工作材料。~/.openclaw/ 裡還有執行配置、憑據、session transcripts、managed skills 等系統狀態。

這意味著“複製 workspace”只能遷移一部分：規則、人格、使用者資料、長期記憶、daily notes、workspace skills 可以隨 workspace 遷移；openclaw.json、OAuth/API keys、channel credentials、sessions、managed skills 不在 workspace 裡。

所以更準確的說法是：複製 workspace 可以遷移 Agent 的工作上下文和個性材料，但不能完整複製執行態、憑據和歷史會話。

3. Workspace 不是硬沙箱

官方警告非常關鍵：

The workspace is the default cwd, not a hard sandbox.

也就是說：

• 相對路徑會以 workspace 為基準解析。
• 絕對路徑仍可能訪問 host 上其他位置。
• 如果需要隔離，必須啟用 agents.defaults.sandbox 或 per-agent sandbox config。
• 啟用 sandbox 且 workspaceAccess 不是 "rw" 時，tools 會在 ~/.openclaw/sandboxes 下的 sandbox workspace 裡工作，而不是直接操作 host workspace。

flowchart TD
  A[Tool uses relative path] --> B[Resolve inside workspace]
  C[Tool uses absolute path] --> D[Can reach host path unless sandboxed]
  E[Sandbox enabled] --> F[Sandbox workspace under ~/.openclaw/sandboxes]

所以不要把 workspace 當作安全邊界。它只是預設工作目錄和上下文容器。真正的執行邊界在 sandbox、tool policy、exec approvals 和 channel allowlists。

4. 標準檔案地圖

OpenClaw 期望 workspace 裡有一組標準檔案。它們不是隨便命名的筆記，而是會影響 prompt、工具使用和會話行為的上下文檔案。

如果 bootstrap file 缺失，OpenClaw 會注入 “missing file” marker 並繼續；openclaw setup 可以補齊缺失預設檔案，不覆蓋已有檔案。

5. AGENTS.md：操作規則

AGENTS.md 是 operating instructions。它適合寫：

• Agent 的工作流程。
• 專案優先順序。
• 不要做什麼。
• 如何使用 memory。
• 遇到阻塞如何彙報。
• 哪些命令或目錄是預設入口。

它不適合寫：

• 情緒風格和人格。
• OAuth token 或 API key。
• 巨長曆史記錄。
• 臨時任務流水賬。

一個好 AGENTS.md 應該可執行、可檢查、可更新。它不是品牌文案。

6. SOUL.md：聲音、態度和邊界

官方 SOUL guide 說：SOUL.md is where your agent's voice lives。

它適合寫：

• tone。
• opinions。
• brevity。
• humor。
• boundaries。
• default level of bluntness。

它不適合寫：

• life story。
• changelog。
• security policy dump。
• 沒有行為效果的巨大情緒牆。

官方的原則很實用：Short beats long. Sharp beats vague.

換成中文就是：短比長好，明確比虛好。

SOUL.md 和 AGENTS.md 的分工：

人格不是放飛。官方也提醒：Personality is not permission to be sloppy。

7. TOOLS.md：工具約定，不是授權配置

這一點在前幾篇反覆出現，因為太容易錯：

TOOLS.md does not control tool availability; it is only guidance.

適合寫入 TOOLS.md 的內容：

• 本機工具路徑。
• 常用命令說明。
• 工具使用順序。
• 憑據在哪裡取，但不要寫憑據本身。
• 某些 CLI 的注意事項。

不適合寫：

• “允許使用 exec”這類授權。
• token、密碼、私鑰。
• 大段教程全文。

工具是否能呼叫，由 tool policy、provider profile、sandbox policy 等硬邊界決定。TOOLS.md 只能影響模型習慣。

8. MEMORY.md 和 memory/

MEMORY.md 是 curated long-term memory。workspace 文件特別說明：只在 main private session 載入，不應在 shared/group contexts 裡隨意載入。

memory/YYYY-MM-DD.md 是 daily memory log。官方建議 session start 時讀今天和昨天。

結合前兩篇，可以這樣理解：

長期規則不要塞 daily note 後就期待每輪生效；臨時狀態也不要全部塞 MEMORY.md。

9. BOOTSTRAP.md 和 BOOT.md

這兩個名字相近，但職責不同。

官方 bootstrapping 文件說，first run 會：

1. seed AGENTS.md、BOOTSTRAP.md、IDENTITY.md、USER.md。
2. 執行短 Q&A ritual。
3. 寫 identity + preferences 到 IDENTITY.md、USER.md、SOUL.md。
4. 完成後移除 BOOTSTRAP.md，確保只跑一次。

如果你已經預置 workspace，可以跳過 bootstrap：

openclaw onboard --skip-bootstrap

或者在配置裡設定：

{
  "agents": {
    "defaults": {
      "skipBootstrap": true
    }
  }
}

Bootstrapping 總是在 gateway host 上執行。如果 macOS app 連線的是遠端 Gateway，workspace 檔案也在遠端機器上。

10. skills/ 是 workspace 級最高優先順序

Workspace-specific skills 位於：

<workspace>/skills

它們在同名衝突時優先順序最高，會覆蓋 project agent skills、personal agent skills、managed skills、bundled skills 和 skills.load.extraDirs。

適合放 workspace skills 的場景：

• 某個 Agent 專屬工作流。
• 某個專案獨有工具 SOP。
• 不希望影響全域性 Agent 的技能。
• 需要和 workspace 規則一起版本控制的流程。

不適合放：

• 全域性通用技能。
• 含大量第三方依賴但沒有審查的技能。
• 帶金鑰的指令碼。

技能越貼近這個 workspace，越應該放這裡；越通用，越應該放管理層級更高的位置。

11. 哪些東西不要進 workspace

官方明確列出這些不屬於 workspace，也不應該提交到 workspace repo：

• ~/.openclaw/openclaw.json
• ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• ~/.openclaw/agents/<agentId>/agent/codex-home/
• ~/.openclaw/credentials/
• ~/.openclaw/agents/<agentId>/sessions/
• ~/.openclaw/skills/

原因很直接：config 是執行環境配置，不是 Agent 的工作記憶；credentials 包含 channel/provider/OAuth 狀態；sessions 是歷史 transcript 和 metadata，可能很大且敏感；managed skills 是全域性或本機管理資產，不屬於單個 workspace。

Workspace 可以做 private git backup，但仍然不要提交 secrets。即使是 private repo，也應避免 API keys、OAuth tokens、passwords、raw chats、敏感附件。

12. 推薦的私有備份方式

官方建議把 workspace 當作 private memory，放進私有 git repo 備份。

最小 .gitignore 可以包含：

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

備份時優先提交：

AGENTS.md
SOUL.md
TOOLS.md
IDENTITY.md
USER.md
HEARTBEAT.md
MEMORY.md
memory/
skills/

遷移到新機器時：

1. clone private repo 到目標路徑。
2. 在 ~/.openclaw/openclaw.json 設定 agents.defaults.workspace。
3. 執行 openclaw setup --workspace <path> 補缺失檔案。
4. 如果需要舊 session，再單獨複製 ~/.openclaw/agents/<agentId>/sessions/。

不要把 workspace 遷移誤解成完整系統遷移。配置和憑據要另行處理。

13. 常見誤解

常見誤解可以按這組邊界校正：

• 複製 workspace 不等於完整複製 Agent。它只能遷移工作上下文；config、credentials、sessions 不在裡面。
• Workspace 不是沙箱。它只是預設 cwd；需要 sandbox 才有隔離。
• TOOLS.md 不能授權工具。它只是使用指導，工具可用性由 tool policy 控制。
• SOUL.md 不應該寫所有規則。SOUL.md 管聲音和邊界，操作規則放 AGENTS.md。
• MEMORY.md 不是越全越好。太長會吃 context，應儲存高訊號長期事實。
• BOOTSTRAP.md 不應長期保留。它是 one-time first-run ritual，完成後刪除。
• private git repo 也不應該放金鑰。仍然不要提交 secrets。

14. 給 Agent 的實踐任務

把下面任務交給你的 OpenClaw Agent：

请审查当前 workspace：
1. 列出 AGENTS.md、SOUL.md、USER.md、IDENTITY.md、TOOLS.md、HEARTBEAT.md、MEMORY.md、memory/、skills/ 是否存在。
2. 说明每个文件的职责，并指出是否有内容放错位置。
3. 检查是否有 API key、OAuth token、密码、私钥或 raw chat dump。
4. 用 /context list 检查是否有 bootstrap 文件被 TRUNCATED。
5. 给出一个最小 private git backup 清单，不包含 ~/.openclaw/openclaw.json、credentials、sessions。

重點看它有沒有分清楚“規則檔案”“執行配置”“憑據”“session 歷史”和“沙箱邊界”。

15. 本章自檢

讀完這一篇，你應該能回答：

1. Workspace 為什麼是 Agent 的 home？
2. Workspace 和 ~/.openclaw/ 的邊界是什麼？
3. 為什麼 workspace 不是硬沙箱？
4. AGENTS.md、SOUL.md、TOOLS.md 的職責差異是什麼？
5. BOOTSTRAP.md 和 BOOT.md 的區別是什麼？
6. skills/ 為什麼是 workspace 級最高優先順序？
7. 哪些檔案不應該提交到 workspace repo？

能回答這些問題，再看下一篇多 Agent，才會理解為什麼“給每個 Agent 一個 workspace”比“只換一個名字”重要。

16. 接下來去哪

17. 官方資料

• Agent Workspace
• Agent Runtime
• SOUL.md Personality Guide
• Agent Bootstrapping
• Context
• Memory Overview