配置 Agent

OpenClaw 的 Agent 配置解決的是一個問題：誰來處理訊息、在哪個 workspace 工作、能用哪些 skills 和 tools、上下文如何隔離、會話和認證狀態放在哪裡。新手不要先背欄位，先把 Agent 當作一個有住處、有工具、有身份、有邊界的工作單元。

1. 一個 Agent 到底包含什麼

在 OpenClaw 裡，一個 Agent 不是一個 prompt 名字，而是一組完整邊界：

• Workspace：工作目錄、啟動檔案、記憶、workspace skills。
• Agent dir：每個 Agent 自己的狀態目錄，包含 auth profiles、模型 registry 和 per-agent 配置。
• Session store：這個 Agent 的會話歷史和路由狀態。
• Skills allowlist：這個 Agent 允許載入和呼叫哪些 skills。
• Model config：這個 Agent 使用哪個模型、允許哪些模型切換。

flowchart TD
    Agent["Agent"]
    Workspace["Workspace"]
    AgentDir["agentDir"]
    Sessions["Session store"]
    Skills["Skills allowlist"]
    Models["Models"]
    Channels["Channel bindings"]

    Agent --> Workspace
    Agent --> AgentDir
    Agent --> Sessions
    Agent --> Skills
    Agent --> Models
    Channels --> Agent

    style Agent fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Workspace fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style AgentDir fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Channels fill:#fee2e2,stroke:#ef4444,stroke-width:2px

2. 先理解 workspace

agents.defaults.workspace 是 Agent 的預設工作目錄。檔案工具、workspace 級 skills、bootstrap 檔案和長期記憶都會圍繞它展開。

但 workspace 不是天然沙箱。官方 Agent workspace 文件提醒：它是預設 cwd 和上下文根，不是硬許可權邊界。需要隔離時，要配置 sandbox 或 per-agent sandbox。

新手原則：

• 私人 Agent、工作 Agent、公開入口不要共用同一個 workspace。
• workspace 要當作私有記憶處理。
• 不要把客戶資料、金鑰和公開入口混在同一個 workspace。

3. repoRoot 和 workspace 不一樣

repoRoot 只是幫助系統提示更準確，讓 Agent 知道專案根目錄在哪裡。它不是許可權邊界。

如果你只是讓 OpenClaw 管理個人助手，先把 workspace 配清楚就夠。只有當 workspace 裡包含多個專案、或者你需要明確某個儲存庫上下文時，再考慮 repoRoot。

4. Bootstrap 檔案不要堆太滿

OpenClaw 會從 workspace 注入常見 bootstrap 檔案，例如 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md、MEMORY.md。

這些檔案不是越大越好。更穩的分工是：

官方配置還給了幾個重要開關：agents.defaults.skipBootstrap 禁止自動建立 bootstrap 檔案；agents.defaults.skipOptionalBootstrapFiles 跳過選定 optional 檔案；agents.defaults.contextInjection 控制什麼時候注入 workspace bootstrap，預設 always；agents.defaults.bootstrapMaxChars 控制單個 bootstrap 檔案注入上限，預設 12000；agents.defaults.bootstrapTotalMaxChars 控制所有 bootstrap 檔案總注入上限，預設 60000。

如果所有內容都塞進一個巨大檔案，Agent 會更難找到重點，也更容易觸發上下文截斷。

5. Skills allowlist 怎麼理解

OpenClaw 可以透過 agents.defaults.skills 給預設 Agent 設定 skill allowlist，也可以在具體 agent 上覆蓋。

繼承規則的重點是：

• 不寫預設 allowlist：預設不限制 skills。
• 具體 Agent 不寫 skills：繼承 defaults。
• 具體 Agent 寫空列表：這個 Agent 不啟用 skills。
• 具體 Agent 寫非空列表：使用這個最終集合，不和 defaults 合併。

新手可以這樣用：私人主 Agent 寬一點，共享入口或群組入口窄一點。越接近陌生人輸入，skills 越應該少。

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" },
      { id: "docs", skills: ["docs-search"] },
      { id: "locked-down", skills: [] },
    ],
  },
}

6. Skills 的位置和優先順序

OpenClaw 載入 skills 的優先順序從高到低是：

同名 skill 衝突時，高優先順序 wins。Codex CLI 的 native $CODEX_HOME/skills 不是 OpenClaw 的自動 skill root；需要遷移時走 openclaw migrate codex --dry-run 和互動選擇。

第三方 skills 要按不可信內容處理。讀完再啟用，必要時搭配 sandbox 和更窄的 tools policy。

7. Session 隔離比模型更重要

多人、多渠道、多賬號時，先處理 session，再討論模型。

官方配置裡常見的 DM scope 包括按 sender、channel、account、peer 隔離。新手只要記住：不要讓陌生人共享 main session，不要讓家庭群、工作群、個人私信混在一個上下文裡。

模型可以換，混亂的上下文會讓 Agent 誤判身份、許可權和歷史承諾。

Session 相關狀態通常在：

~/.openclaw/agents/<agentId>/sessions/

Auth profiles 是 per-agent 的：

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

8. 多 Agent 路由什麼時候需要

一個 Gateway 可以執行多個隔離 Agent。它適合這些情況：

• 個人生活和工作需要分開。
• 支援入口和私人入口需要分開。
• 不同渠道需要不同 workspace、skills 或模型。
• 某些群組只允許只讀或受限工具。

不要為了“看起來多 Agent”而拆。拆分的理由應該是許可權、上下文或職責真的不同。

建立新 Agent 可以用：

openclaw agents add work
openclaw agents list --bindings

路由上要記住一個概念：binding（繫結）把某個 channel account 或入口對映到某個 Agent。

9. 新手常見坑

• 把 workspace 當成安全沙箱。
• 公開入口和私人助手共用 workspace。
• Agent skill allowlist 寫錯，以為會和 defaults 合併。
• Bootstrap 檔案堆滿資料，導致真正規則被淹沒。
• 多賬號路由到同一個 session。
• 只換模型，不治理 tools、skills 和 session。
• 多個 Agent 複用 agentDir。
• 把第三方 skills 當成可信程式碼直接啟用。

10. 怎麼判斷 Agent 配置健康

健康標準：

• 每個 Agent 的職責一句話能說清。
• 每個 Agent 有明確 workspace。
• 每個 Agent 有獨立 agentDir 和 session store。
• 公開或共享入口的 skills 和 tools 更窄。
• 多賬號或多渠道不會共享 main session。
• bootstrap 檔案分工清楚，沒有一個檔案承載全部知識。
• 需要隔離時已經使用 sandbox，而不是隻依賴 workspace。

Agent 配置的目標不是欄位完整，而是讓每個入口都有清楚邊界。

11. 本章自檢

1. workspace、repoRoot、agentDir 分別解決什麼問題？
2. 具體 Agent 的非空 skills 會不會和 defaults 合併？
3. 什麼時候應該拆成多個 Agent？

12. 接下來去哪

13. 官方資料

• Configuration — agents
• Agent runtime
• Agent workspace
• Multi-agent routing
• Skills