Openclaw记录写到第二篇。上一篇把基础服务部署完Openclaw跑起来之后我干的第一件事就是把手机里的几个IM全接了上去——飞书、钉钉、QQ、企业微信一个都没落下。这个开源网关服务说白了就是把大模型能力接入各种聊天软件让你在平时用惯的IM里直接跟AI对话、调工具、查资料、触发自动化任务不用再专门开个网页去聊天。这篇文章适合两类人一是已经把Openclaw跑起来、正卡在“消息进不来/发不出”这个环节的朋友二是正在选型、想知道飞书、钉钉、QQ、企微四个平台哪个接入成本最低、坑最多的人。我会把四个平台的接入方式、权限配置、高频报错全部过一遍包括飞书机器人发不了表格、钉钉Stream模式怎么配、企微群ID从哪里拿这类天天有人问的问题。1. 先把四类IM的接入逻辑理清楚1.1 Openclaw接入IM的两种模式很多人第一次配IM接入上来就找Webhook地址其实Webhook只是其中一种方式。Openclaw这类网关接入IM底层无非两条路。第一条是回调模式IM平台收到用户消息后通过HTTP请求把事件推送到你配置的回调地址上Openclaw处理完了再调用IM平台的API把回复发出去。这条路的硬性要求是你的服务器必须有一个公网可达的HTTPS地址而且这个地址要能稳定接收请求否则消息一多就容易丢事件。第二条是长连接模式Openclaw主动向IM平台建立一个长连接WebSocket或者平台特有的Stream通道平台有新消息就通过这个连接推过来回复也走同一条通道。长连接的好处非常明显不需要公网IP不需要配置回调URL不受传统端口限制内网开发机也能直接调试。我个人的建议是只要能走长连接就尽量走长连接。飞书有长连接事件订阅钉钉有Stream模式QQ社区方案里的OneBot本身就是WebSocket协议只有企业微信的老接口还在用回调URL模式。四个平台里三个都有现代的长连接方案没必要死磕回调。1.2 四个平台的特性横向对比接入之前先花两分钟把四个平台的脾气摸清楚后面配置会顺畅很多。我整理了一张表是我折腾完之后的实际感受。平台推荐接入方式双向对话单向通知配置难度适合场景飞书长连接事件订阅支持支持中个人助理、知识库问答、完整Agent钉钉Stream模式支持支持中企业内部告警、审批联动、运维通知QQOneBotWebSocket支持支持低个人自用、群聊互动、测试环境企业微信应用回调 群机器人Webhook支持支持较高公司内部群、客户群运营、流程通知为什么要做这个对比因为四个平台的定位完全不一样。飞书对开发者最友好权限体系细事件类型全适合做复杂的Agent交互钉钉的强项是和企业内部系统打通它的Stream模式把回调地址这个问题彻底解决了QQ的优势是用户量大、上手快但官方机器人开放平台的申请门槛不低社区方案更常见企业微信则强在“组织内部关系链”天然适合对接公司群和客户群。选型这事儿没有标准答案。我自己是飞书做主力对话入口钉钉专收告警和定时任务输出企微挂在公司群里给同事用QQ留着自己折腾测试。2. 部署前的基础环境检查2.1 先确认Openclaw核心服务状态因为这是系列第二篇基础部署过程我就不重复了但接入IM之前有一个动作必须做确认Openclaw本体是健康的。我见过不少朋友IM应用配置了半天最后发现是网关服务挂了消息从来没进到Openclaw里。检查三步就够了。第一步看服务进程用systemd部署的话执行systemctl status openclaw看到active (running)说明进程活着第二步看健康接口Openclaw一般会暴露一个本地健康检查端口curl http://127.0.0.1:端口/health返回ok就说明HTTP服务正常第三步看日志journalctl -u openclaw -f实时盯一下确认没有反复重启或者数据库连接报错。这三步做完只能说明服务“活着”还不能说明服务“健康”。我建议顺手在日志里确认一下模型API的连通性随便触发一个最简单的不经过IM渠道的测试请求能正常返回才继续往下走。网关本身没起来后面所有IM接入都白搭。2.2 四平台凭证清单与统一管理接入四个平台没有任何捷径就是一堆密钥来回拷贝。最容易翻车的地方不是配置写错而是密钥本身拿错了。飞书有App ID和App Secret钉钉有Client ID和Client Secret企业微信有Corp ID、AgentId和SecretQQ方案的token还分两种——这些凭证长得都差不多一不留神就串了。我强烈建议在开始配置之前先创建一个.env或者credentials.md文件把四个平台的凭证分类列好每行标注用途。我自己的模板大概是这样的# 飞书 FEISHU_APP_IDcli_xxxxxxxx FEISHU_APP_SECRETxxxxxxxx FEISHU_VERIFICATION_TOKENxxxxxxxx FEISHU_ENCRYPT_KEYxxxxxxxx # 钉钉 DINGTALK_CLIENT_IDding_xxxxxxxx DINGTALK_CLIENT_SECRETxxxxxxxx # QQOneBot ONEBOT_WS_URLws://127.0.0.1:3001 ONEBOT_ACCESS_TOKEN # 企业微信 WECOM_CORP_IDww_xxxxxxxx WECOM_AGENT_ID1000002 WECOM_SECRETxxxxxxxx WECOM_TOKENxxxxxxxx WECOM_ENCODING_AES_KEYxxxxxxxx注意一个细节钉钉新版的Client ID和旧版的AppKey是两回事新版接口要用Client ID很多人还在填旧版AppKey结果一直报认证失败。这个问题我在后文钉钉章节细说。密钥管理这块别懒。千万别把密钥直接硬编码到Openclaw配置文件里然后提交到Git仓库哪怕私有仓库也不行。用环境变量引用配置文件和密钥分离这是底线。3. 飞书接入实操3.1 创建自建应用拿到三串关键凭证飞书是四个平台里最接近“完整Agent体验”的因为它的消息类型丰富、API权限细、还有多维表格这类生态。接入的第一步是去飞书开放平台创建应用我走的是“企业自建应用”通道个人开发者也行流程类似。创建完应用后在“应用能力”里添加“机器人”能力这步很多人漏了。不添加机器人能力后面配了权限也等于零。然后去“权限管理”里开通消息相关的API权限至少要有这几个im:message读取消息、im:message:send_as_bot以机器人身份发送消息、im:message:receive_v1接收消息事件、im:resource如果需要收发图片/文件。飞书的权限是即开即用的不需要等审核这点比想象中省事。最后也是最关键的去“事件与回调”页面配置事件订阅。先说结论选“使用长连接接收事件”这能帮你省掉一台公网服务器的开销。飞书的长连接模式只需要你拿到Verification Token和Encrypt Key不需要填回调URL。订阅事件选择im.message.receive_v1含义就是用户给机器人发消息时触发。最终你会拿到三串东西App ID、App Secret、Verification Token、Encrypt Key严格说是四串但App ID和App Secret是一对的。App ID通常以cli_开头看到这个前缀就对了。3.2 在Openclaw里配置飞书渠道不同的Openclaw版本配置格式略有差异但核心字段是一样的。我用常见的YAML格式示例大家对照自己的配置文件填值channels: feishu: enabled: true app_id: cli_xxxxxxxx app_secret: xxxxxxxx verification_token: xxxxxxxx encrypt_key: xxxxxxxx event_type: im.message.receive_v1 # 长连接模式不用配回调地址配置完成后重启Openclaw然后去飞书里给机器人发一条“你好”正常情况下日志里会看到收到事件的记录随后机器人会回复。如果没回复先别急着怀疑配置去飞书开放平台的“事件订阅”页面看有没有报错记录这是排查的第一步。我踩过的一个坑是长连接模式下Encrypt Key不填也能连接但事件推送的内容是密文解析出来全是乱码。所以Encrypt Key宁可多填也不能空着。另外事件订阅里如果同时勾选了多个事件类型消息可能会重复推送建议只勾最基础的im.message.receive_v1。3.3 飞书高频问题发不了表格、报错权限不足飞书这块有两个问题被问得最多。第一个是机器人发送表格。飞书的文本消息msg_typetext确实不支持表格这是很多人的第一个误解。如果你只是想在对话里展示结构化数据正确的姿势是发富文本消息post类型它支持文本超链接然后用markdown样式来表达表格结构。如果想直接发送一个真正的表格文件那就把数据生成为CSV或XLSX走上传文件接口发出去。下面这个JSON是飞书post消息的基础结构发出去就是一张带格式的富文本卡片{ msg_type: post, content: { post: { zh_cn: { title: 今日任务执行结果, content: [ [{tag: text, text: 任务A}, {tag: text, text: 成功}], [{tag: text, text: 任务B}, {tag: text, text: 失败已重试3次}] ] } } } }第二个高频问题是报错提示没有权限或“CLI权限”。这个“CLI权限”其实指的就是命令行/API调用权限排查思路就三步确认机器人能力已开启确认im:message:send_as_bot权限已添加确认应用已经“创建版本并发布”。飞书的权限生效有一个细节应用未发布前只有你自己能看到但只要发布了权限就真正落地了。4. 钉钉接入实操4.1 钉钉机器人三种模式别选错钉钉的机器人体系有点绕因为它历史包袱重旧接口和新接口并存。简单分类的话有三种第一种是自定义机器人Webhook就是群里添加“自定义机器人”拿到一个Webhook地址往这个地址POST JSON就能在群里发消息。这个方案适合单向通知——发告警、发日报、发定时任务结果非常合适但只能发不能收用户没法跟机器人对话。第二种是企业内部机器人在钉钉开发者后台创建企业内部应用添加机器人能力。这种机器人才支持双向对话。如果在企业内部用依赖“Stream模式”这是钉钉官方推荐的长连接方案不需要公网IP和Openclaw配合非常顺。第三种是钉钉的流式机器人AI机器人这是钉钉面向大模型场景推出的新版机器人开通流程和接口跟传统内部机器人不太一样目前还在迭代中除非你专门研究那个否则普通用户接入Openclaw用第二种就够了。4.2 Stream模式接入步骤避开两个隐藏坑接入Stream模式需要在钉钉开发者后台创建一个“企业内部应用”。创建完成后在应用详情里找到“机器人”能力打开它然后选择StreamMode通信方式。这一步会生成两个关键值Client ID和Client Secret。注意这里的Client ID在新版钉钉开发平台里显示为“AppKey”Client Secret显示为“AppSecret”。很多教程沿用旧叫法让你填“AppKey”但Openclaw的配置项里写的是Client ID你直接把页面上的AppKey值填进去就行。但千万别去填旧版企业应用的AppKey那是老接口的凭证新接口完全认不了这是最经典的坑。配置示例channels: dingtalk: enabled: true client_id: ding_xxxxxxxx client_secret: xxxxxxxx mode: stream配置好后在钉钉里搜索你的应用机器人名称给它发条消息。Stream模式下消息会通过长连接主动推给Openclaw日志里看到receive message就能确认链路通了。还有一个隐藏坑钉钉企业内部应用默认的“服务器出口IP”白名单是空的但Stream模式不走服务器回调所以不用配。如果你同时用了HTTP回调才需要配这个白名单。4.3 钉钉高频问题Webhook文件大小限制、markdown格式长啥样钉钉的自定义Webhook机器人有个硬限制单条消息体积限制。文本消息全部内容加起来不能超过5000个字符超过会被静默丢弃接口不报错但消息就是发不出来。我调试告警时经常遇到这种“无报错丢失”排查起来特别恶心。解决方案是超长文本先做摘要或者拆成多条消息按顺序发。另一个关于Webhook文件大小的问题其实Webhook本身不能直接发文件只能发文本、markdown、链接卡片。要发文件得先调用钉钉的“上传媒体文件”接口把文件上传后拿到media_id再通过机器人消息接口发送。这个上传接口对文件大小有明确限制图片一般是10MB以内普通文件20MB左右具体数值以开放平台当前文档为准超出就需要先压缩。markdown格式是钉钉Webhook最常用的消息类型预警消息尤其常用。它的结构长这样{ msgtype: markdown, markdown: { title: 线上预警, text: ## 系统告警\n 主机web-01\n 状态**CPU使用率 95%**\n 时间2026-01-12 14:30:22\n\n **[查看监控面板](https://example.com)** } }注意钉钉的markdown只支持部分语法子集不支持HTML标签也不支持复杂的表格。实际测试下来标题、加粗、链接、引用、换行是稳定的表格和图片就别想了。5. QQ接入实操5.1 官方机器人和社区方案先分清路径QQ的接入是所有平台里最微妙的因为存在两条截然不同的路。一条是官方路径去QQ开放平台注册开发者账号创建机器人应用申请接入资格。这条路合规、稳定、有官方文档但对个人开发者不太友好申请门槛、审核周期、能力限制都让人头疼。如果你的场景是正式的对外服务走官方路径。另一条是社区路径通过OneBot 11标准协议配合NapCat等社区实现的协议端让一个普通QQ号以机器人形态响应Openclaw的消息。NapCat这类工具本质上是个人使用的接口封装部署简单、功能丰富但存在账号被风控的风险。这里必须多说一句社区方案有合规风险建议只在个人小号、测试环境下使用不要用于正式运营或骚扰他人账号安全需要自己承担。我不会展开讲任何绕过平台限制的内容大家自己评估。5.2 NapCat部署与OneBot接入用社区方案接入Openclaw链路是这样的NapCat负责和QQ服务器通信监听指定端口对外暴露OneBot标准的WebSocket接口Openclaw作为客户端连上去通过这个接口收发消息。部署NapCat并不复杂下载对应平台的运行文件启动后在配置界面设置WebSocket监听地址比如ws://0.0.0.0:3001然后扫码登录一个QQ号。登录成功之后NapCat窗口会显示连接状态这时Openclaw的QQ渠道就可以配置了channels: qq: enabled: true protocol: onebot ws_url: ws://127.0.0.1:3001 access_token: 这里的ws_url填的是NapCat监听地址如果Openclaw和NapCat在同一台机器用127.0.0.1就行如果分开部署填NapCat所在机器的局域网或公网地址。access_token是可选的安全凭证NapCat和Openclaw两边都留空也可以通但建议两边设置一致的token防止局域网内被其他人连上。配置好之后用登录的QQ号给自己发一条消息测试。能收到回复就说明链路通了。这里有个经验QQ场景下默认机器人只在被或者私聊时才应答这样不会打扰群聊。如果你希望群里所有消息都经过Openclaw处理需要额外把at_only配置项关掉但我建议开着不然群里聊天记录都会被模型读到又费token又没必要。5.3 QQ高频问题消息收不到、群聊不回复、连接闪断QQ接入最常见的现象是消息发出去但Openclaw没反应。排查顺序是先看NapCat窗口里有没有消息记录没有说明QQ号没登录成功或被风控有记录但Openclaw没反应说明WebSocket没连上重点检查ws_url地址对不对、端口通不通NapCat显示连接上了但还是不回复那就是Openclaw那边的事件类型没配对。群聊不回复的问题九成是触发条件没满足。默认情况下只有消息里包含机器人才会触发应答。你要确认Openclaw配置里的at_only和NapCat端的回复策略是匹配的两边标准不一致就会静默丢消息。连接闪断是另一个高频问题。OneBot的WebSocket如果长时间没有消息往来某些网络环境下会被中间设备掐断。解决方法是启用心跳机制NapCat和Openclaw两边都把心跳间隔设置到30秒以内保持连接活跃。我一开始没配心跳一晚上断三四次后来加了心跳就稳了。6. 企业微信接入实操6.1 自建应用AgentId和Secret怎么配企业微信接入Openclaw走的是“自建应用”路线。登录企业微信管理后台在“应用管理”里找到“自建”点击创建应用。创建完成后会拿到两个关键值AgentId和Secret。AgentId是一个数字标识这个应用Secret是密钥调用API时用来换access_token。还需要一个Corp ID在管理后台“我的企业”页面底部能看到以ww_开头。这三个值加起来就是企微应用API的完整凭证。接下来是配置“接收消息”回调。在自建应用的API页面里找到“接收消息”设置需要填三个东西URL、Token、EncodingAESKey。URL必须是公网可访问的HTTPS地址指向Openclaw暴露的企微回调接口。例如你的Openclaw域名是im.example.com回调路径是/wecom/callback那URL就填完整拼接后的地址。Token和EncodingAESKey可以自己生成这两个值在Openclaw里配置成一致就行。EncodingAESKey要求43位字符可以用平台自带的随机生成按钮直接生成别自己乱编。最后别忘了配置“企业可信IP”。企微在调用API时会校验来源IP必须把你服务器的公网IP加到应用的可信IP列表里否则接口调用直接报“not allow to access from your ip”。很多人接企微卡住的点就在这配置的URL能访问但API却一直401原因就是可信IP没加。6.2 企微的群ID怎么获取两个靠谱方法群里接机器人最常见的问题是“企微的群ID怎么获取”。很多人找遍了后台都没看到chatid在哪因为这个值不在页面上直接展示需要通过API或回调才能拿到。第一个方法通过回调事件拿ChatId。把自建应用配置好接收消息后在目标群里机器人发一条消息企微会推送一条XML格式的回调到你的回调URL里面就带着ChatId字段。这个方法最直接不用额外调API。第二个方法调用“获取群聊信息”接口。需要先获取access_token然后调用企微的客户联系相关接口。但要注意这个接口通常要求在“客户联系”里配置了对应的权限和secret自建应用默认不一定有权限。如果只是做单向通知还有一个更简单的方案直接在群里添加一个“群机器人”复制它的Webhook地址。这个Webhook里面带keyPOST过去就能往群里推消息不需要获取chatid。但群机器人Webhook只能发消息不能接收消息做双向对话。所以我的建议是双向对话用自建应用单向通知用群机器人两者按需混用。配置示例channels: wecom: enabled: true corp_id: ww_xxxxxxxx agent_id: 1000002 secret: xxxxxxxx token: xxxxxxxx encoding_aes_key: xxxxxxxx6.3 企微高频问题回调验证失败、消息乱码、URL不通企微回调的“URL验证”是个经典坑。你在后台保存URL时企微会向这个URL发一个GET请求附带msg_signature、timestamp、nonce、echostr参数你的回调接口需要正确解密echostr并原样返回才算验证通过。很多人第一次配置接口还没实现或者解密逻辑有bug保存时直接报错。排查思路是先确认URL公网可达、再确认Token和EncodingAESKey一致、最后看解密逻辑是否正确。消息乱码的问题大多是EncodingAESKey填错了。爆料这串密钥是大小写敏感的复制的时候多一个空格都不行。我建议从平台生成的原始值直接复制不要手打。URL不通的问题要区分两种情况本地没部署到公网或者企业可信IP没配。前者需要把Openclaw部署到有公网IP的服务器或者用内网穿透工具把本地端口暴露出去后者则回到6.1的可信IP配置。企微不像飞书有长连接方案这个平台绕不开回调URL所以公网访问是硬条件。7. 四平台联调与排查经验7.1 通用消息链路排查顺序四个平台全接完之后联调阶段最容易出的问题就是“分不清是哪一环断了”。我总结了一套通用的排查顺序遇到消息不通按这个顺序查基本能在五分钟内定位。第一步查IM平台侧。去飞书开放平台、钉钉开发者后台、企微管理后台看应用有没有报错日志QQ看NapCat窗口。平台侧有报错大概率是权限、密钥、白名单的问题。第二步查Openclaw日志。日志里如果能看到收到事件的记录说明链路前半段是通的如果完全没有记录说明事件压根没推过来问题在平台侧的订阅或回调配置。第三步查回复链路。收到消息但机器人没回复看日志里模型有没有正常返回再看发消息时有没有报错。飞书和钉钉的发送报错通常带着明确的HTTP状态码比如403就是权限不够400就是消息格式不对。第四步查消息格式。这是最后一步也是很多人忽略的一步。IM平台对消息格式的要求各不相同同一个JSON结构飞书能识别、钉钉可能报错、企微可能就是乱码。所以跨平台复用代码时一定要先确认目标平台的消息类型是否支持当前的payload结构。7.2 高频报错速查表四平台接完我把遇到过的典型问题和排查方向整理成了一张速查表建议收藏备用。现象可能原因排查方向401 unauthorized密钥填错或过期重新复制AppSecret/ClientSecretinvalid signature签名/加签计算错误检查时间戳、密钥拼接方式回调URL保存失败URL不可达或解密逻辑错误curl测试URL检查Token/EncodingAESKey消息发送成功但无内容消息格式不受支持检查msgtype和payload结构只能收消息不能回复缺少发送权限飞书检查send_as_bot权限群聊不触发回复触发条件限制检查at_only配置、是否机器人API报错not allow ip服务器IP未加入白名单企微添加可信IP、钉钉添加出口IP消息重复推送订阅了多个事件只保留一个消息事件订阅这张表看着简单但每一条背后都是我熬夜排过的雷。尤其是“消息重复推送”这个坑飞书里如果同时订阅了im.message.receive_v1和im.message.message_read_v1同一句话可能被推两次Openclaw就会回两次非常尴尬。只勾选需要的、最少的事件类型是避免这类问题的根本办法。7.3 多平台并行的三条经验最后分享三条我跑通四个平台后的个人经验。第一条凭证必须集中管理。四个平台加起来十几串密钥散落在各个配置文件里迟早会出乱子。我最后把所有密钥统一放到了环境变量文件里Openclaw的配置也改成引用环境变量这样换服务器、换环境只需要改一个文件。第二条配一个平台就测一个平台。不要四个平台全部配完再统一测试。每配完一个立刻发一条消息验证链路确认没问题再配下一个。否则四个平台一起出问题时你根本不知道先去查哪个。我用这个策略四平台串下来总共花了一个多小时中途基本没遇到需要回溯的配置错误。第三条给自己留一个调试入口。我建议Openclaw里保留一个最简单的文本回复逻辑任何渠道收到“ping”都回“pong”作为最基本连通性验证。这样后面改造消息处理逻辑时随时能快速验证每个IM渠道还是不是通的不至于改完代码要拿着四个APP轮流点一遍。最后再说几句这个系列我还会继续写后面打算记Openclaw的多账号隔离、工具调用、定时任务这些。最后分享一点个人体会四平台并行接入这件事难度不在任何一个单独平台而在跨平台的配置迁移和排错思维。飞书的密钥、钉钉的Stream、企微的可信IP这些细节单看都不难难的是同时记住它们各自的规则。我自己是飞书做主力对话、钉钉收告警、企微接公司群、QQ留作个人测试目前稳定跑了两周多没出过大问题。限于篇幅很多平台细节没法在一篇里全部展开——比如飞书的多维表格、钉钉的审批流联动、企微的客户群运营这些每个都能单独写一篇。你如果正好卡在某个平台的接入环节照着上面的配置过一遍绝大多数问题都在权限和密钥这两个地方。如果还搞不定把日志翻出来逐行看IM平台的回调记录加上Openclaw的日志基本就能锁死问题位置。祝大家接入顺利。