---
title: "配置 Agent"
description: "配置 OpenClaw Agent：workspace、repoRoot、bootstrap 注入、skills allowlist、agentDir、session、模型和多 Agent 路由邊界。"
verifiedAt: "2026-05-06"
---

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

> [!NOTE]
> **這一章用 14 分鐘換什麼**：你會知道 workspace、repoRoot、agentDir、session store、bootstrap 檔案和 skills allowlist 分別管什麼，也能判斷什麼時候真的需要多 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 使用哪個模型、允許哪些模型切換。

```mermaid
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
```

> [!IMPORTANT]
> **Agent 是完整作用域**：多 Agent 不是多幾套提示詞，而是多套 workspace、auth profiles、sessions 和路由邊界。

## 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`。

| 欄位 | 作用 | 不是 |
|------|------|------|
| `workspace` | 工具預設 cwd、上下文檔案根、workspace skills 根 | 不是硬沙箱 |
| `repoRoot` | 提示系統專案根目錄，提升上下文準確性 | 不是許可權邊界 |
| `agentDir` | per-agent auth profiles、模型 registry、session 相關狀態 | 不是 workspace |

## 4. Bootstrap 檔案不要堆太滿

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

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

| 檔案 | 應該放什麼 |
|------|------|
| `AGENTS.md` | 操作規則、任務優先順序、工具約定 |
| `SOUL.md` | 人格、邊界、語氣 |
| `TOOLS.md` | 使用者維護的工具說明，不是許可權系統 |
| `USER.md` | 使用者背景和偏好 |
| `MEMORY.md` | 長期精華，謹慎進入共享上下文 |
| `HEARTBEAT.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 越應該少。

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

> [!WARNING]
> **per-agent skills 不是和 defaults 合併**：具體 Agent 寫了非空 `skills`，那就是最終集合。不要以為它會自動繼承 defaults 後再追加。

## 6. Skills 的位置和優先順序

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

| 優先順序 | 來源 | 路徑 |
|:-:|------|------|
| 1 | Workspace skills | `<workspace>/skills` |
| 2 | Project agent skills | `<workspace>/.agents/skills` |
| 3 | Personal agent skills | `~/.agents/skills` |
| 4 | Managed/local skills | `~/.openclaw/skills` |
| 5 | Bundled skills | 安裝包內建 |
| 6 | Extra skill folders | `skills.load.extraDirs` |

同名 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 相關狀態通常在：

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

Auth profiles 是 per-agent 的：

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

> [!CAUTION]
> **不要複用 agentDir**：多個 Agent 複用同一個 `agentDir` 會造成 auth 和 session 碰撞。需要獨立 OAuth 賬號，就從那個 Agent 自己登入。

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

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

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

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

建立新 Agent 可以用：

```bash
openclaw agents add work
openclaw agents list --bindings
```

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

| 該拆 Agent | 不該拆 Agent |
|------|------|
| 私人入口和客服入口不同 | 只是想換一個稱呼 |
| 不同賬號需要不同 OAuth | 只是偶爾做不同任務 |
| 共享群只允許窄 tools | 所有入口許可權完全一樣 |
| 工作和家庭記憶必須隔離 | 只是為了看起來高階 |

> [!TIP]
> **拆 Agent 看邊界，不看任務名**：只要 workspace、auth、session、tools 或 channel binding 有真實差異，就值得拆；只是換稱呼或換模型，通常不值得。

## 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？

> [!IMPORTANT]
> **過關標準**：你能用一句話說清 —— “Agent 配置的核心不是多填欄位，而是把 workspace、skills、auth、session 和 channel binding 的邊界切清楚。”

## 12. 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/openclaw/official/01-gateway-runtime/channels" title="Channel 配置" description="Agent 邊界清楚後，繼續看訊息入口如何路由到 Agent。" />
  <Card href="/zh-Hant/docs/openclaw/official/00-getting-started/workspace" title="配置 Agent Workspace" description="如果 workspace 還沒整理，先回到入門組補齊檔案邊界。" />
  <Card href="/zh-Hant/docs/openclaw/understanding/07-multi-agent" title="理解：多 Agent" description="從理解篇繼續核對 workspace、agentDir、session store 和 routing 的真實邊界。" />
</Cards>

## 13. 官方資料

- [Configuration — agents](https://docs.openclaw.ai/gateway/config-agents)
- [Agent runtime](https://docs.openclaw.ai/concepts/agent)
- [Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace)
- [Multi-agent routing](https://docs.openclaw.ai/concepts/multi-agent)
- [Skills](https://docs.openclaw.ai/tools/skills)
