去年我们内部铺了一套知识库问答助手，PC网页端跑得挺顺，但同事们一天里真正坐在电脑前打开后台的时间其实很少，大部分工作沟通都泡在飞书里。为了问一个问题专门切到网页，使用率很快就跌到三成以下。后来我们把同一个AI助手接进飞书，形态从“打开网页陪聊”变成“在群聊里@一下就有回应”，日均调用量翻了近十倍。这个变化背后，接入通道的工程量比想象要琐碎得多。这篇文章就整理一下我们用OpenClaw这个开源助手网关把AI助手接进飞书的完整过程，覆盖开放平台配置、通道参数、会话处理、群聊交互和联调排错，希望能帮你少走几个弯路。

1. 接入前先搞明白：飞书机器人的消息到底是怎么流回来的

1.1 两种消息通道模式，差别比你想的大

飞书开放平台给机器人提供了两条接收消息的路：事件回调模式和长连接模式。很多第一次接入的人容易忽略它们的区别，等配置做到一半才发现选错了，返工成本不低。

回调模式就是飞书把用户发给机器人的消息封装成事件，POST到你在服务器上配置的一个公网URL上。你的服务收到事件后，处理后调用飞书的“发送消息”API把回复发回去。这个模式历史最久，资料最多，但它有两个硬性要求：一是你必须有一个公网可访问的HTTPS地址，二是这个地址的稳定性直接决定机器人的可用性，一旦网络波动或者域名证书过期，飞书后台就会疯狂报回调失败。

长连接模式则是机器人服务主动和飞书服务器建立一条常驻连接，飞书有新事件就通过这条连接推给你。它不需要公网回调地址，也不存在公网暴露的问题，对部署在内网的AI服务尤其友好。我们最终选择的就是长连接模式，原因后面会细说。

下面这张表格是我当时做选型时的对照，可以直接参考：

1.2 一条消息从发出到回复，完整链路里有四个角色

很多教程上来就让你配这配那，但没讲清楚消息到底经历了什么。我习惯先把链路画出来，心里有全景图，配置才不会乱。

整条链路上有四个角色：飞书客户端（用户发消息的地方）、飞书开放平台（事件分发中心）、OpenClaw（我们引入的助手网关），以及后端AI服务（真正干活的大模型或者知识库检索）。

用户在飞书里给机器人发了一条私聊消息，或者在一个群里@了机器人，飞书客户端先把这条消息送到开放平台，开放平台判断这个应用订阅了哪些事件，然后把事件推送给OpenClaw。OpenClaw收到事件后做校验、去重、解析，提取出用户真正想问的文本，再调用后端的AI接口。AI把答案返回给OpenClaw，OpenClaw再把答案包装成飞书消息API需要的格式调用发送接口，最终用户在飞书里看到回复。

这里有一个容易被忽略的点：事件推送不等于消息发送。接收事件和发送消息在飞书开放平台里是两个独立的能力，需要分别开通权限。很多人明明配好了事件订阅，却发现机器人不会回复，就是因为只加了接收消息的权限，却没在应用权限里开启“发送消息”的能力。

2. 为什么中间要加一个OpenClaw，而不是直接在飞书里写死

2.1 直接在飞书机器人里写业务逻辑，很快会失控

如果你的AI助手只是“收到文本->调用OpenAI接口->发回文本”，那确实不需要额外的网关层，直接在飞书云函数里写几十行代码就能跑。但现实中的AI助手很少这么简单。

我们内部助手背后挂了三套东西：一套私有知识库用于技术文档问答，一套工单系统用于问题转派，还有一套自研的Agent流程负责多轮任务拆解。这些服务分别部署在不同的内网机器上，认证方式各不相同，调用逻辑也是一两个月一变。如果把这些逻辑全部耦合在飞书机器人代码里，每一次业务调整都要改机器人应用、重新发布，联调成本会迅速吞掉收益。

OpenClaw在这里的价值是当消息网关：飞书只是众多消息渠道之一，而OpenClaw把“渠道适配”和“AI业务逻辑”拆开了。飞书发来的消息先被OpenClaw统一标准化成一个消息对象，然后路由到对应的AI配置和工具链上，处理结果再由OpenClaw翻译回飞书的消息格式。渠道侧的复杂性被锁在适配器里，业务侧只需要面向标准消息对象工作。

2.2 OpenClaw在体系里到底承担了哪些职责

从功能上看，OpenClaw主要干了四件事。

第一是事件接入与校验。它负责和飞书建立连接，接收事件，校验签名，处理重试，这些脏活累活不用业务代码关心。第二是消息标准化。私聊、群聊、@消息、系统消息，OpenClaw会把它们统一转换成带有会话ID、发送者ID、文本内容、消息类型等字段的标准结构。第三是智能体路由。根据消息来自哪个群、哪个用户、包含哪些关键词，转发给不同的AI配置，比如产品群走产品知识库，运维群走排障知识库。第四是回复发送与失败重试。调用飞书消息API发送结果，失败时按策略重试，超时时做降级处理。

2.3 部署位置直接决定了接入方案的选型

OpenClaw本身是一个可以独立部署的服务，放在哪里取决于你后端AI服务的位置。

如果AI服务部署在云上，OpenClaw放在同一朵云里最省事，内网调用延迟低。如果AI服务部署在公司内网，比如要读内部知识库、访问内部工单系统，那OpenClaw最好也部署在内网，并且使用长连接模式和飞书通信。因为长连接是出网连接，不需要公网入口，不暴露任何内部端口，安全性上比回调模式好很多。这是我们在内网场景下最终选择长连接模式的根本原因。

3. 飞书开放平台侧配置：从创建应用到具备收发消息能力

3.1 自建应用的创建和权限开通顺序

在飞书开发者后台创建一个企业自建应用，这一步没什么难度，但接下来的操作顺序很关键。我建议严格按照这个顺序来，能少踩好几个坑：

1. 创建应用后，先进入“应用能力”页面，开启机器人能力。不开启机器人能力，后面所有消息相关配置都无从谈起。
2. 到“凭证与基础信息”页面，找到App ID和App Secret，记下来。App Secret相当于应用的密码，后面OpenClaw配置要用的。
3. 进入“权限管理”页面，搜索并开通以下权限：
   • 读取用户发给机器人的单聊消息
   • 读取群聊中@机器人的消息
   • 获取群信息
   • 发送消息
   • 消息卡片相关权限（如果要实现交互卡片）
4. 到“事件与回调”页面，选择长连接模式，然后订阅im.message.receive_v1事件。这是最核心的消息接收事件。
5. 配置完权限和事件后，点击创建版本并发布，等待管理员审核通过。
6. 发布后，在“可用范围”里设置哪些成员或群组可以使用这个机器人，或者提交申请让管理员设置为全公司可用。

这里有一个工程上的细节：权限和事件订阅设置的改动，通常要重新创建版本并发布才会生效。很多人改完权限后发现机器人还是没反应，排查了半天原来是忘了发新版。

3.2 加密策略与校验配置，这里不要图省事

飞书开放平台的事件订阅支持两种安全配置：Encrypt Key加密密钥和Verification Token验证令牌。

建议Encrypt Key一定要配。开启后飞书推送的事件内容会用AES加密，OpenClaw需要拿同一个Encrypt Key解密才能读取消息明文。不配置的话事件体是明文，虽然联调时方便，但消息内容里常常包含内部讨论信息，明文推送风险太高，企业场景下审计也过不去。

Verification Token则是用来校验事件来源的，OpenClaw会对比收到的token和应用配置的token是否一致，不一致就丢弃。这两个配置是双重保险，都配齐了才能防止伪造事件请求。

3.3 长连接模式的额外说明

上面提到我们最终选了长连接模式。在飞书后台配置时，“事件订阅”页面里可以选择长连接，但后台会提示需要申请开通。这个申请一般很快，但要走一遍企业管理员审批。开通后，飞书会给一个长连接地址，OpenClaw的飞书适配器会基于这个地址建立连接。

长连接模式最明显的好处是：不需要准备公网域名，不需要配置反向代理和HTTPS证书，对部署在内网的AI服务来说省掉了最麻烦的一环。而且连接建立后持续复用，没有每次回调建连的开销，事件的推送延迟也低一些。

4. OpenClaw里配置飞书通道：参数逐项拆解

4.1 一份可用的通道配置示例

OpenClaw的配置采用YAML格式，飞书通道是其中的一个channel。下面这份配置是我在实际部署中用过的最小可用版本，字段名以当前通用版本的规范为准，不同版本可能略有差异，但核心思路是一致的：

channels: feishu: enabled: true mode: websocket # websocket = 长连接模式；webhook = 回调模式 app_id: "cli_xxxxxxxxxxxxxxxx" app_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" encrypt_key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" verification_token: "xxxxxxxxxxxxxxxxxxxx" subscribe: - im.message.receive_v1 bot: reply_mode: "mention_only" # 群聊中仅响应被@的消息 ignore_bot_message: true # 忽略其他机器人发的消息 dedup_cache_ttl: 300 # 事件去重缓存时间，单位秒 max_reply_length: 1500 # 单条回复最大长度，避免触发限制 ai: default_agent: "general" routing_rules: - match: { chat_id_prefix: "oc_product_" } agent: "product_qa" - match: { group_topic_contains: "运维" } agent: "ops_qa"

对照这份配置，我把关键参数逐个说一遍。

mode选websocket就是长连接，选webhook就是回调模式。app_id和app_secret填飞书应用凭证，不必多说。encrypt_key要和飞书后台配置的保持一致；verification_token同理。

subscribe指定订阅哪些事件，最基本的im.message.receive_v1必须要有。reply_mode字段在多人群聊中非常关键，选mention_only表示只在被@的时候才回复。如果不设这个约束，机器人在群里会回复任何人说的任何话，试用期还没过就可能被同事抱怨刷屏。

4.2 事件进来之后，OpenClaw内部处理流水线

配置之外，理解处理流水线对排查问题至关重要。一个事件从进入到发出回复，在OpenClaw内部大致经过六个步骤：

第一步是安全校验，验证token和解密事件体。第二步是去重，检查这个事件ID是否在最近时间窗内处理过，防止飞书重试导致重复回复。第三步是消息解析，把飞书的原始消息对象解析成OpenClaw标准消息结构，包括取出@的用户ID、消息文本、群聊ID等。第四步是路由匹配，按配置的规则决定交给哪个AI智能体。第五步是调用AI服务，把标准消息结构连同上下文、知识库检索结果一起发给后端模型。第六步是发送回复，把模型输出转成飞书消息格式，调用发送API回传。

这个流水线里的任何一步失败，都应该有明确的日志记录。我建议在配置里把OpenClaw的日志级别调高到debug，联调阶段能看到每一步的输入输出，排错效率会高很多。

4.3 多智能体路由，一个机器人回答所有问题

在下面这部分配置里，routing_rules是一个很实用的设计：

routing_rules: - match: { chat_id_prefix: "oc_product_" } agent: "product_qa" - match: { group_topic_contains: "运维" } agent: "ops_qa"

它的含义是：如果消息来自聊天ID以oc_product_打头的群，就交给产品知识库智能体；如果群名称里包含“运维”两个字，就交给运维智能体。这让我们只用注册一个飞书机器人，就能在不同场景下自动切换不同AI配置和知识库，不用为每个场景单独建应用。

这个能力在公司内部特别有实用价值。技术群、产品群、人事群挂在同一个飞书机器人下，但各自得到答案的语境和知识范围不同，用户体感上是“这个机器人很懂我们部门”。

5. 从私聊到群聊，再到卡片交互：该按什么顺序开放能力

5.1 私聊是最简单的场景，但权限别加错

私聊场景指的是用户单独给机器人发消息。对于OpenClaw来说，这种消息解析最简单，没有@判断，没有群信息，直接取文本走路由即可。

在飞书权限配置上，要单独留意“读取用户发给机器人的单聊消息”这个权限，和群聊消息权限是两个不同的项。只开了群聊权限不开单聊权限，用户私聊机器人时消息根本不会推送到OpenClaw。

5.2 群聊场景的三个配置联动，缺一个都触发不了

群聊场景是OpenClaw最典型的应用方式，也是踩坑最多的地方。“在群里@机器人没反应”这个问题，我们在联调阶段排查了将近一天才定位清楚，实际上需要三个配置同时生效：

• 飞书后台权限里开启了“读取群聊中@机器人的消息”
• OpenClaw配置中subscribe订阅了im.message.receive_v1
• 应用发布版本成功，且当前群成员在“可用范围”内

这三个条件缺一不可，而且第三个最容易被遗漏。飞书里应用不是发布后就全员可用的，管理员在“可用范围”设置里指定了哪些成员和群组可以用，没被包含的群即使@了机器人，事件也不会推过来。

另外，OpenClaw侧reply_mode设成mention_only时，只处理包含@机器人的消息。如果某个群里有用户直接发消息不@机器人，机器人保持沉默属于预期行为，不算故障。

5.3 卡片交互：从“问一句答一句”变成“点一下就办”

飞书的消息卡片是比普通文本更高级的交互形态。OpenClaw可以发送包含按钮的消息卡片，用户点击按钮后会触发卡片回调事件，OpenClaw再根据回调内容执行后续操作。

举一个我们实际跑通的场景：助手检测到工单系统有新的“高优先级”故障，会主动在群聊里发一张消息卡片，附上故障摘要和两个按钮——“创建工单”和“忽略”。用户点“创建工单”，卡片回调事件会带着按钮的value返回给OpenClaw，OpenClaw收到后调用工单系统API完成建单，然后把卡片更新成“已创建工单 #1234”。

这种交互方式的体验优势非常明显：用户不需要打任何字，也不需要记命令，审批和操作都收敛在聊天界面里。代价是需要在飞书后台额外订阅card.action.trigger事件，并在OpenClaw里配置对应的卡片回调处理逻辑。

6. 联调阶段反复出现的四个问题，以及排查路径

6.1 签名校验失败：先查时间偏移，再查密钥配置

现象：飞书后台事件推送记录里全是“验签失败”，或者OpenClaw日志里报signature verification failed。

排查路径：签名校验依赖时间戳。如果服务器时间和标准时间偏差超过一定范围，签名就会对不上。先在服务器上执行一下时间同步，ntpdate或者装好chrony，确保系统时间正常。如果时间没问题，再看OpenClaw配置里填的encrypt_key和verification_token是否和飞书后台一致，注意复制时是否有隐藏换行符或空格。

这个问题的根因通常就这两类，没有第三个常见原因。我遇到过几次，都是服务器时间被虚拟化平台漂移了，同步完马上恢复。

6.2 同一条消息回复两次：事件重试与幂等处理

现象：用户问一次“今天有什么待办”，群里出现了两条一模一样的回复。

排查路径：飞书为了保证事件不丢失，在网络异常或应用未及时返回成功确认时，会重试推送同一条事件。如果OpenClaw每次都当新消息处理，就会回复多次。

解决方案是OpenClaw配置里的dedup_cache_ttl，它基于事件的message_id做去重，在TTL时间窗口内遇到相同ID直接丢弃。我们最开始把TTL设成60秒，后来发现飞书偶发的重试间隔可能超过一分钟，改成300秒后就稳定了。

事件处理的另一个关键是：收到事件后要尽快返回200确认，不要在事件处理回调里同步等待AI生成结果。AI生成可能要几秒甚至十几秒，一旦超时飞书会认为推送失败触发重试，又变成重复问题。正确的做法是先确认收到事件，再异步处理并发送回复。

6.3 群聊里@机器人没反应：三个条件逐项核对

现象：在群里@机器人，等了几秒没有任何回复，OpenClaw日志里也看不到对应事件。

排查路径：不要急着看OpenClaw配置，先回飞书后台逐项核对：

1. 权限管理里有没有“读取群聊中@机器人的消息”
2. 事件订阅里有没有订阅im.message.receive_v1
3. 应用是否创建了新版本并成功发布
4. “可用范围”是否包含当前群

我们那次就是卡在第四点上。应用发布后默认可用范围是空，需要管理员添加成员或群组。填了可用范围并重新发布时间，事件立刻正常推送。

6.4 回复内容过长发送失败：分段还是改卡片

现象：OpenClaw日志报发送失败，错误信息里提到消息内容超长，用户端没有收到回复。

排查路径：飞书对单条文本消息的内容长度有上限，具体上限以开放平台文档为准，实践中只要配置了max_reply_length字段就能自动规避一部分。但更稳妥的做法是让OpenClaw在回复超长时自动切分成多条消息发送，或者在配置里把长回答转成消息卡片展示。卡片对长文本的承载能力强很多，还能保留结构性排版。

这个问题看似简单，但影响用户信任度。试想同事问了个复杂问题，回了一条就断了，他只会觉得机器人能力不行。

我把这四类问题整理成了一张速查表，贴给团队新同学用：

7. 关于这套方案的取舍建议，来自跑了一段时间后的总结

7.1 什么场景真正适合自建OpenClaw通道

不是所有团队都值得为接一个AI助手而专门维护一套网关服务。我的判断标准是看三点。

第一，AI助手是不是你们的核心业务载体。如果只是管理层想试一下AI能干什么，那直接用飞书自带AI能力或者一个轻量云函数就足够了，完全不必引入OpenClaw。第二，后端AI服务是不是需要访问内部系统和内部知识库。如果答案是肯定，OpenClaw这种支持内网部署和长连接模式的网关优势就会非常突出。第三，是不是有多个群、多种场景、不同知识库需要同时服务。OpenClaw的多智能体路由在这种场景下节省了大量重复开发。

反过来，如果只是做一个简单的FAQ机器人，接一个云端大模型API就够了，那自建网关的运维成本反而成为负担。

7.2 上线之后要补上的运维细节

通道跑通只是开始，真正决定这套系统能不能长期稳定运行的是运维细节，下面几件事是我们跑了一段时间后总结出来的经验：

密钥集中管理。在配置里明文写App Secret的坏习惯最好改掉。飞书应用凭证和Encrypt Key都算敏感信息，建议放到配置中心或环境变量里。不然OpenClaw机器人的配置文件和日志被同事看到，相当于整个消息通道被别人拿走了。

日志脱敏。飞书事件里包含用户ID、群ID、消息文本，可能会携带内部信息。OpenClaw的日志如果按debug级别长期开着，会积累大量敏感内容。建议线上环境保持info级别，debug只在联调阶段开。

监控告警。长连接模式最怕连接掉线后又没自动重连。建议对OpenClaw加一个简单的健康检查，比如每隔几分钟发一条探活消息，或者监控长连接的状态指标，掉线后能第一时间告警。

灰度扩展。不要一上来就全公司可用。先在一个内部群跑一周，确认回复质量和稳定性，再把可用范围扩大到第二批群。这个节奏看起来保守，但能避免AI助手在最开放的场景里出糗。

7.3 最后再分享一点实际运作中的体会

接入通道是最容易低估的部分，因为它看起来只是“配个token、设个回调”的事。真正麻烦的是消息语义在不同场景里的差异。同一个提问，在私聊里可能希望助手直接给出详细答案，但在一个几十人的大群里，冗长答案会影响群聊节奏，更好的做法是返回一句话摘要加一张详情卡片。

现在我们的助手已经能区分私聊和群聊的回复风格，群聊里默认给摘要和卡片，私聊里给完整解释。这个细节改动带来的好评比我们想象的更大，同事们普遍觉得机器人“有分寸感”。

如果你正打算把AI助手接进飞书，我建议先把文章里飞书后台的权限与可用范围这块操作弄清楚，再把OpenClaw长连接模式跑通，这两个环节顺了，整个链路就成功了大半。后面再逐步加上群聊路由、卡片交互和上下文记忆，体验自然会越来越好。