OpenClaw 多 Agent 教程：如何配置多个角色、多个工作区和多套路由规则

OpenClaw 的强项不是只跑一个聊天助手，而是在一个 Gateway 内承载多个 Agent、多个角色和多套配置。如果配置得当，你可以让“代码助手”“资料研究员”“运维值班员”“客服助理”“内容编辑”分别拥有自己的工作区、记忆、工具权限和路由规则。这样既能提升效率，也能避免所有任务都丢给同一个 Agent 后出现上下文混乱、权限过大和责任边界不清的问题。

一、先理解 OpenClaw 的几个核心概念

OpenClaw 官方把它定位为一个自托管的 AI Agent 多渠道 Gateway。简单说，Gateway 是控制平面，负责连接聊天渠道、移动节点、WebChat、工具、会话、鉴权和 Agent 路由。Agent 则是实际处理任务的“角色实例”，可以有自己的工作目录、状态目录、会话存储和行为设定。

在多 Agent 模式下，不同 Agent 不是简单共享同一套上下文，而是可以被隔离。官方文档提到，多 Agent routing 允许在一个 Gateway 进程中运行多个隔离 Agent，每个 Agent 可以拥有独立的 workspace、agentDir 和 session store，并通过 bindings 把不同渠道、账号或对话路由到对应 Agent。

你可以把它理解成一个小型 AI 团队：Gateway 是调度台，channel 是入口，bindings 是分派规则，Agent 是岗位，workspace 是办公桌，agentDir 是个人资料柜，tools 是能使用的工具。

二、什么时候需要多个 Agent

不是所有 OpenClaw 用户都需要多 Agent。刚开始使用时，建议先用一个默认 Agent 跑通 Gateway、认证、渠道和基础工具。当你遇到下面这些情况，再考虑拆成多个 Agent：

1. 任务类型差异很大。例如一个 Agent 做代码重构，另一个 Agent 做资讯选题和写作。
2. 权限等级不同。例如运维 Agent 可以读服务器日志，但内容 Agent 不应该接触 SSH 和生产密钥。
3. 工作区需要隔离。例如客户 A 和客户 B 的项目资料不能混在一起。
4. 角色风格不同。例如一个 Agent 要严谨审计，一个 Agent 要创意发散。
5. 渠道入口不同。例如 Telegram 私聊走个人助理，Slack 工程频道走代码助理，WhatsApp 走生活助理。

如果只是偶尔并行处理一个任务，优先考虑子 Agent 或临时后台任务；如果一个角色长期存在、权限长期不同、工作区长期独立，再配置持久 Agent。

三、推荐的多 Agent 架构

一个实用的 OpenClaw 多 Agent 架构通常包括四层：

1. Gateway 层：统一运行 OpenClaw Gateway，负责渠道接入、鉴权、配置加载和路由。
2. Agent 层：定义多个长期 Agent，例如 coder、researcher、ops、writer、support。
3. Workspace 层：每个 Agent 指向自己的工作目录，避免文件和记忆混用。
4. Binding 层：根据渠道、账号、对话、群组或关键字，把消息路由到正确 Agent。

例如，一个个人或小团队可以这样设计：

四、多套配置应该怎么拆

OpenClaw 的配置不应该全堆在一个默认 Agent 里。更合理的做法是把配置分成三类：

1. 全局配置

全局配置放在 Gateway 层，例如服务端口、认证、渠道插件、日志目录、基础安全策略、默认模型和通用 session 策略。它适合放“所有 Agent 都必须遵守”的规则。

2. Agent 默认配置

Agent defaults 用来设置 Agent 通用默认值，例如默认模型、会话策略、消息格式、工具基线权限。官方配置文档中也把 agent-scoped keys 放在 agents.*、multiAgent.*、session.*、messages.* 和 talk.* 这类配置下管理。

3. 单个 Agent 配置

单个 Agent 配置负责定义这个角色自己的名称、说明、工作区、状态目录、模型、工具允许/禁止列表和绑定规则。例如 coder 可以使用代码编辑工具，researcher 可以使用网页搜索和资料整理工具，writer 可以使用内容模板和 SEO 检查工具。

拆配置的原则是：能全局统一的不要重复写；涉及角色差异、权限差异、工作区差异的必须写到 Agent 自己名下。

五、一个示例配置思路

下面是一个抽象示例，具体字段名要以你当前 OpenClaw 版本的 schema 为准。官方建议在编辑配置前查看配置 schema，避免字段过期或拼错。

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "claude-sonnet-or-other-model"
      },
      "tools": {
        "elevated": false
      }
    },
    "list": [
      {
        "id": "coder",
        "name": "代码助手",
        "workspace": "/data/openclaw/workspaces/coder",
        "agentDir": "/data/openclaw/agents/coder",
        "tools": {
          "allow": ["read", "edit", "test"],
          "deny": ["deploy", "secrets", "payment"]
        }
      },
      {
        "id": "researcher",
        "name": "资料研究员",
        "workspace": "/data/openclaw/workspaces/researcher",
        "agentDir": "/data/openclaw/agents/researcher",
        "tools": {
          "allow": ["web_search", "read", "write_report"],
          "deny": ["shell", "server_admin"]
        }
      },
      {
        "id": "ops",
        "name": "运维值班员",
        "workspace": "/data/openclaw/workspaces/ops",
        "agentDir": "/data/openclaw/agents/ops",
        "tools": {
          "allow": ["read_logs", "server_status"],
          "elevated": false
        }
      }
    ]
  },
  "multiAgent": {
    "enabled": true,
    "bindings": [
      {"channel": "slack", "room": "engineering", "agent": "coder"},
      {"channel": "telegram", "chat": "research", "agent": "researcher"},
      {"channel": "telegram", "chat": "ops-alert", "agent": "ops"}
    ]
  }
}

这个示例的重点不是字段逐字照抄，而是配置结构：每个 Agent 有独立身份、独立目录、独立权限；multiAgent.bindings 负责把入口消息分派给对应 Agent。

六、角色文件应该怎么写

每个 Agent 最好有自己的角色说明文件，例如 agent.md、SOUL.md 或项目约定中的说明文件。它的作用类似“岗位说明书”，不要写成空泛人格设定，而要明确任务边界。

一个好的角色文件至少包含：

1. 职责：这个 Agent 负责什么，不负责什么。
2. 输入：它通常接收哪些任务、文件或消息。
3. 输出：它应该产出代码、报告、清单、回复还是告警。
4. 权限边界：哪些操作必须询问，哪些操作禁止。
5. 质量标准：如何判断任务完成，例如测试通过、引用来源、生成摘要格式。
6. 升级规则：遇到权限、生产系统、敏感数据时如何请求人工确认。

例如 writer Agent 可以写：“你负责 599IT AI 资讯文章的结构、SEO 标题、摘要、标签建议和内容润色；不得修改服务器配置；不得处理支付、账号和密钥；涉及事实更新时间必须标明来源。”这种说明比“你是一个优秀写手”更可执行。

七、bindings 路由规则怎么设计

bindings 是多 Agent 的关键。设计不好，消息会被错误 Agent 接走，轻则答非所问，重则权限越界。建议按优先级设计：

1. 精确绑定优先。指定频道、群组、用户、会话的规则放在前面。
2. 公共规则靠后。例如所有 Telegram 消息默认给 default，不要放在特定规则前面。
3. 高权限 Agent 不做默认入口。ops、server、deploy 这类 Agent 不应该接收所有未知消息。
4. 路由规则每次修改后检查。运行 agents list 或带 bindings 的检查命令，确认消息会进入预期 Agent。

一个常见错误是把“团队群”直接绑定到高权限 Agent。正确做法是让团队群先进入低权限 coordinator 或 default Agent，只有明确触发运维任务时才转给 ops，并且敏感动作需要人工确认。

八、权限和安全：多 Agent 最容易踩坑的地方

多 Agent 最大的好处是隔离，最大的风险也是隔离失败。OpenClaw 官方安全文档特别提醒，tools.elevated 这类逃逸沙箱的能力要严格限制，不要给陌生人或公开入口开放。你应该把高权限工具视为生产服务器 root 权限一样管理。

建议采用以下安全策略：

1. 默认拒绝。所有 Agent 默认不开放高风险工具，按角色逐步加。
2. 最小权限。内容 Agent 不需要 shell，研究 Agent 不需要服务器密钥，客服 Agent 不需要代码仓库写权限。
3. 目录隔离。每个 Agent 的 workspace 和 agentDir 独立，避免跨项目读写。
4. 敏感动作确认。删除文件、发送邮件、部署、修改数据库、操作支付、关闭服务必须人工确认。
5. 日志审计。保存 Agent 接收的任务、调用的工具、输出结果和人工确认记录。
6. 公开渠道低权限。WhatsApp、Telegram 群、Slack 公共频道不要直接绑定高权限 Agent。

九、企业场景下的多 Agent 模板

如果是企业内部使用，可以从下面这套角色开始：

这套模板的关键是“协调 Agent 低权限，高权限 Agent 专用化”。不要让一个全能 Agent 同时管理内容、代码、服务器和客户数据。

十、排错清单

多 Agent 配置出问题时，可以按下面顺序检查：

1. Gateway 是否成功启动，配置是否通过 schema 校验。
2. agents.list 中每个 Agent 的 id 是否唯一。
3. workspace 和 agentDir 路径是否存在，进程是否有读写权限。
4. bindings 是否匹配到了正确渠道、账号、群组或会话。
5. 默认 Agent 是否抢走了本该进入特定 Agent 的消息。
6. 工具权限是否过严，导致 Agent 无法完成任务。
7. 工具权限是否过宽，导致 Agent 能访问不该访问的目录或服务。
8. 模型配置是否可用，API Key 是否只暴露给需要的 Agent。
9. session store 是否混用，导致上下文串台。
10. 日志里是否出现认证、节点版本或 channel plugin 错误。

十一、最佳实践总结

OpenClaw 多 Agent 的核心不是“越多越好”，而是“职责清楚、权限清楚、路由清楚”。建议遵循这几个原则：

1. 先跑通一个 Agent，再拆多个 Agent。
2. 只有长期角色才做持久 Agent，短期并行任务用子 Agent。
3. 每个 Agent 必须有独立职责和权限边界。
4. 高权限 Agent 不接公共入口。
5. bindings 规则从精确到宽泛排列。
6. 配置修改后立刻检查路由结果。
7. 把模型、工具、目录和密钥都当成可治理资源。

当你把这些规则建立起来，OpenClaw 就不再只是一个“能聊天的助手”，而会变成一个可以长期运行的 AI 工作团队。它能同时处理代码、研究、内容、运维和客服，但每个角色都在自己的边界内工作，这才是多 Agent 配置真正的价值。

参考资料：OpenClaw 官方文档中的 Multi-agent routing、Configuration — agents、Configuration reference、Nodes 和 Security 页面，以及 OpenClaw GitHub 项目说明。