配置 Agent Workspace

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

1. 先分清三類目錄

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

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

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

2. workspace 不是 sandbox

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

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

3. 預設位置和建立方式

預設 workspace 是：

~/.openclaw/workspace

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

~/.openclaw/workspace-<profile>

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

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

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

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

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

4. 標準檔案地圖

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

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

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 儲存庫備份。備份物件是規則、人格、身份、工具說明和長期記憶，不是執行時憑據。

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

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 至少排除：

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

7. 多 workspace 和遷移

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

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

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？

11. 接下來去哪

12. 官方資料

• Agent workspace
• Memory overview
• SOUL.md personality guide
• Sandboxing
• Session management