主题
12.3 故障排查手册
症状 → 诊断 → 修复。按现象快速定位。
用法：遇到问题先在这里搜症状，链接指向对应章节的详细方案。
一、输出质量问题
| 症状 | 最可能原因 | 修复 | 详见 |
|---|---|---|---|
| 输出有幻觉/编造 | 没强制引用/验证 | 强制引用 + 执行验证 | 04.3 |
| API 调用参数错 | 凭记忆写 | 强制查文档/读示例 | 04.3 |
| 给的是过时信息 | 训练截止 | 强制先搜索 | 04.3 |
| 不遵守输出格式 | 格式约束被稀释 | 末尾重申格式 | 04.2 |
| 越到后面越不听话 | 自我示范 + 指令衰减 | 早纠正/清上下文 | 04.2 |
| 输出泛泛而谈 | 上下文太满/太模糊 | 清理 + 具体化 | 03.1 |
| 想太多/过度工程 | 没界定复杂度 | 明确"简单任务" | 02.5 |
二、会话问题
| 症状 | 原因 | 修复 | 详见 |
|---|---|---|---|
| 会话越来越慢 | 上下文太长 | /context 检查 → /compact | 03.4 |
| 忘了早期约束 | 指令衰减 | 提升到 CLAUDE.md / 重申 | 04.2 |
| 上下文被污染 | 错误方向留在历史 | /rewind 或 [Edit] | 03.4 |
| 压缩后丢了关键信息 | 口头约定没固化 | 压缩前写进 CLAUDE.md | 03.4 |
| 长任务续不上 | 状态只在上下文 | 用外部 PROGRESS.md | 03.4 |
三、Claude Code 安装/环境
| 症状 | 诊断 | 修复 | 详见 |
|---|---|---|---|
command not found: claude | PATH 问题 | claude doctor 查 PATH | 05.1 |
| 登录后仍提示未认证 | token 问题 | claude auth status → 重登 | 05.1 |
| 设置不生效 | JSON 错误/被覆盖 | claude doctor + 查优先级 | 06.8 |
| 配置神秘失效 | 某自定义搞坏了 | claude --safe-mode 排查 | 06.8 |
| 多个 claude 冲突 | 重复安装 | claude doctor 检测 | 05.1 |
四、CLAUDE.md 不生效
| 症状 | 诊断 | 修复 | 详见 |
|---|---|---|---|
| 它不遵守 CLAUDE.md | 没加载/太模糊/有矛盾/需硬约束 | /context 看是否加载 → 具体化 → 用 hook | 05.6 |
| 加载了但还是不听 | 它是"上下文"不是"配置" | 需 100% 的用 hook | 05.6 |
/compact 后指令丢了 | 只在对话里说过 | 写进 CLAUDE.md | 05.6 |
| CLAUDE.md 太占上下文 | 太长 | /doctor 精简，长内容改 Skill | 05.6 |
五、权限与安全
| 症状 | 原因 | 修复 | 详见 |
|---|---|---|---|
| 每步都要批准，很烦 | 没配 allow 规则 | 配 allow / Shift+Tab 切模式 | 05.5 |
| 它想做危险操作 | 没配 deny | 加 deny 规则 | 05.5 |
| 想禁止但提示词没用 | 提示词是概率性的 | 用 deny 规则/hook | 06.5 |
| "组织策略禁止" | 企业管控 | 联系管理员 | 10.3 |
六、MCP / 连接器
| 症状 | 原因 | 修复 | 详见 |
|---|---|---|---|
| 授权了但"没权限" | 工具没加载 | /mcp 查状态，重启/重连 | 01.6 |
| 工具在但调用失败 | token 过期 | claude mcp login <name> | 07.3 |
| 工具太多变慢 | 定义占满上下文 | 启用 tool search | 07.5 |
| 它不主动用连接器 | 没触发 | 显式指明用哪个工具 | 01.6 |
| 担心注入 | 读了外部内容 | 数据边界声明 + 只读 | 07.3 |
七、Skill 问题
| 症状 | 原因 | 修复 | 详见 |
|---|---|---|---|
| 技能该触发没触发 | description 不好 | 补触发词和场景 | 08.3 |
| 技能到处误触发 | description 太宽 | 加边界词/禁自动触发 | 08.3 |
| 改了技能没生效 | 没重载 | /reload-skills | 08.1 |
| 技能太占上下文 | 正文太长 | 长内容移到第 3 层 | 08.4 |
八、Artifacts（网页版）
| 症状 | 原因 | 修复 | 详见 |
|---|---|---|---|
| 工件白屏 | 用了 localStorage | 换 useState | 01.4 |
| 样式不生效 | Tailwind 任意值语法 | 用预设类/内联 style | 01.4 |
| 组件不渲染 | 有必填 props | 加默认值 | 01.4 |
| 内容没变工件 | 属于列表/解释类 | 显式要求生成 artifact | 01.4 |
九、CoWork 问题
| 症状 | 原因 | 修复 | 详见 |
|---|---|---|---|
| 找不到我的文件 | 没挂载对文件夹 | 确认挂载目录 | 09.2 |
| 生成的文件不见了 | 在临时区 | 让它放挂载文件夹并给路径 | 09.2 |
| 文档质量差 | 研究阶段没做好 | 先扎实收集内容 | 09.3 |
| 读取很慢 | 云同步文件在下载 | 减少一次处理数量 | 09.2 |
十、成本问题
| 症状 | 原因 | 修复 | 详见 |
|---|---|---|---|
| 额度消耗太快 | 上下文太长/模型太贵 | 精简 + 降模型 + /clear | 03.5 |
| 不知道钱花哪了 | /usage 按类别看 | 01.5 | |
| 子代理停不下来 | 无上限 | --max-budget-usd | 06.6 |
通用排查心法
text
1. 先看现象属于哪一类（输出/会话/配置/权限/MCP/成本）
2. 输出问题 → 先问"上下文干净吗"，再问"约束具体吗"
3. 配置问题 → claude doctor + --safe-mode
4. "它不听话" → 区分"倾向"（改提示词）和"必须"（用 hook）
5. 实在不行 → /feedback 反馈，或点踩