自学教程

Claude Code 排错指南

Claude Code 教程

简介

本指南用于排查 Claude Code 在本地开发、IDE、CLI 使用时遇到的各类异常。
排查通用思路：先看日志 → 核对配置优先级 → 检查权限 → 验证网络/API Key → 缩小会话上下文。

配置优先级回顾：命令行参数 > 环境变量 > 项目 .claude/config.json > 全局用户配置。

前置准备

  1. 开启调试日志：CLAUDE_CODE_LOG_LEVEL=debug
  2. 准备斜杠命令：/config（查看当前生效配置）、/reset（重置会话）
  3. 确认：已安装对应版本 Claude Code，API Key 有效

一、API 连接与鉴权类问题

1. 报错：Invalid API key / 401 Unauthorized

现象：启动会话直接鉴权失败，无法发起模型请求。
原因：

  • API Key 填写错误、复制带空格换行
  • 密钥过期、额度耗尽
  • 环境变量没有正确加载
    排查：
  1. 执行 /config，确认读取到的 ANTHROPIC_API_KEY 是否正确
  2. 单独用 curl 测试密钥连通性，验证密钥本身是否可用
  3. Windows：环境变量修改后重启 IDE / 终端；macOS/Linux 重新 source .env
    解决：去除密钥前后空白字符，更换有效密钥；检查是否达到月度Token限额。

2. 报错：429 Too Many Requests

现象：请求被限流，提示请求速率超限。
原因：并发太高、短时间大量工具调用，超出Anthropic密钥RPM配额。
解决：

  1. 降低会话并行任务数量，减少子代理并发
  2. 开启重试（内置指数退避）
  3. 拆分任务，分批执行；等待冷却后重试

开发环境建议限制 maxToolTurns，避免短时间批量调用触发限流。

3. 网络超时 / connect timeout

现象：请求长时间卡住，最后超时失败。
原因：本地网络无法访问Anthropic服务，代理配置异常。
排查：

  1. 终端测试能否连通API地址
  2. 检查系统代理、IDE代理设置
    解决：修正网络代理；调高 SDK_REQUEST_TIMEOUT；或者切换网络环境。

二、配置加载异常

1. 修改 config.json / CLAUDE.md 不生效

现象：改完配置，但是 Claude Code 行为不变。
原因：

  • 配置文件语法错误（JSON逗号缺失）
  • 环境变量覆盖了配置文件参数
  • IDE/CLI会话没有重启，仍在使用旧会话上下文
    排查：运行 /config，查看当前生效值，判断是哪一层配置生效。
    解决：修复JSON语法；重启会话（/reset）；重启IDE。

2. .claude/ignore 不生效，仍然读取忽略文件

现象：Claude Code 读取 .env、密钥文件、node_modules。
原因：.claude/ignore 文件路径不对、语法错误；.gitignore 不会自动继承。
解决：

  1. 确认文件放在 ./.claude/ignore
  2. 写入规则：
.env
*.env
node_modules/
  1. 执行 /reset 重置会话。

三、文件与权限类报错

1. Permission denied，无法读写文件

现象：工具调用时报文件读写权限拒绝。
原因：

  • 进程没有项目目录读写权限
  • 在配置中关闭了 write 权限
  • 路径被 .claude/ignore 拦截
    排查：/config 查看 permissions 配置；检查操作系统文件权限。
    解决：修改项目目录权限；开启配置里 permissions.write: true；移除ignore匹配规则。

2. Bash 命令执行失败

现象：调用bash工具提示禁止执行。
原因：默认开发环境 permissions.bash:false，关闭shell权限（安全默认）。
解决：

  • 临时：会话内切换模式；
  • 永久：修改 config.json 将 bash 设置为 true；

⚠️ 安全提醒：开启bash权限存在风险，开发完成后建议关闭。

3. 路径穿越警告，拒绝访问上级目录

现象：Agent尝试 ../ 读取项目外文件，被拦截。
原因：Claude Code 内置安全防护，禁止访问项目根目录以外文件。
解决：不要让Agent读取项目外部文件；调整任务范围，限定在当前项目内。

四、会话与上下文异常

1. 会话越来越慢，token消耗暴涨

现象：前期正常，多轮对话后响应缓慢，输入token持续变大。
原因：上下文无限累积，历史消息持续叠加。
解决：

  1. /reset 重置会话，清空历史
  2. 任务拆分，不要在同一个会话持续无限迭代
  3. 使用检查点 /checkpoint，不需要时丢弃旧会话

2. Agent 记忆错乱，记住了上一个任务内容

现象：新建会话，但是Agent还保留之前任务信息。
原因：开启了 autoMemory，跨会话持久记忆。
解决：

  • 开发环境关闭 autoMemory："autoMemory": false
  • 执行 /clear-memory 清空记忆存储
  • 环境变量：CLAUDE_CODE_NO_MEMORY=true

3. Agent 重复执行相同操作，陷入工具死循环

现象：反复读取同一个文件，循环调用工具，无法输出结论。
原因：maxToolTurns 设置过大；提示词缺少终止条件。
解决：

  1. 降低 maxToolTurns（开发推荐 8~10）
  2. 修改 CLAUDE.md，增加规则：达到最大工具轮次必须输出总结
  3. /reset 重启会话。

五、IDE插件问题（VS Code / JetBrains）

1. 插件无法启动 Claude Code

排查：

  1. 确认本地已安装 Claude Code CLI，版本和插件兼容
  2. 查看插件输出面板日志
  3. 确认环境变量加载，密钥配置正确
    解决：重装插件；更新CLI；重启IDE。

2. IDE内会话卡顿、流式输出中断

原因：IDE网络问题；上下文过大；后台任务过多。
解决：重置会话；关闭其他大型后台任务；重启IDE。

六、MCP / Skills 相关报错

1. MCP Server 启动失败

现象：MCP工具加载失败，提示无法连接MCP服务。
原因：MCP配置JSON格式错误；MCP服务依赖缺失；开发环境未开启MCP。
解决：

  1. 开发调试可临时设置 CLAUDE_CODE_NO_MCP=true 关闭MCP，先验证基础功能
  2. 检查MCP服务配置文件，确认命令路径正确

2. Skill 技能无法加载

现象：/skills 看不到自定义技能。
原因：技能目录路径配置错误；技能文件语法错误；yaml/json格式不对。
解决：核对 skillsDir 配置；检查技能文件语法；重启会话。

七、通用排查步骤（标准排错流程）

遇到任何异常，按顺序执行：

  1. 打开debug日志，查看详细报错堆栈
  2. 在会话输入 /config，确认当前生效配置
  3. /reset 重置会话，排除历史上下文干扰
  4. 单独验证API Key能否正常调用Anthropic接口
  5. 检查 .claude/config.json、.claude/ignore、CLAUDE.md语法
  6. 关闭MCP、autoMemory等附加能力，最小化环境复现问题
  7. 新建干净项目，最小Demo复现，判断是否为项目配置导致

八、常见问题速查表

现象优先排查项
鉴权401API Key、环境变量
429限流并发、maxToolTurns
读取不到文件.claude/ignore、文件权限
记忆串会话autoMemory开关
Agent死循环maxToolTurns、提示词终止规则
MCP加载失败MCP配置，临时关闭MCP测试
修改配置不生效配置优先级、会话未重启

九、排错最佳实践

  1. 开发环境默认关闭 bash、autoMemory、按需开启MCP，减少故障面。
  2. 遇到异常优先新建干净会话，隔离历史上下文带来的干扰。
  3. 提交代码前，不要把密钥、本地调试配置提交到仓库。
  4. 遇到奇怪行为，优先看 debug 日志，不要只看Agent输出。
  5. 最小化复现：新建空项目，只保留最简配置，定位问题来源。

小结

Claude Code排错核心思路：查看日志 → 查看当前生效配置 /config → 重置会话排除上下文干扰。绝大多数问题集中在API鉴权、配置覆盖、权限控制、上下文膨胀、MCP/Skills加载这几类。遇到故障先剥离附加功能，使用最小环境复现问题。

标签：

0 条笔记