03 常见报错与排查
文档摘要
03 常见报错与排查 本节摘要:这是全书最后的检索表,用「报错 → 原因 → 解决」三列给出最常踩的坑。按主题分类:安装与平台、认证与权限、模型调用、会话与压缩、MCP 与扩展。遇到报错先查这里。 一、安装与平台类 报错 | 原因 | 解决 非法指令(启动即崩) | 平台包选错(AVX2 装到不支持 AVX2 的 CPU) | 重新探测或强制 baseline 版 找不到符号 | libc 不匹配(musl/gnu) | 选对 libc 版本 找不到模块 | 用错包管理器(非 pnpm)或依赖没装全 | 用 pnpm 重装 node-gyp 失败 | 缺编译工具链(原生依赖) | Windows 装 VS Build Tools 启动慢/卡 | 前端栈重 + 原生依赖编译 |
03 常见报错与排查
本节摘要:这是全书最后的检索表,用「报错 → 原因 → 解决」三列给出最常踩的坑。按主题分类:安装与平台、认证与权限、模型调用、会话与压缩、MCP 与扩展。遇到报错先查这里。
一、安装与平台类
| 报错 | 原因 | 解决 |
|---|---|---|
| 非法指令(启动即崩) | 平台包选错(AVX2 装到不支持 AVX2 的 CPU) | 重新探测或强制 baseline 版 |
| 找不到符号 | libc 不匹配(musl/gnu) | 选对 libc 版本 |
| 找不到模块 | 用错包管理器(非 pnpm)或依赖没装全 | 用 pnpm 重装 |
| node-gyp 失败 | 缺编译工具链(原生依赖) | Windows 装 VS Build Tools |
| 启动慢/卡 | 前端栈重 + 原生依赖编译 | 耐心等首次安装 |
二、认证与权限类
| 报错 | 原因 | 解决 |
|---|---|---|
| 认证失败 / 401 / 403 | API Key 未设 / 错变量名 / 失效 | 核对凭据与环境变量名 |
| 权限被拒(DeniedError) | 权限规则为 deny | 改规则或换 Agent |
| 反复询问很烦 | 太多操作规则是 ask | 把确信安全的改 allow(别滥用) |
| 工具不可见 | 权限可见性过滤隐藏 | 检查 Agent 权限规则 |
三、模型调用与流式类
| 报错 | 原因 | 解决 |
|---|---|---|
| 一直转圈/超时 | 网络到不了端点 | 检查网络/代理/防火墙 |
| 流式响应解析失败 | 协议不匹配 | 检查 Provider/协议配置 |
| provider-error | 厂商返回错误(配额/限流/参数) | 看错误详情,对症处理 |
| 模型行为异常 | 工具集不匹配(如该用 apply_patch 却用 edit) | 检查按模型过滤是否对 |
四、会话与压缩类
| 报错 | 原因 | 解决 |
|---|---|---|
| 上下文超窗口 | 没自动压缩或关了 | 开启自动压缩,别关 |
| Agent 忘事 | 压缩有损 | 用记忆库补长期记忆(OpenWork 教程) |
| 签名失败 | 原生消息被切割(理论不该发生) | 报告 bug,这是硬约束 |
| 换项目后失忆 | 移动会话清空纪元 | 正常现象,重新建立上下文 |
五、MCP 与扩展类
| 报错 | 原因 | 解决 |
|---|---|---|
| MCP 连不上 | 传输/认证问题 | 查状态(connected/failed/needs_auth) |
| needs_auth 卡住 | OAuth 未完成 | 走浏览器登录流程 |
| MCP 工具不可见 | 权限过滤或 server 未提供工具 | 查权限 + server 工具列表 |
| 自定义工具不生效 | 未被动态导入或语法错 | 检查工具目录/文件格式 |
| 技能不显示 | 权限过滤或 frontmatter 缺 name | 检查 SKILL 格式 |
| 插件钩子没触发 | 插件未加载或钩子名错 | 检查插件安装 + 钩子名 |
六、嵌入式与 SDK 类
| 报错 | 原因 | 解决 |
|---|---|---|
| 嵌入式调不通 | in-memory fetch 配置错 | 检查 create() 配置 |
| 客户端类型不符 | 用错客户端(Promise/Effect) | 按项目架构选对客户端 |
| 行为和 serve 不一致 | 理论不该发生(同一客户端+路由) | 报告 bug |
七、排查通用思路
遇到任何报错,按这个顺序排查通常最快:
1. 看报错信息本身(往往直接指出问题) │ 2. 查本表对应类别 │ 3. 看事件流(`--format json`)定位是哪一步 │ 4. 看 OpenTelemetry 追踪(复杂问题) │ 5. 查对应章节深读原理
八、本节要点回顾
- 六大类报错:安装平台 / 认证权限 / 模型调用 / 会话压缩 / MCP扩展 / 嵌入式SDK。
- 三列格式:报错 → 原因 → 解决,快速定位。
- 安装类首查平台包:非法指令/找不到符号多半是平台不匹配。
- 认证类首查凭据:Key 是否设对、变量名是否对。
- 会话类别关压缩:超窗口多半因关了自动压缩。
- 排查思路:报错信息 → 本表 → 事件流 → 追踪 → 章节。
附录 A 到此结束。全书(十三章 + 附录)正文与检索表全部完成。
评论区
(0)
U