课程信息

• 作者：老金

• GitHub：https://github.com/KimYx0207

• 公众号：老金带你玩AI

• X（Twitter）：老金带你玩AI

• 个人博客：https://aiking.dev

• 难度等级：🔴 高级

• 阅读时间：35 分钟

• 前置知识：已熟悉基本使用（03-快速开始）+ 了解技能系统（06-技能系统）

本篇你将学会： 创建多个 AI 助手、配置分工协作、设置消息路由、管理 Agent 间通信

大多数人不需要这篇！ 如果你只是个人使用，一个默认的 main Agent 就够了。只有当你需要"不同平台用不同 AI 性格"或"团队多人使用"时才需要看这篇

什么是 Agent？

我把多 Agent 协作讲成责任拆分，而不是热闹分身；每个 agent 都要有清楚的交付物。

2026-09-13 当前基线（v2026.9.4）：多 Agent 侧这几版的变化集中在「跑得远、断得住」。v2026.8.1 起会话可以跑在配对设备或云端 worker 上，工作区随会话一起走，已经预热的机器和项目初始状态能被后续云会话复用；v2026.9.4 又支持从准备好的本地项目或公开 GitHub 仓库启动 Linux 云会话，并在开聊前先在 Control UI 里做可复用快照。启用云端路线前，要到 Settings → Connections → Cloud workers → Pool 核对备用机器，再按服务商的实际费用核对预算；符合条件的项目可能自动准备 Ready workers，这些机器会持续产生运行费用，直到服务商确认删除。需要关闭备用池时，可在 Profiles 核对并将对应备用目标或共享池上限设为 0，等待未使用机器完成回收，不能把会话结束当成所有云端费用都已停止。具体条件见官方 Ready workers 说明。观察手段也变好了：v2026.8.1 起会话进度卡能跨重载保留，subagent 活动和累积改动在网页端和原生端都能跟。可靠性上，v2026.9.2 起活动中、排队中和被委派的回复能在 Gateway 重启后恢复；v2026.9.4 起 subagent 的结果能回到 Talk（语音模式），多轮委派后也能把最终答案送出去。

v2026.6.8 复核补充：多 Agent 不只是“多开几个会话”。新版继续强化 interrupted tool calls、stale session bindings、compaction handoffs、media delivery retries、Workboard、agent coordination tools、agent run recovery、session metadata 和 Gateway runtime state。排查多 Agent 卡住时，先看 Activity / transcript / Gateway 日志、Workboard 状态和具体 channel / provider，再判断是不是 agent 设计问题。

在 OpenClaw 的世界里，Agent 就是一个独立的 AI 助手实例。每个 Agent 有自己的"大脑"（系统指令）、"记忆"（记忆文件）、"技能"（技能集）和"身份"（认证凭证）。

你可以把 Agent 想象成公司里的员工：

Agent = 一个独立的 AI 员工

它有：
├── 自己的工位（工作空间目录）
├── 自己的工牌（认证凭证）
├── 自己的笔记本（记忆文件）
├── 自己的技能证书（技能集）
├── 自己的性格（SOUL.md 人格设定）
└── 自己的工作日志（会话历史）

💡 术语说明： 上面提到的 SOUL.md 是 Agent 的人格设定文件，定义 AI 的性格和行为风格，后面会详细介绍。

默认情况下，OpenClaw 只有一个 main Agent。对大多数人来说，一个 Agent 就够了 -- 它能处理你所有的消息、执行所有的任务。

为什么需要多个 Agent？

一个 Agent 什么都干，听起来很方便，但实际用起来会遇到问题：

问题一：上下文污染

当你让同一个 Agent 既写代码又管日程，它的系统提示词会变得很长。写代码时加载了一堆日历相关的技能指令，管日程时又带着一堆编程工具的描述。这些无关信息会：

• 浪费 token（花更多钱）

• 降低 AI 的专注度（回答质量下降）

• 增加误触发的概率（该用 A 技能时用了 B）

问题二：人格冲突

你希望编程助手严谨、精确、代码优先；但你希望社交助手轻松、幽默、善于闲聊。一个 Agent 很难同时扮演两种截然不同的角色。

问题三：安全隔离

编程 Agent 需要访问 GitHub、执行 Shell 命令；但你不希望社交 Agent 也有这些权限。万一有人通过社交平台发了一条恶意消息，触发了 Shell 命令执行，后果不堪设想。

问题四：消息路由

你可能希望 Discord 的 #coding 频道由编程 Agent 处理，Telegram 的家庭群由生活 Agent 处理。一个 Agent 没法根据消息来源自动切换行为模式。

多 Agent 架构就是为了解决这些问题：

单 Agent 模式：
┌─────────────────────────────────────┐
│  所有消息 → main Agent → 所有技能    │
│  （上下文臃肿，角色混乱）             │
└─────────────────────────────────────┘

多 Agent 模式：
┌─────────────────────────────────────┐
│  Discord #coding → coding Agent     │
│                    （只加载开发技能）  │
│                                     │
│  Telegram 家庭群 → home Agent       │
│                    （只加载生活技能）  │
│                                     │
│  WhatsApp 私聊 → main Agent         │
│                  （通用技能）         │
└─────────────────────────────────────┘

OpenClaw 的 Agent 架构

架构总览

v2026.5.22 子代理注意：默认子 Agent bootstrap context 已收窄到 AGENTS.md 与 TOOLS.md，不会自动把 persona、identity、user、memory、heartbeat、setup 等文件全部带入 delegated workers。多 Agent 教程里的“自动继承上下文”应按最小必要上下文理解。

v2026.9.7+ 迁移提醒：上面是旧版本的文件范围。当前 Agent 启动时不再读取 TOOLS.md；维护时用 openclaw doctor --fix 将其中的工具笔记合并到 AGENTS.md，并检查权限告警和合并内容。不要为了恢复旧行为把所有个人资料、记忆或凭据复制给子 Agent；仍然只提供完成任务所需的上下文。

⏭️ 小白可跳过 — 这是底层运行时细节

OpenClaw 的多 Agent 架构基于 Pi agent runtime（RPC 模式）运行，采用扁平路由模型（不是层级管理模型）。Gateway 根据消息来源直接路由消息到对应的 Agent，没有"管理者 Agent"在其中调度。每个 Agent 通过 channel routing（消息路由，决定哪条消息由哪个 Agent 处理）配置绑定到不同的频道或账号。

┌─────────────────────────────────────────────────────────────┐
│                     消息平台层                                │
│  WhatsApp │ Telegram │ Discord │ Slack │ Signal │ WebChat   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────┐
│                   Gateway 路由引擎                             │
│                                                              │
│  消息进来 → 检查 bindings 配置 → 匹配 Agent                   │
│                                                              │
│  路由规则：                                                    │
│  ├── Discord #coding 频道 → coding Agent                     │
│  ├── Telegram 群 -100xxxxx → social Agent                    │
│  ├── Slack #team 频道 → work Agent                           │
│  └── 其他所有消息 → main Agent（默认）                         │
└──────┬──────────┬──────────┬──────────┬─────────────────────┘
       │          │          │          │
       ▼          ▼          ▼          ▼
┌──────────┐┌──────────┐┌──────────┐┌──────────┐
│  main    ││  coding  ││  social  ││  work    │
│  Agent   ││  Agent   ││  Agent   ││  Agent   │
│          ││          ││          ││          │
│ 工作空间  ││ 工作空间  ││ 工作空间  ││ 工作空间  │
│ 记忆文件  ││ 记忆文件  ││ 记忆文件  ││ 记忆文件  │
│ 技能集   ││ 技能集   ││ 技能集   ││ 技能集   │
│ 认证凭证  ││ 认证凭证  ││ 认证凭证  ││ 认证凭证  │
│ SOUL.md  ││ SOUL.md  ││ SOUL.md  ││ SOUL.md  │
└──────────┘└──────────┘└──────────┘└──────────┘

关键设计决策

为什么是扁平路由而不是层级管理？

消息 bindings 按配置直接选择 Agent，不必先让一个模型判断消息给谁。这是入口路由的设计；不代表 OpenClaw 禁止子 Agent、运行时委派或编程任务的编排。直接路由的优势包括：

1. 层级管理增加延迟 -- 消息要先经过管理者 Agent 判断，再转发给工作 Agent

2. 管理者 Agent 本身也消耗 token -- 每条消息多一次 AI 调用

3. 路由规则是确定性的 -- 不需要 AI 来判断消息该给谁，配置文件就能搞定

4. 简单可靠 -- 越少的中间环节，越少的出错机会

每个 Agent 有自己的工作空间和状态范围

Agent 之间默认没有任何共享：

资源

是否共享

说明

工作空间

否

每个 Agent 有独立的工作目录

记忆文件

否

每个 Agent 有独立的 MEMORY.md 和日志

记忆后端

可选

内置 SQLite；插件方案按所用版本与插件说明配置，v2026.9.4 已移除 QMD

会话历史

存储按 Agent 分开

跨 Agent 读取仍受会话工具可见性和 agentToAgent 策略控制

认证凭证

按认证流程

每个 Agent 有自己的 SQLite auth store；同名 OAuth profile 可按规则读取 main 的新凭据

技能配置

可选

可以配置 Agent 级别的技能白名单

AI 模型

可选

可以为每个 Agent 指定不同的模型

目录结构详解

~/.openclaw/
├── openclaw.json              # 主配置文件（包含 Agent 列表和路由规则）
│
├── agents/                    # Agent 状态目录
│   ├── main/                  # 默认 Agent
│   │   ├── agent/
│   │   │   └── openclaw-agent.sqlite  # 模型认证与活跃会话状态
│   │   └── sessions/          # 保留的转录产物；不是活跃会话数据库
│   ├── coding/                # 编程 Agent
│   │   ├── agent/
│   │   │   └── openclaw-agent.sqlite
│   │   └── sessions/
│   └── social/                # 社交 Agent
│       ├── agent/
│       │   └── openclaw-agent.sqlite
│       └── sessions/
│
├── workspace/                 # main Agent 的工作空间
│   ├── SOUL.md               # main 的人格设定
│   ├── AGENTS.md             # Agent 协作说明
│   ├── USER.md               # 用户信息
│   ├── MEMORY.md             # main 的长期记忆
│   ├── memory/               # main 的每日日志
│   └── skills/               # main 的工作空间技能
│
├── workspace-coding/          # coding Agent 的工作空间
│   ├── SOUL.md               # coding 的人格设定
│   ├── MEMORY.md             # coding 的长期记忆
│   ├── memory/               # coding 的每日日志
│   └── skills/               # coding 的工作空间技能
│
└── workspace-social/          # social Agent 的工作空间
    ├── SOUL.md               # social 的人格设定
    ├── MEMORY.md             # social 的长期记忆
    ├── memory/               # social 的每日日志
    └── skills/               # social 的工作空间技能

每个 Agent 的工作空间是它的"家"。AI 的文件操作默认在这个目录下进行，记忆文件也存在这里。其中 AGENTS.md（Agent 的系统指令文件）定义了 Agent 之间的协作规则。

Agent 角色定义和配置

创建新 Agent

# 使用向导创建（推荐）
openclaw agents add coding
openclaw agents add social
openclaw agents add work

# 每个 Agent 会自动创建：
# - 独立的工作空间（SOUL.md, AGENTS.md, USER.md）
# - 独立的 agentDir 和会话存储
# - 独立的 SQLite runtime store（模型认证与会话状态）

查看和管理 Agent

# 列出所有 Agent
openclaw agents list

# 更新 Agent 的身份设定
openclaw agents set-identity

在 openclaw.json（JSON5）中配置 Agent

Agent 的核心配置在 ~/.openclaw/openclaw.json（JSON5 格式）的 agents 字段中：

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-8",
      "sandbox": {
        // 非主会话在 Docker 沙箱中运行
        "mode": "non-main",
      },
    },
    "entries": {
      "main": {
        "default": true,
        "workspace": "~/.openclaw/workspace",
        "model": "anthropic/claude-opus-4-8",
      },
      "coding": {
        "workspace": "~/.openclaw/workspace-coding",
        "model": "anthropic/claude-opus-4-8",
        // Agent 级别的 skills 是简单的字符串数组
        "skills": ["coding-agent", "github", "gh-issues", "tmux"],
      },
      "social": {
        "workspace": "~/.openclaw/workspace-social",
        "model": "openai/gpt-5.2",
        "skills": ["summarize", "weather", "goplaces"],
      },
      "work": {
        "workspace": "~/.openclaw/workspace-work",
        "model": "anthropic/claude-sonnet-5",
        "skills": ["gog", "slack", "notion", "trello", "summarize"],
      },
    },
  },

  // bindings 是顶层配置，不嵌套在 agent 内部
  "bindings": [
    {
  "agentId": "coding",
  "match": {
    "channel": "discord",
    "guildId": "123456789",
    "peer": {
      "kind": "channel",
      "id": "987654321"
    }
  }
},
    {
  "agentId": "social",
  "match": {
    "channel": "telegram",
    "peer": {
      "kind": "group",
      "id": "-100123456789"
    }
  }
},
    {
  "agentId": "work",
  "match": {
    "channel": "slack",
    "peer": {
      "kind": "channel",
      "id": "C01234567"
    }
  }
},
  ],
}

Agent 配置字段详解

字段

类型

必填

说明

entries 的对象键

string

是

Agent ID，例如 coding；配置对象中不再单独写 id

workspace

string

否

工作空间目录路径；为清楚区分内容，示例显式指定独立目录

model

string 或 object

否

AI 模型，可以是字符串或 { primary, fallbacks } 对象

skills

string[]

否

Agent 可用的技能列表（简单字符串数组）

sandbox

object

否

沙箱配置

注意：bindings（消息路由绑定）是顶层配置，不嵌套在 Agent 内部。temperature、maxTokens 等参数不是 Agent 级别的直接配置字段。

Agent 人格设定（SOUL.md）

每个 Agent 的工作空间里有一个 SOUL.md 文件，这是 Agent 的"灵魂"。AI 在每次会话启动时都会读取这个文件，作为系统指令的一部分。

编程 Agent 的 SOUL.md 示例：

# coding Agent

你是一个专业的编程助手，专注于帮助用户写代码、调试和架构设计。

## 性格
- 严谨、精确、逻辑清晰
- 代码优先，少说废话
- 遇到不确定的问题会主动说"我不确定"
- 喜欢用代码示例来解释概念

## 专长
- TypeScript / Python / Go / Rust
- 系统架构设计和代码审查
- 性能优化和安全分析
- DevOps 和 CI/CD

## 工作规则
- 所有代码必须有类型注解
- 遵循 SOLID 原则和 DRY 原则
- 不写没有测试的代码
- 代码变更前先解释方案，等用户确认再执行
- 遇到安全相关的代码要特别谨慎

## 沟通风格
- 用中文沟通，代码注释用英文
- 回复简洁，不要长篇大论
- 给出代码时附带简短解释
- 如果用户的需求不明确，先问清楚再动手

社交 Agent 的 SOUL.md 示例：

# social Agent

你是一个轻松有趣的聊天伙伴，帮助用户管理社交消息和日常生活。

## 性格
- 幽默、随和、善于倾听
- 说话像朋友，不像机器人
- 适当使用 emoji 让对话更生动
- 遇到敏感话题会委婉回避

## 专长
- 日常闲聊和情感支持
- 天气查询和出行建议
- 内容摘要和信息整理
- 简单的翻译和语言帮助

## 工作规则
- 不执行任何代码或 Shell 命令
- 不访问文件系统（除了记忆文件）
- 回复要简短，适合手机阅读
- 群聊中只在被 @提及时回复

## 沟通风格
- 轻松口语化，像朋友聊天
- 适当使用表情符号
- 回复控制在 3-5 句话以内
- 如果不知道答案，诚实说不知道

办公 Agent 的 SOUL.md 示例：

# work Agent

你是一个高效的办公助手，帮助用户管理邮件、日程、项目和文档。

## 性格
- 专业、高效、条理清晰
- 主动提醒重要事项
- 善于整理和归纳信息
- 注重时间管理

## 专长
- Gmail 邮件管理和回复
- Google Calendar 日程安排
- Notion/Trello 项目管理
- Slack 消息管理
- 会议纪要和周报生成

## 工作规则
- 处理邮件前先确认用户意图
- 发送邮件/消息前必须让用户确认内容
- 日程冲突时主动提醒
- 重要操作（删除、发送）需要二次确认

## 沟通风格
- 专业但不生硬
- 用列表和要点来组织信息
- 时间相关的信息要明确时区
- 涉及金额时要标明货币单位

为不同 Agent 配置不同的 AI 模型

这是多 Agent 架构的一个隐藏优势：你可以根据任务复杂度为不同 Agent 选择不同的模型，优化成本。

{
  "agents": {
    "entries": {
      "coding": {
        "default": true,
        "model": "anthropic/claude-opus-4-8",
        // 编程需要最强的推理能力，用最好的模型
      },
      "social": {
        "model": "openai/gpt-5.6-luna",
        // 闲聊不需要太强的模型，用便宜的就行
      },
      "work": {
        "model": "anthropic/claude-sonnet-5",
        // 办公任务中等复杂度，用性价比最高的
      },
    },
  },
}

比较成本时，用同一组有代表性的任务记录实际输入、输出、缓存用量和其他服务费用，再按账号或提供商的当前计费规则计算。每天 100 条消息不足以推算固定日费用：消息长度、工具结果、重试和上下文累积都会影响用量。

方案

模型组合示例

需要核对的结果

全部用 Opus

claude-opus-4-8

任务质量与实际费用

按需分配

Opus + Sonnet + Luna

各类任务的完成质量、重试次数与实际费用

全部用 Luna

gpt-5.6-luna

是否达到任务要求，以及是否因重试增加费用

按需分配可以作为降低成本的候选方案，是否节省、能否保持关键任务质量，要以这组任务的实际结果判断。

Agent 间通信机制

⏭️ 小白可跳过 — 这是 Agent 间通信的底层机制，了解概念即可

Sessions 工具：Agent 直接通信

OpenClaw 提供了一组 Sessions 工具，让 Agent 之间可以直接通信。这些工具基于 Pi agent runtime 的 RPC 模式运行，每个 Agent 可以发现、查看和向其他会话发送消息。

四个核心工具：

工具

功能

说明

sessions_list

发现活跃会话

列出当前所有活跃的 Agent 会话

sessions_history

获取会话日志

查看指定会话的历史消息

sessions_send

向另一个会话发消息

向授权目标会话发送请求；返回与后续交付按安装版本处理

sessions_spawn

生成新会话

动态创建一个新的 Agent 会话

sessions_send 的返回方式与版本差异：

它向有权限访问的目标会话发送消息。先用 sessions_list 找到真实 session key，再传递原始问题和所需上下文；Agent ID 本身不是目标会话 key。普通跨 Agent 访问还受 tools.sessions.visibility、tools.agentToAgent 和当前身份控制。

本章固定参考的 v2026.9.4 曾有自动 reply-back ping-pong 与 announcement 轮次。v2026.9.8 已移除这套自动往返：结果可以在调用内返回，或者在原请求会话仍符合身份和生命周期条件时稍后送回一次。继续讨论要显式再次发送；向 Telegram、Discord 等渠道交付要显式使用消息工具，不能靠旧 announce 机制。REPLY_SKIP 和 ANNOUNCE_SKIP 也不再压制旧循环的返回文本。隔离 cron 调用不会建立脱离调用的后台回复等待器。

因此研究→写作→审核应明确每次输入、结果、目标会话和交付动作。不要把 sessions_send 写成“单向通知模式”等参数承诺，也不要把两条定时任务的时间差当作上游成功的证明。

参见 v2026.9.8 委派变更。

Sessions CLI 命令：

# 列出所有活跃会话
openclaw sessions list

# 清理过期会话
openclaw sessions cleanup

间接通信方式

除了 Sessions 工具的直接通信，还有几种间接通信的方式：

方式一：共享文件

把需要共享的数据放在一个公共目录：

{
  "agents": {
    "entries": {
      "research": {
        "default": true,
        "workspace": "~/.openclaw/workspace-research",
      },
      "writer": {
        "workspace": "~/.openclaw/workspace-writer",
      },
    },
  },
}

在两个 Agent 的 SOUL.md 中都指向同一个共享目录：

## 共享数据

当需要与其他 Agent 共享数据时，把文件写入 ~/.openclaw/shared/ 目录。
读取其他 Agent 的输出也从这个目录读取。

方式二：通过用户中转

最简单的方式 -- 你从一个 Agent 那里得到结果，然后手动发给另一个 Agent：

你 → coding Agent：帮我分析这段代码的性能问题
coding Agent → 你：发现 3 个性能瓶颈：1. N+1 查询 2. 未缓存 3. 同步阻塞

你 → work Agent：帮我创建 3 个 Jira Issue，分别是...
work Agent → 你：已创建 PROJ-101, PROJ-102, PROJ-103

方式三：通过定时任务串联

Cron 可以分别安排执行时间，但不会因为两条任务相隔半小时就保证先后依赖。下游开始前应检查上游当天产物和成功状态；需要真正的串行依赖时，在一个受控工作流里等待上游结果再转交。下面先演示各任务的定时设置：

{
  "cron": {
    "enabled": true,
  },
}

注意：cron 是一个配置对象（包含 enabled、sessionRetention、failureAlert 等字段），不是任务数组。具体的定时任务通过 CLI 管理：

# 添加定时任务
openclaw cron add --tz Asia/Shanghai --name "research-phase" --cron "0 9 * * 1-5" \
  --agent research --message "搜索今天的行业新闻，整理成摘要，保存到 ~/.openclaw/shared/daily-news.md"

openclaw cron add --tz Asia/Shanghai --name "writing-phase" --cron "30 9 * * 1-5" \
  --agent writer --message "读取 ~/.openclaw/shared/daily-news.md，基于今天的新闻写一篇简报，发送到 Slack #news 频道"

# 列出所有定时任务
openclaw cron list

# 删除定时任务
openclaw cron list
openclaw cron rm <job-id>  # 替换成列表中的实际 ID

添加任务后，在 Automations 找到它，先核对 Agent、时区、目的地和批准范围。必要时手动 Run now，再查看这次运行的执行结果与送达详情；暂停中的任务也可手动跑一次，这不会启用其日常计划。执行显示 OK 不代表报告已经送到：OK · Error 或 OK · Unknown 仍需查看送达错误或不确定状态。可用 openclaw cron runs --id <job-id> 查看对应记录；没有报告的成功任务也可能安静结束，不能单凭没有新消息判断失败。

v2026.9.6 起，实质修改自动化会使之前的 Always allow 批准失效，即使后来把内容改回去，也需重新批准；只暂停和恢复未改变的任务会保留批准。旧批准升级后也可能需补一次确认，所以修改后要检查下一次是否等批准。v2026.9.7 起，指定已有会话的任务使用它绑定的项目目录或 managed worktree，绑定失效会停止；先恢复绑定或从有效会话重建任务再重试。本节的 --message 任务可以使用相应超时设置；若另建 system-event 任务，不要加入 --timeout-seconds，新版会拒绝，脚本任务则用自己的 --script-timeout-seconds。详见运行历史与定时参数。

方式四：通过支持的入口触发

需要从外部系统触发指定 Agent 时，使用官方 inbound webhook 的 /hooks/agent，先配置 hooks token、允许的 agent ID 和对应访问策略；或者使用已经授权的 sessions_send 工作流。POST /api/message 不是这里可直接使用的 Gateway 接口。不要把 Gateway token 和 hooks token 混用，实际请求字段按 官方 webhook 文档准备。

中断和后台工作怎么处理

Gateway 重启后先查看父会话和子任务状态。v2026.9.7 会把被中断的子任务与失败分开记录，但不会自动重新启动子 Agent，也不会重放中断的工具调用。想重做时先确认旧任务已停止、外部文件或消息是否已经改变，再交代剩余步骤，避免重复发送或重复写入。突然丢失整台机器、SSH 会话或旧版本已丢失的编辑不具备同样的恢复保障。

需要让一条命令跨回合继续执行时，要求 Agent 使用执行工具的 background: true，让长运行命令本身作为根命令，再通过 process 查看状态并收集结果。不要把 command & 当成持久后台任务：v2026.9.5 起根命令完成会清理它留下的子进程。sandbox 的生命周期仍由其后端控制。结束实验时，停止实际任务并核对状态，关闭网页或终端并不等于远端工作已经取消。详见后台命令和重启恢复。

消息路由和绑定配置

路由规则详解

Gateway 按绑定的匹配精度选择 Agent：具体 peer 规则比 guild/team、账号或整个通道的规则更具体；同等精度时按 bindings 顺序匹配。未匹配时回到配置的默认 Agent。私聊也可以通过 direct peer 绑定，不能认定所有私聊必定进入 main。Agent 名单顺序不是绑定优先级。

用 openclaw agents list --bindings 核对实际绑定，再从目标通道发一条测试消息。配置能解析不等于收到的 peer ID 正确。

绑定类型

Discord 绑定：

// 顶层 bindings 数组
{
  "bindings": [
    {
  "agentId": "coding",
  "match": {
    "channel": "discord",
    "guildId": "123456789",
    "peer": {
      "kind": "channel",
      "id": "987654321"
    }
  }
},
  ],
}

• guildId -- Discord 服务器 ID

• peer.id -- Discord 频道 ID，配合 peer.kind: "channel"

• 可以只指定 guildId，这样整个服务器的消息都路由到这个 Agent

Telegram 绑定：

{
  "bindings": [
    {
  "agentId": "social",
  "match": {
    "channel": "telegram",
    "peer": {
      "kind": "group",
      "id": "-100123456789"
    }
  }
},
  ],
}

• peer.id -- Telegram 群组 ID（通常为负数），配合 peer.kind: "group"

• 未匹配私聊走所配置默认 Agent；需要按联系人区分时增加 kind 为 direct 的 peer 绑定。

Slack 绑定：

{
  "bindings": [
    {
  "agentId": "work",
  "match": {
    "channel": "slack",
    "peer": {
      "kind": "channel",
      "id": "C01234567"
    }
  }
},
  ],
}

WhatsApp 绑定：

{
  "bindings": [
    {
  "agentId": "social",
  "match": {
    "channel": "whatsapp",
    "peer": {
      "kind": "group",
      "id": "[email protected]"
    }
  }
},
  ],
}

多平台绑定：

一个 Agent 可以绑定多个平台的多个频道：

// 顶层 bindings 数组中，同一个 agent 可以有多条绑定
{
  "bindings": [
    {
  "agentId": "coding",
  "match": {
    "channel": "discord",
    "guildId": "111111",
    "peer": {
      "kind": "channel",
      "id": "222222"
    }
  }
},
    {
  "agentId": "coding",
  "match": {
    "channel": "discord",
    "guildId": "111111",
    "peer": {
      "kind": "channel",
      "id": "333333"
    }
  }
},
    {
  "agentId": "coding",
  "match": {
    "channel": "telegram",
    "peer": {
      "kind": "group",
      "id": "-100999888777"
    }
  }
},
    {
  "agentId": "coding",
  "match": {
    "channel": "slack",
    "peer": {
      "kind": "channel",
      "id": "C09876543"
    }
  }
},
  ],
}

查看路由状态

# 查看所有 Agent
openclaw agents list

# 输出示例：
# Agent: main (default)
#   No specific bindings (handles unmatched messages)
#
# Agent: coding
#   discord: guild=111111 channel=222222
#   discord: guild=111111 channel=333333
#   telegram: chat=-100999888777
#
# Agent: social
#   telegram: chat=-100123456789

让多个 Agent 在同一个群里讨论：Room Teams

普通 bindings 为一条消息选择接收 Agent；实验性的 Room Teams 使用顶层 broadcast，让多个已配置 Agent 各自在自己的会话里回应，再在限定轮数内互相补充。v2026.9.5 的发布记录强调 Discord / Slack 的参与者回复归属；当前官方配置还支持其他明确列出的群通道。先在一个你有管理权限的测试群里做，别直接接管生产群。

1. 先按本章创建 reviewer、writer，给它们不同的工作区，分别确认模型和实际工具权限。用 openclaw agents list --bindings 检查它们已存在。

2. 按第 5 章配置并允许这个测试群，保留其普通路由绑定；Room Teams 不替代频道连接、发送者白名单或群准入。

3. 把下面片段合并到现有配置，保留两 Agent 原有字段，并把 slack:C0123 换成真实的 <channel>:<peerId>。如果测试 Discord，使用 discord:实际频道ID。不要覆盖现有其他 bindings 或 broadcast 条目。

{
  agents: {
    entries: {
      reviewer: { groupChat: { mentionPatterns: ["@reviewer\\b"] } },
      writer: { groupChat: { mentionPatterns: ["@writer\\b"] } },
    },
  },
  broadcast: {
    "slack:C0123": {
      agents: ["reviewer", "writer"],
      mentionGating: true,
      maxRounds: 2,
      maxTurns: 4,
    },
  },
}

配置加载后，在该测试群发送 @reviewer @writer 请分别检查这段公开文案，最多补充一轮，只输出建议。 检查回复是否标出参与者，并在各自 transcript 里核对内容。只点名 @writer 会选择它开始首轮；mentionGating: true 下没有匹配的参与者 mention 时会选全部，频道自己的 requireMention 仍然生效。

maxRounds 包含首轮，maxTurns 限制启动的 Agent 回合，不是平台实际消息条数；长回复仍可能分成多条。每轮后续看到的是前一轮的署名摘要，顺序策略也不等于同轮流水线。讨论会消耗多次模型请求，活跃轮数与预算保存在内存，Gateway 重启后不能接着恢复原预算。想结束实验，先停止仍在执行的参与者会话，再移除这个 broadcast 条目并核对配置，避免新消息继续触发。完整字段与限制见官方群组讨论配置。

任务分发和协调策略

策略一：按职能分工

最常见的策略，每个 Agent 负责一个领域：

┌──────────────────────────────────────────────────┐
│                  按职能分工                        │
│                                                  │
│  coding Agent    → 写代码、调试、GitHub 管理       │
│  office Agent    → 邮件、日历、项目管理            │
│  social Agent    → 社交消息、闲聊、生活助手        │
│  research Agent  → 信息搜索、内容摘要、分析        │
└──────────────────────────────────────────────────┘

配置示例：

{
  "agents": {
    "entries": {
      "coding": {
        "default": true,
        "skills": ["coding-agent", "github", "gh-issues", "tmux"],
        "model": "anthropic/claude-opus-4-8",
      },
      "office": {
        "skills": ["gog", "slack", "notion", "trello", "summarize"],
        "model": "anthropic/claude-sonnet-5",
      },
      "social": {
        "skills": ["weather", "goplaces", "summarize"],
        "model": "openai/gpt-5.6-luna",
      },
    },
  },
}

策略二：按平台分工

每个 Agent 负责一个消息平台：

┌──────────────────────────────────────────────────┐
│                  按平台分工                        │
│                                                  │
│  whatsapp Agent  → 处理所有 WhatsApp 消息         │
│  telegram Agent  → 处理所有 Telegram 消息         │
│  discord Agent   → 处理所有 Discord 消息          │
│  slack Agent     → 处理所有 Slack 消息            │
└──────────────────────────────────────────────────┘

这种策略适合不同平台有不同用途的场景。比如你用 WhatsApp 跟家人聊天，用 Slack 工作，用 Discord 参与开源社区。

策略三：按安全等级分工

根据操作的风险等级来分配 Agent：

┌──────────────────────────────────────────────────┐
│                按安全等级分工                       │
│                                                  │
│  trusted Agent   → 可信入口，权限按 tools 策略      │
│  limited Agent   → 有限权限，处理群聊消息          │
│  readonly Agent  → 只读权限，处理公开频道          │
└──────────────────────────────────────────────────┘

配置示例：群聊 Agent 只开放读取和搜索，公开频道 Agent 只开放 read。沙箱镜像先按沙箱章节准备；可信入口还要在渠道侧限制发送人，下面的 bindings 只负责路由。技能若需要未开放的工具将无法执行。

{
  "agents": {
    "defaults": {
      "sandbox": {
        // 非主会话在 Docker 沙箱中运行
        "mode": "non-main",
      },
    },
    "entries": {
      "trusted": {
        "default": true,
        "skills": ["coding-agent", "github", "gog", "slack"],
        // 可信入口；工具权限继承实际 tools 策略
      },
      "limited": {
        "skills": ["summarize", "weather", "goplaces"],
        "tools": {
          "allow": ["read", "web_search", "web_fetch"],
          "sandbox": { "tools": { "allow": ["read", "web_search", "web_fetch"] } },
        },
        "sandbox": { "mode": "all", "workspaceAccess": "ro" },
        // 只开放读取与搜索工具，处理群聊
      },
      "readonly": {
        "skills": ["summarize"],
        "tools": { "allow": ["read"] },
        "sandbox": { "mode": "all", "workspaceAccess": "ro" },
        // 仅开放 read；技能名称不会额外授予命令执行权限
      },
    },
  },
  "bindings": [
    {
  "agentId": "limited",
  "match": {
    "channel": "telegram",
    "peer": {
      "kind": "group",
      "id": "-100111222333"
    }
  }
},
    {
  "agentId": "readonly",
  "match": {
    "channel": "discord",
    "guildId": "444555666"
  }
},
  ],
}

策略四：流水线协作

多个 Agent 按顺序处理同一个任务，每个 Agent 负责一个阶段：

研究 Agent → 写作 Agent → 审核 Agent
   │              │              │
   ▼              ▼              ▼
 收集资料      撰写内容       审核质量
 整理要点      格式排版       修改建议
 保存到共享    读取资料       最终发布

这种策略可以通过 sessions_send 工具直接传递、定时任务或 HTTP API 来串联（详见上面的"Agent 间通信机制"章节）。

批量并行委派：先做一个有上限的 Swarm

普通 sessions_spawn 适合一个或少数子任务。Swarm 适合一批相似、能独立交付的任务，例如让多个助手分别检查几段文案；它从 Code Mode 编排，用 collector 子任务返回结果，不向父会话自动发送完成通知。

先使用当前 OpenClaw 运行时，明确开启 Code Mode，确认原生 sessions_spawn 在当前工具目录且有权限。只有同名 MCP 工具不满足要求，目标 Agent 也必须满足 subagents.allowAgents。把下面片段合并到现有配置，先用小上限：

{
  tools: {
    codeMode: true,
    swarm: {
      maxConcurrent: 2,
      maxChildrenPerGroup: 5,
      maxTotalPerGroup: 5,
    },
  },
}

在新对话里让助手先读 API.read("agents.d.ts") 核对当前 API，再把下面 JavaScript 交给 OpenClaw Code Mode 执行。它只总结你提供的五句话，不能作为 shell 脚本运行：

const excerpts = ["明确交付物。", "保留来源。", "限制修改范围。", "先检查已有结果。", "报告无法确认的部分。"];
const outcomes = await Promise.allSettled(
  excerpts.map((text, index) => agents.run(
    `只解释这句话的意思，最多30字，不调用外部工具：${text}`,
    { label: `note-${index + 1}` },
  )),
);
return outcomes.map((outcome, index) => outcome.status === "fulfilled"
  ? { index, answer: outcome.value }
  : { index, error: String(outcome.reason) });

这会发起五个模型子任务，最多同时执行两个；按你自己的账户计费和限额。Promise.allSettled 保留成功与失败结果，不要因为某个失败就自动重开整批。结果必须由 agents.run() 的 await 或低层 agents_wait 收集，不能用 sessions_yield 等待 collector 的自动通知。

需要停止时，点击父对话 Stop，检查其关联子任务和清理是否都结束。若 Stop 超时或报告未完成，通过 subagent 列表核对剩余子任务再取消；父任务停止不等于所有后代进程已停止。实验结束把 tools.swarm 改为 false，并检查是否有 Agent 级别显式重新启用。

v2026.9.7 起默认每组 collector 并发从 8 提到 32，且使用独立执行通道，不与普通子任务共享运行槽；普通子任务限额也按各发起会话分别计算。上面的明确小限额适合第一次练习。Swarm 是带权限与资源上限的委派，不是默认生成无限 Agent。详见官方 Swarm 流程与停止说明。

实战案例

案例一：客服 + 技术支持双 Agent

场景： 你运营一个开源项目，Discord 服务器里有 #general 频道（闲聊）和 #support 频道（技术支持）。你希望闲聊频道由一个友好的社区 Agent 处理，技术支持频道由一个专业的技术 Agent 处理。

第一步：创建 Agent

openclaw agents add community
openclaw agents add tech-support

第二步：配置 SOUL.md

~/.openclaw/workspace-community/SOUL.md：

# Community Agent

你是开源项目 MyProject 的社区助手。

## 性格
- 热情友好，欢迎新成员
- 熟悉项目的基本功能和使用方法
- 会引导用户去正确的频道提问

## 规则
- 不回答深度技术问题，引导用户去 #support 频道
- 不执行任何代码或命令
- 回复简短，适合 Discord 阅读
- 遇到 Bug 报告，引导用户创建 GitHub Issue

## 常用回复模板
- 欢迎新人："欢迎加入！建议先看看我们的文档：https://docs.myproject.dev"
- 技术问题："这个问题建议到 #support 频道提问，那边有专门的技术支持"
- Bug 报告："感谢反馈！请到 GitHub 创建一个 Issue：https://github.com/myproject/issues/new"

~/.openclaw/workspace-tech-support/SOUL.md：

# Tech Support Agent

你是开源项目 MyProject 的技术支持助手。

## 性格
- 专业、耐心、善于解释
- 会一步步引导用户排查问题
- 给出的解决方案要附带代码示例

## 专长
- MyProject 的安装和配置
- API 使用和集成
- 常见错误排查
- 性能优化建议

## 规则
- 只回答跟 MyProject 相关的技术问题
- 不确定的答案要标注"我不确定，建议查看官方文档"
- 复杂问题建议用户创建 GitHub Issue
- 涉及安全漏洞的问题，私信通知项目维护者

## 排查流程
1. 先确认用户的版本号和运行环境
2. 让用户提供错误日志
3. 根据日志定位问题
4. 给出解决方案
5. 确认问题是否解决

第三步：配置路由

{
  "agents": {
    "entries": {
      "main": {
        "default": true,
        "workspace": "~/.openclaw/workspace",
      },
      "community": {
        "workspace": "~/.openclaw/workspace-community",
        "model": "openai/gpt-5.6-luna",
        "skills": ["summarize"],
      },
      "tech-support": {
        "workspace": "~/.openclaw/workspace-tech-support",
        "model": "anthropic/claude-sonnet-5",
        "skills": ["coding-agent", "github", "summarize"],
      },
    },
  },
  "bindings": [
    {
  "agentId": "community",
  "match": {
    "channel": "discord",
    "guildId": "111222333",
    "peer": {
      "kind": "channel",
      "id": "444555666"
    }
  }
},
    {
  "agentId": "tech-support",
  "match": {
    "channel": "discord",
    "guildId": "111222333",
    "peer": {
      "kind": "channel",
      "id": "777888999"
    }
  }
},
  ],
}

效果：

• #general 频道的消息由 community Agent 处理，用当前目录里的低成本模型，回复轻松友好

• #support 频道的消息由 tech-support Agent 处理，用工具调用和长上下文更稳的模型，回复专业精准

• 私聊消息由 main Agent 处理

案例二：翻译 + 内容创作多 Agent

场景： 你是一个内容创作者，需要把中文内容翻译成英文，然后润色发布。你希望有一个翻译 Agent 和一个写作 Agent 协作完成。

第一步：创建 Agent

openclaw agents add translator
openclaw agents add writer

第二步：配置 SOUL.md

~/.openclaw/workspace-translator/SOUL.md：

# Translator Agent

你是一个专业的中英翻译助手。

## 翻译原则
- 信、达、雅 -- 准确、通顺、优美
- 技术术语保留英文原文
- 保持原文的语气和风格
- 不添加原文没有的内容

## 输出格式
- 翻译结果保存到 ~/.openclaw/shared/translations/ 目录
- 文件名格式：YYYY-MM-DD-原标题-en.md
- 文件开头标注原文来源和翻译日期

## 工作流程
1. 接收用户的中文内容
2. 分析内容类型（技术文章/博客/社交媒体）
3. 根据类型调整翻译风格
4. 输出翻译结果
5. 标注不确定的翻译，等待用户确认

~/.openclaw/workspace-writer/SOUL.md：

# Writer Agent

你是一个英文内容润色和创作助手。

## 写作风格
- 清晰、简洁、有节奏感
- 适合英文读者的表达习惯
- 避免中式英语
- 善用短句和主动语态

## 工作流程
1. 读取 ~/.openclaw/shared/translations/ 目录中的翻译稿
2. 润色英文表达，使其更地道
3. 调整段落结构，适合目标平台
4. 添加 SEO 友好的标题和摘要
5. 保存到 ~/.openclaw/shared/published/ 目录

## 输出格式
- 博客文章：Markdown 格式，包含 frontmatter
- 社交媒体：纯文本，控制字数
- 技术文档：保持代码块和格式

第三步：配置定时任务串联

通过 CLI 添加定时任务来串联两个 Agent：

openclaw cron add --tz Asia/Shanghai --name "translate-new-content" --cron "0 10 * * *" \
  --agent translator \
  --message "检查 ~/.openclaw/shared/drafts/ 目录，翻译所有新的中文稿件，保存到 ~/.openclaw/shared/translations/"

openclaw cron add --tz Asia/Shanghai --name "polish-translations" --cron "0 11 * * *" \
  --agent writer \
  --message "检查 ~/.openclaw/shared/translations/ 目录，润色所有新的翻译稿，保存到 ~/.openclaw/shared/published/"

手动触发的工作流：

你 → translator Agent：帮我翻译这篇文章（粘贴中文内容）
translator Agent → 翻译完成，保存到 shared/translations/2026-02-25-article-en.md

你 → writer Agent：帮我润色 shared/translations/2026-02-25-article-en.md
writer Agent → 润色完成，保存到 shared/published/2026-02-25-article-en.md

案例三：研究 + 写作 + 审核流水线

场景： 你需要定期生成行业研究报告。流程是：研究 Agent 收集资料 → 写作 Agent 撰写报告 → 审核 Agent 检查质量。

第一步：创建三个 Agent

openclaw agents add researcher
openclaw agents add report-writer
openclaw agents add reviewer

第二步：配置各 Agent 的 SOUL.md

~/.openclaw/workspace-researcher/SOUL.md：

# Researcher Agent

你是一个专业的行业研究员。

## 研究方法
- 从多个来源收集信息
- 交叉验证关键数据
- 标注信息来源和可信度
- 区分事实和观点

## 输出格式
把研究结果保存到 ~/.openclaw/shared/research/ 目录：

文件结构：
- summary.md -- 研究摘要（500 字以内）
- data.json -- 结构化数据（数字、统计）
- sources.md -- 信息来源列表
- raw-notes.md -- 原始笔记

## 研究模板

### summary.md
- 行业概况（3-5 句话）
- 关键趋势（3-5 个要点）
- 重要数据（表格形式）
- 风险提示

~/.openclaw/workspace-report-writer/SOUL.md：

# Report Writer Agent

你是一个专业的报告撰写者。

## 写作原则
- 数据驱动，每个观点都有数据支撑
- 结构清晰，使用标题和小标题
- 图表优先，能用图表说明的不用文字
- 结论明确，给出可操作的建议

## 工作流程
1. 读取 ~/.openclaw/shared/research/ 目录中的研究资料
2. 根据研究摘要确定报告结构
3. 撰写完整报告
4. 保存到 ~/.openclaw/shared/reports/draft-YYYY-MM-DD.md

## 报告模板
1. 执行摘要
2. 行业背景
3. 关键发现
4. 数据分析
5. 趋势预测
6. 建议和行动项
7. 附录（数据来源）

~/.openclaw/workspace-reviewer/SOUL.md：

# Reviewer Agent

你是一个严格的内容审核员。

## 审核标准
- 事实准确性：数据是否有来源支撑？
- 逻辑一致性：论点和论据是否匹配？
- 完整性：是否遗漏了重要信息？
- 可读性：表达是否清晰易懂？
- 格式规范：标题、图表、引用是否规范？

## 审核流程
1. 读取 ~/.openclaw/shared/reports/ 目录中的报告草稿
2. 逐节审核，标注问题
3. 生成审核报告，保存到 ~/.openclaw/shared/reviews/
4. 审核报告包含：
   - 总体评分（1-10）
   - 问题列表（按严重程度排序）
   - 修改建议
   - 通过/需修改/拒绝 的结论

## 输出格式
审核报告保存为 review-YYYY-MM-DD.md，格式：

### 总体评分：X/10

### 问题列表
1. [严重] 第 3 节的数据来源缺失
2. [中等] 第 5 节的预测缺乏依据
3. [轻微] 第 2 节有一个错别字

### 修改建议
- ...

### 结论：需修改

第三步：配置流水线

通过 CLI 添加定时任务来串联三个 Agent：

openclaw cron add --tz Asia/Shanghai --name "weekly-research" --cron "0 9 * * 1" \
  --agent researcher \
  --message "进行本周的 AI 行业研究，收集最新动态、融资信息、产品发布，保存到 ~/.openclaw/shared/research/"

openclaw cron add --tz Asia/Shanghai --name "weekly-report" --cron "0 14 * * 1" \
  --agent report-writer \
  --message "基于 ~/.openclaw/shared/research/ 中的资料，撰写本周 AI 行业研究报告，保存到 ~/.openclaw/shared/reports/"

openclaw cron add --tz Asia/Shanghai --name "weekly-review" --cron "0 16 * * 1" \
  --agent reviewer \
  --message "审核 ~/.openclaw/shared/reports/ 中最新的报告草稿，生成审核报告保存到 ~/.openclaw/shared/reviews/"

每周一的流程：

• 9:00 -- researcher Agent 收集资料

• 14:00 -- report-writer Agent 撰写报告

• 16:00 -- reviewer Agent 审核报告

你只需要在周一下午查看审核结果，根据修改建议做最终调整。

工坊：从一条消息到正确 Agent

多 Agent 配置最常见的失败，不是 Agent 不聪明，而是消息没有被送到正确的人手里。下面用一个完整链路练习来理解路由。

假设你有三个入口：

• Telegram 私聊：处理个人事务

• Discord #general：处理社区闲聊

• Discord #support：处理技术支持

你希望：

• 私聊默认给 main

• #general 给 community

• #support 给 tech-support

第一步，列出 Agent：

openclaw agents list

你需要看到类似结构：

Agent: main
Agent: community
Agent: tech-support

第二步，确认配置里的绑定：

{
  "bindings": [
    {
  "agentId": "community",
  "match": {
    "channel": "discord",
    "guildId": "111222333",
    "peer": {
      "kind": "channel",
      "id": "444555666"
    }
  }
},
    {
  "agentId": "tech-support",
  "match": {
    "channel": "discord",
    "guildId": "111222333",
    "peer": {
      "kind": "channel",
      "id": "777888999"
    }
  }
},
  ],
}

第三步，启动 Gateway 并观察日志：

openclaw gateway --port 18789 --verbose

发送一条消息到 #support：

安装后报 Cannot find module，怎么处理？

日志里应该能看到这条链：

[AGENT] Message received from discord:guild=111222333 channel=777888999
[AGENT] Routing: matched binding -> agent=tech-support
[AGENT] Loading workspace: ~/.openclaw/workspace-tech-support
[AGENT] Loading SOUL.md
[AGENT] Loading skills: coding-agent, github, summarize

如果消息进了 community，不要先改 SOUL.md。SOUL.md 只影响“Agent 拿到消息后怎么回答”，不影响“消息先给谁”。先查 guildId、channelId、bindings 顺序和是否有重复绑定。

Sessions 转交：让一个 Agent 把任务交给另一个 Agent

OpenClaw 的多 Agent 不只靠频道绑定，也可以通过 Sessions 工具让 Agent 之间传话。适合这些场景：

• 社区 Agent 收到技术问题，需要转给技术支持。

• 研究 Agent 完成资料收集，需要交给写作 Agent。

• 主 Agent 收到一个临时复杂任务，需要生成一个独立会话处理。

Sessions 常用工具：

工具

用途

sessions_list

查看可用会话

sessions_send

向某个会话发送消息

sessions_spawn

生成一个新的 Agent 会话

一个自然的转交流程是：

用户在 #general 问：安装后报 Cannot find module。

community Agent：
1. 判断这是技术问题。
2. 回复用户：这个问题我会转给技术支持处理。
3. 使用 sessions_send 把原始问题、来源频道、已知上下文发给 tech-support。

tech-support Agent：
1. 收到转交消息。
2. 根据自己的 SOUL.md 开始排查。
3. 如果需要用户补充日志，再回到原频道或让 community 转达。

给 community 的 SOUL.md 可以这样写：

## 技术问题转交

当用户在社区频道提出安装、报错、API、部署、性能问题时：

1. 不要直接猜答案。
2. 简短说明会转给技术支持。
3. 保留用户原话、频道来源、时间和你已经判断的问题类型。
4. 通过 Sessions 工具转给 tech-support。
5. 如果转交失败，告诉用户去 #support 频道继续。

给 tech-support 的 SOUL.md 可以这样写：

## 接收转交

收到其他 Agent 转来的问题时：

1. 先读原始问题，不要只读转交摘要。
2. 如果缺版本号、系统、日志，列出需要补充的信息。
3. 不假设 community Agent 的判断一定正确。
4. 输出可执行排查步骤。

这样写的关键，是不要让第一个 Agent “代替”第二个 Agent 做判断。转交应该保留上下文，让接收方能重新判断。

并行改同一个代码仓库：使用 managed worktree

共享目录适合交接报告；两个 Agent 同时编辑同一份代码时，更适合给任务各建一个 managed worktree，也就是独立工作副本。它会分开各自的修改，但不会自动形成安全隔离，也不会自动安装依赖或合并成果。

使用当前 v2026.9.8 时，先选一个你已授权 Agent 修改、已有提交的仓库，把下面路径换成它的实际绝对路径：

openclaw worktrees create /path/to/repo --name review-task
openclaw worktrees list --json

在 Control UI 的新会话位置选择中确认任务使用这个工作副本，再交代允许修改的范围和交付物。v2026.9.6 起，新 worktree 在未指定起始分支时会优先使用获取到的远端默认分支；如果任务依赖某个本地分支，在创建时明确指定 --base-ref，不要只凭原目录当前分支推测。

完成后先审阅改动并处理未提交、未推送的成果，再清理。需要仅删除不丢失工作的副本时，使用实际 worktree ID：

openclaw worktrees remove <id> --if-lossless
openclaw worktrees list --json

这个选项会保留不符合清理条件的副本。普通 remove 是归档路线，并不等于 Git 的非强制删除；--force 可能允许快照丢失，不能拿来处理“为什么没删掉”。高级的精确状态归档和恢复另按官方 managed worktree 说明操作。固定 v2026.9.4 环境要先查本机 openclaw worktrees --help，不要直接套用当前版新增选项。

共享文件协作：什么时候用共享目录，什么时候不用

多 Agent 协作很容易走向“大家读写同一个目录”。这很方便，但也容易混乱。共享目录适合传递产物，不适合共享人格、凭证或未整理的上下文。

适合放共享目录：

~/.openclaw/shared/research/        # 研究材料
~/.openclaw/shared/reports/         # 报告草稿
~/.openclaw/shared/reviews/         # 审核意见
~/.openclaw/shared/handovers/       # 转交记录

不适合放共享目录：

SOUL.md
USER.md
openclaw-agent.sqlite 与旧版 auth-profiles.json
未脱敏的用户私聊
API Key 或 Bot Token

一个稳妥的交接文件可以长这样：

# handovers/2026-06-09-support-001.md

## 来源

- 平台：Discord
- 频道：#general
- 转交方：community
- 接收方：tech-support

## 用户原始问题

安装后报 Cannot find module，怎么处理？

## 已知信息

- 用户未提供系统版本
- 用户未提供 OpenClaw 版本
- 用户未提供完整日志

## 建议接收方先问

1. 运行 `openclaw --version` 的结果
2. 安装方式：npm、Docker、源码
3. 完整错误日志

这个文件不是为了做形式，而是为了防止第二个 Agent 只收到一句“有人安装失败了”。转交越具体，后续追问越少。

错误 Agent 回复时的排查路径

当用户说“为什么不是 tech-support 回答我”，按下面顺序查。

第一步，看消息入口：

平台是什么？Telegram、Discord、Slack、WebChat？
消息来自私聊还是频道？
频道 ID 是不是配置里的 ID？

第二步，看 bindings：

openclaw agents list

再检查配置：

{
  "bindings": [
    {
  "agentId": "tech-support",
  "match": {
    "channel": "discord",
    "guildId": "111222333",
    "peer": {
      "kind": "channel",
      "id": "777888999"
    }
  }
},
  ],
}

第三步，比较匹配范围。具体 peer 比整个 guild 更优先，同等精度时才看 bindings 顺序。下面把具体规则写在前面便于阅读，但不能把“第一条”当成所有情况下的优先级：

{
  "bindings": [
    {
  "agentId": "tech-support",
  "match": {
    "channel": "discord",
    "guildId": "111222333",
    "peer": {
      "kind": "channel",
      "id": "777888999"
    }
  }
},
    {
  "agentId": "community",
  "match": {
    "channel": "discord",
    "guildId": "111222333"
  }
},
  ],
}

第四步，看 Agent 是否加载了正确 workspace：

openclaw gateway --verbose 2>&1 | grep "Loading workspace"

如果 workspace 对了但回答风格不对，才去改 SOUL.md。如果 workspace 都不对，改 SOUL.md 没用。

多 Agent 协作的边界设计

一个 Agent 应该像一个明确的工作台，而不是一个“更聪明的总管”。你可以给它专长、工具、记忆和入口，但不要让每个 Agent 都能做所有事。

设计时可以按任务风险分层：

风险层

例子

建议

低风险

总结公开消息、整理 FAQ、翻译文章

可以自动处理

中风险

读取项目文件、生成工单草稿、整理客户反馈

输出草稿，等待确认

高风险

执行命令、修改配置、发布消息、接触凭证

限定到专门 Agent，并要求明确授权

例如 community 可以总结频道内容，但不应该有 shell、GitHub 发布、部署权限。tech-support 可以指导用户跑诊断命令，但不应该直接在生产服务器执行命令。devops 可以读部署日志，但应该有更严格的 sandbox 和工具白名单。

如果你发现一个 Agent 的 SOUL.md 里写了太多“也负责……”，通常说明应该拆 Agent 或拆 Skill。

Agent 的工具和权限分配

为什么要限制 Agent 的工具？

默认情况下，每个 Agent 可以使用所有已安装的技能和工具。但这不是最佳实践：

1. 安全风险 -- 社交 Agent 不应该有执行 Shell 命令的能力

2. 上下文浪费 -- 加载不需要的技能会浪费 token

3. 误触发 -- 技能越多，误触发的概率越高

技能白名单配置

为每个 Agent 配置只需要的技能：

{
  "agents": {
    "entries": {
      "coding": {
        "default": true,
        // Agent 级别的 skills 是简单的字符串数组
        "skills": ["coding-agent", "github", "gh-issues", "tmux"],
      },
      "office": {
        "skills": ["gog", "slack", "notion", "trello", "summarize"],
      },
      "social": {
        "skills": ["weather", "goplaces", "summarize"],
        "tools": { "deny": ["exec", "process"] },
      },
    },
  },

  // 是否启用技能在顶层 skills.entries 中配置
  "skills": {
    "entries": {
      "coding-agent": { "enabled": true },
      "gog": { "enabled": true },
    },
  },
}

公开频道或其他不可信消息入口不要跳过这一节。沙箱默认关闭；下面的 skills 配置只筛选可见技能，config.allowedCommands、autoApprove 等自定义属性不是通用执行权限。命令、文件与网络边界仍需 tools 策略、sandbox 和所用外部 CLI 实际配置落实。

沙箱隔离

对于处理不可信消息的 Agent（比如公开频道的 Agent），建议启用沙箱。OpenClaw 使用 mode: "non-main" 模式，让非主会话在 Docker 沙箱中运行：

{
  "agents": {
    "defaults": {
      "sandbox": {
        // 非主会话自动在 Docker 沙箱中运行
        "mode": "non-main",
      },
    },
  },
}

工具 allowlist 和 denylist：

v2026.9.4 的默认沙箱工具策略如下，实际可用工具还受顶层与 Agent 的工具策略限制：

类型

工具列表

默认 allowlist

exec, process, read, ls, write, edit, apply_patch, view_image, sessions_list, sessions_history, sessions_search, sessions_send, sessions_spawn, sessions_yield, subagents, session_status

默认 denylist

browser, canvas, computer, mobile_ui, nodes, automations, gateway，以及渠道工具

共享沙箱策略配置在 tools.sandbox.tools，Agent 覆盖配置在 agents.entries.<id>.tools.sandbox.tools。deny 优先于 allow。这些默认列表可以修改，不能据此保证浏览器永远不可用；要开放沙箱浏览器，需要同时配置 browser 沙箱和工具策略。要禁止某个工具在沙箱内外执行，使用顶层或 Agent 的 tools.deny。

认证隔离

v2026.9.4 的模型认证资料存放在各 Agent 的 <agentDir>/openclaw-agent.sqlite。旧 auth-profiles.json 是迁移来源，不能当作当前凭据共享接口直接复制。

非主 Agent 的同名 OAuth profile 在自身凭据过期或刷新失败时，可以读取 main 的更新凭据；因此“每个 Agent 的 OAuth 完全独立”并不准确。需要独立账号时，从目标 Agent 的认证流程登录。模型 provider 认证、gog 的 Google Workspace 授权和 gh 的 GitHub 授权是不同流程，不能互相替代。

# 查看目标 Agent 的认证状态；不要输出或复制凭据内容
openclaw models status --agent coding

# GitHub 技能由 gh 管理认证，使用目标运行环境的 gh
gh auth status

不要复用多个 Agent 的 agentDir，也不要复制 OAuth refresh token 或正在使用的 SQLite 文件。静态 key 的共享也应按实际 SecretRef 或认证管理流程处理。

Agent 性能监控

查看 Agent 使用统计

# 查看所有 Agent
openclaw agents list

# 查看活跃会话
openclaw sessions list

# 清理过期会话
openclaw sessions cleanup

监控关键指标

下面的数字只是示例观察阈值，便于开始记录，不是 OpenClaw 官方性能标准。先用自己的模型、任务和网络跑几次，再决定哪些目标适合你的工作。

指标

说明

示例观察阈值

异常处理

响应时间

从收到消息到发出回复

< 10s

检查模型选择和网络

Token 消耗

每条消息的平均 token 数

< 5000

检查技能加载是否过多

错误率

工具调用失败的比例

< 5%

检查工具配置和权限

会话长度

平均每个会话的消息数

因场景而异

检查是否需要优化 SOUL.md

成本优化建议

1. 为低复杂度任务使用便宜的模型

{
  "agents": {
    "entries": {
      "social": {
        "model": "openai/gpt-5.6-luna",
        // 闲聊用便宜模型
      },
    },
  },
}

2. 限制技能加载数量

每个加载的技能都会增加系统提示词的长度，消耗更多 input token。只启用真正需要的技能。

3. 调整压缩后的近期对话预算

{
  "agents": {
    "defaults": {
      "compaction": {
        "keepRecentTokens": 15000,
        // 压缩时保留近期对话的 token 预算；不是压缩触发阈值
      },
    },
  },
}

4. 使用模型故障转移降低成本

Agent 的 model 字段支持故障转移配置：

{
  "agents": {
    "entries": {
      "work": {
        // model 可以是对象形式，指定主模型和备用模型
        "model": {
          "primary": "anthropic/claude-sonnet-5",
          "fallbacks": [
            "openai/gpt-5.6-luna",
            "ollama/llama3.1",
          ],
        },
      },
    },
  },
}

主模型不可用时自动切换到备用模型列表中的下一个。注意字段名是 fallbacks（复数形式）。

自定义 Agent 开发

从零创建一个专业 Agent

下面我们从零开始创建一个"DevOps 监控 Agent"，它能监控服务器状态、处理告警、执行简单的运维操作。

第一步：创建 Agent

openclaw agents add devops

第二步：编写 SOUL.md

~/.openclaw/workspace-devops/SOUL.md：

# DevOps Agent

你是一个专业的 DevOps 运维助手，负责监控服务器状态和处理告警。

## 性格
- 冷静、精确、注重细节
- 遇到紧急情况会立即通知用户
- 操作前会确认，操作后会验证

## 专长
- 服务器状态监控
- 日志分析和错误排查
- Docker 容器管理
- 简单的运维操作（重启服务、清理磁盘等）

## 安全规则（最重要）
- 永远不要执行 rm -rf 或类似的危险命令
- 重启服务前必须确认用户意图
- 不修改防火墙规则
- 不修改 SSH 配置
- 所有操作都要记录到日志

## 告警处理流程
1. 收到告警 → 分析告警内容
2. 判断严重程度（P0/P1/P2/P3）
3. P0/P1 → 立即通知用户 + 尝试自动修复
4. P2/P3 → 记录到日志 + 下次汇报时提及

## 自动修复策略
- 磁盘空间不足 → 清理 Docker 无用镜像和日志
- 服务无响应 → 尝试重启服务（最多 3 次）
- 内存使用过高 → 识别占用最多的进程并报告
- CPU 持续高负载 → 收集 top 信息并报告

## 日报格式
每天 18:00 生成运维日报：
- 服务器健康状态概览
- 今日告警统计
- 资源使用趋势
- 需要关注的问题

第三步：创建工作空间技能

mkdir -p ~/.openclaw/workspace-devops/skills/server-monitor

~/.openclaw/workspace-devops/skills/server-monitor/SKILL.md：

---
name: server-monitor
description: 用户明确要求检查服务器资源、容器或服务状态时使用；重启服务前核对对象并确认授权。
---

# 服务器监控技能

## 健康检查

当用户要求检查服务器状态时，执行以下命令并整理结果：

```bash
# CPU 和内存
top -bn1 | head -20

# 磁盘空间
df -h

# Docker 容器状态
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# 最近的错误日志
journalctl --since "1 hour ago" --priority err --no-pager | tail -20

服务管理

当用户要求重启服务时：

1. 确认服务名称
2. 检查服务当前状态：systemctl status <service>
3. 确认用户意图："确定要重启 <service> 吗？"
4. 执行重启：systemctl restart <service>
5. 验证重启结果：systemctl status <service>
6. 记录操作到日志

第四步：配置路由和定时任务

{
"agents": {
"entries": {
"devops": {
"workspace": "~/.openclaw/workspace-devops",
"model": "anthropic/claude-sonnet-5",
"skills": ["server-monitor", "summarize"],
},
},
},
"bindings": [
{
"agentId": "devops",
"match": {
"channel": "slack",
"peer": {
"kind": "channel",
"id": "C-ops-channel"
}
}
},
],
"cron": {
"enabled": true,
},
}

通过 CLI 添加定时任务：

openclaw cron add --tz Asia/Shanghai --name "health-check" --cron "*/30 * * * *"
--agent devops
--message "执行服务器健康检查，如果发现异常，通过 Slack 通知 #ops 频道"

openclaw cron add --tz Asia/Shanghai --name "daily-report" --cron "0 18 * * *"
--agent devops
--message "生成今日运维日报，发送到 Slack #ops 频道"

### Agent 开发最佳实践

1. SOUL.md 要具体，不要模糊

差的写法

你是一个助手，帮用户做事。

好的写法

你是一个 TypeScript 编程助手。

• 所有代码使用 TypeScript 严格模式
• 遵循 Airbnb 代码风格
• 函数必须有 JSDoc 注释
• 不使用 any 类型

2. 明确定义边界

在 SOUL.md 中明确说明 Agent 不应该做什么：

不要做的事

• 不要执行任何 Shell 命令
• 不要修改系统文件
• 不要回答跟你职责无关的问题
• 不要泄露其他用户的信息

3. 提供错误处理指引

异常处理

• 如果工具调用失败，告诉用户具体的错误信息
• 如果不确定答案，说"我不确定"而不是编造
• 如果用户的请求超出你的能力范围，建议他们联系人工支持

4. 定期审查和优化

每周检查一次：

- Agent 的响应质量是否符合预期？

- 有没有误触发或漏触发的情况？

- Token 消耗是否合理？

- SOUL.md 是否需要更新？

## Agent 调试技巧

### 开启详细日志

启动 Gateway 时开启 Agent 调试

openclaw gateway --verbose

或者在配置中开启

{
"logging": {
"level": "debug",
},
}

开启后，你会在日志中看到：

[AGENT] Message received from telegram:chat=-100123456789
[AGENT] Routing: matched binding → agent=social
[AGENT] Loading workspace: ~/.openclaw/workspace-social
[AGENT] Loading SOUL.md (tokens: 320)
[AGENT] Loading MEMORY.md (tokens: 150)
[AGENT] Loading skills: weather, goplaces, summarize
[AGENT] Total system prompt tokens: 1,850
[AGENT] Calling model: openai/gpt-5.6-luna
[AGENT] Model response received (tokens: 120, time: 1.2s)
[AGENT] Sending response to telegram:chat=-100123456789

### 常见问题排查

问题：消息没有路由到正确的 Agent

排查步骤：

1. 检查 bindings 配置是否正确：

openclaw agents list

1. 确认频道 ID 是否正确（Discord 和 Telegram 的 ID 格式不同）

1. 检查是否有多个 Agent 绑定了同一个频道（先匹配的会生效）

1. 查看路由日志：

openclaw gateway --verbose 2>&1 | grep "AGENT.*Routing"

问题：Agent 的回复不符合 SOUL.md 的设定

排查步骤：

1. 确认 SOUL.md 文件路径正确（在 Agent 的工作空间根目录下）

1. 检查 SOUL.md 是否被正确加载：

openclaw gateway --verbose 2>&1 | grep "Loading SOUL"

1. SOUL.md 的指令是否太模糊？尝试用更具体的语言

1. 是否有其他技能的指令覆盖了 SOUL.md 的设定？检查技能优先级

问题：Agent 的工具调用失败

排查步骤：

1. 检查技能是否正确启用（查看 openclaw.json 中对应 Agent 的 skills 数组配置）

1. 检查工具依赖是否安装（如 gh、ffmpeg）

1. 检查权限配置（确认工具在沙箱 allowlist 中）

1. 查看工具调用日志：

openclaw gateway --verbose 2>&1 | grep "Tool call"

问题：Agent 之间的共享文件不同步

排查步骤：

1. 确认共享目录存在且两个 Agent 都有读写权限

1. 检查定时任务的执行顺序（写入 Agent 必须先于读取 Agent 执行）

1. 查看会话日志（使用 sessions_history 工具或检查 Gateway 日志）

### 使用 WebChat 调试

WebChat 是调试 Agent 最方便的工具。你可以在浏览器中直接跟任意 Agent 对话：

启动 Gateway（如果还没启动）

openclaw gateway --port 18789

打开浏览器访问

http://localhost:18789/

登录后在 New session 页面选择 coding 或 social

在 Control UI 的新会话入口选择目标 Agent，并检查会话显示的 Agent 和工作区。不要只凭 URL 查询参数认定路由已经切换。

## 常见问题

### Q1：最多能创建多少个 Agent？

没有硬性限制，但每个 Agent 都会占用一些磁盘空间（工作空间、会话历史、记忆文件）。实际使用中，3-5 个 Agent 是比较常见的配置。超过 10 个 Agent 可能会让管理变得复杂。

### Q2：Agent 之间能共享记忆吗？

默认不能。每个 Agent 有独立的 MEMORY.md 和每日日志。如果你需要共享某些信息，可以：

1. 把可共享的信息放进经审查的公共目录（如 ~/.openclaw/shared/），指定谁负责写入

1. 为需要读取的 Agent 配置实际文件访问权限；启用 sandbox 时还需核对只读挂载和可见路径，再在 SOUL.md 中说明用途

1. 手动复制记忆文件（不推荐，容易冲突）

1. 使用 Memory Wiki 插件（memory-wiki，v2026.4.7 起随包内置）-- 提供结构化的知识页面层，支持确定性的页面组织和跨 Agent 共享查询。详见官方文档 memory-wiki

1. 使用 Honcho 后端 -- 支持跨会话、多 Agent 感知的记忆系统

### Q3：能不能让一个 Agent 调用另一个 Agent？

可以。OpenClaw 提供了 Sessions 工具来实现 Agent 间的直接通信：

- sessions_list -- 列出当前权限可见的会话；最近更新不证明会话正在执行

- sessions_send -- 向另一个会话发消息（向授权目标会话发送请求；返回与后续交付按安装版本处理）

- sessions_spawn -- 生成新的 Agent 会话

如果不需要实时通信，也可以使用定时任务 + 共享文件的方式（参见"Agent 间通信机制"章节）。

### Q4：删除 Agent 会丢失数据吗？

openclaw agents delete <id> 会从配置中删除 Agent，并处理对应 workspace、Agent 状态和会话目录，通常移到 Trash。执行前核对实际路径和备份，不能假定工作区会原地保留；路径清理失败时按命令报告处理。

### Q5：多个 Agent 绑定同一个频道会怎样？

同一条入站消息通常只路由到一个 Agent。先比较 bindings 的匹配范围：具体会话或群组范围优先于账号、通道的兜底规则；同一优先级内才由 bindings 数组中靠前的规则决定。Agent 配置对象的排列顺序不决定路由。重叠绑定时核对 accountId、peer、guildId 或 teamId，并显式设置默认 Agent。

显式配置了本章的 Room Teams / broadcast 时，符合群准入的一条消息可以交给多个参与者；这项设置优先于普通路由绑定。匹配的 ACP 类型绑定则是独占路线，会交给指定 ACP 会话，不进行 broadcast fan-out。排查时先区分普通绑定、broadcast 与 ACP，不能靠把同一频道绑定多次来实现团队讨论。

### Q6：Agent 的会话是独立的吗？

会话状态按 Agent 分开存储，但这不等于其他 Agent 永远不能读到历史。v2026.9.4 的普通跨 Agent 会话访问默认开启，由 tools.sessions.visibility 和 tools.agentToAgent 控制；需要限制时明确收窄可见性或关闭普通跨 Agent 访问。要求严格隔离时使用独立 Gateway 或 OS/主机边界。

### Q7：如何迁移 Agent 到另一台机器？

复制以下目录到新机器：

Agent 状态（认证凭证、会话历史）

~/.openclaw/agents/<agentId>/

Agent 工作空间（SOUL.md、记忆、技能）

~/.openclaw/workspace-<agentId>/

然后在新机器的 openclaw.json 中添加对应的 Agent 配置。

### Q8：多 Agent 模式下 Gateway 的资源消耗会增加吗？

Gateway 本身的资源消耗不会显著增加。Agent 是按需加载的 -- 只有收到消息时才会激活对应的 Agent。空闲的 Agent 不占用 CPU 和内存。主要的额外消耗来自：

- 磁盘空间：每个 Agent 的工作空间和会话历史

- AI API 调用：每个 Agent 独立计费

v2026.4.22 优化了插件启动性能（捆绑插件加载时间降低 82-90%，doctor --non-interactive 运行时间降低约 74%），多 Agent 场景下 Gateway 的首次响应速度明显改善。

### Q9：能不能动态创建和销毁 Agent？

Agent 的创建需要通过 CLI 命令（openclaw agents add）。但在运行时，Agent 可以通过 sessions_spawn 工具动态生成新的会话，实现临时任务的分发。

## 下一步

多 Agent 协作搞定！去 09. Docker 部署 学习如何把 OpenClaw 容器化部署到服务器上！