基于 OpenClaw 多 Agent 系统设计与接入飞书运用实践

在企业数字化转型的浪潮中，多 Agent（智能体）系统正成为提升效率的关键武器。本文将以 OpenClaw 平台为例，手把手教你搭建一套企业级多机器人系统，并深度集成飞书协作平台。

一、架构基础：理解三层核心关系

搭建多 Agent 系统前，首先要厘清三个关键概念的层级关系：

层级	定义	通俗理解
Accounts	飞书开放平台的 App ID + Secret	机器人的"身份证"，用于身份验证
Agents	独立的工作空间（Workspace）	机器人的"大脑"，存储人设和记忆
Bindings	账号与智能体的映射规则	消息路由的"导航系统"

核心设计原则：一个账号只能绑定一个智能体，但一个智能体可以同时服务多个账号。Bindings 本质上是一张路由表，决定了每条消息该由哪个"大脑"处理。

二、实战配置：从零开始搭建

2.1 创建独立工作空间

物理隔离是防止"记忆串台"的关键：

复制代码

mkdir -p ./.openclaw/workspaces/app_robot1_workspace
mkdir -p ./.openclaw/workspaces/app_robot2_workspace

2.2 配置 openclaw.json

以下配置经过生产环境验证，覆盖私聊和群聊全场景：

复制代码

{
  "agents": {
    "list": [
      {
        "id": "agent_robot1",
        "workspace": "./.openclaw/workspaces/robot1_workspace",
        "model": "claude-opus-4"
      },
      {
        "id": "agent_robot2",
        "workspace": "./.openclaw/workspaces/robot2_workspace",
        "model": "qwen-coder-plus"
      }
    ]
  },
  "bindings": [
    {
      "agentId": "agent_robot1",
      "match": {
        "channel": "feishu",
        "accountId": "app_robot1"
      }
    },
    {
      "agentId": "agent_robot2",
      "match": {
        "channel": "feishu",
        "accountId": "app_robot2"
      }
    }
  ],
  "channels": {
    "feishu": {
      "enabled": true,
      "accounts": {
        "app_robot1": {
          "appId": "cli_xxxxxxxxxxxxxxxx",
          "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "botName": "主管"
        },
        "app_robot2": {
          "appId": "cli_yyyyyyyyyyyyyyyy",
          "appSecret": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
          "botName": "代码专家"
        }
      },
      "groups": {
        "oc_xxxxxxxxxxxxxxxx": {
          "requireMention": true
        }
      }
    }
  },
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["agent_robot1", "agent_robot2"]
    }
  }
}

Bindings 配置要点 ：推荐只匹配 accountId（不添加 peer 限定），这样该账号的所有消息（无论私聊还是群聊）都会被正确路由。只有在需要复杂逻辑（如同一账号在不同群使用不同智能体）时，才考虑添加 peer 字段。

2.3 重启服务使配置生效

复制代码

openclaw gateway restart

三、五大避坑经验

坑位一：权限未发版导致群聊静默

症状：日志报错 Access denied. [cardkit:card:write]，私聊正常但群聊无响应。

根因：飞书应用新建后，"发送消息卡片"等权限处于"已申请"状态，必须走发版流程才能生效。

解决方案：

1. 飞书开放平台 → 应用权限 → 开通 cardkit:card:write 和 im:message:group_msg
1. 创建新版本 → 申请发布 → 等待管理员审核通过

💡 很多教程忽略了这个关键步骤，但不走发布流程，权限永远不会真正生效。

坑位二：智能体"串台"现象

症状：与机器人 B 对话，却收到了机器人 A 的回复内容和记忆。

根因：Bindings 配置不完整，导致消息路由到错误的智能体。

解决方案 ：在 match 中明确指定 accountId。最稳妥的做法是只匹配 channel + accountId，避免使用 peer 限定。

⚠️ 经验教训：我曾尝试分别为群聊和私聊配置两条 binding（一条用 peer.kind: "group"，一条用 peer.kind: "dm"），结果重启后 DM 配置被覆盖丢失。统一使用无 peer 限定的配置更可靠。

坑位三：小模型输出原始 JSON

症状：机器人回复一串 {"name": "tool_name", "arguments": {...}} 格式的文本，而不是自然语言。

根因：小参数模型（如 Qwen 7B）在处理 Function Calling 时不稳定，错误地将工具调用 JSON 当作回复输出。

解决方案：

• 在 SOUL.md 中明确指示："请用自然语言回答，不要输出工具调用格式"
• 或者为关键角色配置更强的模型（Claude、GPT-4o）作为主控

坑位四：JSON 格式错误导致服务启动失败

症状：修改配置后 gateway restart 失败，报错 JSON5: invalid character。

根因：多余的逗号、缺失的括号、或复制粘贴带来的隐藏字符。

解决方案：

• 使用 VS Code 编辑，开启 JSON 语法检查
• 运行 openclaw doctor --fix 自动修复格式问题
• 修改后用 PowerShell 验证：Get-Content ~/.openclaw/openclaw.json | ConvertFrom-Json

坑位五：多机器人群聊死循环

症状：群内两个机器人互相接话，"好的我来处理"、"收到"、"我来补充"...刷屏不止。

根因：群聊未开启 requireMention，两个机器人都误以为对方在跟自己对话。

解决方案：多机器人共存的群必须开启 @ 触发：

复制代码

"groups": {
  "oc_你的群组ID": {
    "requireMention": true
  }
}

四、进阶能力：智能体协作

启用 agentToAgent 后，智能体之间可以相互调用，实现专业分工协作：

协作场景示例：

1. 用户在群里 @助教："帮我分析这段代码的报错原因"
1. 助教（Claude）接收请求，识别需要代码分析能力
1. 通过内部通道调用代码专家（Qwen）
1. 代码专家分析后返回技术方案
1. 助教整合成易懂的回复，@用户给出最终答案

前置条件：

• agentToAgent.enabled 设为 true
• 被调用的 Agent 必须在 allow 白名单中
• 所有参与协作的 Agent 都已正确绑定且能独立运行

五、总结

多 Agent 系统的核心价值在于专业分工：让最擅长创意的模型处理创意，让最擅长代码的模型处理代码，让最擅长长文本的模型处理长文本。这种组合产生的效果是化学反应，而非简单的叠加。

配置过程中最大的两个挑战是飞书权限发版流程 和 Bindings 路由规则，理解并正确处理这两点，你就已经超越了绝大多数实践者。

本文由 lead 撰写，基于实践经验整理，供技术参考。