跳轉到主要內容

​
代理程式工作區

The workspace is the agent’s home. 工作區是代理程式的家。它是唯一用於操作的工作目錄。 file tools and for workspace context. Keep it private and treat it as memory. 這與 ~/.openclaw/ 是分開的，後者用於儲存設定、憑證，以及 sessions. Important: the workspace is the default cwd, not a hard sandbox. 工具 會相對於工作區解析相對路徑，但除非啟用沙箱，否則絕對路徑仍可存取主機上的其他位置。 2. 若需要隔離，請使用 agents.defaults.sandbox（以及/或每個代理的沙箱設定）。 3. 啟用沙箱且 workspaceAccess 不是 "rw" 時，工具會在 ~/.openclaw/sandboxes 下的沙箱工作區中運作，而不是你的主機工作區。

​
預設位置

  • 預設：~/.openclaw/workspace
  • 若設定了 OPENCLAW_PROFILE 且不是 "default"，預設位置會變為 ~/.openclaw/workspace-<profile>。
  • 可在 ~/.openclaw/openclaw.json 中覆寫：
{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}
  1. openclaw onboard、openclaw configure 或 openclaw setup 會在缺少時建立工作區並植入啟動檔案。
如果你已自行管理工作區檔案，可以停用啟動檔案建立： 
{ agent: { skipBootstrap: true } }

​
額外的工作區資料夾

較舊的安裝可能建立了 ~/openclaw。 6. 同時保留多個工作區目錄可能造成驗證或狀態漂移的混淆，因為一次只會有一個工作區處於啟用狀態。 建議： 保持單一啟用中的工作區。 8. 8. 若不再使用多餘的資料夾，請將其封存或移到垃圾桶（例如 trash ~/openclaw）。 若不再使用多餘的資料夾，請將其封存或移到垃圾桶（例如 trash ~/openclaw）。 建議： 保留單一作用中的工作區。若不再使用額外資料夾，請將其封存或移至垃圾桶（例如 trash ~/openclaw）。若你刻意保留多個工作區，請確保 agents.defaults.workspace 指向目前作用中的那一個。 openclaw doctor 會在偵測到額外工作區目錄時發出警告。

​
9. 工作區檔案對照表（各檔案的用途）

以下是 OpenClaw 在工作區內預期的標準檔案：
  • AGENTS.md
    • 代理程式的操作指示，以及如何使用記憶。
      1. 在每個工作階段開始時載入。
    • 適合放置規則、優先順序與「行為方式」細節。
  • SOUL.md
    • 11. 人設、語氣與界線。
      1. 每個工作階段都會載入。
  • USER.md
    • 使用者是誰，以及該如何稱呼。
      1. 每個工作階段都會載入。
  • IDENTITY.md
    • 14. 代理的名稱、氛圍與表情符號。
      1. 在啟動儀式期間建立/更新。
  • TOOLS.md
    • 關於你本地工具與慣例的備註。
    • 不會控制工具可用性；僅作為指引。
  • HEARTBEAT.md
    • 心跳執行的可選微型檢查清單。
    • 請保持精簡以避免消耗過多 token。
  • BOOT.md
    • 16. 啟用內部掛鉤時，於閘道重新啟動時執行的選用啟動檢查清單。
      1. 保持精簡；對外傳送請使用訊息工具。
  • BOOTSTRAP.md
    • 一次性的首次執行儀式。
      1. 僅在全新工作區時建立。
    • 儀式完成後請刪除。
  • memory/YYYY-MM-DD.md
    • 每日記憶紀錄（每天一個檔案）。
    • 建議在工作階段開始時閱讀今天 + 昨天的內容。
  • MEMORY.md（可選）
    • 精選的長期記憶。
      1. 僅在主要的私人工作階段中載入（非共享/群組情境）。
  1. 有關流程與自動記憶體清空，請參見 Memory。
  • skills/（可選）
    • 工作區專屬 Skills。
    • 當名稱衝突時，會覆寫受管／隨附的 Skills。
  • canvas/（可選）
    • 用於節點顯示的 Canvas UI 檔案（例如 canvas/index.html）。
  1. 若任何啟動檔案缺失，OpenClaw 會將「缺少檔案」標記注入到工作階段中並繼續。 大型啟動檔在注入時會被裁切；可透過 agents.defaults.bootstrapMaxChars 調整上限（預設：20000）。 openclaw setup 可在不覆寫現有檔案的情況下重建缺失的預設值。

​
25. 工作區中不包含的內容

  1. 這些位於 ~/.openclaw/ 下，且不應提交到工作區儲存庫：
  • ~/.openclaw/openclaw.json（設定）
  • ~/.openclaw/credentials/（OAuth 權杖、API 金鑰）
  • ~/.openclaw/agents/<agentId>/sessions/（工作階段逐字稿與中繼資料）
  • ~/.openclaw/skills/（受管 Skills）
若需要遷移工作階段或設定，請分別複製它們並將其排除在版本控制之外。

​
Git 備份（建議，私有）

將工作區視為私人記憶。 29. 將其放在私人 git 儲存庫中，以便備份與復原。 請在執行 Gateway 的機器上執行以下步驟（工作區位於該處）。

​
1）初始化儲存庫

若已安裝 git，全新的工作區會自動初始化。若此工作區尚未是儲存庫，請執行： 31. 若此工作區尚未成為儲存庫，請執行： 
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 網頁 UI
  1. 在 GitHub 建立新的 私有 儲存庫。
  2. 不要以 README 初始化（避免合併衝突）。
  3. 複製 HTTPS 遠端 URL。
    1. 新增遠端並推送：
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 網頁 UI
  1. 在 GitLab 建立新的 私有 儲存庫。
  2. 不要以 README 初始化（避免合併衝突）。
  3. 複製 HTTPS 遠端 URL。
    1. 新增遠端並推送：
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

​
34. 請勿提交機密資料

即使在私有儲存庫中，也請避免在工作區儲存機密：
  • API 金鑰、OAuth 權杖、密碼或私有憑證。
  • ~/.openclaw/ 之下的任何內容。
  • 原始聊天轉存或敏感附件。
若必須儲存敏感參考，請使用佔位符，並將真正的機密保存在其他地方（密碼管理器、環境變數或 ~/.openclaw/）。 建議的 .gitignore 起始範本： 
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

​
將工作區移至新機器

  1. 將儲存庫複製到目標路徑（預設為 ~/.openclaw/workspace）。
  2. 在 ~/.openclaw/openclaw.json 中將 agents.defaults.workspace 設為該路徑。
  3. 執行 openclaw setup --workspace <path> 以植入任何缺失的檔案。
  4. 若需要工作階段，請另行從舊機器複製 ~/.openclaw/agents/<agentId>/sessions/。

​
35) 進階說明

  • 多代理路由可為每個代理使用不同的工作區。 37. 路由設定請參見 Channel routing。
  • 若啟用 agents.defaults.sandbox，非主要工作階段可在 agents.defaults.sandbox.workspaceRoot 之下使用每個工作階段的沙箱工作區。