WorkBuddy接入飞书群机器人教程

本文详细解析了WorkBuddy接入飞书群机器人时常见“无响应”问题的系统性排查与配置方案，聚焦Webhook地址精准填写、Verification Token与Encrypt Key双向严格同步、HTTPS回调地址公网可达性验证，以及飞书群内机器人安全校验启用四大关键环节，手把手指导用户快速定位网络、密钥、权限和平台设置中的隐性断点，助你彻底打通WorkBuddy与飞书的消息通路，让自动化协作真正落地生效。

如果您已在飞书创建应用并启用机器人能力，但WorkBuddy无法响应群内指令或收不到消息，则极可能因Webhook地址未正确配置或安全校验参数不匹配所致。以下是解决此问题的具体操作路径：

一、配置飞书端Webhook地址与启用事件订阅

该步骤确保飞书平台明确知道将群消息事件推送至WorkBuddy服务端的唯一入口，并激活事件转发通道。

1、登录飞书开放平台（https://open.feishu.cn/），进入已创建的WorkBuddy企业自建应用详情页。

2、在左侧菜单栏中点击「事件订阅」，确认「启用事件订阅」开关处于开启状态。

3、在「请求URL」输入框中，粘贴WorkBuddy官方生成的完整Webhook地址，格式必须为：https://workbuddy.codebuddy.cn/api/v1/feishu/webhook?token=xxx，不得增删任何字符或参数。

4、点击「重新生成」Verification Token与Encrypt Key，获取最新密钥对。

5、勾选需监听的事件类型，至少包含：message.receive、im.message.group_at_msg.read、im.message.pins.read。

二、同步Token与Encrypt Key至WorkBuddy控制台

该步骤确保WorkBuddy服务端能通过飞书签名验证机制识别合法请求，避免因密钥不一致导致401错误或消息丢弃。

1、打开WorkBuddy客户端，点击右上角个人头像 →「Claw 设置」→「飞书集成」页签。

2、清空当前「Verification Token」与「Encrypt Key」字段中的全部内容，包括隐藏空格与换行符。

3、将飞书开放平台「事件订阅」页新生成的Verification Token完整复制，粘贴至对应输入框。

4、同理，将新生成的Encrypt Key完整复制并粘贴至「Encrypt Key」字段。

5、点击「保存配置」，系统将立即校验密钥有效性并刷新本地缓存。

三、验证Webhook地址连通性与HTTPS可用性

该步骤用于排除网络层拦截、证书过期或反向代理配置错误等基础设施问题，确保飞书可成功发起HTTP POST请求。

1、在本地终端执行以下命令，测试回调地址是否可达且返回200状态码：

curl -I -X POST "https://workbuddy.codebuddy.cn/api/v1/feishu/webhook?token=xxx"

2、若返回HTTP/2 405或HTTP/2 400，说明服务端已接收到请求，Webhook地址有效；若返回Failed to connect或超时，则需检查服务器防火墙、Nginx反向代理SSL配置及域名DNS解析。

3、确认WorkBuddy部署服务器出口IP已加入飞书自定义机器人「IP白名单」，白名单地址须为纯IPv4格式，无端口、无协议头，如：192.168.1.100。

4、若使用CDN或WAF，需放行飞书请求源IP段（如：110.242.0.0/16、112.124.0.0/16等），并关闭对X-Request-ID或X-Feishu-Signature头的清洗策略。

四、启用飞书群内安全设置并绑定机器人

该步骤确保群聊侧具备接收和触发Webhook事件的权限基础，防止因群机器人未启用或校验方式不兼容导致消息静默丢失。

1、进入目标飞书群聊，点击右上角「更多」→「设置」→「群机器人」→「添加机器人」。

2、选择「自定义机器人」，填写名称（如WorkBuddy-正式环境），并勾选「启用安全设置」。

3、安全校验方式选择「密钥校验」，在密钥输入框中填入与WorkBuddy控制台一致的Verification Token值。

4、确认「允许机器人发送消息」与「允许@机器人」两项权限已开启。

5、点击「完成」后，复制该机器人专属Webhook地址，再次核对是否与WorkBuddy后台配置的全局Webhook地址完全一致。

今天带大家了解了的相关知识，希望对你有所帮助；关于科技周边的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~