多Agent框架对接飞书机器人：架构设计与消息路由实战

接手这个项目之前，我其实已经踩过不少“机器人对接”的坑。单独给飞书塞一个机器人webhook不难，难的是把多个各司其职的agent串起来，让它们在同一套体系里被调度、被路由、还能共享上下文。这次用openclaw这类多agent框架对接飞书机器人，整体跑下来最大的感受是：真正的复杂度不在“连上飞书”，而在“让多个agent在飞书背后协作时，消息怎么走、会话怎么认、任务怎么交出去”。这篇文章就把我从架构设计到落地排障的完整过程拆开讲，包括为什么这么选型、核心参数怎么配、现场踩了哪些坑，希望能给正在做类似“群聊里养多个AI助手”的同学省点时间。

1. 项目定位与整体架构设计

1.1 多agent对接飞书的本质是什么

很多人第一次听到“openclaw多agent对接飞书机器人”，第一反应是“这不就是写个webhook转发吗”。实际动手之后才会发现，单agent场景下，你只需要把飞书的消息原样丢给一个大模型，拿回结果再发出去就完事了。但多agent意味着飞书里的同一个群、同一个人发来的消息，要根据内容语义去匹配不同的agent来处理——有的agent负责查日程，有的负责跑数据分析，有的专门做知识问答，有的可能是个审批流机器人。这时候你需要的不再是一条简单的转发链路，而是一个带路由、带状态、带任务编排的消息处理中枢。

openclaw这类框架解决的正是这个链路中“多agent生命周期管理”的部分：每个agent注册成什么名字、有什么职责描述、能调用哪些工具、最多允许多轮对话、上下文窗口如何回收，这些东西如果自己从零写，工作量非常大。对接飞书则是把外部入口接进来：飞书群里收到的消息，推送到openclaw的路由层，路由层根据消息内容分发给对应的agent，agent处理完后把结果通过飞书API回传。整条链路的主角是“消息”，而飞书只是最外层的一层壳。

我做这个项目时，整体架构分成了四层，这里先说清楚每层干的事：

• 接入层：飞书的两个入口，自定义机器人和应用机器人。自定义机器人适合快速验证，应用机器人适合正式场景，后面第3章会展开讲。
• 适配层：把飞书事件回调里的各种消息格式，统一成openclaw内部的标准消息结构。这个层最容易被忽略，但多入口、多消息类型场景下不做统一，后面会乱到不可收拾。
• 调度层：openclaw内置的agent路由与任务分发。核心是配置每个agent的“身份说明”，让路由层能判断一条消息该给谁。
• 执行层：各个agent实际干活的部分，包括调用工具、查数据库、请求大模型等。

这个分层设计的好处是，任何一层替换都不影响其他层。比如今天用飞书，明天要接钉钉，只需要换掉接入层和适配层，调度和执行完全不用动。

1.2 为什么选openclaw而不是直接写路由代码

市面上多agent框架其实不少，但选openclaw作为对接飞书的中间层，我主要看中几个点。

第一，它自带语义路由。也就是每个agent有一个自然语言描述的“人设”，比如“你是负责处理日程相关任务的助手，你可以创建日程、查询日程、删除日程”。来了消息之后，openclaw会基于这条消息和所有agent的描述做相似度匹配，命中哪个就把消息交给哪个。这比自己在代码里写if-else关键词规则要灵活得多，也符合“多个agent在群里用自然语言协作”的真实场景。

第二，它保留了每个agent独立的会话状态。多agent系统的一个坑是，如果所有agent共享一套历史，很容易出现“日程机器人看到了数据分析机器人的对话，然后给出了奇怪的回答”。openclaw按agent维度维护各自的上下文，互不污染，这一点在我实际用下来非常关键。

第三，它本身不绑定任何特定IM平台。openclaw提供的是agent层的运行时能力，IM接入需要自己做适配。这就给了很大自由度，你可以自由选择飞书还是其他平台，且对接方式完全可控。

当然，openclaw的劣势也很明显：它的文档在“如何对接外部IM”这部分写得很简略，很多适配细节得自己从源码里翻，而且社区资料也少。但这反而适合我这种喜欢控制底层的场景——你需要真正理解消息在它内部是怎么流转的，出问题才不慌。

2. 核心机制拆解：agent注册、消息路由与会话保持

2.1 agent注册与“人设”配置的细节

openclaw启动时会读取一个配置文件，里面声明了当前系统里有哪些agent。每个agent的核心字段大概是下面这种结构：

yaml复制agents:
  - name: calendar_agent
    description: "负责日程相关的操作，包括创建日程、查询日程、删除日程、修改日程。当用户提到安排会议、看日程、约时间时使用。"
    model: gpt-4o-mini
    max_turns: 10
    temperature: 0.3
    tools:
      - calendar_create
      - calendar_query
      - calendar_delete
  - name: data_agent
    description: "负责数据分析任务，包括查询数据仓库、生成统计报表、解读数据趋势。当用户提到报表、统计、数据、图表时使用。"
    model: gpt-4o
    max_turns: 20
    temperature: 0.1
    tools:
      - data_query
      - data_visualize

这里最关键的字段就是description。很多人会随便写一两句话，结果路由准确率惨不忍睹。我的经验是，description要写成“功能说明+触发场景举例”的结构，让路由模型充分理解这个agent在什么情况下该被选中。比如“日程相关操作”和“当用户提到安排会议、看日程、约时间时使用”同时出现，命中率会明显提升。

另外max_turns这个参数也值得注意。它限制的是一个agent单次任务最多能进行多少轮内部对话，不是限制和用户的对话轮数。比如data_agent在跑一个数据分析任务时，可能需要先查数据、再生成图表、再写结论，每步都是一轮agent内部调用，如果max_turns设得不够，任务会中途断掉。我一开始把data_agent设为5，结果一查数据再画图就报“超过最大轮数”，后来调成20才稳定。

还有temperature。多agent场景下我建议把每个agent的temperature都调低，控制在0.1到0.3之间。因为agent之间协作时，稳定性比创造性重要，回答飘的agent会把整个任务链带跑偏。

2.2 消息路由是怎么工作的，为什么会出现“抢消息”

openclaw的消息路由流程大致是这样的：一条消息进来之后，框架会把消息内容与每个agent的description做一次语义匹配打分，然后选出得分最高的agent来响应。如果没有任何一个agent的得分超过阈值，就轮到默认agent（兜底agent）接管。

听起来很简单，但实际运行中会遇到两个典型问题。

第一个是“抢消息”。如果你同时有一个日程agent和一个任务管理agent，description都写了“当用户提到安排、计划、日程时使用”，那一条“帮我安排一下下周的日程”就可能被两个agent同时高分命中，路由结果不稳定，有时候给A，有时候给B。解决办法就是重新梳理description的边界，把“日程”和“任务”在描述里做明确区分，比如任务agent强调“待办事项、Todo List、任务清单、跟踪进度”，日程agent强调“时间、会议、日期、预约”。

第二个是“阈值问题”。openclaw如果所有agent的匹配分数都不高，会走默认agent。默认agent的设置也很讲究，它本质上是一个“万能助手”，所以description尽量写成“当其他agent都不适合时，回答用户的普通问题，包括闲聊、常识问答、翻译等”。如果没有正确的默认agent，一些普通问题会被硬塞给语义最接近但其实不合适的agent，产生奇怪的回答。我项目里踩过这个坑：用户问了一句“今天星期几”，结果被日程agent接住了，它绕了一大圈去查日历然后再回答，真实场景下用户只会觉得这个机器人反应很慢。

2.3 会话保持：多agent场景下如何认人、认会话

对接飞书后，会话保持是个很容易被忽略但必须处理的问题。想象这样一个场景：用户在群里@机器人问“帮我安排一个明天下午三点的会”，日程agent创建完会议之后，用户又追问一句“把我的待办也加一下”。这一句应该给谁？如果只按“当前群最近有对话”来关联，系统根本无法判断这个“加待办”是接着上一轮的日程任务，还是一个新的独立请求。

我在openclaw里处理会话保持的方式是引入了一个session_id的概念。每个从飞书来的消息，适配层会生成一个唯一的session_id，规则是：

• 单聊场景：直接用用户的open_id作为session_id。
• 群聊场景：用open_chat_id + "_" + sender_open_id作为session_id，也就是同一个群里不同的发言者，各自有独立的会话上下文。

这样做的好处是，群聊里两个不同的人同时和机器人聊天，不会互相串上下文。如果只按群维度做会话绑定，A问了数据分析的问题，B接着问“结果呢”，机器人会把B的问题当成A上一轮的延续，直接导致上下文错乱。

openclaw内部支持将同一个session_id下的多轮消息关联到同一个agent实例，这样就能做到“在同一个会话里，用户连续说的几句相关的话，被路由到同一个agent，且携带上下文”。如果你的openclaw版本不支持显式传session_id，那就要在适配层自己做会话映射表，把飞书会话映射到agent实例，再用一个内存或Redis缓存来存这个映射关系。

2.4 事件去重与幂等，这一层必须写

飞书的事件回调有个特点：它会做重试，也就是同一条事件可能被推送多次。尤其当你的回调接口响应超时或返回了非2xx状态码，飞书会按一定策略重新推送。如果不做去重，用户发一条“帮我查天气”，你的机器人可能收到两条一模一样的消息，然后回两条同样的回答，非常尴尬。

我在适配层加了一个简单的event_id去重机制。飞书每个事件都有唯一的event_id字段，我用Redis的SETNX来做幂等判断，处理成功的event_id会缓存24小时，重复事件直接丢弃：

python复制import redis
import hashlib

r = redis.Redis(host='localhost', port=6379, db=0)

def is_duplicate(event_id: str) -> bool:
    key = f"feishu:event:{hashlib.md5(event_id.encode()).hexdigest()}"
    if r.setnx(key, "1"):
        r.expire(key, 86400)
        return False
    return True

这个逻辑虽然简单，但能挡掉绝大多数重复推送的坑。还有一点，你回调接口处理完后一定要同步返回一个{"code": 0}给飞书，不然它会一直重试。

3. 飞书机器人对接实操：接入方式与配置全过程

3.1 两种接入方式怎么选：自定义机器人 vs 应用机器人

对接飞书机器人有两条路，先做个对比：

如果你只是想把openclaw里的agent结果推送到一个群里展示，自定义机器人足够。但我们现在要做的是“用户可以在飞书上和多个agent对话”，必须能接收消息，所以只能选应用机器人。我的建议是直接一步到位，如果项目需要交互，就不要再走自定义机器人绕一圈，最后还是要迁移。

应用机器人的整个配置链路涉及几个前置步骤。首先是创建应用，然后在“权限管理”里开通如下权限：

• im:message（读取与发送单聊、群聊消息）
• im:message.p2p（读取用户发给机器人的单聊消息）
• im:chat（读取群聊信息）
• im:resource（上传与读取图片、文件资源，如果需要发图片的话）

权限开通后要等管理员审核，然后发布应用版本，才能被搜索到、被添加到群聊里。这里有一个容易被卡住的点：应用默认是“仅自己可见”，也就是说只有开发者自己能用。要在测试群里多人使用，你得在“版本管理与发布”里创建一个正式版本并发布，或者至少创建“企业内可用版本”。第一次做的时候我在这里卡了很久，看着权限都配了，但别人就是搜不到这个机器人。

3.2 事件订阅的回调地址配置与验签

飞书应用机器人通过“事件订阅”来接收用户消息。核心配置项是“请求地址”，也就是你服务器的回调URL，飞书会把用户消息事件推送到这个URL。

回调地址必须是公网可访问的HTTPS地址，本地调试时可以先用内网穿透工具把本地端口暴露出去。推荐在本地调试阶段直接把回调地址指到穿透域名，省去频繁发版的痛苦。

飞书在推送事件时，会根据你在后台配置的“加密策略”决定是否对事件内容做加密，同时在请求头里带上签名。验签是必须做的，不是为了防攻击，而是防止别人往你回调地址伪造消息，造成agent被恶意调用。飞书最新的签名校验方式是X-Lark-Signature，用时间戳和加密密钥拼起来做HMAC-SHA256，对比请求头里的签名是否一致。下面是我用的验签代码：

python复制import hashlib
import hmac
import base64

def verify_signature(encrypted_key: str, timestamp: str, nonce: str, body: str, signature: str) -> bool:
    string_to_sign = f"{timestamp}{nonce}{encrypted_key}{body}"
    hmac_code = hmac.new(
        key=encrypted_key.encode("utf-8"),
        msg=string_to_sign.encode("utf-8"),
        digestmod=hashlib.sha256
    ).digest()
    expected = base64.b64encode(hmac_code).decode("utf-8")
    return hmac.compare_digest(expected, signature)

还要注意“加密策略”的开关状态。如果后台开启了加密，你收到的事件body是经过AES加密的密文，需要先用encrypt_key解密才能拿到明文事件。这一步很多教程都没写，我当时也是踩了坑：验签通过了但解析事件内容时全是乱码。

解密逻辑如下：

python复制from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
from cryptography.hazmat.primitives import padding
import base64
import json

def decrypt_event(encrypt_key: str, encrypt_data: str) -> dict:
    data = base64.b64decode(encrypt_data)
    iv = data[:16]
    ciphertext = data[16:]
    cipher = Cipher(algorithms.AES(encrypt_key.encode("utf-8")), modes.CBC(iv))
    decryptor = cipher.decryptor()
    padded = decryptor.update(ciphertext) + decryptor.finalize()
    unpadder = padding.PKCS7(128).unpicker()
    plaintext = unpadder.update(padded) + unpadder.finalize()
    return json.loads(plaintext)

采集事件内容之后，你会得到一个im.message.receive_v1事件，里面包含消息ID、消息类型（text/post/image等）、聊天类型（p2p/group）、发送者open_id、群聊open_chat_id等字段。这些字段就是适配层构造openclaw消息输入的关键。

3.3 发送消息的两种方式与频率限制

openclaw的agent处理完消息后，需要把结果发回飞书。发送消息有主动发送和被动回复两种方式，在我们这个场景里，因为agent是异步处理的，大概率要主动调用飞书API发消息。

先要获取tenant_access_token，这是企业自建应用的调用凭证，有效期两小时，需要缓存并定时刷新：

python复制import requests
import time

APP_ID = "your_app_id"
APP_SECRET = "your_app_secret"

def get_tenant_access_token():
    url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
    resp = requests.post(url, json={
        "app_id": APP_ID,
        "app_secret": APP_SECRET
    })
    data = resp.json()
    return data["tenant_access_token"]

def send_text_message(token, receive_id, content, receive_id_type="open_id"):
    url = "https://open.feishu.cn/open-apis/im/v1/messages"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json; charset=utf-8"
    }
    payload = {
        "receive_id": receive_id,
        "msg_type": "text",
        "content": json.dumps({"text": content})
    }
    params = {"receive_id_type": receive_id_type}
    resp = requests.post(url, headers=headers, params=params, json=payload)
    return resp.json()

实际使用中要注意频率限制。飞书API的默认限流是每条连接每秒最多10次请求，超了会被返回错误码99991400之类的限流提示。agent回复如果涉及很长的内容，或者多个agent同时回消息，很容易触发限流。我加了一个简单的队列和退避重试机制，限流时sleep 1秒再重试，实测能解决大部分问题。

还有一个容易忽略的点：如果你的agent回复内容很长，飞书单条消息有长度限制，text消息建议控制在15000字节以内，超过的话要主动截断或者分片发送。这一点在对接大模型输出时尤其常见，因为我用的是openclaw的agent流式输出，内容可能一下子冲得很长。

4. 端到端联动：从飞书消息到agent任务编排

4.1 整体的消息流转链路

把前面这些模块拼起来，一个完整的消息流转链路长这样：

1. 用户在飞书群里@机器人，发出一条消息。
2. 飞书把事件推送到你的回调地址。
3. 适配层做验签、解密、event_id去重。
4. 适配层将飞书事件标准化为openclaw消息格式，提取session_id、用户ID、消息文本。
5. openclaw路由层根据文本和agent description做匹配，选定目标agent。
6. agent执行任务，可能调用工具、请求模型、做多轮内部推理。
7. agent返回最终回复文本。
8. 适配层调用飞书API把文本发回对应的会话。
9. 如果agent在加工过程中状态有变化，比如任务中断、需要用户补充信息，也通过飞书消息与用户交互。

这个链路中，步骤5到7是openclaw内部处理的，其他步骤都需要你自己写适配代码。我在这里再补充一个建议：回调接口里不要同步等待agent处理完再返回，因为大模型推理经常要几秒甚至几十秒，飞书webhook的同步响应超时通常也就几秒，等不起。正确做法是回调接口收到消息后，先把消息丢进一个任务队列，立刻返回{"code": 0}给飞书，后台worker从队列里取消息，丢给openclaw处理，最后再把结果发到飞书。这样既不会让飞书重试，也不至于阻塞回调接口。

4.2 多agent任务编排的会话状态机

多agent场景特有的一项工作是处理“用户在一个会话里连续触发不同agent”的情况。比如用户先问数据分析agent要一份报表，然后紧接着在同一个会话里让日程agent安排会议。这时候两个agent是串行响应的，但它们的上下文是各自独立的。

openclaw通过session_id来区分会话。我们适配层传session_id给openclaw后，它在内部会识别为同一个会话的延续。但多agent场景下，session_id相同并不代表所有agent共享上下文，它只会让“同一次路由结果选中的agent”获得上下文延续。

我实际用下来觉得比较好的做法是：用户在群里的每次都当作一个“新请求”，但把上一轮选中的agent作为“当前激活agent”记录下来。当新的消息进来，先看它是否和上一轮处于同一主题，如果是，就直接路由给当前激活agent，不经过全量语义匹配；如果不是，就全量匹配并切换。

这个逻辑的意义在于省token和提升响应速度。全量语义匹配每次都把所有agent描述和消息一起发给路由模型，成本不低，而且如果消息比较短，比如“是的”“再来一个”，语义匹配基本是瞎猜。利用上一轮激活的agent做上下文承接，准确率会高很多。

会话状态机的简化伪代码如下：

python复制session_state = {}

def route_message(session_id, text):
    if session_id in session_state:
        last_agent = session_state[session_id]
        # 判断是否延续上一个话题：由openclaw语义判断
        if openclaw.is_same_topic(last_agent, text):
            return last_agent
    # 全量语义路由
    agent = openclaw.semantic_route(text)
    session_state[session_id] = agent
    return agent

这里sleep和is_same_topic是openclaw的已封装能力，不同版本API名可能不同，但思路一致。这个状态机提升了整体体验，也让多个agent之间“接力干活”成为可能。

4.3 让openclaw具备“主动发消息”能力

飞书场景中有一个很实用的能力：让agent不只是被动回复，还能主动在某个时间点推送消息。比如你有一个日程agent，每天早晨9点把当天的会议安排推到群里；或者有一个监控agent，检测到异常时自动发告警。

openclaw本身不负责定时调度，所以我额外写了一个scheduler模块，用APScheduler做定时任务，每天触发时找到对应的agent，把当前任务文本丢进队列，让agent生成内容后推送到飞书：

python复制from apscheduler.schedulers.blocking import BlockingScheduler
from apscheduler.triggers.cron import CronTrigger

scheduler = BlockingScheduler()

def daily_report_job():
    queue.put({
        "session_id": "system_daily_report",
        "agent": "data_agent",
        "text": "请生成昨天的业务数据日报，包含订单量、销售额、退款率。"
    })

scheduler.add_job(daily_report_job, CronTrigger(hour=9, minute=0))
scheduler.start()

这个扩展很重要，因为它让飞书机器人从“你问我答”升级成了“主动服务的数字员工”。

5. 常见问题排查与避坑指南

5.1 路由不准、抢消息，问题出在配置和描述

多agent系统里最让人头疼的就是路由不准。我遇到过三种典型情况：

第一种是agent之间的description有重叠，导致一条消息被两个agent高分命中。解决办法前面讲过，把职责边界拆清楚，在description里增加触发场景的负例，比如“当用户提到XX时，不应该使用本agent”。

第二种是description写得太短。Agent描述只有一句话“你可以处理日程”，路由模型根本学不到触发场景。我后来总结出的写法模板是：功能定位+典型行为+触发关键词+不处理什么。比如：

负责日程相关操作，包括创建、查询、修改、删除日程。当用户提到会议、日程、安排时间、约日期时使用。不负责待办任务、不负责提醒类事项。

这样一个description下来，路由命中率明显提升，基本不会和别的agent抢。

第三种是兜底agent缺失或不正确。没有兜底agent时，低分消息会被强塞给分数最高的agent，答非所问。设置一个明确的默认agent之后，普通问题会走正常对话，多agent系统才真正稳定下来。

5.2 消息发不出、回调不触发，先查这四处

我总结了飞书对接最常见的几个外部问题，基本就是这四个地方：

1. 权限没配对。有些权限虽然开通了，但版本没有发布，实际不生效。特别是im:message.p2p这种单聊权限，要确认在“权限管理”里已经开通并发布。
2. 回调地址没走通。飞书在后台“事件订阅”里有个“调试”按钮，可以模拟推送一条测试事件，如果回调地址配置有问题，点调试就能看到错误信息。开发阶段务必先用这个功能验证回调连通性。
3. 事件没订阅。后台“事件订阅”里要添加im.message.receive_v1事件，否则用户消息根本不会推送过来。别笑，这个我亲眼见过有人配了回调地址却忘了订阅事件，结果怎么发消息都没反应。
4. 加密开关状态不一致。如果你后台开启了加密，代码里却用明文解析，那必然出错。

整理成一张速查表：

5.3 openclaw侧的几个隐藏坑

再讲几个openclaw实际使用中的坑，这些搞不定会非常折磨人。

第一，agent内部工具调用的超时时间要设置合理。默认的超时时间可能只有30秒，但agent涉及到联网请求或者大数据量查询时，很容易超过。我在配置里把工具超时调到了120秒，数据agent甚至调到300秒。

第二，多个agent并发执行时，要留意底层的并发和线程池限制。如果同一秒内来了10条消息，分别路由给10次agent调用，底层API的并发限制可能会把请求打爆。我在worker里加了并发控制，同一时刻最多只跑3个agent任务，超过的排队等。

第三，agent的上下文窗口是有限的，聊多了老对话会被截断。这在飞书群聊场景非常常见，一个活跃的群里用户一整天都在和机器人对话。建议在适配层加一个上下文长度控制，当超过一定量的时候自动清空该session的上下文，或者用summary的方式压缩历史。

第四，日志一定要加步骤串联。openclaw内部处理、飞书API发送、队列消费，分别打日志时要把消息ID串联起来。遇到问题才能从飞书事件ID一路追到最终发送结果，不然出了问题你连是路由错了还是发送失败都分不清楚。

6. 上线运行与资源规划，稳比快重要

6.1 一套相对成熟的上线部署方案

整个系统跑稳定之后，我采用了这套部署方案：

• 回调服务：Nginx + uWSGI跑一个Flask应用，负责接收飞书事件、验签、去重、入队。
• 任务队列：Redis + RQ，队列里存标准化的消息任务，worker从队列消费。
• worker处理服务：消费队列里的消息，调用openclaw的agent能力，拿到结果后调用飞书API回复。
• openclaw运行时：独立进程，承载agent注册、路由、上下文管理。
• Redis：同时承担event_id去重、session_state映射、pending消息缓存。

这个架构单机就能跑起来，我在一台4核8G的服务器上实测，支撑了大概几十个活跃用户和一批定时任务，CPU和内存都还算稳。如果后续用户量上去，优先要扩展的是worker数量，其次是给Redis加持久化，避免重启丢状态。

另外建议把openclaw的agent上下文做成可持久化的。默认情况下agent重启后上下文会清空，飞书用户如果前一天还在聊，第二天再发消息，agent完全不记得。我在Redis里按session_id存了每个agent的历史摘要，重启后重新灌回去，对用户体验有非常大的改善。

6.2 监控与日志，最小但必须做的一套

这个系统一般不会挂得很夸张，但容易“带病运行”很久而不自知。比如某天飞书限流了，worker在疯狂重试，表面上看用户消息没回但系统没报错，直到有人来问才知道。所以我至少做了两块：

• 关键指标计数：每收到一条飞书事件、每路由到一个agent、每成功发送一条消息、每失败一次，都打点计数。用简单的Prometheus暴露出来，或者哪怕用日志文件定期看也行。
• 超时告警：如果一条消息从入队到发出去超过2分钟，说明链路有阻塞，就把这条消息的ID打到错误日志里。我用的方式是每天定时扫一遍日志，发现有超时记录就人工排查。

这套东西很轻，但能让你在用户吐槽之前先发现问题。

写在最后的一点体会

这个项目从最开始“接入一个机器人”，到最后变成“在飞书里养了一组协作的数字员工”，中间改了很多轮架构，也踩了不少坑。我最大的体会是：多agent系统集成到IM平台，真正的难点一直不在“能不能通”，而在“通了之后稳不稳、准不准、乱不乱”。把路由描述写好、会话状态管好、异步链路做好、去重幂等加好，这四件事做到位，系统基本就能稳定运转了。

最后再分享一个小技巧：飞书机器人回调的本地调试，一定要用事件订阅里的调试工具先把链路验证通了再继续往下做。很多人一上来就直接在群里试，出问题都不知道是飞书问题还是openclaw问题。先把两端分别验证好，再接起来，这是最快的路径。