官方教程中文版Gateway 运行时
配置 Agent
基于 OpenClaw 官方 agents 配置文档，帮助新手理解 workspace、skills、bootstrap、session 和多 Agent 路由。
OpenClaw 的 Agent 配置解决的是“谁来处理消息、在哪个 workspace 工作、能用哪些 skills 和 tools、上下文如何隔离”。新手不要先背字段，先把 Agent 当作一个有住处、有工具、有身份、有边界的工作单元。
先理解 workspace
agents.defaults.workspace 是 Agent 的默认工作目录。文件工具、workspace 级 skills、bootstrap 文件和长期记忆都会围绕它展开。
但 workspace 不是天然沙箱。官方 Agent workspace 文档提醒：它是默认 cwd 和上下文根，不是硬权限边界。需要隔离时，要配置 sandbox 或 per-agent sandbox。
新手原则：
- 私人 Agent、工作 Agent、公开入口不要共用同一个 workspace。
- workspace 要当作私有记忆处理。
- 不要把客户数据、密钥和公开入口混在同一个 workspace。
repoRoot 和 workspace 不一样
repoRoot 只是帮助系统提示更准确，让 Agent 知道项目根目录在哪里。它不是权限边界。
如果你只是让 OpenClaw 管理个人助手，先把 workspace 配清楚就够。只有当 workspace 里包含多个项目、或者你需要明确某个仓库上下文时，再考虑 repoRoot。
Skills allowlist 怎么理解
OpenClaw 可以通过 agents.defaults.skills 给默认 Agent 设置 skill allowlist，也可以在具体 agent 上覆盖。
继承规则的重点是：
- 不写默认 allowlist：默认不限制 skills。
- 具体 Agent 不写 skills：继承 defaults。
- 具体 Agent 写空列表：这个 Agent 不启用 skills。
- 具体 Agent 写非空列表：使用这个最终集合，不和 defaults 合并。
新手可以这样用：私人主 Agent 宽一点，共享入口或群组入口窄一点。越接近陌生人输入，skills 越应该少。
Bootstrap 文件不要堆太满
OpenClaw 会从 workspace 注入常见 bootstrap 文件，例如 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、BOOTSTRAP.md、MEMORY.md。
这些文件不是越大越好。更稳的分工是：
AGENTS.md放操作规则和入口。SOUL.md放人格、边界和语气。TOOLS.md放用户维护的工具说明。USER.md放用户背景。MEMORY.md放长期精华。
如果所有内容都塞进一个巨大文件，Agent 会更难找到重点，也更容易触发上下文截断。
Session 隔离比模型更重要
多人、多渠道、多账号时，先处理 session，再讨论模型。
官方配置里常见的 DM scope 包括按 sender、channel、account、peer 隔离。新手只要记住：不要让陌生人共享 main session，不要让家庭群、工作群、个人私信混在一个上下文里。
模型可以换，混乱的上下文会让 Agent 误判身份、权限和历史承诺。
多 Agent 路由什么时候需要
一个 Gateway 可以运行多个隔离 Agent。它适合这些情况：
- 个人生活和工作需要分开。
- 支持入口和私人入口需要分开。
- 不同渠道需要不同 workspace、skills 或模型。
- 某些群组只允许只读或受限工具。
不要为了“看起来多 Agent”而拆。拆分的理由应该是权限、上下文或职责真的不同。
新手常见坑
- 把 workspace 当成安全沙箱。
- 公开入口和私人助手共用 workspace。
- Agent skill allowlist 写错，以为会和 defaults 合并。
- Bootstrap 文件堆满资料，导致真正规则被淹没。
- 多账号路由到同一个 session。
- 只换模型，不治理 tools、skills 和 session。
怎么判断 Agent 配置健康
健康标准：
- 每个 Agent 的职责一句话能说清。
- 每个 Agent 有明确 workspace。
- 公开或共享入口的 skills 和 tools 更窄。
- 多账号或多渠道不会共享 main session。
- bootstrap 文件分工清楚，没有一个文件承载全部知识。
- 需要隔离时已经使用 sandbox，而不是只依赖 workspace。
Agent 配置的目标不是字段完整，而是让每个入口都有清楚边界。
官方来源
最近更新：2026年5月4日