报错源于飞书配置与WorkBuddy凭证不匹配、权限缺失或网络拦截；需依次检查飞书基础配置、验证Webhook地址与Token、修正WorkBuddy端凭证、排查防火墙与HTTPS证书、必要时重置飞书应用。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在将WorkBuddy接入飞书时遇到报错提示，例如“机器人未启用”“回调地址验证失败”或“400/401/500错误”，通常源于飞书应用配置项与WorkBuddy服务端凭证不匹配、权限缺失或网络策略拦截。以下是解决此问题的步骤：
一、检查飞书自建应用基础配置
该步骤用于确认飞书侧应用元信息是否完整且符合WorkBuddy对接要求，避免因基础字段缺失导致签名验证或事件订阅失败。
1、登录飞书开放平台，进入「企业自建应用」列表，找到已创建的WorkBuddy应用。
2、点击「基本信息」，核对「应用名称」是否含非法字符（如空格、斜杠），必须与WorkBuddy控制台中填写的机器人名称完全一致。
3、在「机器人」模块下，确认「机器人名称」和「头像」已保存；若未点击「保存」，后续所有配置均不生效。
4、检查「应用可见范围」是否设置为「本企业全部成员」或包含当前调试账号的部门/角色；范围过窄会导致飞书无法向WorkBuddy推送事件。
二、验证Webhook回调地址与Token密钥
该步骤用于排除因回调地址不可达或签名密钥不一致引发的400/401错误，确保飞书能成功将消息投递至WorkBuddy服务端并完成双向认证。
1、在飞书应用「事件订阅」页面，查看「启用事件订阅」是否已开启；关闭状态下所有事件（如消息、卡片提交）均不会触发WorkBuddy响应。
2、核对「请求URL」是否为WorkBuddy官方生成的唯一回调地址（格式形如 https://workbuddy.codebuddy.cn/api/v1/feishu/webhook?token=xxx），不得手动修改参数或添加路径后缀。
3、点击「重新生成」获取最新Verification Token与Encrypt Key，立即同步至WorkBuddy控制台对应配置项，旧Token即时失效。
4、使用curl命令本地测试回调地址连通性：
curl -I -X POST "https://workbuddy.codebuddy.cn/api/v1/feishu/webhook?token=xxx"
三、修正WorkBuddy端机器人凭证绑定
该步骤用于修复因凭证粘贴错误、版本不匹配或缓存残留导致的鉴权失败，确保WorkBuddy能正确识别并响应飞书发来的加密事件。
1、打开WorkBuddy客户端，进入「设置」→「集成」→「飞书」页签。
2、清空当前已填的App ID、App Secret、Verification Token、Encrypt Key四项字段；严禁复制飞书后台带换行或空格的密钥值。
3、逐项从飞书开放平台「凭证与基础信息」页严格复制粘贴，App Secret需勾选「显示」后再复制，否则为掩码状态。
4、点击「测试连接」按钮，观察返回结果：若提示「签名验证通过」，说明凭证有效；若提示「密钥不匹配」，需重新执行第2–3步。
四、排查企业防火墙与HTTPS证书问题
该步骤用于定位因网络中间件拦截、SSL证书不可信或域名解析异常引发的500/502/504错误，保障飞书服务器与WorkBuddy服务端通信链路畅通。
1、确认WorkBuddy服务运行主机可被公网访问：在另一台设备浏览器中直接访问回调URL，应返回HTTP 200及JSON格式{"code":0,"msg":"ok"}；返回连接超时或SSL_ERROR_BAD_CERTIFICATE即为证书或代理问题。
2、若使用Nginx/Apache反向代理，检查配置中是否启用strict-transport-security（HSTS）且证书由受信CA签发；飞书强制要求回调域名具备有效DV或OV证书，自签名证书必然失败。
3、检查企业出口防火墙是否屏蔽了飞书IP段（参考飞书官方文档最新IP白名单），未放行会导致飞书服务器无法发起POST请求，日志中仅显示“无请求到达”。
4、在WorkBuddy日志目录（默认C:/User/WorkBuddy/Claw/logs/）中检索feishu字样，定位最近一条ERROR级记录，提取trace_id后联系腾讯CodeBuddy技术支持提供原始报文。
五、重置飞书应用并重建机器人实例
该步骤用于彻底清除因历史配置冲突、权限缓存污染或应用状态异常导致的深层故障，适用于前四步均无效的顽固性报错场景。
1、在飞书开放平台进入该应用「设置」→「停用应用」，确认停用操作完成。
2、等待5分钟后，点击「删除应用」，输入企业管理员密码完成永久移除；删除后原App ID与凭证全部作废，不可恢复。
3、重新执行「创建企业自建应用」流程，严格按WorkBuddy官方文档要求选择「机器人」类型，并在「权限管理」中勾选「发送消息」「读取群信息」「接收消息事件」三项最小必要权限。
4、完成新应用创建后，在「机器人」页点击「添加机器人」，填写名称并获取全新凭证，再同步至WorkBuddy端完成绑定与测试。
