---
title: "配置 Agent Workspace"
description: "理解 OpenClaw Agent Workspace：長期工作現場、標準啟動檔案、sandbox 邊界、私有 git 備份和遷移方式。"
verifiedAt: "2026-05-06"
---

OpenClaw 的 workspace 是 Agent（智慧代理）的長期工作現場。它放身份、人格、規則、工具說明、長期記憶和 workspace 級 skills。它不是 `~/.openclaw/`，也不是硬隔離 sandbox。

> [!NOTE]
> **這一章用 12 分鐘換什麼**：你會分清 workspace、配置目錄、執行時狀態、sandbox workspace、標準啟動檔案和 private git 備份；以後遷移機器時不會把金鑰和 session 一起提交。

## 1. 先分清三類目錄

新手最容易把三類目錄混成一類：

| 目錄 | 放什麼 | 能不能進 git |
|------|------|------|
| Agent workspace | `AGENTS.md`、`SOUL.md`、`USER.md`、`TOOLS.md`、`MEMORY.md`、`memory/`、workspace skills | 可以，但應該是 private repo |
| `~/.openclaw/` | config、credentials、auth profiles、sessions、managed skills、runtime state | 不要整體進 git |
| sandbox workspace | sandbox 開啟後給工具使用的隔離工作區 | 看 sandbox 策略，不等同於主 workspace |

workspace 是 Agent 的“工作現場”。`~/.openclaw/` 是 OpenClaw 的執行時系統目錄。兩者不要混。

```mermaid
flowchart TD
    Workspace["Agent Workspace"]
    Rules["啟動規則和人格"]
    Memory["長期記憶"]
    Skills["Workspace skills"]
    State["~/.openclaw"]
    Config["配置和憑據"]
    Sessions["sessions / auth profiles"]
    Sandbox["Sandbox workspace"]
    Tools["工具執行現場"]

    Workspace --> Rules
    Workspace --> Memory
    Workspace --> Skills
    State --> Config
    State --> Sessions
    Sandbox --> Tools

    style Workspace fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style State fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Sandbox fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
```

> [!IMPORTANT]
> **一句話區別**：workspace 是 Agent 讀來工作的“家”；`~/.openclaw/` 是系統執行狀態；sandbox workspace 是工具隔離執行時的工作區。

## 2. workspace 不是 sandbox

官方文件說得很直接：workspace 是 default cwd（預設工作目錄），不是 hard sandbox（硬隔離邊界）。工具的相對路徑通常從 workspace 解析，但絕對路徑仍可能訪問主機其他位置，除非你配置了 sandbox。

如果啟用了 sandbox，並且 `workspaceAccess` 不是 `"rw"`，工具會在 `~/.openclaw/sandboxes` 下的 sandbox workspace 裡工作，而不是直接操作主機 workspace。

| 你以為 | 實際 |
|------|------|
| workspace 限制 Agent 只能訪問這個目錄 | 不是；它只是預設 cwd |
| `TOOLS.md` 能控制工具許可權 | 不能；它只是說明文件 |
| 開 sandbox 後還一定操作主 workspace | 不一定；取決於 sandbox 的 workspace access |
| 把敏感內容放 workspace 裡沒事 | 不對；workspace 會進入 Agent 上下文 |

> [!WARNING]
> **許可權控制靠配置和 sandbox，不靠目錄名**：如果你要限制工具訪問範圍，去配置 sandbox 和 tool policy，不要指望 workspace 路徑自動保護主機。

## 3. 預設位置和建立方式

預設 workspace 是：

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

如果設定了非 default 的 `OPENCLAW_PROFILE`，預設 workspace 會變成：

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

你也可以在配置裡顯式指定：

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

`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 會建立 workspace，並在缺少標準檔案時補齊啟動檔案。

如果你已經自己維護 workspace 檔案，可以關閉 bootstrap 檔案建立：

```json5
{ agents: { defaults: { skipBootstrap: true } } }
```

> [!TIP]
> **只保留一個 active workspace**：舊安裝可能建立過 `~/openclaw`。多個 workspace 同時存在時，auth、記憶和狀態很容易漂移。用 `openclaw doctor` 檢查多餘 workspace 提醒。

## 4. 標準檔案地圖

OpenClaw 會把 workspace 檔案作為 Agent 上下文的一部分。每個檔案應該只做一件事。

| 檔案 / 目錄 | 作用 | 新手寫法 |
|------|------|------|
| `AGENTS.md` | 操作規則和長期約定 | 寫任務優先順序、工具使用方式、邊界 |
| `SOUL.md` | 人格、語氣、邊界 | 寫 Agent 應該像誰、怎麼說話 |
| `USER.md` | 使用者畫像 | 寫稱呼、時區、偏好、長期背景 |
| `IDENTITY.md` | Agent 名稱、符號、風格 | 寫名片資訊，不寫金鑰 |
| `TOOLS.md` | 本地工具約定 | 寫工具說明，不當許可權系統 |
| `HEARTBEAT.md` | 心跳檢查清單 | 保持很短，避免 token 消耗 |
| `BOOT.md` | Gateway 重啟後的啟動檢查 | 只寫必要檢查 |
| `BOOTSTRAP.md` | 第一次啟動儀式 | 新 workspace 完成後可以刪除 |
| `memory/YYYY-MM-DD.md` | 每日記憶日誌 | 寫當天觀察、過程、待沉澱線索 |
| `MEMORY.md` | 長期記憶精華 | 只放未來會反覆用到的事實 |
| `skills/` | workspace 級 skills | 同名時優先順序最高 |
| `canvas/` | 可選 Canvas UI 檔案 | 有明確 UI 需求再放 |

如果某個 bootstrap 檔案缺失，OpenClaw 會把“缺失檔案”標記注入 session，並繼續執行。大檔案會被截斷；可以透過 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 調整限制。

> [!TIP]
> **workspace 檔案要分工，不要堆料**：規則放 `AGENTS.md`，人格放 `SOUL.md`，使用者偏好放 `USER.md`，長期精華才進 `MEMORY.md`。

> [!CAUTION]
> **`MEMORY.md` 不要給共享群聊亂用**：長期記憶可能包含個人背景、偏好和敏感線索。共享或群聊上下文要單獨設計。

## 5. 哪些內容不該進 workspace git

不要把 OpenClaw 執行時狀態提交到 workspace 儲存庫。典型包括：

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

這些檔案可能包含模型授權、渠道登入態、OAuth、session transcript、本機執行狀態或 managed skills。遷移機器時可以單獨處理，但不能當作普通內容同步。

最穩的判斷方式：如果一個檔案包含賬號、token、OAuth、會話記錄、瀏覽器登入態、模型授權或本機快取，它就不是 workspace 內容。

## 6. 私有 git 備份怎麼做

官方建議把 workspace 當作 private memory（私有記憶），用 private git 儲存庫備份。備份物件是規則、人格、身份、工具說明和長期記憶，不是執行時憑據。

新手可以從這些檔案開始：

```bash
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"
```

`.gitignore` 至少排除：

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

> [!WARNING]
> **private repo 也不是金鑰儲存庫**：私有儲存庫適合備份記憶和規則，不適合備份 API key、OAuth token、瀏覽器態和原始聊天轉儲。

## 7. 多 workspace 和遷移

多個 workspace 可以存在，但新手應該只保留一個 active workspace，並讓 `agents.defaults.workspace` 明確指向它。

遷移到新機器時，按這個順序做：

```mermaid
flowchart TD
    Clone["複製 private workspace repo"]
    Config["更新 agents.defaults.workspace"]
    Setup["openclaw setup --workspace <path>"]
    Verify["openclaw doctor / gateway status"]
    Sessions["按需單獨複製 sessions"]

    Clone --> Config
    Config --> Setup
    Setup --> Verify
    Verify --> Sessions

    style Clone fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Setup fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Verify fill:#dcfce7,stroke:#22c55e,stroke-width:2px
```

關鍵點：

- 先複製 private workspace 儲存庫到目標路徑。
- 再修改 `~/.openclaw/openclaw.json` 的 `agents.defaults.workspace`。
- 執行 `openclaw setup --workspace <path>` 補齊缺失檔案。
- 歷史 sessions 如確實需要，再單獨複製 `~/.openclaw/agents/<agentId>/sessions/`。
- 多 Agent 場景可以拆 workspace，例如 personal、work、shared 分開。
- 共享 Agent 不要複用個人長期記憶 workspace。

## 8. 新手常見坑

- 以為 workspace 就是 sandbox：它只是預設工作目錄，不是硬隔離。
- 把 `TOOLS.md` 當許可權系統：它只是說明，許可權要在配置和 sandbox 裡控制。
- 把 `MEMORY.md` 暴露給群聊 Agent：長期記憶可能含有個人背景和敏感線索。
- 把 `~/.openclaw/` 整目錄提交到 git：這會把執行時狀態也帶進去。
- 多個 workspace 同時改：Agent 行為會變得不可預測。
- 遷移時只複製 workspace，不處理配置指向：新機器可能仍然指向舊預設路徑。
- 在 sandbox 開啟後，還以為工具一定直接操作主 workspace。

## 9. 怎麼驗收

讀完這一章，你應該能做到：

- 能說清 workspace 路徑在哪裡，以及 `~/.openclaw/` 裡哪些內容不屬於 workspace。
- 能開啟標準檔案，並知道每個檔案解決什麼問題。
- 能解釋 workspace 為什麼不是 sandbox。
- 能確認 private git 裡沒有 token、OAuth、session transcript、auth profile、`.env` 和本機快取。
- 能在新機器上按同一個 workspace 路徑啟動，並讓 OpenClaw 補齊缺失檔案。
- 能為 shared Agent 使用獨立 workspace，而不是複用個人長期記憶。

## 10. 本章自檢

1. workspace、`~/.openclaw/`、sandbox workspace 分別放什麼？
2. 為什麼 workspace 不是安全隔離邊界？
3. 哪些執行時檔案不應該提交到 workspace git？

> [!IMPORTANT]
> **過關標準**：你能用一句話說清 —— “workspace 是 Agent 的長期工作現場，但許可權、憑據、session 和執行時狀態必須由配置目錄、sandbox 和私有憑據體系分別管理。”

## 11. 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/openclaw/official/01-gateway-runtime" title="Gateway 執行時" description="入門閉環完成後，繼續理解 Gateway、Agent、Channel、安全和自動化。" />
  <Card href="/zh-Hant/docs/openclaw/official/01-gateway-runtime/architecture" title="理解 Gateway 架構" description="從長期執行的控制面開始拆 OpenClaw 的執行時。" />
  <Card href="/zh-Hant/docs/openclaw/understanding/06-workspace" title="理解：Workspace" description="從原理篇繼續核對 workspace、memory、skills 和 sandbox 的邊界。" />
</Cards>

## 12. 官方資料

- [Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace)
- [Memory overview](https://docs.openclaw.ai/concepts/memory)
- [SOUL.md personality guide](https://docs.openclaw.ai/concepts/soul)
- [Sandboxing](https://docs.openclaw.ai/gateway/sandboxing)
- [Session management](https://docs.openclaw.ai/concepts/session)
