一、什么是"一个 Agent"？

一个 Agent 是一个完全隔离的 AI 大脑，拥有独立的：

组成	说明
工作空间（Workspace）	SOUL.md、AGENTS.md、USER.md、技能、本地文件
状态目录（agentDir）	认证配置、模型注册、Agent 专属配置
会话存储（Sessions）	聊天历史、路由状态，完全独立
认证配置（Auth）	API Key、模型凭证，各 Agent 独立
技能（Skills）	工作空间级技能独立，共享级技能通用

一句话：不同 Agent = 不同人格、不同记忆、不同能力、不同权限

二、单 Agent vs 多 Agent

对比	单 Agent（默认）	多 Agent
Agent 数量	1 个（id: main）	多个（自定义 id）
人格	一个 SOUL.md	每个 Agent 独立 SOUL.md
记忆	共享	完全隔离
通道	所有消息进同一个 Agent	按规则路由到不同 Agent
适合场景	个人使用	多人/多场景/多角色

三、快速上手（创建多 Agent）

步骤 1：创建 Agent

# 创建一个"工作"Agent
openclaw agents add work

# 创建一个"生活"Agent
openclaw agents add life

每个 Agent 会自动获得独立的工作空间和状态目录。

步骤 2：绑定通道路由

# 将 Telegram 消息路由到 work Agent
openclaw agents bind --agent work --bind telegram:ops

# 将 WhatsApp 消息路由到 life Agent
openclaw agents bind --agent life --bind whatsapp

步骤 3：重启验证

openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

四、路由规则（消息如何分配到 Agent）

路由是确定性的，按最具体匹配优先：

优先级	匹配条件	示例
1（最高）	精确 peer 匹配（DM/群组 ID）	指定某个人的私聊 → work Agent
2	父级 peer 匹配（线程继承）	线程跟随父消息的 Agent
3	Discord guildId + roles	特定服务器+角色 → 某 Agent
4	Discord guildId	特定服务器 → 某 Agent
5	Slack teamId	特定团队 → 某 Agent
6	accountId 匹配	特定账号 → 某 Agent
7	通道级匹配	整个通道 → 某 Agent
8（最低）	默认 Agent	没有匹配时的兜底

五、六大核心使用场景

场景 1：按通道分流（日常聊天 vs 深度工作）

QQ （qqbot）用快速模型日常聊天，企业微信（wecom）用强力模型深度工作：

{
  agents: {
    list: [
      { id: "chat", name: "日常", model: "claude-sonnet-4-6", workspace: "~/.openclaw/workspace-chat" },
      { id: "opus", name: "深度工作", model: "claude-opus-4-6", workspace: "~/.openclaw/workspace-opus" }
    ]
  },
  bindings: [
    { agentId: "chat", match: { channel: "qqbot" } },
    { agentId: "opus", match: { channel: "wecom" } }
  ]
}

效果：QQ 聊天用便宜快速的模型，企业微信上的复杂问题用最强模型

场景 2：多人共享一台服务器

Alex 和 Mia 共用一个 QQ 号码，但各自有独立的 AI 助手：

{
  agents: {
    list: [
      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
      { id: "mia", workspace: "~/.openclaw/workspace-mia" }
    ]
  },
  bindings: [
    { agentId: "alex", match: { channel: "qqbot", peer: { kind: "direct", id: "+15551230001" } } },
    { agentId: "mia", match: { channel: "qqbot", peer: { kind: "direct", id: "+15551230002" } } }
  ]
}

效果：同一个号码，不同人私聊到不同 Agent，互不干扰

场景 3：家庭群专属 Agent（受限权限）

给家庭 QQ 群配一个专属 Agent，限制权限防止误操作：

Copy

{
  agents: {
    list: [{
      id: "family", name: "Family Bot",
      workspace: "~/.openclaw/workspace-family",
      sandbox: { mode: "all", scope: "agent" },
      tools: {
        allow: ["exec", "read", "sessions_list"],
        deny: ["write", "edit", "browser", "cron"]
      }
    }]
  },
  bindings: [{
    agentId: "family",
    match: { channel: "qqbot", peer: { kind: "group", id: "[email protected]" } }
  }]
}

效果：家庭群里的 Agent 只能查询不能修改，安全可控

场景 4：每个 Discord Bot 一个 Agent

不同 Discord 频道用不同 Bot（不同人格）：

{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "coding", workspace: "~/.openclaw/workspace-coding" }
    ]
  },
  bindings: [
    { agentId: "main", match: { channel: "discord", accountId: "default" } },
    { agentId: "coding", match: { channel: "discord", accountId: "coding" } }
  ]
}

效果：一个 Bot 负责闲聊，另一个 Bot 负责代码审查

场景 5：Sub-Agent（后台并行任务）

主 Agent 可以生成子 Agent 并行处理任务：

# 在 Web UI 中
/subagents spawn main "帮我调研 AI Agent 的最新论文" --model claude-sonnet-4-6

# 查看状态
/subagents list

# 查看输出
/subagents log 1

效果：主 Agent 不阻塞，子 Agent 后台跑完自动汇报结果

命令	说明
/subagents list	列出当前会话的子 Agent
/subagents spawn <agentId> <task>	生成子 Agent 执行任务
/subagents kill <id\|all>	终止子 Agent
/subagents log <id>	查看子 Agent 输出日志
/subagents steer <id> <msg>	引导子 Agent 方向
/subagents info <id>	查看子 Agent 详情

场景 6：嵌套 Sub-Agent（编排器模式）

允许子 Agent 再生成子 Agent，实现复杂任务分解：