Claude Code 故障排查

可复现实践

分离机器、账户、自定义配置和仓库故障

按固定诊断阶梯找到第一个失败层，再修改提示词或重装。

准备

• 准确 symptom、时间、命令、工作目录和第一个可操作错误。
• 允许运行只读诊断并创建临时空目录。
• 计划脱敏用户名、路径、token、repo 名和 debug logs。

执行步骤

1. 识别 executable 和 version

   不同 shell 或重复安装可在项目配置介入前解释行为。

   command -v claude
   type -a claude 2>/dev/null || true
   claude --version

2. 分开检查安装与认证

   doctor 是只读诊断；auth status 回答另一类问题。

   claude doctor
   claude auth status --text

3. 比较 safe mode 和空目录

   在同一 shell 中创建唯一空目录；如果无自定义或仓库外问题消失，重装前先查 project settings、hooks、MCP、plugins 或 memory。

   DIAGNOSTIC_DIR=$(mktemp -d "${TMPDIR:-/tmp}/claude-diagnostic.XXXXXX")
   printf '%s\n' "$DIAGNOSTIC_DIR"
   cd "$DIAGNOSTIC_DIR"
   claude --safe-mode

4. 收集窄范围 debug 证据

   只打开相关 categories，写入受控文件，共享前脱敏。

   claude --debug "api,hooks" --debug-file ./claude-debug.log

预期结果

把 symptom 归到 executable/install、authentication/provider、customization、repository 或 external-service 层，并得到可复现下一步。

验证

• 只改变一个怀疑层后重复原动作。
• 比较原 repo、safe mode 和空目录行为。
• 记录仍未验证部分，不凭相关性宣称 root cause。

失败处理

清理或回退

• 脱敏和审查后返回原目录，确认 DIAGNOSTIC_DIR 是刚才打印的 mktemp 路径，只删除该目录。
• 一次只恢复一个配置改动；修复 malformed settings 前保留备份。

边界与不适用场景

• Debug logs 可能包含敏感路径和 request context，不能未脱敏公开。
• doctor 显示 Search OK 不能排除 WSL 跨文件系统性能或搜索结果不完整。