Agent 工作區

工作區就是 agent 的家。它是檔案工具和工作區上下文唯一使用的工作目錄。請將它視為私密空間，當作記憶來對待。

工作區和 ~/.openclaw/ 是分開的——後者存放設定檔、認證資訊和 session。

重要： 工作區是預設工作目錄，不是嚴格的沙盒。工具會把相對路徑解析到工作區，但絕對路徑仍然可以存取主機上的其他位置，除非啟用沙盒模式。如果你需要隔離，請使用 agents.defaults.sandbox（以及/或者 per-agent 沙盒設定）。 啟用沙盒且 workspaceAccess 不是 "rw" 時，工具會在 ~/.openclaw/sandboxes 下的沙盒工作區運作，而不是你的主機工作區。

預設位置

  • 預設：~/.openclaw/workspace
  • 如果 OPENCLAW_PROFILE 已設定且不是 "default"，預設路徑會變成 ~/.openclaw/workspace-<profile>。
  • 在 ~/.openclaw/openclaw.json 中覆寫：
{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

openclaw onboard、openclaw configure 或 openclaw setup 會建立工作區，並在引導檔案缺失時填入預設內容。 沙盒種子複製只接受工作區內的一般檔案；解析到來源工作區外部的 symlink/hardlink 會被忽略。

如果你已經自行管理工作區檔案，可以停用引導檔案的建立：

{ agent: { skipBootstrap: true } }

多餘的工作區資料夾

舊版安裝可能建立了 ~/openclaw。保留多個工作區目錄容易造成認證或狀態不一致的困擾，因為同一時間只有一個工作區是啟用的。

建議： 只保留一個啟用的工作區。如果你不再使用多餘的資料夾，把它們歸檔或移到垃圾桶（例如 trash ~/openclaw）。 如果你刻意保留多個工作區，請確保 agents.defaults.workspace 指向啟用的那一個。

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

工作區檔案總覽（各檔案的用途）

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

  • AGENTS.md

    • Agent 的操作指令，以及記憶的使用方式。
    • 每次 session 啟動時載入。
    • 適合放規則、優先順序和「該怎麼行動」的細節。

  • SOUL.md

    • 人格設定、語調與行為邊界。
    • 每次 session 載入。

  • USER.md

    • 使用者資訊與稱呼偏好。
    • 每次 session 載入。

  • IDENTITY.md

    • Agent 的名稱、風格與 emoji。
    • 在引導儀式中建立/更新。

  • TOOLS.md

    • 關於本地工具與慣例的筆記。
    • 不控制工具的可用性，純粹是指引。

  • HEARTBEAT.md

    • 可選的心跳執行小清單。
    • 保持簡短，避免浪費 token。

  • BOOT.md

    • 可選的啟動清單，在啟用內部 hook 的情況下於 gateway 重啟時執行。
    • 保持簡短；用 message 工具做對外發送。

  • BOOTSTRAP.md

    • 一次性的首次執行儀式。
    • 只在全新的工作區建立。
    • 儀式完成後刪除。

  • memory/YYYY-MM-DD.md

    • 每日記憶日誌（每天一個檔案）。
    • 建議在 session 開始時讀取今天和昨天的記錄。

  • MEMORY.md（可選）

    • 經過整理的長期記憶。
    • 只在主要的私人 session 載入（不在共享/群組情境中使用）。

請參閱 Memory 瞭解工作流程和自動記憶刷寫。

  • skills/（可選）

    • 工作區專屬的 skills。
    • 名稱衝突時會覆寫受管理/內建的 skills。

  • canvas/（可選）

    • Canvas UI 檔案，供節點顯示用（例如 canvas/index.html）。

如果任何引導檔案缺失，OpenClaw 會在 session 中注入一個「檔案缺失」標記然後繼續。大型引導檔案在注入時會被截斷；可用 agents.defaults.bootstrapMaxChars（預設 20000）和 agents.defaults.bootstrapTotalMaxChars（預設 150000）調整限制。 openclaw setup 可以重建缺失的預設檔案，不會覆寫已存在的檔案。

不在工作區裡的東西

以下內容存放在 ~/.openclaw/ 下，不應該提交到工作區的 repo：

  • ~/.openclaw/openclaw.json（設定檔）
  • ~/.openclaw/credentials/（OAuth token、API key）
  • ~/.openclaw/agents/<agentId>/sessions/（session 對話記錄 + 中繼資料）
  • ~/.openclaw/skills/（受管理的 skills）

如果需要遷移 session 或設定，請單獨複製，並把它們排除在版本控制之外。

Git 備份（建議使用，保持私有）

把工作區視為私密記憶。放到一個私有 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 上建立一個新的私有倉庫。
  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 上建立一個新的私有倉庫。
  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

不要提交機密資訊

即使在私有 repo 中，也要避免在工作區存放機密：

  • API key、OAuth token、密碼或私有認證資訊。
  • ~/.openclaw/ 底下的任何東西。
  • 未經處理的聊天記錄傾印或敏感附件。

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

建議的 .gitignore 範本：

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

將工作區搬到新機器

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

進階說明

  • 多 agent 路由可以為每個 agent 使用不同的工作區。請參閱 Channel routing 瞭解路由設定。
  • 如果啟用了 agents.defaults.sandbox，非主要 session 可以使用 agents.defaults.sandbox.workspaceRoot 下的 per-session 沙盒工作區。
arrow_back
上一頁
Context
下一頁
OAuth
arrow_forward