Claude Code 故障排查：安装、认证、配置、Gateway 与性能

安装与 PATH、认证、模型路由、项目配置、扩展工具和长会话性能是不同故障层。先记录最小复现、完整错误、当前目录和最近一次正常状态。

如果同一时间修改了 CLI 版本、gateway URL、Key 和模型名，任何错误都很难归因。恢复到已知状态后一次只改变一个变量。

先运行版本命令和 claude doctor。命令不存在时查看 shell 实际解析到的路径；存在但版本不符时检查是否同时安装了原生、Homebrew、WinGet 或旧 npm 版本。

安装脚本返回 HTML、403 或 TLS 错误属于下载网络问题，不应通过不断更换认证方式解决。确认代理、证书、地区和官方安装 URL。

用 /status 确认 ANTHROPIC_BASE_URL 与凭据来源。Bearer gateway 应使用 ANTHROPIC_AUTH_TOKEN，x-api-key gateway 使用 ANTHROPIC_API_KEY。请求头不匹配通常返回 401。

404 常见于 base URL 已经包含多余路径，未知模型则指向模型 ID 或路由。先直接请求 /v1/messages，再检查 Claude Code，避免两层同时猜。

运行 claude doctor 检查 JSON，再在会话内使用 /context 查看 CLAUDE.md 和规则。确认启动目录、文件作用域、设置优先级和组织托管策略。

CLAUDE.md 在会话中途修改不会自动替换已经进入上下文的版本。开启新会话后再检查，不要不断提高规则语气。

MCP 使用 claude mcp list、get 和会话内 /mcp 检查；stdio 服务独立运行其启动命令，HTTP 服务独立检查 URL、TLS 与认证。

Hook 先用固定 JSON 输入执行脚本，再用 /hooks 验证是否加载。检查 matcher、执行目录、权限、超时和退出码，避免把脚本错误归咎于模型。

长会话可能积累大量文件、日志和工具结果。先用 /context 查看组成，无关任务使用 /clear，同一任务用带保留要求的 /compact。

仓库搜索异常时检查 ripgrep、生成目录和大型 vendored 代码；monorepo 从具体包目录启动。gateway 若缓冲 SSE，也会表现为长时间无输出，需要在服务端验证流式转发。

记录操作系统、安装方式、claude --version、复现命令、预期与实际行为、完整错误和是否使用 gateway。配置问题附脱敏后的相关片段，不要发送整个 home 目录。

明确哪些检查已完成及结果，例如直连 Messages 成功但 CLI 失败，或禁用某个 MCP 后恢复。高质量证据能直接缩短定位路径。