---
title: "06 · Workspace：Agent 的工作空間和身份容器"
description: "講清 OpenClaw workspace 的真實邊界：它是預設 cwd 和專案上下文，不是配置庫、憑據庫或硬沙箱。"
verifiedAt: "2026-05-06"
---

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

一句話先記住：

> [!TIP]
> Workspace 是 Agent 的家目錄，是 file tools 的預設工作目錄，也是 workspace context 的來源；但它不是 `~/.openclaw/`，不是憑據庫，也不是硬沙箱。

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

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

預設位置：

```text
~/.openclaw/workspace
```

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

```text
~/.openclaw/workspace-<profile>
```

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

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

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

## 2. Workspace 不是 `~/.openclaw/`

這個邊界很重要。

```mermaid
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。

```mermaid
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。

> [!WARNING]
> Workspace 只是預設 cwd。需要安全隔離時，要看 sandbox、tool policy、exec approvals 和 channel allowlists。

## 4. 標準檔案地圖

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

| 檔案或目錄 | 官方定位 | 實踐邊界 |
| --- | --- | --- |
| `AGENTS.md` | Operating instructions for the agent and memory usage | 寫工作規則、優先順序、行為約束 |
| `SOUL.md` | Persona, tone, boundaries | 寫聲音、態度、邊界，不寫操作手冊 |
| `USER.md` | Who the user is and how to address them | 寫使用者資料和稱呼偏好 |
| `IDENTITY.md` | Agent name, vibe, emoji | 寫名稱和外在身份 |
| `TOOLS.md` | Local tool conventions | 只寫工具使用約定，不控制工具可用性 |
| `HEARTBEAT.md` | Tiny checklist for heartbeat runs | 寫短巡檢清單，避免 token burn |
| `BOOT.md` | Startup checklist on gateway restart when internal hooks enabled | 寫閘道器啟動後的短動作 |
| `BOOTSTRAP.md` | One-time first-run ritual | 只在新 workspace 首次入職用，完成後刪除 |
| `MEMORY.md` | Curated long-term memory | 寫長期事實、偏好、決策 |
| `memory/YYYY-MM-DD.md` | Daily memory log | 寫每天的執行觀察和短期記錄 |
| `skills/` | Workspace-specific skills | workspace 級最高優先順序技能 |
| `canvas/` | Canvas UI files | node displays 相關 UI 檔案 |

如果 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` 的分工：

| 需求 | 放哪裡 |
| --- | --- |
| “回答要短，不要客服腔” | `SOUL.md` |
| “改檔案前先跑測試” | `AGENTS.md` |
| “遇到使用者錯誤假設要直接指出” | `SOUL.md` |
| “釋出前必須執行 `pnpm build`” | `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` 只能影響模型習慣。

> [!IMPORTANT]
> `TOOLS.md` 能告訴 Agent 怎麼用工具，不能授予工具許可權。授權永遠看 tool policy。

## 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 時讀今天和昨天。

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

| 層 | 用途 | 風險 |
| --- | --- | --- |
| `MEMORY.md` | 長期穩定事實 | 太長會增加 context 壓力 |
| `memory/YYYY-MM-DD.md` | 每日工作觀察 | 舊檔案需要搜尋召回 |
| `DREAMS.md` | Dreaming human review surface | 不等同長期記憶 |

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

## 9. `BOOTSTRAP.md` 和 `BOOT.md`

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

| 檔案 | 觸發時機 | 做什麼 |
| --- | --- | --- |
| `BOOTSTRAP.md` | brand-new workspace 的 first-run ritual | 收集身份資訊，寫入 `IDENTITY.md`、`USER.md`、`SOUL.md`，完成後刪除 |
| `BOOT.md` | gateway restart，且 internal hooks 啟用時 | 執行短啟動清單 |

官方 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：

```bash
openclaw onboard --skip-bootstrap
```

或者在配置裡設定：

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

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

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

Workspace-specific skills 位於：

```text
<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` 可以包含：

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

備份時優先提交：

```text
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：

```text
请审查当前 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. 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/openclaw/understanding/07-multi-agent" title="07 · 多 Agent" description="繼續看不同 workspace、不同模型、不同許可權和不同會話入口如何組合。" />
  <Card href="/zh-Hant/docs/openclaw/understanding/05-context-management" title="05 · Context 管理" description="回到 context 篇，確認 workspace 檔案如何被注入、截斷和計入視窗。" />
  <Card href="/zh-Hant/docs/openclaw/official/00-getting-started/workspace" title="官方教程：Workspace" description="對照官方 Workspace 頁繼續核對標準檔案、私有備份和遷移邊界。" />
</Cards>

## 17. 官方資料

- [Agent Workspace](https://docs.openclaw.ai/concepts/agent-workspace)
- [Agent Runtime](https://docs.openclaw.ai/concepts/agent)
- [SOUL.md Personality Guide](https://docs.openclaw.ai/concepts/soul)
- [Agent Bootstrapping](https://docs.openclaw.ai/concepts/bootstrapping)
- [Context](https://docs.openclaw.ai/concepts/context)
- [Memory Overview](https://docs.openclaw.ai/concepts/memory)
