写完这篇指南之前，先说说我在实际迭代中踩过的坑。团队协作工具里的 AI 助手，跟网页端聊天机器人完全是两回事：网页端不在乎谁来找你，但飞书里至少得知道这是哪个群、哪个部门、@了谁，权限、隔离、超时重试、部署保活这些事，每一项都直接影响“能不能稳定用”。所以这篇内容不只是贴一段接 Webhook 的代码，而是从选型开始，把 OpenClaw 接入飞书这件事完整拆开，讲清楚我的落地方案和后来遇到的一堆现场问题。1. 方案先行：为什么要把 OpenClaw 接到飞书上1.1 团队消息入口是天然的 AI 助手入口我们团队最早试过好几个形态：独立网页、命令行、甚至做成了内部小站点。结果使用率一直上不去，真正高频被用的反而是群里 @机器人 这种最“原始”的方式。原因不复杂——大家上班本来就泡在飞书里，查知识、转派事务、确认排期都是顺手的事。如果还要专门打开另一个页面，哪怕只多一步，使用意愿也会断崖式下降。把 OpenClaw 接到飞书，本质上不是接一个 API，而是把 AI 能力塞进大家原本就在用的消息流里。用户在群里发一句“帮我查一下本周的设备报修记录”，机器人就能直接回答；在单聊里问“下午两点会议改到四楼行不行”，它也能去更新日程。这类交互适合谁？我觉得最适合三种团队：一是行政或客服性质的事务型岗位，每天大量重复问答；二是研发运维团队，需要快速检索内部文档和工单；三是管理者，希望用自然语言把数据汇报拉到聊天窗口里。个人开发者同样能用同一套方案，把自己家里的服务状态推给飞书群，相当于拥有了一个会主动汇报的“值班机器人”。1.2 两种接入形态：Webhook 回调与长连接飞书开放平台提供给开发者的机器人接入方式，核心可以分为两类。第一类是 Webhook 回调。你在飞书开放平台配置一个公网 HTTPS 地址，所有消息事件由飞书服务器主动 POST 到这个地址。这种模式链路直观、排查方便，但要求你有一个稳定公网入口。家里宽带没有固定公网 IP、或者服务器藏在 NAT 后面的人，会非常痛苦。第二类是长连接模式。飞书开放平台从早期单纯依赖 Webhook 扩展了长连接回传方式，应用通过 SDK 主动和飞书服务端建立长连接，事件会顺着这个已经建立的连接推下来。好处在于不需要公网回调地址，只要能访问外网的服务器甚至开发机都能用。我实际测试下来，长连接模式对个人部署特别友好，省去了配置 Nginx 反向代理和 HTTPS 证书的环节。1.3 我为什么最终选择“长连接为主，Webhook 为辅”个人部署我会推荐长连接。理由有三点：第一，免公网 IP 和域名，一台云主机拉起进程就能跑；第二，SDK 自动处理断线重连，稳定性比我最初写死 Webhook 时好很多；第三，省掉一层反向代理，故障点变少。但如果是企业级场景，尤其是需要把 OpenClaw 的能力嵌入到内部审批、工单这类系统里，我还是建议用 Webhook 回调。因为企业内网通常有成熟的网关和统一鉴权策略，回调链路更容易纳入监控，消息轨迹也完整。两种模式不是互斥的，飞书官方也允许应用同时配置。我的习惯是“开发调试用长连接，正式多实例部署用 Webhook”，生产环境还可以靠回调地址做负载均衡。这里先记住一个结论：方案没有绝对好坏，只有适不适合现有网络条件。2. 接入前的四个准备：应用凭证、权限域、运行环境、依赖2.1 在飞书开放平台创建企业自建应用第一次操作的同学容易找不到入口，实际上就是进飞书开放平台，选择“企业自建应用”创建。创建完成后，在“凭证与基础信息”里能看到 app_id 和 app_secret。这两个值一个用于识别应用身份，一个用于签名和获取 token，请务必像保存数据库密码一样对待它们。我习惯把这几个值直接写入环境变量而不是硬编码到代码里。app_id 和 app_secret 一旦泄露，别人可以伪装成你的机器人在群里发消息，轻则被管理员封禁，重则引发安全事故。建议把这一条当作默认红线。在创建应用时，还要选择“机器人”能力。这一步不选，后面所有回调都不会生效。选完之后，应用还处于未发布状态，你自己能看到，别人在群里根本找不到它，所以后面必须走完发布流程。2.2 事件订阅与回调配置要让 OpenClaw 能收到用户消息，必须在“事件订阅”中配置对应事件。核心事件是 im.message.receive_v1，表示收到消息事件。它既覆盖单聊消息，也覆盖群聊中 @机器人 的消息。配置事件订阅时，飞书会要求你填写“请求地址”。如果走 Webhook 模式，这个地址必须是公网可达的 HTTPS 回调解；如果你用长连接模式，这个位置不需要填 URL，但代码里必须用官方 SDK 建立长连接。这里有个高频误区：不少人以为长连接不需要在后台“开启”，其实还是要添加事件、订阅对应权限、并通过校验之后才会生效。同时需要留意“加密策略”。飞书允许配置 Encrypt Key 和 Verification Token。我自己强烈建议开启加密，回调体里的内容会经过 AES 加密，代码里解密后才能拿到明文。很多新手在这里栽跟头——因为回调验证时飞书返回的不是明文 challenge，而是被加密后的字符串，导致 URL 校验怎么都过不去。关于验证流程，后面实操章节会专门给出代码。2.3 OpenClaw 运行时与模型 API 准备OpenClaw 的正常运转需要三样东西：Python 运行时、LLM 模型的 API Key、以及执行工具链的环境。我目前用的是 Python 3.10，安装 OpenClaw 的方式是pip install openclaw，不同版本可能略有差异，建议以官方安装文档为准。模型侧我同时保留了对话模型和嵌入模型两套配置，对话模型负责回复生成，嵌入模型负责把团队文档转成向量，方便做知识库检索。接飞书时还需要一个飞书官方 SDK，在 Python 里对应的包名通常是lark_oapi。这个 SDK 统一封装了获取 tenant_access_token、建立长连接、发送消息等操作，比直接拼 REST API 省一半时间。2.4 权限的最小化原则很多机器人接完不能发消息，九成原因都是权限没配够。飞书的权限系统非常细，比如“读取单聊消息”“读取群组消息”“发送单聊消息”“发送群组消息”都是独立权限。你至少要给应用开启以下权限：读取用户发给机器人的单聊消息、读取群聊中 @机器人的消息、以应用身份发送消息。我的做法是先只开这几个最小权限，跑通后再按功能增量加，比如要让机器人读取云文档，再加文档相关权限。尽量避免一次性开启“全部消息权限”，那样每个群所有人都能命令你的机器人，容易造成越权。权限配置完成后记得重新发布应用版本，否则配置不会生效，这是无数人验收时才发现的老坑。3. 实操：从零到一完成 OpenClaw 接入飞书3.1 应用发布与可用性检查在开放平台左侧菜单找到“版本管理与发布”，创建一个新版本并提交发布。管理员审核通过后，应用才会出现在组织成员可见的机器人列表里。这里有个细节：版本描述里最好写清楚机器人的功能和使用方式，因为很多企业管理员会直接按描述判断要不要放行。发布完成之后，在飞书搜索你创建的应用名，就能看到机器人，直接可以开始单聊测试。建议先手动在单聊里发一句“你好”，观察事件是否进入你配置的回调服务或长连接日志。这一步能快速区分问题出在“应用没有消息权限”还是“代码链路不通”。3.2 回调服务的骨架代码：挑战验证与事件转发这段代码我按“尽量跑起来”的标准给一个最小实现。无论你用长连接还是 Webhook，事件处理的思路一致：先解包，再校验，最后把消息交给 OpenClaw。用 Flask 写一个最小 Webhook 服务：from flask import Flask, request, jsonify from lark_oapi.adapter.flask import adapter app = Flask(__name__) @app.route("/openclaw/callback", methods=["POST"]) def openclaw_callback(): payload = request.json # 飞书 Webhook 模式首次配置时，会发送 url_verification 挑战 if payload and payload.get("type") == "url_verification": return jsonify({ "challenge": payload.get("challenge") }) # 其他消息事件交给后续处理 return handle_event(payload) if __name__ == "__main__": app.run(host="0.0.0.0", port=8000, debug=False)如果开启了加密，上面这段直接校验不过。要先用 Encrypt Key 解密：import base64, json from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes def decrypt_payload(encrypt_key: str, data: str) -> dict: # 实际实现请参考飞书官方 AES-256-CBC 示例，注意填充逻辑 raw = base64.b64decode(data) # 取出 key、iv、密文，并按 PKCS7 解填充 return json.loads(decrypted_text)我个人不推荐自己手写解密，太容易错。直接用lark_oapi官方事件处理器，SDK 会在内部完成解密验证。下面这版是官方风格的简化形态：from lark_oapi.api.im.v1 import ( P2ImMessageReceiveV1, P2ImMessageReceiveV1Handler ) class MessageHandler(P2ImMessageReceiveV1Handler): def handle(self, evt: P2ImMessageReceiveV1) -> None: event = evt.event message = event.message chat_id = message.chat_id content = json.loads(message.content) # content 是 JSON 字符串 text = content.get("text", "") # 交给下一层处理 process_message(chat_id, text, event.sender)使用官方事件处理器时，只需要注册到长连接客户端即可，不用自己处理解密、重试等琐碎逻辑。3.3 接入 OpenClaw 的完整消息链路实际处理流程可以拆成三步：抽取消息、调用 OpenClaw、用飞书 API 回发。抽取这一步要特别处理@机器人的情况。群聊里用户发“@OpenClaw 今天巡检情况怎么样”，消息文本中会带上@_user_xxx这类占位符，不清理掉会严重影响 LLM 的理解质量。我的做法是用正则把@_user_[0-9]+替换为空字符串，只保留语义部分。调用 OpenClaw 时，需要把会话 ID 设为 chat_id，这是为了让同一个群、同一个单聊的上下文连续。如果不设置，每次消息都是独立的，机器人会像失忆一样，没法接着上一句聊。import json def call_openclaw(text: str, chat_id: str) -> str: # 忽略空文本 if not text.strip(): return "请说具体需求" result = openclaw.chat( session_id=chat_id, message={"role": "user", "content": text} ) return result.answer回发消息直接用飞书 API，注意使用的是 tenant_access_token：from lark_oapi.api.im.v1 import ( CreateMessageRequest, CreateMessageRequestBody, CreateMessageResponse ) def send_text_message(chat_id: str, text: str): request = CreateMessageRequest.builder() \ .receive_id_type("chat_id") \ .request_body( CreateMessageRequestBody.builder() .receive_id(chat_id) .msg_type("text") .content(json.dumps({"text": text}, ensure_ascii=False)) .build() ) \ .build() client.im.v1.message.create(request)这里有个判断：让 OpenClaw 自己调用一个飞书插件来发消息，还是在外层直接调 API？我的经验是外层发消息更好。因为外层代码可以统一处理格式、失败重试和长度截断，避免 LLM 生成长文本时格式漂移。3.4 部署成 24 小时在线服务要让机器人全天在线，本质上要解决三件事：进程退出后自动拉起、开机自动启动、日志持续收集。我用的是 systemd，这是目前最省心的方式。先写好一个 service 文件：[Unit] Description=OpenClaw Feishu Bot After=network.target [Service] User=claw WorkingDirectory=/opt/openclaw-bot EnvironmentFile=/etc/openclaw-bot.env ExecStart=/usr/bin/python3 main.py Restart=always RestartSec=5 [Install] WantedBy=multi-user.target把 service 文件放到/etc/systemd/system/，然后执行：sudo systemctl daemon-reload sudo systemctl enable openclaw-bot sudo systemctl start openclaw-botRestart=always保证进程因为异常或内存溢出退出后五秒内自动拉起。我还会额外加一个大一点的进程保护，并让日志输出到固定文件：journalctl -u openclaw-bot -f看到这里可能有人问：为什么不用 Docker？Docker 当然可以，而且更适合迁移。如果团队已有容器平台，建议写个Dockerfile，把 service 文件换成容器健康检查。但我个人部署单机机器人时还是用 systemd，因为少一层容器网络，后续排查飞书 503 或超时时更直接。4. 核心链路细节与权限设计：从“能跑”到“好用”4.1 消息请求的完整时序理清时序对后面排查问题帮助极大。一次用户在群里 @机器人的请求，完整路径是这样的：用户发送消息 -> 飞书服务器投递事件到你的长连接或回调服务 -> SDK 触发message.receive_v1-> 代码解析文本 -> 调用 OpenClaw 生成回复 -> 再次调用飞书 API 主动发送消息 -> 用户看到回答。这里最核心也最容易忽视的问题：OpenClaw 调用 LLM 生成回答的时间可能很长，而飞书要求回调处理有明确时限。如果你在回调函数里同步等待 LLM 回复，很可能超过服务端的等待阈值，飞书会判定处理失败并进行重投。重投又会再次触发 LLM 计算，导致重复、慢、甚至消息队列堆积。正确姿势是把 LLM 调用放到异步任务里，回调函数先马上返回一个接收成功的信号，让飞书确认事件已经送达；然后后台线程慢慢生成回答，最终通过 API 推送过去。用 Python 的线程池或者队列都能实现，结构大概是这样：from concurrent.futures import ThreadPoolExecutor pool = ThreadPoolExecutor(max_workers=8) def handle_event(evt): # 快速入队，不再阻塞当前回调 pool.submit(process_message, evt) # process_message 内：解析 -> OpenClaw -> 发送这样既规避了超时，又能利用多线程并发服务多个群。唯一代价是消息响应从“请求-响应”变成了“异步回发”，需要在使用体验上做一点心理预期管理。4.2 把 OpenClaw 调教成团队助手而不是聊天机器接入之后，默认的 OpenClaw 像一个通用聊天机器人，这不是我们要的。真正团队的 AI 助手，应该知道自己身处什么组织、为谁服务、能调用哪些工具、遇到什么场景禁止越权。我建议在 OpenClaw 的 system prompt 里显式注入几类信息：团队内部叫法、常用工具清单、消息回答风格、以及“不知道就说不知道”的兜底原则。举一个我的实际配置片段：你是团队值班助手，当前环境为“某内部运维群”。 你可以查询工单系统、更新值班记录、翻查知识库。 请用简明、专业、不超过150字的方式回答。 如果你不确定，不要编造，提示用户联系人工。这个配置看起来简单，但直接决定了机器人的可靠性。很多接入后“感觉不聪明”的问题，其实不是模型不行，而是 prompt 里缺少约束。另外，OpenClaw 的工具调用权限也要单独控制。比如我给机器人只开放了“查询类工具”，写入类的操作全部放到审核队列，避免它在群里误改配置。4.3 多群隔离与权限白名单如果你只在一个群里测试，这个环节可以不看；但一旦部署到多个业务群，就会出现 A 群的人问 B 群的数据，或者群里随便一个成员都能命令机器人执行敏感操作。我强烈建议在 OpenClaw 上层加一层白名单中间件。白名单中间件至少要做两件事：第一，校验 chat_id 是否在允许服务的列表里，不在列表内直接拒绝；第二，校验触发者身份，群聊里只有管理员或指定角色可以使用写类工具。飞书事件体里带有sender.sender_id.open_id，拿这个 open_id 去和预设的运营者名单匹配就行。我遇到过一个真实事件：机器人进了测试大群后，有人发了“给所有人发一条广告消息”，要不是当时机器人没有发单聊消息的权限，后果就是群发轰炸。所以我后来把权限收敛得特别紧，宁可加权限后重新发布，也不开全量权限。4.4 结合知识库与主动推送的进阶玩法接入飞书的 OpenClaw 不该只会被动回答，它完全可以变成一个主动值守系统。我把内部知识库的更新、定时巡检脚本的输出、甚至天气和工作提醒都接进来了：每天早上八点，OpenClaw 调用定时任务，把前一天工单的数据汇总推送到运维群；每周五下午五点，推送周报提醒。主动推送的实现难点不在于发消息，而在于定时触发。OpenClaw 本身通常提供定时任务机制，我建议把发布任务放在独立进程里，避免和回调主进程耦合。另外，虽然飞书支持机器人往群里发消息，但过度推送会造成打扰，建议限制频率并对每条主动推送赋予明确标题。实践证明，“安静但有回应”的机器人，比“话痨机器人”更受团队欢迎。5. 常见问题与排查实录5.1 URL 校验永远失败，回调服务收不到请求Webhook 模式下，配置请求地址时飞书会发送一个url_verification事件。很多人第一次都卡在这里。排查顺序建议是这样：先看回调服务的日志，确认飞书到底有没有打进来；如果日志里完全没有请求，就是地址不通或者证书问题；如果收到了但校验失败，多半是返回体不符合要求。正确返回应该是直接回显challenge字段，并且 HTTP 状态码为 200。开启加密后，这个challenge还需要先用 Encrypt Key 解密再明文返回。我见过最隐蔽的坑是：代码里返回了{"challenge": 解密后的值}，但字段名拼错，飞书要求的是保留原名。保持响应体结构和请求体一致，是最容易被忽略的规则。5.2 机器人不回复，但日志里明明收到了事件这是另一个高频问题。日志有事件，说明链路通到了回调入口；但机器人没说话，问题多半出在后续代码逻辑。最常见的有四个原因：解析消息内容时，飞书 content 字段偶尔不是标准 JSON，而是带转义的字符串，导致 json.loads 失败；OpenClaw 调用模型时报错，但异常被吞掉了；发送消息时缺少im:message相关权限；异步线程池满了，任务一直排队。我的建议是在处理链路的每一步都打印结构化日志，带上chat_id和event_id，这样能快速定位卡点。用这个笨办法，我基本都能在十分钟内定位到问题。5.3 重复回复同一句话这个现象几乎是异步化之后必然出现的：飞书事件没有收到成功的 ACK，于是隔几秒重投一次，你的后台任务又跑了一遍，用户就看到两条相同回复。解决思路有两条：一是回调入口收到事件后，立刻执行去重；二是在处理函数开头检查这个消息是否已经处理过。最简单且稳妥的去重方案是拿message_id做记忆。处理完一条消息后，把它的 message_id 写入一个带过期时间的缓存，例如 Redis 或 Python 的磁盘缓存，重复到达时直接丢弃。我会把 TTL 设成一个小时，因为飞书重试通常发生在短时间窗口内，时间太长反而会造成新消息被误判为重复。5.4 长连接模式频繁掉线我早期用长连接时遇到过一个问题：跑了一两天后连接断开，机器人就静默失联。排查后发现是网络层对空闲连接做超时回收，SDK 没有及时发送心跳。解决方法是升级到新版 SDK，并在代码里拿到长连接状态后持续监听异常回调，遇到断线主动重建。另外一个容易踩的坑是：长连接模式下不要和定时任务塞在同一进程里用纯线程调度，部分环境的协程调度会让心跳任务饿死。更好的做法是定时任务独立进程，两者互不干扰。5.5 排查一页速查表症状常见原因快速处理URL 校验失败返回体非 challenge 明文 / 网络不通检查日志、确认端口与证书收不到事件未添加 im.message.receive_v1在开放平台补订阅并重新发布机器人不回复权限缺失或消息解析失败补权限，按日志定位异常点重复回复回调未 ACK / 重试投递入口对 message_id 去重发消息报权限错误未发布新的权限版本重新发布应用版本长连接掉线SDK 版本过旧 / 心跳中断升级 SDK，监视异常回调6. 我在实际部署中的几点体会如果让我重新做一遍接入，我会先把“消息处理”的异步模型画清楚，再开始写回调代码。整个接入过程中，最耽误我时间的不是 OpenClaw 本身的配置，而是飞书回调的同步、重复、超时这三件事。这几个问题没有一起想清楚，就会陷入“明明代码看起来没问题，可机器就是表现得痴呆”的困境。还有一个体会是关于模型的选择：同一套飞书接入层，换上不同的对话模型，回复质量差异很大。我的建议是先用一个常规模型跑通全链路，确认飞书侧稳定后，再迭代模型和 prompt。很多朋友一开始就在 prompt 上精雕细琢，结果连消息都没能发出去，前面的努力全部白费。最后分享一个小技巧：给 OpenClaw 接一个前置拦截层，把“打招呼”“发谢谢”“无意义消息”直接过滤掉，不送进 LLM。这条看起来很简单，但能把大模型的调用量直接降下来一半，响应速度也会有明显提升。24 小时在线这件事，不只是让机器人不睡觉，更要让它在每一条消息上都保持高效和专业。
写完这篇指南之前，先说说我在实际迭代中踩过的坑。团队协作工具里的 AI 助手，跟网页端聊天机器人完全是两回事：网页端不在乎谁来找你，但飞书里至少得知道这是哪个群、哪个部门、@了谁，权限、隔离、超时重试、部署保活这些事，每一项都直接影响“能不能稳定用”。所以这篇内容不只是贴一段接 Webhook 的代码，而是从选型开始，把 OpenClaw 接入飞书这件事完整拆开，讲清楚我的落地方案和后来遇到的一堆现场问题。1. 方案先行：为什么要把 OpenClaw 接到飞书上1.1 团队消息入口是天然的 AI 助手入口我们团队最早试过好几个形态：独立网页、命令行、甚至做成了内部小站点。结果使用率一直上不去，真正高频被用的反而是群里 @机器人 这种最“原始”的方式。原因不复杂——大家上班本来就泡在飞书里，查知识、转派事务、确认排期都是顺手的事。如果还要专门打开另一个页面，哪怕只多一步，使用意愿也会断崖式下降。把 OpenClaw 接到飞书，本质上不是接一个 API，而是把 AI 能力塞进大家原本就在用的消息流里。用户在群里发一句“帮我查一下本周的设备报修记录”，机器人就能直接回答；在单聊里问“下午两点会议改到四楼行不行”，它也能去更新日程。这类交互适合谁？我觉得最适合三种团队：一是行政或客服性质的事务型岗位，每天大量重复问答；二是研发运维团队，需要快速检索内部文档和工单；三是管理者，希望用自然语言把数据汇报拉到聊天窗口里。个人开发者同样能用同一套方案，把自己家里的服务状态推给飞书群，相当于拥有了一个会主动汇报的“值班机器人”。1.2 两种接入形态：Webhook 回调与长连接飞书开放平台提供给开发者的机器人接入方式，核心可以分为两类。第一类是 Webhook 回调。你在飞书开放平台配置一个公网 HTTPS 地址，所有消息事件由飞书服务器主动 POST 到这个地址。这种模式链路直观、排查方便，但要求你有一个稳定公网入口。家里宽带没有固定公网 IP、或者服务器藏在 NAT 后面的人，会非常痛苦。第二类是长连接模式。飞书开放平台从早期单纯依赖 Webhook 扩展了长连接回传方式，应用通过 SDK 主动和飞书服务端建立长连接，事件会顺着这个已经建立的连接推下来。好处在于不需要公网回调地址，只要能访问外网的服务器甚至开发机都能用。我实际测试下来，长连接模式对个人部署特别友好，省去了配置 Nginx 反向代理和 HTTPS 证书的环节。1.3 我为什么最终选择“长连接为主，Webhook 为辅”个人部署我会推荐长连接。理由有三点：第一，免公网 IP 和域名，一台云主机拉起进程就能跑；第二，SDK 自动处理断线重连，稳定性比我最初写死 Webhook 时好很多；第三，省掉一层反向代理，故障点变少。但如果是企业级场景，尤其是需要把 OpenClaw 的能力嵌入到内部审批、工单这类系统里，我还是建议用 Webhook 回调。因为企业内网通常有成熟的网关和统一鉴权策略，回调链路更容易纳入监控，消息轨迹也完整。两种模式不是互斥的，飞书官方也允许应用同时配置。我的习惯是“开发调试用长连接，正式多实例部署用 Webhook”，生产环境还可以靠回调地址做负载均衡。这里先记住一个结论：方案没有绝对好坏，只有适不适合现有网络条件。2. 接入前的四个准备：应用凭证、权限域、运行环境、依赖2.1 在飞书开放平台创建企业自建应用第一次操作的同学容易找不到入口，实际上就是进飞书开放平台，选择“企业自建应用”创建。创建完成后，在“凭证与基础信息”里能看到 app_id 和 app_secret。这两个值一个用于识别应用身份，一个用于签名和获取 token，请务必像保存数据库密码一样对待它们。我习惯把这几个值直接写入环境变量而不是硬编码到代码里。app_id 和 app_secret 一旦泄露，别人可以伪装成你的机器人在群里发消息，轻则被管理员封禁，重则引发安全事故。建议把这一条当作默认红线。在创建应用时，还要选择“机器人”能力。这一步不选，后面所有回调都不会生效。选完之后，应用还处于未发布状态，你自己能看到，别人在群里根本找不到它，所以后面必须走完发布流程。2.2 事件订阅与回调配置要让 OpenClaw 能收到用户消息，必须在“事件订阅”中配置对应事件。核心事件是 im.message.receive_v1，表示收到消息事件。它既覆盖单聊消息，也覆盖群聊中 @机器人 的消息。配置事件订阅时，飞书会要求你填写“请求地址”。如果走 Webhook 模式，这个地址必须是公网可达的 HTTPS 回调解；如果你用长连接模式，这个位置不需要填 URL，但代码里必须用官方 SDK 建立长连接。这里有个高频误区：不少人以为长连接不需要在后台“开启”，其实还是要添加事件、订阅对应权限、并通过校验之后才会生效。同时需要留意“加密策略”。飞书允许配置 Encrypt Key 和 Verification Token。我自己强烈建议开启加密，回调体里的内容会经过 AES 加密，代码里解密后才能拿到明文。很多新手在这里栽跟头——因为回调验证时飞书返回的不是明文 challenge，而是被加密后的字符串，导致 URL 校验怎么都过不去。关于验证流程，后面实操章节会专门给出代码。2.3 OpenClaw 运行时与模型 API 准备OpenClaw 的正常运转需要三样东西：Python 运行时、LLM 模型的 API Key、以及执行工具链的环境。我目前用的是 Python 3.10，安装 OpenClaw 的方式是pip install openclaw，不同版本可能略有差异，建议以官方安装文档为准。模型侧我同时保留了对话模型和嵌入模型两套配置，对话模型负责回复生成，嵌入模型负责把团队文档转成向量，方便做知识库检索。接飞书时还需要一个飞书官方 SDK，在 Python 里对应的包名通常是lark_oapi。这个 SDK 统一封装了获取 tenant_access_token、建立长连接、发送消息等操作，比直接拼 REST API 省一半时间。2.4 权限的最小化原则很多机器人接完不能发消息，九成原因都是权限没配够。飞书的权限系统非常细，比如“读取单聊消息”“读取群组消息”“发送单聊消息”“发送群组消息”都是独立权限。你至少要给应用开启以下权限：读取用户发给机器人的单聊消息、读取群聊中 @机器人的消息、以应用身份发送消息。我的做法是先只开这几个最小权限，跑通后再按功能增量加，比如要让机器人读取云文档，再加文档相关权限。尽量避免一次性开启“全部消息权限”，那样每个群所有人都能命令你的机器人，容易造成越权。权限配置完成后记得重新发布应用版本，否则配置不会生效，这是无数人验收时才发现的老坑。3. 实操：从零到一完成 OpenClaw 接入飞书3.1 应用发布与可用性检查在开放平台左侧菜单找到“版本管理与发布”，创建一个新版本并提交发布。管理员审核通过后，应用才会出现在组织成员可见的机器人列表里。这里有个细节：版本描述里最好写清楚机器人的功能和使用方式，因为很多企业管理员会直接按描述判断要不要放行。发布完成之后，在飞书搜索你创建的应用名，就能看到机器人，直接可以开始单聊测试。建议先手动在单聊里发一句“你好”，观察事件是否进入你配置的回调服务或长连接日志。这一步能快速区分问题出在“应用没有消息权限”还是“代码链路不通”。3.2 回调服务的骨架代码：挑战验证与事件转发这段代码我按“尽量跑起来”的标准给一个最小实现。无论你用长连接还是 Webhook，事件处理的思路一致：先解包，再校验，最后把消息交给 OpenClaw。用 Flask 写一个最小 Webhook 服务：from flask import Flask, request, jsonify from lark_oapi.adapter.flask import adapter app = Flask(__name__) @app.route("/openclaw/callback", methods=["POST"]) def openclaw_callback(): payload = request.json # 飞书 Webhook 模式首次配置时，会发送 url_verification 挑战 if payload and payload.get("type") == "url_verification": return jsonify({ "challenge": payload.get("challenge") }) # 其他消息事件交给后续处理 return handle_event(payload) if __name__ == "__main__": app.run(host="0.0.0.0", port=8000, debug=False)如果开启了加密，上面这段直接校验不过。要先用 Encrypt Key 解密：import base64, json from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes def decrypt_payload(encrypt_key: str, data: str) -> dict: # 实际实现请参考飞书官方 AES-256-CBC 示例，注意填充逻辑 raw = base64.b64decode(data) # 取出 key、iv、密文，并按 PKCS7 解填充 return json.loads(decrypted_text)我个人不推荐自己手写解密，太容易错。直接用lark_oapi官方事件处理器，SDK 会在内部完成解密验证。下面这版是官方风格的简化形态：from lark_oapi.api.im.v1 import ( P2ImMessageReceiveV1, P2ImMessageReceiveV1Handler ) class MessageHandler(P2ImMessageReceiveV1Handler): def handle(self, evt: P2ImMessageReceiveV1) -> None: event = evt.event message = event.message chat_id = message.chat_id content = json.loads(message.content) # content 是 JSON 字符串 text = content.get("text", "") # 交给下一层处理 process_message(chat_id, text, event.sender)使用官方事件处理器时，只需要注册到长连接客户端即可，不用自己处理解密、重试等琐碎逻辑。3.3 接入 OpenClaw 的完整消息链路实际处理流程可以拆成三步：抽取消息、调用 OpenClaw、用飞书 API 回发。抽取这一步要特别处理@机器人的情况。群聊里用户发“@OpenClaw 今天巡检情况怎么样”，消息文本中会带上@_user_xxx这类占位符，不清理掉会严重影响 LLM 的理解质量。我的做法是用正则把@_user_[0-9]+替换为空字符串，只保留语义部分。调用 OpenClaw 时，需要把会话 ID 设为 chat_id，这是为了让同一个群、同一个单聊的上下文连续。如果不设置，每次消息都是独立的，机器人会像失忆一样，没法接着上一句聊。import json def call_openclaw(text: str, chat_id: str) -> str: # 忽略空文本 if not text.strip(): return "请说具体需求" result = openclaw.chat( session_id=chat_id, message={"role": "user", "content": text} ) return result.answer回发消息直接用飞书 API，注意使用的是 tenant_access_token：from lark_oapi.api.im.v1 import ( CreateMessageRequest, CreateMessageRequestBody, CreateMessageResponse ) def send_text_message(chat_id: str, text: str): request = CreateMessageRequest.builder() \ .receive_id_type("chat_id") \ .request_body( CreateMessageRequestBody.builder() .receive_id(chat_id) .msg_type("text") .content(json.dumps({"text": text}, ensure_ascii=False)) .build() ) \ .build() client.im.v1.message.create(request)这里有个判断：让 OpenClaw 自己调用一个飞书插件来发消息，还是在外层直接调 API？我的经验是外层发消息更好。因为外层代码可以统一处理格式、失败重试和长度截断，避免 LLM 生成长文本时格式漂移。3.4 部署成 24 小时在线服务要让机器人全天在线，本质上要解决三件事：进程退出后自动拉起、开机自动启动、日志持续收集。我用的是 systemd，这是目前最省心的方式。先写好一个 service 文件：[Unit] Description=OpenClaw Feishu Bot After=network.target [Service] User=claw WorkingDirectory=/opt/openclaw-bot EnvironmentFile=/etc/openclaw-bot.env ExecStart=/usr/bin/python3 main.py Restart=always RestartSec=5 [Install] WantedBy=multi-user.target把 service 文件放到/etc/systemd/system/，然后执行：sudo systemctl daemon-reload sudo systemctl enable openclaw-bot sudo systemctl start openclaw-botRestart=always保证进程因为异常或内存溢出退出后五秒内自动拉起。我还会额外加一个大一点的进程保护，并让日志输出到固定文件：journalctl -u openclaw-bot -f看到这里可能有人问：为什么不用 Docker？Docker 当然可以，而且更适合迁移。如果团队已有容器平台，建议写个Dockerfile，把 service 文件换成容器健康检查。但我个人部署单机机器人时还是用 systemd，因为少一层容器网络，后续排查飞书 503 或超时时更直接。4. 核心链路细节与权限设计：从“能跑”到“好用”4.1 消息请求的完整时序理清时序对后面排查问题帮助极大。一次用户在群里 @机器人的请求，完整路径是这样的：用户发送消息 -> 飞书服务器投递事件到你的长连接或回调服务 -> SDK 触发message.receive_v1-> 代码解析文本 -> 调用 OpenClaw 生成回复 -> 再次调用飞书 API 主动发送消息 -> 用户看到回答。这里最核心也最容易忽视的问题：OpenClaw 调用 LLM 生成回答的时间可能很长，而飞书要求回调处理有明确时限。如果你在回调函数里同步等待 LLM 回复，很可能超过服务端的等待阈值，飞书会判定处理失败并进行重投。重投又会再次触发 LLM 计算，导致重复、慢、甚至消息队列堆积。正确姿势是把 LLM 调用放到异步任务里，回调函数先马上返回一个接收成功的信号，让飞书确认事件已经送达；然后后台线程慢慢生成回答，最终通过 API 推送过去。用 Python 的线程池或者队列都能实现，结构大概是这样：from concurrent.futures import ThreadPoolExecutor pool = ThreadPoolExecutor(max_workers=8) def handle_event(evt): # 快速入队，不再阻塞当前回调 pool.submit(process_message, evt) # process_message 内：解析 -> OpenClaw -> 发送这样既规避了超时，又能利用多线程并发服务多个群。唯一代价是消息响应从“请求-响应”变成了“异步回发”，需要在使用体验上做一点心理预期管理。4.2 把 OpenClaw 调教成团队助手而不是聊天机器接入之后，默认的 OpenClaw 像一个通用聊天机器人，这不是我们要的。真正团队的 AI 助手，应该知道自己身处什么组织、为谁服务、能调用哪些工具、遇到什么场景禁止越权。我建议在 OpenClaw 的 system prompt 里显式注入几类信息：团队内部叫法、常用工具清单、消息回答风格、以及“不知道就说不知道”的兜底原则。举一个我的实际配置片段：你是团队值班助手，当前环境为“某内部运维群”。 你可以查询工单系统、更新值班记录、翻查知识库。 请用简明、专业、不超过150字的方式回答。 如果你不确定，不要编造，提示用户联系人工。这个配置看起来简单，但直接决定了机器人的可靠性。很多接入后“感觉不聪明”的问题，其实不是模型不行，而是 prompt 里缺少约束。另外，OpenClaw 的工具调用权限也要单独控制。比如我给机器人只开放了“查询类工具”，写入类的操作全部放到审核队列，避免它在群里误改配置。4.3 多群隔离与权限白名单如果你只在一个群里测试，这个环节可以不看；但一旦部署到多个业务群，就会出现 A 群的人问 B 群的数据，或者群里随便一个成员都能命令机器人执行敏感操作。我强烈建议在 OpenClaw 上层加一层白名单中间件。白名单中间件至少要做两件事：第一，校验 chat_id 是否在允许服务的列表里，不在列表内直接拒绝；第二，校验触发者身份，群聊里只有管理员或指定角色可以使用写类工具。飞书事件体里带有sender.sender_id.open_id，拿这个 open_id 去和预设的运营者名单匹配就行。我遇到过一个真实事件：机器人进了测试大群后，有人发了“给所有人发一条广告消息”，要不是当时机器人没有发单聊消息的权限，后果就是群发轰炸。所以我后来把权限收敛得特别紧，宁可加权限后重新发布，也不开全量权限。4.4 结合知识库与主动推送的进阶玩法接入飞书的 OpenClaw 不该只会被动回答，它完全可以变成一个主动值守系统。我把内部知识库的更新、定时巡检脚本的输出、甚至天气和工作提醒都接进来了：每天早上八点，OpenClaw 调用定时任务，把前一天工单的数据汇总推送到运维群；每周五下午五点，推送周报提醒。主动推送的实现难点不在于发消息，而在于定时触发。OpenClaw 本身通常提供定时任务机制，我建议把发布任务放在独立进程里，避免和回调主进程耦合。另外，虽然飞书支持机器人往群里发消息，但过度推送会造成打扰，建议限制频率并对每条主动推送赋予明确标题。实践证明，“安静但有回应”的机器人，比“话痨机器人”更受团队欢迎。5. 常见问题与排查实录5.1 URL 校验永远失败，回调服务收不到请求Webhook 模式下，配置请求地址时飞书会发送一个url_verification事件。很多人第一次都卡在这里。排查顺序建议是这样：先看回调服务的日志，确认飞书到底有没有打进来；如果日志里完全没有请求，就是地址不通或者证书问题；如果收到了但校验失败，多半是返回体不符合要求。正确返回应该是直接回显challenge字段，并且 HTTP 状态码为 200。开启加密后，这个challenge还需要先用 Encrypt Key 解密再明文返回。我见过最隐蔽的坑是：代码里返回了{"challenge": 解密后的值}，但字段名拼错，飞书要求的是保留原名。保持响应体结构和请求体一致，是最容易被忽略的规则。5.2 机器人不回复，但日志里明明收到了事件这是另一个高频问题。日志有事件，说明链路通到了回调入口；但机器人没说话，问题多半出在后续代码逻辑。最常见的有四个原因：解析消息内容时，飞书 content 字段偶尔不是标准 JSON，而是带转义的字符串，导致 json.loads 失败；OpenClaw 调用模型时报错，但异常被吞掉了；发送消息时缺少im:message相关权限；异步线程池满了，任务一直排队。我的建议是在处理链路的每一步都打印结构化日志，带上chat_id和event_id，这样能快速定位卡点。用这个笨办法，我基本都能在十分钟内定位到问题。5.3 重复回复同一句话这个现象几乎是异步化之后必然出现的：飞书事件没有收到成功的 ACK，于是隔几秒重投一次，你的后台任务又跑了一遍，用户就看到两条相同回复。解决思路有两条：一是回调入口收到事件后，立刻执行去重；二是在处理函数开头检查这个消息是否已经处理过。最简单且稳妥的去重方案是拿message_id做记忆。处理完一条消息后，把它的 message_id 写入一个带过期时间的缓存，例如 Redis 或 Python 的磁盘缓存，重复到达时直接丢弃。我会把 TTL 设成一个小时，因为飞书重试通常发生在短时间窗口内，时间太长反而会造成新消息被误判为重复。5.4 长连接模式频繁掉线我早期用长连接时遇到过一个问题：跑了一两天后连接断开，机器人就静默失联。排查后发现是网络层对空闲连接做超时回收，SDK 没有及时发送心跳。解决方法是升级到新版 SDK，并在代码里拿到长连接状态后持续监听异常回调，遇到断线主动重建。另外一个容易踩的坑是：长连接模式下不要和定时任务塞在同一进程里用纯线程调度，部分环境的协程调度会让心跳任务饿死。更好的做法是定时任务独立进程，两者互不干扰。5.5 排查一页速查表症状常见原因快速处理URL 校验失败返回体非 challenge 明文 / 网络不通检查日志、确认端口与证书收不到事件未添加 im.message.receive_v1在开放平台补订阅并重新发布机器人不回复权限缺失或消息解析失败补权限，按日志定位异常点重复回复回调未 ACK / 重试投递入口对 message_id 去重发消息报权限错误未发布新的权限版本重新发布应用版本长连接掉线SDK 版本过旧 / 心跳中断升级 SDK，监视异常回调6. 我在实际部署中的几点体会如果让我重新做一遍接入，我会先把“消息处理”的异步模型画清楚，再开始写回调代码。整个接入过程中，最耽误我时间的不是 OpenClaw 本身的配置，而是飞书回调的同步、重复、超时这三件事。这几个问题没有一起想清楚，就会陷入“明明代码看起来没问题，可机器就是表现得痴呆”的困境。还有一个体会是关于模型的选择：同一套飞书接入层，换上不同的对话模型，回复质量差异很大。我的建议是先用一个常规模型跑通全链路，确认飞书侧稳定后，再迭代模型和 prompt。很多朋友一开始就在 prompt 上精雕细琢，结果连消息都没能发出去，前面的努力全部白费。最后分享一个小技巧：给 OpenClaw 接一个前置拦截层，把“打招呼”“发谢谢”“无意义消息”直接过滤掉，不送进 LLM。这条看起来很简单，但能把大模型的调用量直接降下来一半，响应速度也会有明显提升。24 小时在线这件事，不只是让机器人不睡觉，更要让它在每一条消息上都保持高效和专业。