08. 多 Agent 协作指南

课程信息
难度等级：🔴 高级
阅读时间：35 分钟
前置知识：已熟悉基本使用（03-快速开始）+ 了解技能系统（06-技能系统）
本篇你将学会： 创建多个 AI 助手、配置分工协作、设置消息路由、管理 Agent 间通信
大多数人不需要这篇！ 如果你只是个人使用，一个默认的 main Agent 就够了。只有当你需要"不同平台用不同 AI 性格"或"团队多人使用"时才需要看这篇

什么是 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 架构

架构总览

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

OpenClaw 的多 Agent 架构基于 Pi agent runtime（RPC 模式）运行，采用扁平路由模型，不是层级管理模型。没有"管理者 Agent"来调度其他 Agent，而是由 Gateway 根据消息来源直接路由到对应的 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  │
└──────────┘└──────────┘└──────────┘└──────────┘

关键设计决策

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

OpenClaw 官方明确表示不会合并"Agent 层级框架（管理者的管理者/嵌套规划树）"。原因很实际：

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

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

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

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

每个 Agent 是完全独立的

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

资源	是否共享	说明
工作空间	否	每个 Agent 有独立的工作目录
记忆文件	否	每个 Agent 有独立的 MEMORY.md 和日志
记忆后端	可选	可配置 Builtin(SQLite)、QMD、Honcho 等后端
会话历史	否	每个 Agent 的对话记录完全隔离
认证凭证	否	每个 Agent 的 auth-profiles.json 独立
技能配置	可选	可以配置 Agent 级别的技能白名单
AI 模型	可选	可以为每个 Agent 指定不同的模型

目录结构详解

~/.openclaw/
├── openclaw.json              # 主配置文件（包含 Agent 列表和路由规则）
│
├── agents/                    # Agent 状态目录
│   ├── main/                  # 默认 Agent
│   │   ├── agent/
│   │   │   └── auth-profiles.json    # main 的认证凭证
│   │   └── sessions/                  # main 的会话历史
│   │       ├── session-abc123.json
│   │       └── session-def456.json
│   │
│   ├── coding/                # 编程 Agent
│   │   ├── agent/
│   │   │   └── auth-profiles.json    # coding 的认证凭证
│   │   └── sessions/                  # coding 的会话历史
│   │
│   └── social/                # 社交 Agent
│       ├── agent/
│       │   └── auth-profiles.json    # social 的认证凭证
│       └── sessions/                  # social 的会话历史
│
├── 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

查看和管理 Agent

在 openclaw.json（JSON5）中配置 Agent

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

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

  // bindings 是顶层配置，不嵌套在 agent 内部
  "bindings": [
    {
      "agent": "coding",
      "channel": "discord",
      "guildId": "123456789",
      "channelId": "987654321",
    },
    {
      "agent": "social",
      "channel": "telegram",
      "chatId": "-100123456789",
    },
    {
      "agent": "work",
      "channel": "slack",
      "teamId": "T01234567",
      "channelId": "C01234567",
    },
  ],
}

Agent 配置字段详解

字段	类型	必填	说明
`id`	`string`	是	Agent 唯一标识符，只能用字母、数字、连字符
`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 示例：

社交 Agent 的 SOUL.md 示例：

办公 Agent 的 SOUL.md 示例：

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

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

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

成本对比（假设每天处理 100 条消息）：

方案	模型	估算日成本
全部用 Opus	claude-opus-4-6	~$5-10
按需分配	Opus + Sonnet + Mini	~$2-4
全部用 Mini	gpt-5.2-mini	~$0.5-1

按需分配能在保证关键任务质量的同时，大幅降低成本。

Agent 间通信机制

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

Sessions 工具：Agent 直接通信

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

四个核心工具：

工具	功能	说明
`sessions_list`	发现活跃会话	列出当前所有活跃的 Agent 会话
`sessions_history`	获取会话日志	查看指定会话的历史消息
`sessions_send`	向另一个会话发消息	支持 reply-back ping-pong 和 announce step 模式
`sessions_spawn`	生成新会话	动态创建一个新的 Agent 会话

sessions_send 的两种模式：

reply-back ping-pong -- 发送消息并等待对方回复，适合需要来回协商的场景

announce step -- 单向通知，不等待回复，适合流水线式的任务传递

使用示例：

coding Agent 完成代码审查
    │
    ├── sessions_list → 发现 writer Agent 的活跃会话
    │
    ├── sessions_send → 向 writer Agent 发送审查结果
    │   （announce step 模式，不等待回复）
    │
    └── writer Agent 收到消息，开始生成审查报告

Sessions CLI 命令：

间接通信方式

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

方式一：共享文件

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

{
  "agents": {
    "list": [
      {
        "id": "research",
        "workspace": "~/.openclaw/workspace-research",
      },
      {
        "id": "writer",
        "workspace": "~/.openclaw/workspace-writer",
      },
    ],
  },
}

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

方式二：通过用户中转

最简单的方式 -- 你从一个 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 定时任务让 Agent 按顺序执行：

{
  "cron": {
    "enabled": true,
    "store": "file",
    "maxConcurrentRuns": 2,
  },
}

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

方式四：通过 HTTP 请求触发

一个 Agent 完成任务后，可以通过 Gateway 的 HTTP API 触发另一个 Agent。在 coding Agent 的技能中，完成审查后通过 HTTP 请求触发 writer Agent：

消息路由和绑定配置

路由规则详解

Gateway 收到消息后，按以下顺序匹配 Agent：

消息进来
    │
    ▼
1. 检查 bindings 配置
   ├── 匹配到 → 路由到对应 Agent
   └── 未匹配 → 继续
    │
    ▼
2. 检查是否是私聊
   ├── 是 → 路由到 main Agent（默认）
   └── 否 → 继续
    │
    ▼
3. 回退到默认 Agent（main）

绑定类型

Discord 绑定：

// 顶层 bindings 数组
{
  "bindings": [
    {
      "agent": "coding",
      "channel": "discord",
      "guildId": "123456789",
      "channelId": "987654321",
    },
  ],
}

guildId -- Discord 服务器 ID

channelId -- Discord 频道 ID

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

Telegram 绑定：

{
  "bindings": [
    {
      "agent": "social",
      "channel": "telegram",
      "chatId": "-100123456789",
    },
  ],
}

chatId -- Telegram 群组 ID（负数开头）

私聊默认走 main Agent，不需要绑定

Slack 绑定：

{
  "bindings": [
    {
      "agent": "work",
      "channel": "slack",
      "teamId": "T01234567",
      "channelId": "C01234567",
    },
  ],
}

WhatsApp 绑定：

{
  "bindings": [
    {
      "agent": "social",
      "channel": "whatsapp",
      "groupId": "120363xxx@g.us",
    },
  ],
}

多平台绑定：

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

// 顶层 bindings 数组中，同一个 agent 可以有多条绑定
{
  "bindings": [
    {
      "agent": "coding",
      "channel": "discord",
      "guildId": "111111",
      "channelId": "222222",
    },
    {
      "agent": "coding",
      "channel": "discord",
      "guildId": "111111",
      "channelId": "333333",
    },
    {
      "agent": "coding",
      "channel": "telegram",
      "chatId": "-100999888777",
    },
    {
      "agent": "coding",
      "channel": "slack",
      "teamId": "T01234567",
      "channelId": "C09876543",
    },
  ],
}

查看路由状态

任务分发和协调策略

策略一：按职能分工

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

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

配置示例：

{
  "agents": {
    "list": [
      {
        "id": "coding",
        "skills": ["coding-agent", "github", "gh-issues", "tmux"],
        "model": "anthropic/claude-opus-4-6",
      },
      {
        "id": "office",
        "skills": ["gog", "slack", "notion", "trello", "summarize"],
        "model": "anthropic/claude-sonnet-4-6",
      },
      {
        "id": "social",
        "skills": ["weather", "goplaces", "summarize"],
        "model": "openai/gpt-5.2-mini",
      },
    ],
  },
}

策略二：按平台分工

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

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

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

策略三：按安全等级分工

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

┌──────────────────────────────────────────────────┐
│                按安全等级分工                       │
│                                                  │
│  trusted Agent   → 有完整权限，只接受你的私聊      │
│  limited Agent   → 有限权限，处理群聊消息          │
│  readonly Agent  → 只读权限，处理公开频道          │
└──────────────────────────────────────────────────┘

配置示例：

{
  "agents": {
    "defaults": {
      "sandbox": {
        // 非主会话在 Docker 沙箱中运行
        "mode": "non-main",
      },
    },
    "list": [
      {
        "id": "trusted",
        "skills": ["coding-agent", "github", "gog", "slack"],
        // 完整权限，只处理私聊
      },
      {
        "id": "limited",
        "skills": ["summarize", "weather", "goplaces"],
        // 有限权限，处理群聊
      },
      {
        "id": "readonly",
        "skills": ["summarize"],
        // 只读权限，处理公开频道
      },
    ],
  },
  "bindings": [
    {
      "agent": "limited",
      "channel": "telegram",
      "chatId": "-100111222333",
    },
    {
      "agent": "readonly",
      "channel": "discord",
      "guildId": "444555666",
    },
  ],
}

策略四：流水线协作

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

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

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

实战案例

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

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

第一步：创建 Agent

第二步：配置 SOUL.md

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

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

第三步：配置路由

{
  "agents": {
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
      },
      {
        "id": "community",
        "workspace": "~/.openclaw/workspace-community",
        "model": "openai/gpt-5.2-mini",
        "skills": ["summarize"],
      },
      {
        "id": "tech-support",
        "workspace": "~/.openclaw/workspace-tech-support",
        "model": "anthropic/claude-sonnet-4-6",
        "skills": ["coding-agent", "github", "summarize"],
      },
    ],
  },
  "bindings": [
    {
      "agent": "community",
      "channel": "discord",
      "guildId": "111222333",
      "channelId": "444555666",
    },
    {
      "agent": "tech-support",
      "channel": "discord",
      "guildId": "111222333",
      "channelId": "777888999",
    },
  ],
}

效果：

#general 频道的消息由 community Agent 处理，用便宜的 GPT-5.2-mini，回复轻松友好

#support 频道的消息由 tech-support Agent 处理，用更强的 Claude Sonnet，回复专业精准

私聊消息由 main Agent 处理

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

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

第一步：创建 Agent

第二步：配置 SOUL.md

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

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

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

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

手动触发的工作流：

你 → 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

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

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

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

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

第三步：配置流水线

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

每周一的流程：

9:00 -- researcher Agent 收集资料

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

16:00 -- reviewer Agent 审核报告

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

Agent 的工具和权限分配

为什么要限制 Agent 的工具？

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

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

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

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

技能白名单配置

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

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

  // 技能的详细配置放在顶层 skills.entries 中
  "skills": {
    "entries": {
      "coding-agent": {
        "config": {
          "workDir": "~/projects",
          "allowedCommands": ["npm", "node", "git", "tsc", "pnpm"],
          "autoApprove": false,
        },
      },
      "gog": {
        "config": {
          "timezone": "Asia/Shanghai",
          "language": "zh-CN",
        },
      },
    },
  },
}

⏭️ 小白可跳过 — 默认的沙箱配置已经足够安全

沙箱隔离

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

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

工具 allowlist 和 denylist：

沙箱环境中，Agent 可用的工具受到严格限制：

类型	工具列表
allowlist（允许使用）	`bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`
denylist（禁止使用）	`browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`

allowlist 中的工具是 Agent 在沙箱中可以调用的全部工具。denylist 中的工具即使在 allowlist 中也会被阻止，确保沙箱内的 Agent 无法访问浏览器、管理 Gateway 或操作 Discord 等外部服务。

认证隔离

每个 Agent 的认证凭证是独立的：

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

main Agent 的 Google 凭证不会自动共享给 coding Agent。如果 coding Agent 也需要访问 Google，需要单独认证：

如果你确实需要共享凭证，可以手动复制：

但不推荐这样做 -- 独立认证更安全，而且可以为不同 Agent 使用不同的账号。

Agent 性能监控

查看 Agent 使用统计

监控关键指标

指标	说明	健康范围	异常处理
响应时间	从收到消息到发出回复	< 10s	检查模型选择和网络
Token 消耗	每条消息的平均 token 数	< 5000	检查技能加载是否过多
错误率	工具调用失败的比例	< 5%	检查工具配置和权限
会话长度	平均每个会话的消息数	因场景而异	检查是否需要优化 SOUL.md

成本优化建议

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

{
  "agents": {
    "list": [
      {
        "id": "social",
        "model": "openai/gpt-5.2-mini",
        // 闲聊用便宜模型
      },
    ],
  },
}

2. 限制技能加载数量

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

3. 调整会话压缩阈值

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 15000,
        // 更早压缩会话，减少 token 消耗
      },
    },
  },
}

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

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

{
  "agents": {
    "list": [
      {
        "id": "work",
        // model 可以是对象形式，指定主模型和备用模型
        "model": {
          "primary": "anthropic/claude-sonnet-4-6",
          "fallbacks": [
            "openai/gpt-5.2-mini",
            "ollama/llama3.1",
          ],
        },
      },
    ],
  },
}

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

自定义 Agent 开发

从零创建一个专业 Agent

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

第一步：创建 Agent

第二步：编写 SOUL.md

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

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

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

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

{
  "agents": {
    "list": [
      {
        "id": "devops",
        "workspace": "~/.openclaw/workspace-devops",
        "model": "anthropic/claude-sonnet-4-6",
        "skills": ["server-monitor", "summarize"],
      },
    ],
  },
  "bindings": [
    {
      "agent": "devops",
      "channel": "slack",
      "teamId": "T01234567",
      "channelId": "C-ops-channel",
    },
  ],
  "cron": {
    "enabled": true,
  },
}

通过 CLI 添加定时任务：

Agent 开发最佳实践

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

2. 明确定义边界

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

3. 提供错误处理指引

4. 定期审查和优化

每周检查一次：

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

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

Token 消耗是否合理？

SOUL.md 是否需要更新？

Agent 调试技巧

开启详细日志

{
  "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.2-mini
[AGENT] Model response received (tokens: 120, time: 1.2s)
[AGENT] Sending response to telegram:chat=-100123456789

常见问题排查

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

排查步骤：

检查 bindings 配置是否正确：

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

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

查看路由日志：

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

排查步骤：

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

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

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

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

问题：Agent 的工具调用失败

排查步骤：

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

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

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

查看工具调用日志：

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

排查步骤：

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

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

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

使用 WebChat 调试

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

通过 URL 参数 ?agent=<agentId> 可以指定跟哪个 Agent 对话，方便逐个测试。

常见问题

最多能创建多少个 Agent？

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

Agent 之间能共享记忆吗？

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

把共享信息写入公共目录（如 ~/.openclaw/shared/）

在每个 Agent 的 SOUL.md 中指示它读取公共目录

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

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

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

能不能让一个 Agent 调用另一个 Agent？

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

sessions_list -- 发现活跃会话

sessions_send -- 向另一个会话发消息（支持 reply-back ping-pong 和 announce step 模式）

sessions_spawn -- 生成新的 Agent 会话

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

删除 Agent 会丢失数据吗？

删除 Agent 会移除 Agent 的状态目录（~/.openclaw/agents/<agentId>/），但不会删除工作空间目录。你的 SOUL.md、记忆文件、技能文件都还在。如果要彻底清理，需要手动删除工作空间目录。

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

只有第一个匹配的 Agent 会处理消息。如果你不小心把两个 Agent 绑定到了同一个频道，检查 openclaw.json 中 agents.list 的顺序 -- 排在前面的 Agent 优先匹配。

Agent 的会话是独立的吗？

是的，完全独立。coding Agent 的对话历史不会出现在 social Agent 的上下文中。这是设计如此 -- 保证每个 Agent 的上下文干净、专注。

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

复制以下目录到新机器：

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

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

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

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

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

v2026.4.20+ 优化了插件启动性能（冷启动时间降低约 74%，依赖加载时间降低 82-90%），多 Agent 场景下 Gateway 的首次响应速度明显改善。

能不能动态创建和销毁 Agent？

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

下一步

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

08-多Agent协作指南

08. 多 Agent 协作指南#

什么是 Agent？#

为什么需要多个 Agent？#

OpenClaw 的 Agent 架构#

架构总览#

关键设计决策#

目录结构详解#

Agent 角色定义和配置#

创建新 Agent#

查看和管理 Agent#

在 openclaw.json（JSON5）中配置 Agent#

Agent 配置字段详解#

Agent 人格设定（SOUL.md）#

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

Agent 间通信机制#

Sessions 工具：Agent 直接通信#

间接通信方式#

消息路由和绑定配置#

路由规则详解#

绑定类型#

查看路由状态#

任务分发和协调策略#

策略一：按职能分工#

策略二：按平台分工#

策略三：按安全等级分工#

策略四：流水线协作#

实战案例#

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

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

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

Agent 的工具和权限分配#

为什么要限制 Agent 的工具？#

技能白名单配置#

沙箱隔离#

认证隔离#

Agent 性能监控#

查看 Agent 使用统计#

监控关键指标#

成本优化建议#

自定义 Agent 开发#

从零创建一个专业 Agent#

Agent 开发最佳实践#

Agent 调试技巧#

开启详细日志#

常见问题排查#

使用 WebChat 调试#

常见问题#

最多能创建多少个 Agent？#

Agent 之间能共享记忆吗？#

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

删除 Agent 会丢失数据吗？#

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

Agent 的会话是独立的吗？#

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

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

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

下一步#

08. 多 Agent 协作指南

什么是 Agent？

为什么需要多个 Agent？

OpenClaw 的 Agent 架构

架构总览

关键设计决策

目录结构详解

Agent 角色定义和配置

创建新 Agent

查看和管理 Agent

在 openclaw.json（JSON5）中配置 Agent

Agent 配置字段详解

Agent 人格设定（SOUL.md）

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

Agent 间通信机制

Sessions 工具：Agent 直接通信

间接通信方式

消息路由和绑定配置

路由规则详解

绑定类型

查看路由状态

任务分发和协调策略

策略一：按职能分工

策略二：按平台分工

策略三：按安全等级分工

策略四：流水线协作

实战案例

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

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

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

Agent 的工具和权限分配

为什么要限制 Agent 的工具？

技能白名单配置

沙箱隔离

认证隔离

Agent 性能监控

查看 Agent 使用统计

监控关键指标

成本优化建议

自定义 Agent 开发

从零创建一个专业 Agent

Agent 开发最佳实践

Agent 调试技巧

开启详细日志

常见问题排查

使用 WebChat 调试

常见问题

最多能创建多少个 Agent？

Agent 之间能共享记忆吗？

能不能让一个 Agent 调用另一个 Agent？

删除 Agent 会丢失数据吗？

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

Agent 的会话是独立的吗？

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

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

能不能动态创建和销毁 Agent？

下一步