設定 OpenClaw 工作區：自訂路徑與檔案管理指南

身為開發者，你一定遇過這種狀況：當你在開發 AI Agent 時，檔案散落在各處，有些是暫存的對話紀錄，有些是核心的指令說明，最後搞得你根本不敢隨便把資料夾推上 Git，深怕洩漏了 API key 或弄丟了重要的記憶。

Agent workspace（工作區）就是為了解決這個問題而設計的。它是 Agent 的家，也是 file tools 和工作區上下文唯一使用的目錄。你可以把它當成 Agent 的私有記憶，並與存放設定、憑證與 Session 的 ~/.openclaw/ 分開管理。

重要提示： 工作區是 預設的 cwd（當前工作目錄），而不是一個嚴格的沙盒。雖然工具會根據工作區解析相對路徑，但除非啟用了 sandboxing，否則絕對路徑仍然可以存取主機上的其他地方。如果你需要隔離環境，請使用 agents.defaults.sandbox（或針對個別 Agent 進行沙盒設定）。當啟用 sandboxing 且 workspaceAccess 不是 "rw" 時，工具會在 ~/.openclaw/sandboxes 下的沙盒工作區運行，而不是你的主機工作區。

預設位置 (Default location)

• 預設路徑：~/.openclaw/workspace
• 如果設定了 OPENCLAW_PROFILE 且不是 "default"，預設路徑會變成 ~/.openclaw/workspace-<profile>。
• 你可以在 ~/.openclaw/openclaw.json 中覆蓋此設定：

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

執行 openclaw onboard、openclaw configure 或 openclaw setup 時，如果工作區不存在，系統會自動建立並放入引導檔案（bootstrap files）。沙盒的種子副本只接受工作區內的正規檔案，任何指向工作區外部的 symlink 或 hardlink 都會被忽略。

如果你偏好手動管理工作區檔案，可以停用自動建立引導檔案的功能：

{ agent: { skipBootstrap: true } }

額外的工作區資料夾 (Extra workspace folders)

舊版的安裝程式可能會建立 ~/openclaw。保留多個工作區資料夾可能會導致身分驗證混亂或狀態偏移，因為一次只能有一個工作區處於啟動狀態。

建議做法： 只保留一個啟動中的工作區。如果你不再使用額外的資料夾，請將它們封存或移至垃圾桶（例如 trash ~/openclaw）。如果你刻意要保留多個工作區，請確保 agents.defaults.workspace 指向目前要使用的那一個。

當 openclaw doctor 偵測到多餘的工作區目錄時會發出警告。

工作區檔案地圖 (Workspace file map)

以下是 OpenClaw 預期在工作區內看到的標準檔案：

• AGENTS.md

  • Agent 的操作指令以及它該如何使用記憶。
  • 在每個 Session 開始時載入。
  • 適合放置規則、優先順序和「行為準則」等細節。

• SOUL.md

  • 角色性格、語氣和界線。
  • 每個 Session 都會載入。

• USER.md

  • 使用者是誰以及該如何稱呼。
  • 每個 Session 都會載入。

• IDENTITY.md

  • Agent 的名稱、氛圍和 emoji。
  • 在引導儀式（bootstrap ritual）期間建立或更新。

• TOOLS.md

  • 關於你本地工具和慣例的筆記。
  • 這不會控制工具的可用性，僅作為引導使用。

• HEARTBEAT.md

  • 選填，用於 heartbeat 執行的微型檢查清單。
  • 建議保持簡短以避免消耗過多 token。

• BOOT.md

  • 選填，當內部 hook 啟用且 Gateway 重啟時執行的啟動檢查清單。
  • 保持簡短；如需對外發送訊息，請使用 message tool。

• BOOTSTRAP.md

  • 僅限一次性的首次執行儀式。
  • 只會為全新的工作區建立。
  • 儀式完成後請刪除它。

• memory/YYYY-MM-DD.md

  • 每日記憶日誌（一天一個檔案）。
  • 建議在 Session 開始時讀取今天與昨天的內容。

• MEMORY.md（選填）

  • 經過整理的長期記憶。
  • 僅在主要的私有 Session 中載入（不適用於共享或群組上下文）。

關於工作流和自動記憶清理，請參考 Memory。

• skills/（選填）

  • 工作區專屬的技能。
  • 當名稱衝突時，會覆蓋受管理的或內建的技能。

• canvas/（選填）

  • 用於 node 顯示的 Canvas UI 檔案（例如 canvas/index.html）。

如果缺少任何引導檔案，OpenClaw 會在 Session 中注入「檔案缺失」標記並繼續執行。大型引導檔案在注入時會被截斷；你可以透過 agents.defaults.bootstrapMaxChars（預設：20000）和 agents.defaults.bootstrapTotalMaxChars（預設：150000）來調整限制。openclaw setup 可以重新建立缺失的預設檔案，且不會覆蓋現有檔案。

哪些東西不在工作區 (What is NOT in the workspace)

以下檔案位於 ~/.openclaw/ 下，不應該被提交到工作區的 Git repo 中：

• ~/.openclaw/openclaw.json（設定檔）
• ~/.openclaw/credentials/（OAuth token, API keys）
• ~/.openclaw/agents/<agentId>/sessions/（Session 逐字稿 + 元數據）
• ~/.openclaw/skills/（受管理的技能）

如果你需要遷移 Session 或設定，請分開複製它們，並確保它們不在版本控制範圍內。

Git 備份（推薦，私有） (Git backup)

請將工作區視為私有記憶。將它放在 私有 (private) 的 Git repo 中，以便備份與復原。

請在運行 Gateway 的機器上執行以下步驟（也就是工作區所在地）。

1) 初始化 Repo

如果已安裝 Git，全新的工作區會自動初始化。如果該工作區還不是 repo，請執行：

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"

2) 新增私有遠端倉庫（適合新手的選項）

選項 A：GitHub 網頁介面

1. 在 GitHub 上建立一個新的 private repository。
2. 不要勾選初始化 README（避免合併衝突）。
3. 複製 HTTPS 遠端 URL。
4. 新增遠端並推送：

git branch -M main
git remote add origin <https-url>
git push -u origin main

選項 B：GitHub CLI (gh)

gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push

選項 C：GitLab 網頁介面

1. 在 GitLab 上建立一個新的 private repository。
2. 不要勾選初始化 README（避免合併衝突）。
3. 複製 HTTPS 遠端 URL。
4. 新增遠端並推送：

git branch -M main
git remote add origin <https-url>
git push -u origin main

3) 持續更新

git status
git add .
git commit -m "Update memory"
git push

不要提交秘密資訊 (Do not commit secrets)

即使是在私有 repo 中，也要避免在工作區儲存秘密資訊：

• API keys、OAuth tokens、密碼或私有憑證。
• ~/.openclaw/ 下的任何東西。
• 聊天紀錄的原始傾印（raw dumps）或敏感附件。

如果你必須儲存敏感引用，請使用佔位符，並將真正的秘密存放在其他地方（密碼管理員、環境變數或 ~/.openclaw/）。

建議的 .gitignore 範本：

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

將工作區遷移到新機器 (Moving the workspace to a new machine)

1. 將 repo clone 到目標路徑（預設為 ~/.openclaw/workspace）。
2. 在 ~/.openclaw/openclaw.json 中將 agents.defaults.workspace 設定為該路徑。
3. 執行 openclaw setup --workspace <path> 來補齊任何缺失的檔案。
4. 如果你需要 Session 資料，請另外從舊機器複製 ~/.openclaw/agents/<agentId>/sessions/。

進階注意事項 (Advanced notes)

• 多 Agent 路由可以為每個 Agent 使用不同的工作區。請參閱 Channel routing 了解路由設定。
• 如果啟用了 agents.defaults.sandbox，非主 Session 可以使用位於 agents.defaults.sandbox.workspaceRoot 下的各 Session 專屬沙盒工作區。

相關文件 (Related)

• Standing Orders — 工作區檔案中的持久指令
• Heartbeat — HEARTBEAT.md 工作區檔案
• Session — Session 儲存路徑
• Sandboxing — 沙盒環境中的工作區存取

下一步

• 想要更自動化的指令嗎？看看 Standing Orders。
• 了解如何管理 Agent 的長期記憶：Memory。

需要更多協助嗎？請詢問 AI Setup Assistant！