OpenClaw+飞书多智能体实战：架构、调度与群聊机器人落地

1. 为什么选择“OpenClaw + 飞书 + 多智能体”这个组合

说句实在话，刚拿到 OpenClaw 这套工具链的时候，我第一反应是“又一个套壳框架”。但真正跑起来之后，我发现它对智能体的编排方式和飞书开放平台的契合度，确实比我预想中要顺滑不少。如果你手头正好有团队协作的需求，又不想把智能体局限在命令行里自嗨，那这个组合值得认真试一试。

先聊清楚这三个东西分别解决什么问题。

OpenClaw 是一套开源智能体运行框架，核心能力是让智能体具备“感知—决策—行动”的闭环。它可以把大模型、工具调用、记忆存储、定时任务这些要素组装成一个可运行的服务进程。打个比方，它像是一台没有外壳的机器人，你给它接上眼睛（API）、手脚（工具脚本），再给它一个大脑（大模型），它就能自己跑起来干活。

飞书这边，看中的是它的“群聊即入口”特性。绝大多数团队已经习惯了在飞书群里讨论工作、同步进度、发通知。把智能体接进飞书群，等于让机器人直接住进了你同事们的日常对话流里。用户不用学新工具，只要在群里@机器人发需求就行，这个体验门槛比单独开一个 Web 后台要低太多。

多智能体则是解决“一个智能体什么都干，但什么都干不精”的问题。我在早期测试阶段试过把所有任务塞给一个 Agent，结果是——它既要处理会议纪要、又要写周报、还要回答技术问答，上下文一长就开始串逻辑，回答质量肉眼可见地下降。拆成多个专职智能体之后，各自维护独立的上下文和工具集，配合一个调度中枢来分发请求，整体效果明显稳定得多。

所以这套组合的核心思路可以总结成一句话：用 OpenClaw 做智能体的运行时底座，用飞书群做交互入口，用多智能体架构做职责拆分。适合的场景包括但不限于：团队内部的知识问答机器人、自动化周报汇总助手、会议纪要与待办提取工具、定时巡检并推送通知的监控助手。

如果你是第一次接触智能体应用开发，或者已经在用单一智能体但觉得能力不够用，这篇文章应该能帮你把配置思路和踩坑点都理清。

2. 整体架构设计与智能体职责拆分

2.1 一个中心调度器 + 多个专职 Worker

我最终定下来的架构是三层的：入口层、调度层、执行层。

• 入口层：飞书机器人接收用户消息，把事件通过长连接推送给本地服务。
• 调度层：一个中心调度智能体，负责理解用户意图，决定把任务路由给哪个专职智能体。
• 执行层：多个 Worker 智能体，各自拥有独立的系统提示词、工具集和会话记忆。

这个设计的出发点是：让“听懂需求”和“干活”分离。调度器只做意图识别和任务分配，不需要具备具体业务知识；Worker 只在收到分派任务时被激活，不会因为其他群里的消息而被污染上下文。

举个例子，我在群里发一条“整理一下本周的客户反馈并提炼出三条改进建议”，调度器会先判断这条消息属于“分析归纳类”任务，于是把它路由给“数据分析 Worker”。如果发的是“提醒大家明天下午三点前提交报销单”，则会被路由给“行政助理 Worker”，它调起定时提醒工具，向指定群发送一条带有提醒卡片的消息。

这种一套调度、多个 Worker 的架构有个明显的好处：扩展新能力时，不需要改动调度器逻辑。比如我想加一个“代码审查助手”，只需要新起一个 Worker，然后在调度器的路由表里加一条匹配规则。整个过程不需要重新发布主服务，也不需要重启飞书应用，成本非常低。

2.2 智能体职责划分表：谁该干什么

我把常用的智能体划分方式整理成了一个表格，大家可以直接照抄这个思路来设计自己的 Worker 矩阵。这里把每个 Worker 的核心职责和对应工具写清楚。

这个表不是死的。实际配置时，如果你团队规模小，可以先砍掉不常用的 Worker，只保留“纪要助手 + 数据看板 + 行政助理”三个；等用顺手了再逐步加。

我特别想强调一点：每个 Worker 的知识边界一定要写死在系统提示词里。比如技术问答 Worker 的提示词里明确写了“只能回答与内部系统、代码库、部署文档相关的问题，其他问题一律拒绝回答并引导用户@调度器”，这样就不会出现机器人被群里闲聊带偏、一本正经胡说八道的情况。

2.3 为什么不用“单一通用智能体”方案

我知道很多人会问：为什么非要拆成多个智能体？用一个超级智能体，什么工具都配上，不是更省事吗？

说下我的实测结果。单一智能体方案在一开始看起来确实很美好——所有任务丢给同一个 Agent 处理，它自己判断该调什么工具。但跑了两周之后，出现了三个让人头疼的问题：

第一，上下文污染。群里消息五花八门，闲聊、求助、@提醒混在一起。单一智能体的记忆机制会尽量保留最近的对话，但它在整理会议纪要时，可能会把几小时前别人在群里开的玩笑当成有效输入，导致纪要不专业。

第二，工具冲突。给一个 Agent 挂太多工具，它有时会选错。比如数据看板需要调 CRM 接口，而行政助理调的是日历接口，两者返回的数据结构完全不同，单一 Agent 在切换工具时偶尔会出现“把日历数据当成业务数据做聚合”的乌龙。

第三，提示词膨胀后失焦。为了让一个 Agent 覆盖所有场景，你只能把系统提示词越写越长，最后它反而记不住重点是啥。拆分成多个 Worker 之后，每个 Worker 的提示词可以控制在 500 字以内，专注一个领域，效果反而更可控。

基于这些实际教训，我最终选择了多智能体这套方案。虽然它需要多维护几个进程和配置，但稳定性换回来了，值得。

3. 环境准备与飞书开放平台配置

3.1 基础依赖安装与项目初始化

先讲环境准备。我用的是一台常规的 Linux 服务器，2C4G 配置就够跑三个 Worker 加一个调度器了。如果你只是本地开发调试，MacBook 也完全没问题。

服务端核心依赖如下：

# 安装 Python 3.10+ 环境 sudo apt update && sudo apt install -y python3.10 python3.10-venv # 创建虚拟环境 python3.10 -m venv openclaw_env source openclaw_env/bin/activate # 安装 OpenClaw 框架 pip install openclaw # 安装飞书 SDK 与异步 HTTP 框架 pip install lark-oapi fastapi uvicorn

这里插一句，为什么需要 FastAPI？因为 OpenClaw 本身是一个运行时进程，它需要接收飞书那边推送过来的事件消息。FastAPI 用来起一个轻量 Web 服务，统一接收飞书事件回调、Webhook 推送，然后转交给 OpenClaw 的调度器处理。也就是说，FastAPI 在这里承担的是“网关层”职责。

安装完成之后，初始化一个项目目录：

mkdir openclaw-feishu && cd openclaw-feishu openclaw init --template multi-agent

multi-agent模板会自动生成一个多智能体的配置文件骨架，包含agents/目录、config.yaml、tools/目录。这个模板帮我省了不少事，不用手动从零搭配置结构。

3.2 飞书开放平台：创建应用、配置权限与事件订阅

这部分是整个配置流程中最容易被卡住的地方，我尽量把每一步踩过的坑都标清楚。

第一步，打开飞书开放平台，创建一个企业自建应用。应用类型选择“企业自建应用”。

第二步，配置权限。需要在“权限管理”里开通以下几项（推荐直接搜中文关键词）：

• 读取用户发来的群消息（im:message相关权限）
• 读取群信息、获取群成员列表（im:chat相关权限）
• 发送消息（im:message:send_as_bot）
• 上传图片、文件（如果需要机器人发附件或卡片）
• 事件订阅（event:im.message.receive_v1）

这里有个新手极易踩的坑——权限申请之后需要创建版本并发布。有一回我改完权限，以为立刻生效，结果机器人一直收不到消息事件，后台排查了半天，才发现是发布版本那一步没做。

第三步，配置事件订阅。在“事件与回调”页面里，添加事件接收消息 im.message.receive_v1。回调地址就填我前面提到的 FastAPI 服务的地址，比如https://你的域名/openclaw/event。

不过要提醒一句，飞书要求回调地址必须通过验签。如果你没有配置公网 HTTPS 域名，开发阶段可以先开启“长连接模式”，SDK 会主动和飞书服务器建立长连接，不需要暴露公网 IP。我当时测试阶段就是先用的长连接模式，部署到正式服务器后才切换到 Webhook 模式。这个切换很关键，能省略很多开发期配证书、配域名的麻烦。

第四步，拿到 App ID 和 App Secret。这两个凭证是后续 OpenClaw 连接飞书的核心凭据。在“凭证与基础信息”页面可以看到。把这两个值写到 OpenClaw 的配置里就完成了飞书侧的大部分工作。

3.3 OpenClaw 飞书适配器配置方法

OpenClaw 支持通过适配器（Adapter）连接不同即时通讯平台。飞书适配器在config.yaml中的配置大概长这样：

platform: adapter: feishu app_id: "cli_xxxxx" app_secret: "xxxxx" event_mode: websocket # 开发阶段用 websocket，生产环境切换为 webhook encrypt_key: "" # 如果开启加密，填 Encrypt Key verification_token: "" # 旧版事件订阅可用，新应用一般用签名校验

有几个配置项要特别说清楚：

event_mode决定事件的接收方式。websocket适合本地调试，不需要公网地址；webhook适合生产环境，用之前必须把回调域名配好并完成 HTTPS 证书部署。

encrypt_key和verification_token在“事件订阅”页面可以获取。新版的飞书应用主要用签名校验（即把 App Secret 和请求参数做 HMAC 计算验证），但如果你的应用开启了事件加密，就必须配置 Encrypt Key，否则收到的推送是密文，框架没法自动解。

配置写完以后，启动 OpenClaw 验证一下：

openclaw start --config config.yaml

正常情况下日志里会出现feishu adapter connected字样。然后你可以去飞书群里 @机器人发一句“你好”，看机器人是否回复。这一步通了，说明飞书和 OpenClaw 之间的链路已经打通了，后面就可以开始配置多智能体了。

4. 多智能体配置与工具调用实现

4.1 Worker 的配置编写示例

接下来是重头戏：配置具体的智能体。在agents/目录下，每个 Worker 对应一个 YAML 文件。我拿“纪要助手”举例，它的配置是这样的：

agent: name: meeting_minutes desc: 负责会议音频转录、纪要生成和待办提取 model: provider: openai_compatible api_base: "http://你的大模型服务地址/v1" api_key: "sk-xxx" model_name: "your-model-name" system_prompt: | 你是一个专业的会议纪要助手。你只处理会议相关的任务。 当收到音频文件或转写文本时，你需要： 1. 提取发言人和核心观点 2. 生成结构化会议纪要（议题、结论、待办事项） 3. 对模糊信息主动提问，不要臆测 如果你收到的消息与会议无关，请礼貌告知用户只处理会议相关内容。 tools: - audio_transcriber - todo_extractor memory: type: buffer max_messages: 30

这里有三个细节值得展开。

system_prompt我要求它明确写清楚“边界意识”。与其让模型自己猜什么时候该管、什么时候不该管，不如直接告诉它“你只管会议”。边界越清晰，误判率越低。

tools字段需要指定工具名称，而这些工具本身是在tools/目录下定义的。比如audio_transcriber的脚本负责调用第三方语音转文字接口，把返回文本交给模型处理。

memory.type选择buffer，意思是只保留最近 30 条消息作为上下文。会议纪要这种任务本身是短会话性的，不需要跨月记忆，保留太多反而拖慢响应速度。

4.2 调度器的路由匹配逻辑配置

调度器是整个多智能体架构里最关键的一环。它的配置重点在于路由规则。参考代码如下：

agent: name: dispatcher desc: 统一入口，识别意图并分发任务 model: provider: openai_compatible api_base: "http://你的大模型服务地址/v1" api_key: "sk-xxx" model_name: "your-model-name" router: enabled: true rules: - match: ["会议", "纪要", "录音", "音频", "待办"] target: meeting_minutes - match: ["周报", "数据", "指标", "统计", "图表"] target: data_dashboard - match: ["提醒", "日程", "公告", "报销"] target: admin_assistant - match: ["文档", "代码", "排错", "怎么用"] target: tech_qa fallback: "tech_qa"

路由规则的写法是关键词匹配。调度器接收消息后，先判断是否包含规则中列出的词，然后定向分发给对应的 Worker。

不过纯关键词匹配有个缺陷：用户表达太模糊时容易误判。比如“帮我看一下上周的数据”这个请求里没有“周报”，但明显应该是数据相关。为了解决这个问题，我会再加一层模型化路由判断——把原始消息、所有 Worker 的描述和路由规则一起丢给大模型，让它额外给一个意图分类结果。两条结果合并，优先采纳模型分类，只有当模型也无法判断时才走关键词路由兜底。

这个改动看似简单，但对准确率的提升是立竿见影的。我把误判率从大约 20% 降到了 5% 以内。

4.3 自定义工具脚本的接入方法

聊完路由，说说工具接入。OpenClaw 的一个特性是支持写任意 Python 脚本作为“工具”，只需要暴露一个统一的函数签名即可。拿todo_extractor举例：

import re def todo_extractor(text: str, **kwargs) -> dict: pattern = r"(?P<todo>待办|计划|必须|需要)[:：]?\s*(?P<content>.*)" items = [] for line in text.splitlines(): m = re.search(pattern, line) if m: items.append({ "type": m.group("todo"), "content": m.group("content").strip(), }) return {"todos": items}

这里逻辑非常简单，实际生产环境你可以换成调用大模型做结构化抽取，效果更好。但原理是相通的：每个工具本质上就是一个输入输出函数。

还有一点值得注意：工具命名和描述要写得非常直白，因为它要被大模型“理解并选择”。比如不要写成def f1(text)，要写成def todo_extractor(text)并添加 docstring。否则大模型根本不知道该在什么场景下调它。

4.4 模型服务选型的现实考量

我在这里加一节，是因为模型选型直接决定了最终回答质量，而很多人一开始会忽略。

OpenClaw 支持openai_compatible、anthropic、gemini等多种接口协议。我的选择标准是：不同 Worker 用不同精度的模型，而不是全家桶统一用一个模型。

调度器，因为只做意图分类和路由，响应速度要快，可以用一个中等体量模型，成本低、延迟低。

纪要助手和数据 Worker，因为要生成结构化内容、分析文本，必须用当前能力最强的模型。这类 Worker 的调用频率相对低，成本压力不大。

行政助理这个 Worker，多数时候只是触发提醒、发卡片消息，用最便宜的模型就行，能省不少 token 就省。

这一套“按需分配”模式，同样的任务量，成本大约能降 40%。如果你的项目要长期运行，这是一笔不可忽略的账。

5. 实操过程：飞书多智能体从启动到跑通全流程

5.1 启动顺序与日志检查清单

配置全部写好之后，启动顺序很重要。我的建议是“从依赖到服务”：

1. 先启动大模型接口服务（如果是自建模型服务，确保端口可达）
2. 再启动 OpenClaw 主服务
3. 最后查看日志确认各模块状态

启动命令：

openclaw start --config config.yaml --log-level debug

日志中需要重点确认以下内容：

[INFO] Adapter [feishu] connected [INFO] Agent [dispatcher] loaded [INFO] Agent [meeting_minutes] loaded [INFO] Agent [data_dashboard] loaded [INFO] Tool [audio_transcriber] registered [INFO] Tool [todo_extractor] registered [INFO] Router rules loaded: 4

这几行日志分别对应了：飞书适配器是否在线、各智能体是否加载成功、工具是否注册成功、路由规则是否生效。如果哪一行缺失，直接按对应模块去查，不要盲目重启。

5.2 飞书群内联调：发布会话与工具调用链路

启动成功之后，去飞书群里做一轮完整联调。我建议按以下清单逐条测试：

• 基础消息应答：发“你好”，机器人应回复欢迎语。
• 调度分发测试：发“帮我记一下明天上午 10 点和设计团队开会，待办是确定首页改版方案”，这条消息应被调度器识别为会议待办内容，路由给纪要助手，并由相关工具解析出待办。
• 工具调用测试：上传一段录音文件，看调度器能否识别并转给纪要助手，纪要助手能否正确转写并生成纪要。
• 路由兜底测试：发“Hello”这种无关消息，看是否会走 fallback 路由。

测试时一定要开 Debug 日志。你可以直接看到每条消息在调度器内部走的完整链路：消息进来 → 意图分类 → 命中路由规则 → 进入 Worker → 调工具 → 生成回复 → 发回飞书群。这个链路只要走通一次，后面基本就顺畅了。

5.3 分组配置与消息卡片推送模板

很多团队有多个群，不同群的智能体权限不一样。比如“全员群”只需要行政助理发公告，“研发群”才需要技术问答 Worker。OpenClaw 里可以通过scope字段控制：

agent: name: tech_qa scope: chats: - "oc_xxx研发群" - "oc_yyy后端群"

这个配置的意义在于：技术问答 Worker 只处理指定群的请求，其他群的用户 @它时，它会自动拒绝并告知仅限特定群使用。这能有效避免智能体被跨群滥用。

另外，飞书消息卡片模板值得单独说一下。普通文本回复在群里很容易被刷掉，但卡片消息可以做到结构化展示。比如纪要助手生成待办时，可以返回以下格式：

{ "msg_type": "interactive", "card": { "header": {"title": {"tag": "plain_text", "content": "会议纪要 - 2025-06-12"}}, "elements": [ {"tag": "div", "text": {"tag": "lark_md", "content": "**议题：** 首页改版方案评审"}}, {"tag": "div", "text": {"tag": "lark_md", "content": "**待办：**\n- 张三：输出视觉稿，周三前提交\n- 李四：更新交互说明文档，周二前完成"}} ] } }

把这个 JSON 作为工具返回值，OpenClaw 收到之后会原样发往飞书并渲染成卡片。效果比纯文本好太多，用户的阅读成本直接下降一个量级。我建议所有 Worker 的输出结构都优先设计成“文字摘要 + 卡片详情”的组合。

6. 常见问题与排查技巧实录

6.1 机器人收不到消息的排查路径

这是所有问题里最高频的一个。收到“机器人不回消息”的反馈时，按顺序排查：

第一，检查事件订阅是否生效。去飞书开放平台对应应用的事件列表里，看接收消息事件状态是否已启用。

第二，检查回调日志。如果是 Webhook 模式，看 FastAPI 服务是否收到了 POST 请求。如果请求根本没进来，那就是回调地址配置或防火墙问题。

第三，检查权限范围。有些权限是“仅应用所在群”生效，如果机器人还没被拉进群，自然收不到消息。确保机器人已被添加到目标群聊。

第四，检查消息事件里是否过滤了机器人自己发的消息。飞书事件推送会包含机器人自己的消息，需要在代码里判断sender_type是否为bot，是就直接丢弃，否则会出现机器人自己和自己对话的死循环。这个坑很隐蔽，我当时调试时日志刷了满屏才定位到。

6.2 多智能体串线、上下文错乱的修复方法

多智能体架构跑一段时间后，偶尔会出现“串线”——明明应该路由给纪要助手的内容，却被技术问答 Worker 抢答了。这个问题的根源多半在调度器：

一是路由规则太宽泛。比如匹配到“怎么用”三个字就全给技术问答，但“这个录音怎么用”明明应该是纪要助手处理的。解决办法是把规则改成组合匹配，至少命中两个关键词才触发。

二是 Worker 的系统提示词边界不清晰。如果技术问答 Worker 的提示词里没有写“拒绝非技术类问题”，那么一旦消息被分发过来，它就会硬着头皮回答。我给每个 Worker 都补上了“收到非本领域任务时，必须拒绝并提示用户重新@调度器”的指令，串线率显著下降。

三是会话记忆串号。OpenClaw 的默认 buffer 记忆是按 Agent 实例隔离的，但如果你在配置中不小心把memory_id设成了同一个值，所有 Worker 就会共享上下文。检查agents/*.yaml，确保memory_id是各自独立的。

6.3 延迟高、响应慢的优化建议

如果机器人的响应时间很长，尤其是从发消息到收到回复超过 10 秒，基本可以确定是链路中的某一环拖慢了速度。

首要嫌疑是大模型接口侧的响应速度。当前模型推理速度通常较慢，如果你用的是高端大模型，接口延迟可能在 5 秒左右起步。减负方案之一是给调度器单独配一个快模型，让路由分类在 1 秒内完成，任务落到 Worker 之后再用慢但强的模型去生成答案，这样整体感知延迟会小不少。

第二个嫌疑是长文本输入。飞书群里如果贴了一大段文档或代码，整个链路处理时间会显著上升。可以考虑在工具层做预处理，超出长度阈值时先做截断或摘要，再进入 Worker。

第三个嫌疑是工具链串行调用。如果纪要助手的流程是“下载音频 → 转写 → 生成纪要 → 提取待办”，每一步都串行执行，累积时间非常可观。优化方式是把可以并行的步骤拆出来，比如生成纪要和提取待办可以在转写完成之后同时进行。

6.4 测试用例表：上线前自测清单

最后整理一份我每次变更配置后都会执行的测试用例表，供你上线前快速自查：

P0 用例没有通过就不能上线，P1 用例要求上线前必须修复，P2 用例可以列入后续迭代。

7. 复盘与后续可扩展方向

这套 OpenClaw 飞书多智能体系统从配置完成到现在，已经稳定跑了一段时间。整体稳定性比我预想的好，但让我感受最深的一点是：智能体的能力上限不取决于模型，而取决于你给它配的工具和工作流设计。同样的大模型，单纯聊天和接上工具链之后产生的效果差距非常大。

运行过程中也踩过几个让我印象深刻的坑。比如飞书 Webhook 模式下的签名验证，曾经因为服务器和飞书服务器的时间偏差超过 5 分钟导致所有回调都被拒绝，后来通过同步 NTP 解决。再比如调度器把一条消息错误路由给了两个 Worker，两个 Worker 同时回复，群里出现两条互相矛盾的回答。后来我在调度器里加了“每消息仅分发一次”的标志位，才彻底杜绝了这个问题。

关于后续扩展，有两条路径我认为值得投入。

一条是给现有 Worker 增加记忆持久化能力。当前设计里每个 Worker 只保留短期会话记忆，跨天查询历史记录还需要外部存储。下一步可以给 OpenClaw 配一个向量数据库，把会议纪要、问答记录、决策过程全部写入索引，之后就能直接问机器人“两个月前的版本上线讨论结论是什么”。

另一条是加入定时触发任务，让智能体从“被动响应”变成“主动服务”。比如每周五下午自动拉取本周数据生成周报草稿，推送到指定群。这个功能配合 OpenClaw 的定时器机制可以零成本实现，但价值却非常大，因为它把智能体从一个问答工具升级成了团队的自动化协作者。

最后再分享一个小技巧：所有 OpenAI 兼容接口都可以在 OpenClaw 中以同一套配置方式接入，所以如果你需要同时使用多个模型服务（比如国内模型 + 开源模型），完全可以在不同 Worker 的配置里分别指定，互不干扰。这也算是这套框架对多智能体场景比较友好的一点吧。