Agent 报错不求人：20 个最常见错误的排查手册

整理了群里被问最多的 20 个 Agent 报错，覆盖 Dify、Coze、QClaw、OpenClaw、Hermes 五大平台。建议收藏。 🔴 Dify 类： 1. 「知识库检索不到」→ 切混合检索 + 调低分数阈值 + 增大 Top K 2. 「模型调用失败」→ 检查 API Key 是否到期 / 额度是否用完 3. 「工作流节点报错」→ 检查上一个节点的输出格式是否匹配 4. 「Webhook 无响应」→ 检查 URL 是否正确 + 防火墙是否放行 🔴 Coze 类： 5. 「插件加载失败」→ 检查网络，部分插件需要科学环境 6. 「发布到微信失败」→ 确认微信服务号已认证 + Bot 状态为「已发布」 7. 「知识库更新后不生效」→ 重建索引 + 清除缓存 8. 「回复速度突然变慢」→ 检查是否被限流，免费版有 QPS 限制 🔴 QClaw 类： 9. 「微信绑定失败」→ 用微信App扫码（不是截图），确认电脑管家已安装 10. 「技能安装失败」→ 关闭杀毒软件重试 11. 「Gateway 掉线」→ 重启 QClaw + 检查网络 12. 「任务执行到一半卡住」→ 任务超时，拆成多个小任务 🔴 OpenClaw 类： 13. 「npm install 失败」→ Node.js 版本不对，需 ≥ 18 14. 「command not found」→ 关掉终端重新打开 15. 「API Key 认证失败」→ Key 前后有空格 / Key 已过期 16. 「微信插件连接失败」→ 重新扫码，确认是手机App扫 🔴 Hermes 类： 17. 「安装脚本下载失败」→ 用国内镜像 res1.hermesagent.org.cn 18. 「wsl --install 报错」→ 以管理员身份运行 PowerShell 19. 「hermes: command not found」→ 执行 source ~/.bashrc 20. 「模型调用返回空」→ API Key 配置有误，执行 hermes doctor 诊断 💡 终极解决方案：把完整报错信息复制给 ChatGPT 或 Kimi，95% 的问题AI都能帮你定位。