配置 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