Claude Code故障排查全实战：十大错误与修复

mindmap
  root((Claude Code故障域))
    安装与认证
      command not found
      npm EACCES
      401/403认证失败
      WSL路径冲突
    API与网络
      429 速率限制
      529 服务过载
      500 内部错误
      网络代理/SSL
    上下文与记忆
      上下文溢出
      auto-compact抖动
      记忆丢失
      /compact无效
    行为与逻辑
      无限还原循环
      指令被忽略
      越界修改
      幻觉输出
    性能与资源
      高CPU/内存
      会话冻结
      MCP断连
      文件索引卡死

# 在Claude Code会话中执行
/doctor

✓ Node.js v22.14.0 (supported)
✓ Claude CLI v2.1.33
✓ API connection: OK
✓ Git: configured
⚠ MCP servers: 2 of 3 connected (filesystem: disconnected)
✗ Context window: 87% used (threshold: 80%)

# 启动时开启调试模式
claude --debug

# 或在会话中切换
/debug

# 通过环境变量（适用于脚本和CI）
export CLAUDE_DEBUG=1
claude -p "fix the auth bug"

# 查看当前上下文使用情况
/status

# 查看所有生效的配置
/config

# 查看CLAUDE.md层级合并结果
/config --show-rules

# 查看当前权限配置
/permissions

# 清空上下文但保留会话
/clear

# 完全重置（相当于重启）
/reset

$ claude
bash: claude: command not found

# 检查npm全局安装路径
npm config get prefix
# 典型输出：/usr/local 或 /home/user/.npm-global

# 检查claude是否实际存在
ls $(npm config get prefix)/bin/claude

# 方案A：将npm全局路径加入PATH（推荐）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 方案B：重新安装到系统路径
npm install -g @anthropic-ai/claude-code --prefix /usr/local

# 方案C：使用npx免安装运行（临时方案）
npx @anthropic-ai/claude-code

# 检查是否有Windows路径干扰
echo $PATH | tr ':' '\n' | grep -i windows

# 在~/.bashrc或~/.zshrc中固定PATH
export PATH="/usr/local/bin:/usr/bin:/bin:$HOME/.npm-global/bin:$PATH"

npm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'

# 方案A：配置npm使用用户目录（最佳实践）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 然后重新安装
npm install -g @anthropic-ai/claude-code

# 方案B：使用nvm管理Node.js（彻底解决）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install --lts
npm install -g @anthropic-ai/claude-code

Error: Authentication failed. Please check your API key or login again.

# 检查当前认证状态
claude auth status

# 查看使用的认证方式
claude auth whoami

# 场景A：使用Anthropic API Key
claude config set apiKey "sk-ant-xxxxx"

# 场景B：使用OAuth登录（Max/Pro订阅用户）
claude login

# 场景C：认证过期，重新登录
claude logout
claude login

# 场景D：使用API Key但通过环境变量
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

Error: rate_limit_error - This request would exceed your organization's rate limit.

# 方案A：调整auto-compact阈值，减少每次请求的Token数
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=60  # 默认80，降到60提前压缩

# 方案B：使用更经济的模型进行日常任务
claude model sonnet  # 从opus切换到sonnet

# 方案C：在settings.json中配置速率感知
# ~/.claude/settings.json
{
  "env": {
    "CLAUDE_DELAY_MS": "500"
  }
}

# 等待速率窗口重置（通常1分钟）
# 在此期间用/clear清空上下文减少下次请求大小
/clear

Error: api_error - Overloaded. Please retry after a brief wait.

# 方案A：使用Claude Code内置的自动重试（默认已启用）
# 如果重试仍然失败，手动等待30-60秒

# 方案B：切换模型（Opus过载时Sonnet通常可用）
claude model sonnet

# 方案C：在CI/CD中配置重试策略
# GitHub Actions示例
- name: Run Claude Code
  run: |
    for i in 1 2 3; do
      claude -p "$TASK" && break || sleep $((i * 30))
    done

Warning: Context window approaching limit. Auto-compacting...
# 或
Error: Input too long. Please reduce the context.

/status  # 查看上下文占用百分比

# 方案A：主动压缩（最佳实践）
/compact
# 可以带提示词指定保留什么
/compact "保留数据库架构和API设计，丢弃探索性搜索"

# 方案B：调整auto-compact触发阈值
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50  # 提前到50%就压缩

# 方案C：避免一次性读取大文件
# 不要让Claude读整个5000行文件，而是指定范围
# 不推荐：Read ./database/schema.sql（全部读取）
# 推荐：告诉Claude只读特定部分

# 症状识别：频繁看到"Auto-compacting..."输出
# 修复：提高阈值避免频繁触发
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70

# 或者完全禁用auto-compact（仅在手动管理时使用）
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=100

graph TD
    A[200K 总上下文] --> B[系统指令 ~15K]
    A --> C[CLAUDE.md规则 ~5K]
    A --> D[对话历史]
    A --> E[Auto-compact缓冲 ~33-45K]
    B --> F[可用空间 ~135K]
    D --> F
    F --> G{当前使用量}
    G -->|<60%| H[安全区]
    G -->|60-80%| I[主动压缩区]
    G -->|>80%| J[自动压缩区]
    J --> K[重要信息可能丢失]
    I --> L[带提示词压缩 - 推荐]

Let me revert that change and try again...
(test fails)
Let me try a different approach...
(makes similar change)
(test fails again)
Let me revert...

# 方案A：立即中断（Ctrl+C）
# 然后提供更具体的指导
# 不推荐："Fix the test"
# 推荐："The test fails because the mock returns null. Change line 45 to return a valid User object."

# 方案B：使用/rewind回到安全点
/rewind  # 选择进入循环前的检查点

# 方案C：增加CLAUDE.md中的约束
# 在CLAUDE.md中添加：
# "When a test fails, do NOT revert changes. Instead, read the test file carefully 
#  and make minimal targeted fixes. Maximum 3 attempts before asking for guidance."

# CLAUDE.md示例
## 调试规则
- 测试失败时，先完整阅读错误信息，不要急于修改
- 每次只修改一个可能导致失败的因素
- 连续失败2次后，停下来描述你的假设，等用户确认
- 不要使用git checkout或git stash来还原代码

# 第一步：确认CLAUDE.md是否被加载
/config --show-rules

# 第二步：检查是否有冲突规则
# CLAUDE.md优先级：local > project > user
# 检查各层级文件
ls -la CLAUDE.md              # 项目根目录
ls -la .claude/CLAUDE.md      # .claude目录
ls -la ~/.claude/CLAUDE.md    # 用户全局

# CLAUDE.md模块化拆分示例
.claude/
├── CLAUDE.md              # 核心规则（<50行）
├── rules/
│   ├── coding-style.md    # 编码规范
│   ├── testing.md         # 测试要求
│   └── git-conventions.md # Git提交规范

Warning: MCP server "filesystem" disconnected
# 或
Error: Failed to connect to MCP server "github"

# 第一步：检查MCP状态
/mcp

# 第二步：检查MCP配置
cat ~/.claude/settings.json | grep -A 20 mcpServers
# 或项目级别
cat .claude/settings.json | grep -A 20 mcpServers

# 第三步：手动测试MCP服务器
npx @modelcontextprotocol/server-filesystem /tmp

// 常见问题1：npx命令找不到
// settings.json中使用完整路径
{
  "mcpServers": {
    "filesystem": {
      "command": "/usr/local/bin/npx",  // 使用完整路径
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

// 常见问题2：环境变量未传递
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxx"  // 确保环境变量正确
      }
    }
  }
}

// 常见问题3：WSL中的MCP连接问题
// 使用node直接运行而非npx
{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["/home/user/.npm-global/lib/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js", "/home/user/projects"]
    }
  }
}

# 重启所有MCP服务器
/mcp restart

# 重启特定服务器
/mcp restart filesystem

# 查看MCP服务器日志
ls ~/.claude/logs/mcp-*.log

# 监控Claude Code进程
top -p $(pgrep -f claude-code)

# 查看内存详情
ps aux | grep claude-code

# 方案A：强制中断（首选）
# 按 Ctrl+C 中断当前操作
# 如果无反应，按 Ctrl+\ (SIGQUIT)

# 方案B：从另一个终端杀掉进程
kill -SIGINT $(pgrep -f "claude-code")

# 方案C：清理临时文件
rm -rf /tmp/claude-*-cwd  # 沙箱临时文件

// .claude/settings.json
{
  "permissions": {
    "deny": [
      "Read(node_modules/**)",
      "Read(**/dist/**)",
      "Read(**/*.min.js)"
    ]
  }
}

# CLAUDE.md
## 文件搜索规则
- 搜索时排除 node_modules, .git, dist, build 目录
- 使用 Glob 工具时始终指定具体路径，不要用 /**/ 全局搜索
- 不要使用 cat 读取超过500行的文件，使用 Read 工具并指定范围

flowchart TD
    A[遇到错误] --> B{错误类型?}

    B -->|安装/启动失败| C[运行 /doctor]
    B -->|API错误码| D[查看错误码对照表]
    B -->|行为异常| E[检查 /status 上下文]
    B -->|性能问题| F[检查进程资源]
    B -->|MCP问题| G[运行 /mcp 诊断]

    C --> C1{Node版本?}
    C1 -->|<18.x| C2[升级Node.js到LTS]
    C1 -->|OK| C3[检查PATH和权限]
    C3 --> C4[claude auth status]
    C4 -->|失败| C5[重新认证]
    C4 -->|OK| C6[检查网络/代理]

    D --> D1{错误码}
    D1 -->|429| D2[速率限制 - 减少Token/切换模型]
    D1 -->|529| D3[服务过载 - 等待/切换模型]
    D1 -->|500| D4[服务端错误 - 重试]
    D1 -->|401/403| D5[认证问题 - 重新登录]

    E --> E1{上下文使用率}
    E1 -->|>80%| E2[/compact 主动压缩]
    E1 -->|<50%| E3[检查CLAUDE.md规则冲突]
    E3 --> E4[/config --show-rules]

    F --> F1{内存使用}
    F1 -->|>5GB| F2[清理/clear重启]
    F1 -->|正常| F3[检查auto-compact抖动]

    G --> G1{连接状态}
    G1 -->|全部断连| G2[重启Claude Code]
    G1 -->|部分断连| G3[检查对应MCP配置]
    G3 --> G4[手动测试MCP命令]

    C5 --> Z[问题解决]
    C6 --> Z
    D2 --> Z
    D3 --> Z
    D4 --> Z
    D5 --> Z
    E2 --> Z
    E4 --> Z
    F2 --> Z
    F3 --> Z
    G2 --> Z
    G4 --> Z

Error: rate_limit_error - 429 Too Many Requests

# 尝试1：等待（无效，1分钟后再次触发）
# 尝试2：降低请求频率（无效，单次请求就超限）
# 尝试3：升级API计划（无效，问题依旧）

# 第一步：开启调试模式
claude --debug

# 第二步：查看请求详情
# 日志显示单次请求携带了180K Token
cat ~/.claude/logs/latest.log | grep "token_count"
# 输出：token_count: 183247

# 第三步：检查为什么上下文这么大
/status
# 输出：Context 91% used (182K/200K)

# 第四步：查看对话历史
# 发现Claude在会话中读取了一个5000行的数据迁移文件
# 这个文件占用了约70K Token

根因：不是请求频率过高，而是单次请求的Token数接近200K上限。
     当输入Token + max_tokens超过模型上下文窗口时，
     API返回的错误码与429相同，但本质是"上下文溢出"。

修复：
1. /compact "保留架构讨论，丢弃数据迁移文件内容"
2. 在CLAUDE.md中添加规则：
   "数据库迁移文件不要完整读取，只读取相关的schema定义部分"
3. 设置auto-compact阈值：
   export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=55

# 在Claude Code会话中
/status      # 上下文状态
/doctor      # 快速健康检查

# 更新Claude Code到最新版本
npm update -g @anthropic-ai/claude-code

# 清理历史日志
find ~/.claude/logs/ -name "*.log" -mtime +7 -delete

# 检查配置是否有冲突
/config --show-rules

# 运行/init生成CLAUDE.md
/init

# 配置.gitignore排除敏感配置
echo ".claude/settings.local.json" >> .gitignore

# 验证CLAUDE.md被正确加载
/config --show-rules

# 故障处理规则
- 遇到测试失败时，先完整阅读错误堆栈，不要急于修改代码
- 连续修改同一文件失败3次后，停止并向用户描述当前假设
- 不要使用 git checkout 或 git stash 放弃更改
- 每次修改前先说明要改什么、为什么改
- 读取大文件（>500行）时使用 offset/limit 参数分段读取