multi-agents-orchestration

OpenClaw 多 Agent 编排方法论

> 本 skill 定义了 OpenClaw 多 Agent 团队的编排方法论：两种协作模式的本质区别、如何共存、配置落点、排障指南。主 Agent 在需要搭建或调整团队协作时加载此 skill。

一、两种协作模式

OpenClaw 多 Agent 协作有两条独立链路。理解它们的区别是搭建团队的前提。

模式 A：后台调度（Backend Spawn）—— 主链路

主 Agent 通过 sessions_spawn 在后台拉起子 Agent。用户只和主 Agent 对话。

用户 → 主Agent → sessions_spawn(agentId, task) → 专业Agent → 结果回传 → 主Agent汇总输出

调用示例：

sessions_spawn({
  agentId: "finance",
  task: "分析这份财报，给出结论、依据和风险提示",
  mode: "run",
  runtime: "subagent"
})

特征：

模式 B：Discord @Mention —— 外显层

Agent 作为独立 Discord Bot 出现，用户或其他 Bot 通过 @ 直接触发。

Discord用户 → @某Bot → Discord Account → Gateway Binding → 对应Agent → 回复用户

特征：

模式 C：Bot-Bot @Mention —— 增强层（第三优先级）

Bot 之间在 Discord 里互相 @。非主流程，仅在明确需要公开协作时启用。

要求 allowBots: true 且 bot ID 进入白名单。核心调度仍应走 spawn。

二、两种模式的本质区别

| 维度 | Backend Spawn | Discord @Mention | |------|--------------|-----------------| | 本质 | 主Agent的内部编排能力 | 外部渠道的接入入口 | | 触发方式 | 主Agent代码调用 sessions_spawn | 用户在Discord频道 @ Bot | | 用户感知 | 只看到主Agent的汇总输出 | 看到独立Bot在频道发言 | | 配置依赖 | agents.list + subagents.allowAgents | 额外需要 token + accounts + bindings | | 是否必须 | 是（核心链路） | 否（可选增强） | | Agent间协作 | 主Agent内部路由，用户无感 | Bot之间公开@，用户可见 | | 适合场景 | 内部编排、复杂任务链、统一输出 | 角色外显、分频道值守、公开协作 |

三、两种模式如何同时运行

核心机制：同一个 Agent 可以同时被两种方式触发。

配置层面：
  agents.list 注册 Agent 身份    → spawn 链路使用
  discord accounts + bindings   → @mention 链路使用
  两套配置独立，互不冲突
运行层面：
  主Agent后台 spawn finance     → finance 在后台处理并返回结果
  用户在Discord @finance Bot   → finance 在频道直接回复
  两条链路并行，互不干扰

共存配置示例

一个 Agent 同时支持两种模式，需要两块配置：

1) agents.list 中注册（spawn 用）：

{
  "id": "finance",
  "name": "财务分析师",
  "workspace": "/Users/{USER}/.openclaw/workspace-finance",
  "identity": { "name": "财务分析师", "emoji": "📊" },
  "model": "kimi-coding/k2p5",
  "subagents": { "allowAgents": ["*"] }
}

2) Discord accounts + bindings 中配置（@mention 用）：

// accounts 部分
"finance": {
  "name": "财务分析师",
  "token": "BOT_TOKEN",
  "groupPolicy": "allowlist",
  "guilds": { "GUILD_ID": {} }
}
// bindings 部分
{
  "agentId": "finance",
  "match": { "channel": "discord", "accountId": "finance" }
}

只要 spawn 不要 Discord？ 只配 agents.list，不配 accounts/bindings。 只要 Discord 不要 spawn？ 不推荐，但技术上可以只配 Discord 侧。 两个都要？ 两块都配，各自生效。

四、三种部署模式选择

模式 A：后台编排优先（推荐默认）

模式 B：后台编排 + Discord 外显并存

模式 C：全 Discord 可见协作

五、Agent vs Skill 判断

| 需求 | 用 Agent | 用 Skill | |------|---------|---------| | 独立 workspace / session / 记忆 | Yes | | | 需要被主Agent后台 spawn | Yes | | | 需要在Discord作为独立Bot | Yes | | | 只是临时换个专业视角 | | Yes | | 只是输出格式变化 | | Yes | | 不想增加运维成本 | | Yes |

判断标准： 独立身份/记忆/调度 → Agent；专业视角/格式转换 → Skill。

六、推荐架构分层

主控层  → main（任务理解、拆解、调度、汇总、对外输出）
专业层  → finance / compliance / news / ...（接收后台子任务）
技术层  → product-manager / frontend / backend / qa（产品研发落地）
接入层  → Discord accounts / bindings / channel rules（外部入口）
工具层  → skills（knowledge-organizer / coding-agent / ppt-writer）

每个角色必须定义三件事： 1. 职责 —— 它负责什么 2. 边界 —— 它不负责什么，什么时候交给别人 3. 协作关系 —— 它什么时候该找谁复核、补充、执行

七、配置落点总览

文件结构

~/.openclaw/
├── openclaw.json                # 主Gateway配置（agents/discord/bindings）
├── openclaw-rescue.json         # Rescue Gateway独立配置
├── workspace/                   # 主Agent workspace
│   ├── SOUL.md                  # 角色定位、职责、边界
│   ├── IDENTITY.md              # 身份显示
│   ├── HEARTBEAT.md             # 定时/心跳
│   ├── TEAM.md                  # 团队花名册
│   └── skills/                  # Skills目录
└── workspace-{agent-id}/        # 各专业Agent workspace
    ├── SOUL.md
    ├── IDENTITY.md
    └── HEARTBEAT.md

改完是否需要重启

| 改了什么 | 是否重启 Gateway | |---------|----------------| | openclaw.json | 必须重启 | | openclaw-rescue.json | 必须重启 rescue | | SOUL.md / IDENTITY.md | 新 session 生效，必要时重启 | | TEAM.md | 不需要 | | skills/ 下的 SKILL.md | 新调用生效 |

八、完整搭建流程

Step 1：创建 Agent Workspace

mkdir -p ~/.openclaw/workspace-{agent-id}

SOUL.md 四段式模板：

## 你是谁
一句话定义角色定位。
职责
负责什么、产出什么、工作范围
做事风格
如何分析问题、如何组织回答、输出格式要求
边界
不做什么、什么时候转交给其他角色、协作关系

IDENTITY.md 示例：

- Name: 角色名称
Creature: AI XXX专家
Vibe: 严谨 / 保守 / 数据导向
Emoji: 🎯

Step 2：在 openclaw.json 注册 Agent

{
  "agents": {
    "defaults": {
      "workspace": "/Users/{USER}/.openclaw/workspace"
    },
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "主Agent",
        "workspace": "/Users/{USER}/.openclaw/workspace",
        "identity": { "name": "OpenClaw", "emoji": "🦞" },
        "model": "anthropic/claude-opus-4-6"
      },
      {
        "id": "your-agent-id",
        "name": "角色名称",
        "workspace": "/Users/{USER}/.openclaw/workspace-your-agent-id",
        "identity": { "name": "角色名称", "emoji": "🎯" },
        "model": "kimi-coding/k2p5",
        "subagents": { "allowAgents": ["*"] }
      }
    ]
  }
}

关键： main 必须显式存在、"default": true、放 list 第一位。

Step 3：重启 Gateway

openclaw gateway restart

Step 4：验证后台 Spawn

sessions_spawn({
  agentId: "your-agent-id",
  task: "做一个最小测试回复",
  mode: "run",
  runtime: "subagent"
})

验证顺序：最小任务能拉起 → 输出符合 SOUL.md → 接入真实工作流。

到此后台调度链路已打通。以下为可选的 Discord 外显配置。

Step 5（可选）：暴露为 Discord Bot

5a. 创建 Discord Bot：

5b. 配置 Discord accounts：

"channels": {
  "discord": {
    "enabled": true,
    "groupPolicy": "allowlist",
    "allowBots": true,
    "allowFrom": ["USER_ID"],
    "guilds": {
      "GUILD_ID": { "requireMention": true, "users": ["USER_ID"] }
    },
    "accounts": {
      "your-agent-id": {
        "name": "角色名称",
        "token": "BOT_TOKEN",
        "groupPolicy": "allowlist",
        "guilds": { "GUILD_ID": {} }
      }
    }
  }
}

5c. 配置 binding：

"bindings": [{
  "agentId": "your-agent-id",
  "match": { "channel": "discord", "accountId": "your-agent-id" }
}]

5d. 重启 Gateway 并在 Discord 验证。

九、Discord requireMention 三层覆盖

覆盖优先级：channel > account > top-level

| 层级 | 配置位置 | 效果 | |------|---------|------| | top-level | channels.discord.guilds.GUILD_ID | 全局默认 | | per-account | accounts.{id}.guilds.GUILD_ID | 覆盖该Bot的默认行为 | | per-channel | accounts.{id}.guilds.GUILD_ID.channels.CH_ID | 覆盖该Bot在特定频道的行为 |

最佳实践：

十、模型选择

| 角色 | 推荐模型 | 理由 | |------|---------|------| | 主 Agent (main) | anthropic/claude-opus-4-6 | 最强推理，负责编排 | | 专业 Agent | kimi-coding/k2p5 | 成本优化，262K上下文 | | Rescue Agent | kimi-coding/k2p5 | 独立配置文件管理 |

Rescue 的模型在 ~/.openclaw/openclaw-rescue.json 中单独配置：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "kimi-coding/k2p5",
        "fallbacks": ["anthropic/claude-opus-4-6", "anthropic/claude-sonnet-4-5"]
      }
    }
  }
}

十一、故障排查

| 问题 | 原因 | 解决 | |------|------|------| | 主Agent身份被覆盖 | main 没显式配置或没设 default: true | main 放 list 第一位，设 "default": true | | spawn 调不到成员 | Gateway 没加载新配置 | openclaw gateway restart | | requireMention 行为不符预期 | 三层覆盖冲突 | 检查 channel > account > top-level 优先级 | | Bot A @ Bot B 无响应 | allowBots 非 true 或 bot ID 不在白名单 | 设 allowBots: true，bot ID 加入 allowFrom 和 users | | Discord Bot 创建限流 | 连续创建太多 | 分批创建，先验证 spawn 再补 Discord | | Rescue 模型不对 | 改错了配置文件 | 修改 openclaw-rescue.json（非主配置） | | 配了但不生效 | 没重启 Gateway | 所有 openclaw.json 改动后 openclaw gateway restart |

十二、核心原则总结

1. 后台 spawn 是主链路，Discord @mention 是外显层 —— 先打通 spawn，再按需加 Discord 2. 同一 Agent 两种模式可并行 —— agents.list 管 spawn，accounts + bindings 管 Discord，互不冲突 3. bot-bot @ 是增强不是主流程 —— 核心调度走 spawn，公开协作才用 bot-bot @ 4. 改配置必须重启 Gateway —— 最常见的「不生效」原因 5. 每个角色定义职责、边界、协作关系 —— 没有清晰边界的 Agent 不如不建