Claude Code 故障排除与速查

先保留完整错误，再用 doctor、safe mode 和最小设置逐层隔离。不要用跳过权限、删除项目状态或反复重装代替定位根因。

当前实测版本：2.1.209 (Claude Code) · 核对日期 2026-07-15

第一轮只读检查

claude --version
claude auth status --text
claude doctor
pwd
git status --short --branch

claude doctor 会读取当前目录设置但不弹 workspace trust。会话内 /doctor 可以进行更完整检查，并在允许时修复问题。

需要调试日志时：

claude --debug
claude --debug-file /tmp/claude-debug.log

分享日志前删除 Token、Authorization header、邮箱、账号、绝对私人路径和业务数据。

按症状查找

症状	先检查	不要先做
claude 找不到	which claude、安装方式、PATH、重开终端	原生版和 npm 版反复叠装
项目不可信或进错目录	pwd、Git 根目录、仓库来源	在主目录直接信任所有内容
认证失败	claude auth status --text、账号类型、系统时间、代理、网关变量	把 Key 粘到聊天、Issue 或截图
配置没有生效	setting sources、JSON 语法、local/project/user 层	同时修改三层设置
权限弹窗太多	当前 permission mode、allow/deny 和实际命令	--dangerously-skip-permissions
长会话遗漏事实	/context、/compact、目标是否变化	不断把整个仓库追加进上下文
MCP Pending / Failed	claude mcp list/get、项目审批、启动命令、认证	重复添加同名服务
IDE 没连接	只开一个有效 IDE、集成终端目录、--ide	假设所有 IDE 窗口自动同步
Remote Control 不可用	claude.ai 登录、订阅、组织策略、网络	用 API Key 推断一定可用
401 / 404 / 模型不存在	Key、Base URL、模型、分组、余额	随机在 URL 后增删路径

安装与版本冲突

which claude
ls -l "$(which claude)"
claude --version

原生安装更新：

claude update

从旧 npm 安装迁移：

claude install stable

更新后仍显示旧版本，通常是 PATH 先命中了另一个安装。先确认实际二进制位置，再移除不用的来源；不要盲目删除配置和会话。

认证方式与 Endpoint

先查看状态，不要先反复登录：

claude auth status --text

需要使用 Anthropic 官方登录时，当前 CLI 区分订阅账号和 Console API 计费账号：

claude auth login --claudeai
claude auth login --console

SuperToken 等自定义 endpoint 通常来自环境变量或外部配置，不应在没确认当前来源时用登录命令覆盖。状态输出可能包含认证方式和 Base URL 等环境元数据，分享前先脱敏。claude setup-token 生成长期认证 token 且要求 Claude 订阅，只用于明确需要的受控环境，不能把结果粘进聊天、日志或仓库。

项目信任与目录

pwd
git rev-parse --show-toplevel
git status --short --branch

检查项目中的：

• CLAUDE.md 与 .claude/settings.json。
• .mcp.json 及其启动命令。
• .claude/skills、agents、Hooks 和 plugins。
• 包管理器脚本与测试命令。

显式 -p 或 stdout 不是 TTY（管道、重定向）都会跳过 trust 对话，只能在预先固定和审查的目录中运行。Print 模式会静默忽略无法通过校验的 settings 文件，因此排错时要单独验证设置和实际工具范围。

用 Safe mode 隔离定制

claude --safe-mode

如果 Safe mode 正常，问题大概率在 CLAUDE.md、自动记忆、settings、MCP、skill、agent、Hook、plugin、LSP 或其他项目定制。逐项恢复，每次只改变一层。

需要更小基线：

claude --bare \
  --permission-mode plan \
  "只报告当前目录和可读取的项目入口，不修改"

Bare mode 不自动发现 CLAUDE.md，并跳过大部分定制。它不会读取 OAuth 或 keychain 凭据；Anthropic 认证只接受 ANTHROPIC_API_KEY 或通过 --settings 提供的 apiKeyHelper，Bedrock、Vertex 和 Foundry 使用各自凭据。不要把这种预期的认证变化误判成代码问题。

设置与权限

指定加载来源做对比：

claude --setting-sources user
claude --setting-sources project
claude --setting-sources user,project,local

一次性最小设置：

claude --settings '{"permissions":{"allow":["Read"],"deny":["Read(./.env)"]}}' \
  --permission-mode plan

若未授权动作在 dontAsk 下直接失败，这是预期行为；它不会弹窗请求扩大范围。acceptEdits 也不表示所有 Bash 或网络动作自动允许。

Auto mode 行为不符合预期时，比较默认规则与有效配置：

claude auto-mode defaults
claude auto-mode config

上下文和会话

会话内：

• /context 查看占用。
• /compact 保留需求、事实、diff、验证和未完成项。
• /clear 目标改变时清空当前对话。
• /resume 选择历史会话。

CLI：

claude -c
claude -r
claude --fork-session -r SESSION_ID

恢复后要求 Claude 重报目录、分支、diff 和未完成步骤。历史会话不会保证工作区仍处在同一提交。

MCP

claude mcp list
claude mcp get SERVER_NAME

项目级 .mcp.json 未审批时会显示 Pending，不会连接。检查：

1. 当前项目是否正确。
2. server 名称和 scope。
3. stdio 命令在同一 shell 能否独立启动。
4. HTTP/SSE endpoint、OAuth 或 header 是否有效。
5. 项目选择是否被拒绝；必要时使用 reset-project-choices 后重新审查。
6. --strict-mcp-config 是否忽略了其他来源。

SSH 或无图形界面环境中，使用 claude mcp login --no-browser NAME 打印授权 URL，并按提示回填 redirect URL。

不要把 Authorization header 直接写进截图或仓库。优先使用环境变量、OAuth 和可撤销的短期凭据。

IDE

pwd
git rev-parse --show-toplevel
claude --ide --permission-mode plan

--ide 只在恰好有一个有效 IDE 时自动连接。关闭无关窗口，确认 IDE workspace 与集成终端是同一个 checkout。使用 Worktree 时比较真实路径，不只比较项目名。

Remote Control、Chrome 和云端能力

Remote Control：

claude --remote-control

未登录时，当前 CLI 明确要求 claude.ai 订阅登录。若已登录仍不可用，检查套餐、组织策略、版本和网络；不要假设 API Key 等同于订阅权限。

Chrome：

claude --chrome

能启动参数不等于浏览器已正确授权。检查当前官方集成状态、profile、站点范围和重要动作确认。

Ultrareview：

claude ultrareview --timeout 30 main

--timeout 的单位是分钟。失败时区分登录、网络、代码上传策略、目标分支和服务可用性。它是云端审查，不是本地 diff 命令。

SuperToken 接入错误

先看 Claude Code 安装与接入 SuperToken。配置后开新终端，再检查环境变量是否存在，但不要打印完整值。

错误	常见原因	处理
401	Key 错误、过期、被撤销或变量没加载	重新创建最小权限 Key，只检查前后少量字符和变量来源
403	分组、账号或模型权限不足	检查控制台分组和模型可用范围
404	Base URL 路径或兼容接口错误	Claude Code 的 SuperToken Base URL 按接入页填写，不随意追加 /v1
模型不存在	模型名与分组映射不一致	从当前模型广场复制准确模型 ID
429	频率、额度或余额限制	检查用量、余额、并发与重试策略
连接超时	DNS、代理、网络策略或 endpoint 不可达	分层检查网络，不输出代理凭据

“保存了配置”不是验证。必须在一个无敏感信息的测试项目里完成真实请求，并记录成功模型、入口和时间。

破损项目状态的最后手段

先预览将删除的内容：

claude project purge --dry-run /path/to/project

确认目标无误并备份后，使用逐项确认：

claude project purge --interactive /path/to/project

它会删除该项目的 Claude Code 状态，包括 transcripts、tasks、file history 和 config entry。只有确认问题来自不可恢复的项目状态、已经备份需要保留的信息，并理解无法恢复的后果时才使用。它不是普通缓存清理命令；不要在排错手册中默认使用 --yes 或 --all。

命令速查

# 健康与隔离
claude --version
claude auth status --text
claude doctor
claude --safe-mode
claude --bare

# 会话
claude --permission-mode plan
claude auto-mode config
claude -c
claude -r
claude --fork-session -r SESSION_ID

# IDE / 并行 / 远程
claude --ide
claude --background
claude agents --json
claude --worktree task-name --tmux
claude --remote-control

# MCP / 插件
claude mcp list
claude plugin list
claude plugin details PLUGIN_NAME

# 调试
claude --debug-file /tmp/claude-debug.log

请求支持前准备

提供版本、操作系统、入口、脱敏错误、最小复现、当前目录类型、权限模式、是否启用 Safe mode，以及问题在默认认证还是 SuperToken 网关下发生。

不要提供 API Key、完整环境变量、cookies、私人会话、客户代码或未脱敏日志。

官方资料

以下链接待网络恢复后重新读取：

• Troubleshooting
• Settings
• Permissions
• MCP
• Security