openclaw-lark 故障排查完全手册diagnose、doctor 诊断命令与常见错误速查表【免费下载链接】openclaw-lark飞书官方出品的 OpenClaw 飞书/Lark Channel 插件项目地址: https://gitcode.com/gh_mirrors/op/openclaw-larkopenclaw-lark是飞书官方出品的 OpenClaw 飞书/Lark Channel 插件可让 Agent 直接收发飞书消息、读写文档、多维表格、日历与任务。当机器人不回复、授权反复失败或报权限错误时无需翻源码——插件内置了/feishu doctor与/feishu_diagnose两套诊断命令配合一份常见错误码速查表几分钟即可定位绝大多数问题。本文就是这本排查手册。什么时候需要打开排查工具箱 以下三种情况请直接使用诊断命令机器人多次授权后仍然报错自动授权流程没跑通消息发出去后无反应、卡片卡住、流式输出中断想一次性看清应用权限 用户授权的完整状态。 常规权限问题会自动触发授权流程无需手动诊断诊断命令主要针对疑难杂症。4 个核心命令速查一键定位问题命令在飞书聊天会话中直接输入即可详见 src/commands/index.ts 中的命令注册逻辑命令作用输出形式/feishu doctor深度诊断环境 应用权限 用户权限Markdown 报告含权限对照表和一键申请链接/feishu_diagnose全局体检Node 版本、账户、连通性、工具注册、最近错误日志纯文本报告HEALTHY / DEGRADED / UNHEALTHY/feishu auth批量发起用户权限授权仅限应用 owner授权卡片/feishu start启动前校验插件配置通过 / 警告 / 失败/feishu help查看全部子命令帮助文本第一步用 /feishu doctor 出诊断报告/feishu doctor是主力工具它会按账户逐项检查并生成 Markdown 报告实现见 src/commands/doctor.ts。报告会包含 4 大板块报告四大检查板块环境信息检查凭证完整性appSecret 自动打码、账户启用状态、API 连通性调用bot/v3/info探测见 src/channel/probe.ts工具配置检查检查tools.profile是否为minimal/coding/messaging等精简档——精简档下飞书工具可能无法加载应用身份权限检查列出缺少的必需权限scope并生成一键申请链接管理员点击即可去开放平台开通用户身份权限检查显示 Token 状态✓ 有效 / ⟳ 需刷新 / ✗ 已过期、Token 自动刷新offline_access是否开启以及一张权限对照表——逐项对比应用已开通与用户已授权两列。常见警告与一键修复方法看到 ⚠️/❌ 别慌报告里通常自带修复命令。高频场景速查报告提示原因修复方法❌ 旧版插件未禁用新旧插件冲突openclaw config set plugins.entries.feishu.enabled false --json然后openclaw gateway restart⚠️ 工具 Profile 当前为minimal等精简档未加载飞书工具openclaw config set tools.profile full然后openclaw gateway restart❌ 缺少 N 个必需权限应用 scope 未开通点报告中的申请链接由应用管理员在开放平台开通并发布新版本⚠️ 暂无用户授权尚无用户 OAuth 授权属正常提示用户首次使用需要用户身份的功能时会自动触发授权✗ 未开启 Token 自动刷新缺少offline_accessToken 2 小时后过期开通offline_access后让用户发送/feishu auth重新授权第二步用 /feishu_diagnose 做全局体检/feishu_diagnose实现见 src/commands/diagnose.ts偏向系统级体检一次跑完环境Node.js 版本 18 会告警官方建议 Node.js v22、插件版本、系统架构账户飞书账户数量、逐个账户的凭证 / 启用状态 / API 连通性 / Bot 信息 / 应用权限 / 品牌配置工具注册当前注册了哪些飞书工具文档、多维表格、任务、日历等最近错误自动读取~/.openclaw/logs/gateway.log末尾 256KB提取最近 20 条 error/warn 日志。最后给出总体状态HEALTHY健康、DEGRADED存在警告、UNHEALTHY存在失败项。向官方反馈问题时直接贴这份报告即可。第三步消息不响应按 message_id 追踪处理链路 ️机器人吞消息是最难查的问题之一。插件会在日志中为每条消息打上[msg:{messageId}]标签diagnose模块内置了按 message_id 追踪与自动异常分析能力见 src/commands/diagnose.ts。分析器会还原完整时间线并自动检测 5 类异常缺失阶段正常链路应为「消息接收 → 分发到 Agent → 卡片创建 → 卡片发送 → 流式输出 → 处理完成 → 回复收尾」缺哪步即定位到哪步性能超时接收→分发超 0.5s、分发→建卡超 5s、建卡→首次流式输出超 30s 会给出警告重复投递同一条消息被 WebSocket 重投递多次流式 seq 不连续卡片流式更新中断或丢帧错误事件rejected消息被拒、reply error、tool fail、CardKit 非 0 错误码等。 手动排查时日志文件固定在~/.openclaw/logs/gateway.log用grep msg:你的message_id即可取出完整链路。常见错误码速查表 ⚡错误码常量集中在 src/core/auth-errors.tsLARK_ERROR统一错误处理见 src/core/api-error.ts。遇到报错先对号入座错误码 / 关键字含义解决办法99991672应用 scope 不足应用缺少所需 API 权限插件会自动给出权限名 授权链接管理员到开放平台开通并发布新版本99991679用户 scope 不足用户 Token 权限不够向机器人发送/feishu auth重新授权99991668/99991677access_token 无效 / 已过期插件会尝试自动刷新重试仍失败则/feishu auth重新授权20026/20037/20064/20073refresh_token 无效 / 过期 / 被吊销 / 已使用均指向同一动作重新走/feishu auth授权流程230011/231003消息已被撤回 / 已删除属正常终止场景插件会自动停止对该消息的操作无需修复API 连通性: 连接失败appId/appSecret 错误、网络不通或凭证缺失核对飞书开放平台应用凭证检查服务器到飞书开放平台的网络无法查询应用权限状态缺少核心权限application:application:self_manage管理员在开放平台开通该权限后重试FAQ高频问题一问一答Q1点击卡片按钮没反应然后报错应用未开通「消息卡片回传交互」能力。登录飞书开放平台 → 选择应用 →事件与回调→ 订阅方式改为长链接并添加回调card.action.trigger→ 创建应用版本、提交审核并发布完整步骤见 skills/feishu-troubleshoot/SKILL.md。Q2诊断提示未找到已启用的飞书账户说明 OpenClaw 配置里还没有配置/启用飞书账户请在配置文件中补全appId、appSecret并启用后重启 gateway。Q3授权成功了但功能还是不行大概率是应用权限开了用户权限没授权。跑一次/feishu doctor看权限对照表里用户已授权列的 ❌ 项然后发送/feishu auth补齐。Q4环境版本要求Node.jsv22node -v查看OpenClaw 版本需2026.2.26openclaw -v查看不满足请先升级。相关模块路径一览 模块路径诊断命令文本报告 消息追踪src/commands/diagnose.tsDoctor 诊断Markdown 报告src/commands/doctor.ts命令注册入口src/commands/index.ts批量授权命令src/commands/auth.ts错误码常量与错误类型src/core/auth-errors.ts统一 API 错误处理src/core/api-error.tsAPI 连通性探测src/channel/probe.ts问题排查技能FAQ 诊断指引skills/feishu-troubleshoot/SKILL.md排查心法先/feishu doctor看权限 → 再/feishu_diagnose看环境 → 查消息吞了没就用 message_id 追链路 → 报错对码查上表。四步走完99% 的飞书插件问题都能自行解决。【免费下载链接】openclaw-lark飞书官方出品的 OpenClaw 飞书/Lark Channel 插件项目地址: https://gitcode.com/gh_mirrors/op/openclaw-lark创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考