---
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="/docs/openclaw/official/01-gateway-runtime/channels" title="Channel 配置" description="Agent 边界清楚后，继续看消息入口如何路由到 Agent。" />
  <Card href="/docs/openclaw/official/00-getting-started/workspace" title="配置 Agent Workspace" description="如果 workspace 还没整理，先回到入门组补齐文件边界。" />
  <Card href="/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)
