把 OpenClaw 接到飞书上这件事我前后折腾了两轮第一轮卡在飞书事件订阅的 challenge 验证上第二轮卡在回调超时上。等把整条链路跑通之后回头一看真正难的不是 OpenClaw 本身而是飞书开放平台那一堆“看起来简单、上手全是坑”的配置和回调逻辑。这篇手册就把完整接入过程拆开写清楚从消息链路讲到代码实现再把我在实际对接中踩过的坑按现象、原因、解决方式列出来。适合已经从命令行跑通 OpenClaw、想给它加一个飞书群入口的开发者也适合刚接触飞书开放平台、想给自己的 Agent 接一个 IM 界面的朋友。1. 接入方案怎么选先想清楚消息链路1.1 OpenClaw 接入飞书到底做了什么先说一句最直白的话OpenClaw 本身并不知道飞书是什么飞书也不知道 OpenClaw 是什么。要让两者对话中间必须垫一层“胶水服务”而这一层胶水要解决的只有三件事。第一是接收飞书群里有人发消息飞书要把这个消息事件推给我们自己的服务。第二是转换把飞书消息里带的一堆 JSON 结构、标签、消息类型标识剥掉拿到干净的文本然后把这文本交给 OpenClaw。第三是回传等 OpenClaw 执行完把输出结果再通过飞书的消息接口发回给对应的用户或群。你可以把整个过程理解成前台和后台的对话飞书是前台窗口用户往窗口里递纸条你的服务是传话员负责把纸条上的内容转成内部工单交给 OpenClawOpenClaw 是后台坐席处理完了把答案递回来传话员再把答案抄成前台能识别的格式放回去。传话员这个角色看似不重要实际上最容易出错——纸条格式看错、工单传错、回话找错窗口都会让整条链路挂掉。所以接入之前建议你先把这三件事在脑子里过一遍每一件事分别对应哪些接口、哪些字段、哪些可能出错的地方。有了这个整体框架后面碰到问题才不至于在飞书后台里瞎翻。1.2 两种接入方式对比回调地址与长连接飞书给开发者提供了两种接收消息事件的方式我在接入前犹豫了很久这里直接给结论两种都能用但适合的场景完全不一样。第一种是 Webhook 事件订阅回调。你在飞书后台配置一个 HTTPS 地址飞书一旦收到群消息就往这个地址 POST 一个 JSON 事件。这套方式的好处是逻辑透明任何语言都能写排障也方便用调试工具直接模拟请求就能复现问题。坏处是要求这个地址公网可达如果你在本地开发就得先把服务部署到一台有公网入口的服务器上或者走 HTTPS 代理。另外回调接口必须在几秒内返回成功响应否则飞书会判定超时并开始重试。第二种是 WebSocket 长连接模式。你的服务主动和飞书服务器建立一条长连接消息顺着这条连接推给你不需要暴露公网地址。这套方式对本地开发非常友好很多没配过公网服务器的朋友第一次就跑通了。不过官方 SDK 封装程度比较高不同版本的 API 差别不小真要 Debug 底层连接时反而不如 Webhook 直观。我把两种方式做了一个简单的对比帮你快速决策对比项Webhook 回调WebSocket 长连接公网需求需要 HTTPS 可达地址不需要主动出连接即可实现透明程度高请求响应完全可控中SDK 帮你封装了连接管理本地调试体验一般需要先解决公网收包好本地直接就能跑起来排障方式可用调试工具直接模拟 POST需要看 SDK 日志稍绕适合阶段生产部署、逻辑稳定后本地联调、快速跑通 MVP这篇手册我按 Webhook 回调来写因为它的代码逻辑最直观适合作为理解飞书消息链路的基础。你本地如果实在不方便暴露公网可以先用长连接模式把业务逻辑调通再回来把回调接口补上两者在消息处理那部分逻辑完全一样。2. 动手前的前置准备应用、权限、事件订阅2.1 本地环境与依赖清单在动代码之前先把环境过一遍。我这边的标准清单是这样一台能跑 Python 3.9 以上的机器本地开发机也行生产建议放服务器上OpenClaw 本体已经能用命令行跑通Python 依赖装好flask用来起回调服务requests用来调飞书 OpenAPI一个测试飞书群把机器人拉进去后面所有验证都在这个群里做依赖安装就两行pip install flask requests这里有个经验值OpenClaw 的调用方式一定要先固定下来再开始接飞书。我建议你先在命令行里执行一条最简单的指令比如openclaw run 用一句话介绍你自己确认输出正常。如果这一步都不过后面飞书接入再顺利也没有意义因为根本分不清问题出在哪一侧。2.2 创建飞书自建应用并开通机器人接下来是飞书后台的配置。打开飞书开发者后台创建一个企业自建应用。创建成功后你会看到两个关键凭证App ID 和 App Secret。这两个值后面都要用到建议直接放在环境变量里不要硬编码进代码仓库。然后做四件事顺序不要乱在“应用能力”里开通机器人能力这一步决定了这个应用能不能出现在飞书群里。在权限管理里搜索并开通消息相关权限。需要哪些权限以你看到的界面关键字为准一般搜“消息”会出现接收消息、发送消息、读取消息等选项按需勾上。在事件订阅里添加im.message.receive_v1事件这是接收消息的核心事件。创建版本并发布。第四步特别容易被忽略。飞书自建应用的很多配置改动不是说保存一下就立刻对线上生效必须先“创建版本”版本通过后再“申请发布”。权限、事件订阅、机器人能力的变更都是这个逻辑。我第一次就栽在这上面权限后台全开了但是线上调用发送消息接口一直报权限不足最后发现是版本没发布。2.3 配置事件订阅与回调地址权限和事件都改完之后回到事件订阅页面把事件推送方式选成“将事件发送至开发者服务器”然后填上你的回调地址。我的习惯是一个专用的路径区分不同业务比如https://你的域名/webhook/feishu。填完回调地址飞书会立刻发一个 URL 验证请求到你的接口也就是著名的 challenge 验证。这个阶段有一个非常关键的决策先别开事件加密。飞书后台有一个加密策略配置项开了之后所有事件内容会包在一个encrypt字段里你必须先解密才能看到真正的 JSON。解密逻辑如果没写好光是验证这一步就能卡你一整天。我的建议是第一步把加密关掉只用 Verification Token 做简单校验等整条链路通了、确认没有问题了再回来考虑加密。Verification Token 就在事件订阅配置下方它不是 App Secret不要拿错。回调地址确认通过之后还需要把机器人拉进一个测试群后面发消息才能触发事件。到这一步飞书侧的准备工作算完成了。3. 核心接线接收消息、调用 OpenClaw、把结果发回飞书3.1 回调接口的整体结构这一节直接给代码。我用 Flask 写了一个最小可用的回调服务整体流程是接收飞书 POST 请求、处理 URL 验证、校验 Verification Token、解析消息文本、把文本交给 OpenClaw、再把结果通过飞书消息接口发回给用户。import json import os import re import threading import subprocess import time import requests from flask import Flask, request, jsonify app Flask(__name__) APP_ID os.getenv(FEISHU_APP_ID, ) APP_SECRET os.getenv(FEISHU_APP_SECRET, ) VERIFICATION_TOKEN os.getenv(FEISHU_VERIFICATION_TOKEN, ) _token_cache {token: , expire: 0} def get_tenant_access_token(): # 飞书 token 有效期约 2 小时这里缓存 1 小时避免频繁请求 token 接口 if _token_cache[token] and _token_cache[expire] time.time(): return _token_cache[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}, timeout5, ) data resp.json() if data.get(code) ! 0: raise RuntimeError(fget tenant_access_token failed: {data}) _token_cache[token] data[tenant_access_token] _token_cache[expire] time.time() 3600 return _token_cache[token] def send_text_to_user(open_id, text): token get_tenant_access_token() url https://open.feishu.cn/open-apis/im/v1/messages?receive_id_typeopen_id headers {Authorization: fBearer {token}} payload { receive_id: open_id, msg_type: text, content: json.dumps({text: text}, ensure_asciiFalse), } resp requests.post(url, headersheaders, jsonpayload, timeout10) resp.raise_for_status() def run_openclaw(prompt): # 这个命令换成你自己环境里 OpenClaw 的真实入口 proc subprocess.run( [openclaw, run, prompt], capture_outputTrue, textTrue, timeout120, ) output proc.stdout.strip() if not output: output proc.stderr.strip() return output or (OpenClaw 没有返回内容) def clean_at_part(raw_text): # 去掉飞书消息里 机器人 附带的 at 标签只保留纯文本 return re.sub(rat[^]*.*?/at, , raw_text).strip() def handle_user_message(open_id, prompt): try: answer run_openclaw(prompt) send_text_to_user(open_id, answer) except Exception as exc: send_text_to_user(open_id, fOpenClaw 执行出错{exc}) app.route(/webhook/feishu, methods[POST]) def feishu_callback(): req request.get_json() # 首次配置回调地址时飞书会发一个 URL 验证请求这里直接回传 challenge if req.get(type) url_verification: return jsonify({challenge: req[challenge]}) header req.get(header, {}) if header.get(token) ! VERIFICATION_TOKEN: return jsonify({code: 1, msg: invalid token}) # 只处理消息接收事件其他事件类型一律忽略 if header.get(event_type) im.message.receive_v1: event req.get(event, {}) message event.get(message, {}) message_type message.get(message_type, ) if message_type text: content json.loads(message.get(content, {})) raw_text content.get(text, ) prompt clean_at_part(raw_text) sender event.get(sender, {}) sender_id sender.get(sender_id, {}).get(open_id, ) if prompt and sender_id: # 收到消息后立刻返回耗时任务放到后台线程执行 threading.Thread( targethandle_user_message, args(sender_id, prompt), ).start() return jsonify({code: 0, msg: success}) if __name__ __main__: app.run(host0.0.0.0, port8000)代码里有一个非常关键的设计收到飞书事件之后我没有直接在回调函数里执行 OpenClaw而是开了一个后台线程去跑。这个设计很多人刚开始不理解等你在回调里同步执行了一个耗时 30 秒的任务、然后看到飞书连续重试三次之后就明白了。回调接口必须马上返回成功不能等任务执行完再返回。3.2 消息内容解析别栽在双层 JSON 上飞书事件里的消息内容解析是新手最容易踩的坑。现象是这样的你在日志里看到message.content看起来是{text: 你好}于是很自然地用content[text]去取结果 Python 直接报错。原因在于content字段是一个 JSON 字符串不是对象。飞书在把事件拼成 JSON 时把原本是对象的 content 又序列化了一次塞进了外层 JSON。所以你看到的是“字符串形式的 JSON 里面又包了一个 JSON”。正确做法是先json.loads(message[content])再取text字段。反过来发送消息的时候也要注意方向。调用飞书发送消息接口时content字段要求传入的是字符串化的 JSON也就是json.dumps({text: 你好})而不是直接传一个 Python dict。这两个方向的序列化要求正好相反非常容易搞错。我的习惯是封装一个小函数专门处理发送格式全局统一走它不在业务代码里手写。另外群聊里如果用户 了机器人raw_text里会带上类似at user_idou_xxx机器人名字/at的标签。直接把这串文本丢给 OpenClaw模型会看到一堆陌生标签输出容易跑偏。我用正则把at ....../at整体去掉再取纯文本效果比较干净。如果你希望只有 机器人 才触发 OpenClaw还需要判断消息里是否包含机器人本身的 open_id这一点在不同版本的飞书事件结构里字段名不一样以你实际收到的 payload 为准。3.3 调用 OpenClaw 的三种姿势代码里我用的是最直接的子进程调用方式subprocess.run([openclaw, run, prompt])。这种方式的优点是简单直观和命令行手动执行完全一致出问题的时候方便对比。缺点也很明显每次消息都要新拉起一个进程有启动开销如果任务执行时间长回调线程会被占住同时来多条消息时响应就不及时。如果你的 OpenClaw 是以 HTTP 服务形式跑的我更推荐用requests.post直接打到它本地的 HTTP 接口。这种方式性能好、连接复用适合频繁调用场景而且不存在子进程环境变量、工作目录不一致之类的隐性问题。到底用哪种取决于你 OpenClaw 的部署方式。我这里用子进程主要想让代码不依赖具体服务端口读者拿到手按自己的命令替换即可。还有第三种方式值得留意某些版本的 OpenClaw 自带 Python SDK 或者 client 封装库。如果项目文档里有优先用官方封装因为路径、参数、错误处理都比较规范。无论用哪种方式我都建议加一个超时控制timeout120是我这边的经验值。设置太长飞书用户发出的消息迟迟等不到回复体验很差设置太短OpenClaw 执行稍微复杂一点的任务就被切断。你可以根据自己任务的耗时分布来调但不要不设超时不然后台线程会越积越多。3.4 把回复发回飞书的那点参数细节发送消息接口最常用的参数就是receive_id_type和receive_id。我在代码里用的是receive_id_typeopen_idreceive_id直接取自事件的sender.sender_id.open_id。这里有一个很多新手会忽略的细节如果你要往群里发消息receive_id应该传群聊的chat_id同时把receive_id_type改成chat_id。混用的话会报invalid receive_id。获取 tenant_access_token 的时候用的是/auth/v3/tenant_access_token/internal这个内部接口这是服务端应用的标准入口。响应里会返回一个tenant_access_token这个 token 是有有效期的我这边实测大约是两小时。我做了 1 小时缓存给 token 留了充足的余量避免刚好在过期边界上出问题。缓存逻辑在代码里已经有了正式上线时建议直接复用不要每次都调 token 接口否则频繁请求很容易触达飞书的频控限制。还有一个细节是关于 content 的编码。飞书发送消息接口的content是一段 JSON 字符串里层文本建议用中文原样传入不要手动ensure_asciiTrue转成\u编码。我代码里json.dumps特意加了ensure_asciiFalse就是为了让飞书展示侧更友好调试日志里也能直接看到可读文本。4. 避坑实录这些坑我基本都踩过4.1 URL 验证不过challenge 返回错了配置回调地址的时候飞书会发一个验证请求上面带着typeurl_verification和challenge字段。你的接口必须原样返回{challenge: challenge字段的值}。很多人在这里犯的错是没有判断事件类型把整个请求体原封不动返回或者返回结构里漏了challenge字段飞书就一直提示验证失败。如果你开了事件加密情况会更麻烦challenge 会被加密你需要先解密拿到原文再把加密后的 challenge 返回给飞书。这一步的加密和解密细节如果不对验证同样过不了。这就是我前面反复强调先关加密的原因先用明文模式把链路跑通后面真有安全要求再说加密的事。4.2 回调超时不要在回调里同步干活这是接入 IM 回调类业务最经典的问题。飞书把事件推给你之后需要你的接口尽快返回 HTTP 200超时之后飞书会判定投递失败并且走重试。如果你在回调函数里直接同步调用 OpenClaw而 OpenClaw 一次任务要跑几十秒结果就是飞书这边早就超时放弃了用户那边自然收不到回复。解决方式我在代码里已经演示了回调函数只负责收消息和校验把耗时任务交给threading.Thread后台执行。但要注意线程方案只适合低并发场景。如果你的群多、消息量大建议把消息扔进 Redis 队列再让 worker 进程去消费这样服务重启时消息还能保住在队列里不丢线程方案服务一重启就全没了。4.3 消息内容取不出来content 是个 JSON 字符串这个问题我前面已经讲过原理这里再强调一遍现象。报错可能是TypeError: string indices must be integers也可能是取出来的值一直是None或者直接KeyError。这些基本都能归结到同一个原因把message.content当成 dict 用了它其实是个字符串。顺手记一下接收时json.loads发送时json.dumps两者方向相反别记混。4.4 回复发不出去receive_id_type 是重灾区我遇到的另一类高频问题是发送消息接口一直报参数错误。当时调试了很久最后发现是receive_id_type和receive_id不匹配。飞书接口要求你明确告诉它你传的 ID 是哪一种类型如果你拿的是 open_id但 URL 上的receive_id_type是 user_id它拿这个 open_id 去查用户自然查不到。解决方式很简单URL 上显式写receive_id_typeopen_id不要依赖默认值receive_id从sender.sender_id.open_id取不要自己拼接也不要去猜。这里顺便提醒不同的飞书应用类型支持拿到的 sender_id 字段可能不同有的场景下只有 union_id 没有 open_id。遇到这种情况需要先在应用权限里确认是否有获取 open_id 的权限或者改用其他 ID 类型。总之先看实际事件里有什么再选匹配的receive_id_type。4.5 权限配了但不生效应用版本没有发布后台开了消息权限事件订阅也加了但是线上调用发送接口一直报no permission。这个问题最隐蔽因为后台界面看起来一切正常。原因就是版本没有发布。飞书自建应用的权限和事件配置必须通过“创建版本 - 发布”才真正生效。只点保存等于没改。我踩过这个坑之后给自己定了一个流程每次改完飞书后台配置先在本地记录一下改动点然后立刻创建版本并申请发布发布通过后再做联调。这样不会出现后台改了一堆、线上一个没生效的情况。4.6 限频与长回复发送端要做的两件事飞书开放接口有频控限制消息发送接口尤其明显。高频场景下如果每条回复都临时去获取 token再频繁发请求很容易撞上限制。我这边做了两件事一是 token 缓存二是发送侧串行化。token 缓存的思路很简单只在 token 快过期时去刷新而不是每次发消息都拿一次这样把 token 接口的调用频次降了一个数量级。发送侧串行化是说当 OpenClaw 一次返回特别长、需要分多条消息发送时不要开多个线程并发发而是按顺序逐条发每条之间稍微等一下。并发发送不仅容易触发频控还会让用户收到的消息顺序错乱。4.7 常见问题速查表现象高概率原因解法配置回调地址时验证失败没处理 url_verification 类型或返回结构少了 challenge判断 type 后直接返回{challenge: ...}有消息但 OpenClaw 没执行事件类型没对上或消息被校验逻辑过滤掉了打印原始 payload确认 event_type 和 message_type取 text 字段报错把 JSON 字符串当成字典用先json.loads(message[content])再取字段发送消息报 invalid receive_idreceive_id_type 和实际 ID 类型不匹配按实际 ID 类型显式传receive_id_type发消息提示权限不足应用版本没发布创建版本并申请发布回复内容过长被截断或失败超过飞书文本消息长度限制按长度切片逐条发送加序号前缀群里消息全触发不想理没 机器人的内容没有过滤 事件判断消息里是否包含机器人 open_id 或 at 标签5. 上线维护与后续扩展5.1 进程守护与日志规范代码联调通过之后别以为就万事大吉了。Flask 自带的app.run()是开发服务器直接用来跑生产很容易在进程退出后没人拉起。我这边用 systemd 把服务包成一个常驻进程崩溃自动重启开机自启。如果你用的是容器平台也一定要配置好健康检查和自动重启策略不然半夜一个异常把进程带崩第二天群里全是“机器人不回话”的抱怨。日志这块也要提前规划。不要只print要把时间、消息 ID、open_id、执行耗时打出来方便复盘一条消息到底走完整个链路花了多久。我推荐一个简单的日志格式2025-06-01 12:00:01 [im.message.receive_v1] message_idom_xxx open_idou_xxx cost_ms2345另外注意不要在日志里打印完整的用户消息内容飞书消息里可能有敏感信息。真要打印就截断或者只打印消息类型和长度别给后续的自己找麻烦。5.2 会话状态与多群隔离OpenClaw 如果是有状态对话模式会涉及一个很现实的问题不同群、不同用户的消息全混在一起上下文会串。比如 A 群里问“帮我写个 Python 脚本”B 群里问“刚才那个需求怎么说”如果上下文共享了B 会答非所问。我的处理方式是以chat_id或open_id作为会话维度把每一段对话的历史传给 OpenClaw。简单做就是给 OpenClaw 的 prompt 前面拼上历史记录复杂做可以自己维护独立的数据库表。这一步很影响体验建议在接入初期就把会话 key 定下来避免后面数据结构改来改去。5.3 后续可以扩展的玩法链路稳定之后可玩的东西就多了。比较实用的是定时任务让 OpenClaw 每天早上把项目进展、待办清单整理成一条日报发到指定群里。再进一步可以把 OpenClaw 的输出渲染成飞书卡片消息带按钮、带颜色、带折叠块交互体验比纯文本好很多。如果你有多个 Agent还可以做多机器人路由不同群绑定不同系统提示词让同一个接入层服务不同场景。最后分享一个我自己的固定动作每次改完回调代码先用飞书后台的调试工具或者直接在一个测试群里发一条消息同时盯住日志看三个数字——收到事件的耗时、OpenClaw 执行的耗时、发送消息接口的耗时。这三个数字正常链路基本就稳了。接入 IM 平台这件事难点其实不在 AI而在消息管道。你越早把事件解析和回调边界理清楚后面的扩展就越顺手。