故障排查

2026/6/27大约 4 分钟

故障排查

按症状选入口。claude 无法启动时用 claude doctor（shell）；运行中用 /doctor。

症状	文档
安装失败、PATH、`command not found`	Troubleshoot installation
OAuth 循环、403、Bedrock/Vertex 凭证	同上
Settings/Hooks/MCP 不生效	Debug configuration
API 5xx、429、model not found	Error reference
VS Code / JetBrains 连接	各 IDE 集成页
CPU/内存、搜索、卡顿	下文

启动与登录

`claude` 找不到

重开终端；PATH 含 ~/.local/bin
Windows：确认安装目录在 PATH；PowerShell vs CMD 安装命令正确

登录 / OAuth

claude auth login    # SSH/WSL/容器粘贴验证码

启动卡住 ~15s

账户设置请求超时（v2.1.181 改善）。检查网络/代理。

macOS `open` / 认证 error -600

v2.1.181+ Apple Events 权限；Sandbox 相关修复。

Workspace trust

--worktree、project 级敏感 settings 需先在目录运行 claude 并接受 trust。

性能与稳定性

高 CPU / 内存

定期 /compact
大任务间重启 Claude Code
大 build 目录加入 .gitignore
claude --safe-mode 排查是否 plugin/MCP/hook 导致；若下降则逐项禁用查因

内存 dump：

/heapdump

写入 ~/Desktop（Linux 无 Desktop 则 home）。含 RSS、JS heap 等；.heapsnapshot 用 Chrome DevTools → Memory → Load 分析 retainers。

Auto-compact thrashing

错误：Autocompact is thrashing: the context refilled to the limit...

自动 compact 后立刻被大文件/工具输出再次填满。

恢复：

让 Claude 分段 Read（行范围），不要整文件
/compact keep only the plan and the diff
大探索改 subagent
不需要旧对话则 /clear

命令挂起

Ctrl+C 取消
无响应则关终端；claude --resume 同目录恢复（对话不丢）

集成终端乱码 / 方块字

/terminal-setup

或手动设 terminal.integrated.gpuAcceleration: "off" 并重载窗口。

Context

`Prompt is too long`

/compact

compact 也失败 → /clear 重来，或 --continue 换短任务。

1M 被错误阻止

autocompact 窗口配置 bug（v2.1.128 修复）。确认 CLAUDE_CODE_DISABLE_1M_CONTEXT 未设。

第三方 Provider 仍显示 200K

/context 只有 200K、很早就 compact，但 DeepSeek / 智谱明明标 1M：

cc-switch Provider 里 Pro/Sonnet/Opus 是否写了 [1m]（如 deepseek-v4-pro[1m]、glm-5.1[1m]）
智谱是否设了 CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000
cc-switch provider edit <id> 改完后是否 provider switch 并新开会话
加了 [1m] 报模型不存在 → 升级 Claude Code

详见第 4 章 · 第三方 [1m]、附录 C · 1M 与 cc-switch。

优化习惯

Subagent 探索
CLAUDE.md <200 行；详情放 rules / skills
/context 查看占用

搜索与发现

Search / @file / Glob 找不到文件

Bundled ripgrep 可能无法运行：

# 安装系统 ripgrep 后
export USE_BUILTIN_RIPGREP=0

Alpine：apk add ripgrep；Windows：winget install BurntSushi.ripgrep.MSVC

WSL 搜索结果偏少

项目在 /mnt/c/ 时 IO 慢、匹配少。移到 /home/ 或改用原生 Windows Claude Code。

/doctor 在 WSL 跨文件系统场景下 Search 仍可能显示 OK。

MCP

/mcp                    # 状态与工具数
claude mcp login <name> # v2.1.186+ 命令行 OAuth
claude --safe-mode      # 排除 MCP 配置问题

零工具：查 server 端日志
OAuth：RFC 9728；SSH 加 --no-browser
重连刷屏：已改为按 server 前缀汇总

终端兼容

问题	版本/处理
VS Code 滚轮过快	v2.1.132 修复
Ghostty/Kitty 退出 Ctrl+C 异常	v2.1.85 修复
Emoji/Indic 乱码	v2.1.132 修复
睡眠唤醒全屏异常	v2.1.132；或 `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`
Tmux Ctrl+B	按两次

文件编辑

网络盘 / 云同步 0 字节

v2.1.181 修复 Write/Edit 截断。

`.claude/` 写入被拦

整个 .claude/ 受保护（除 .claude/worktrees/）。弹窗可选「本会话允许编辑 Claude 设置」。

`--dangerously-skip-permissions`

跳过确认（仅隔离环境）；v2.1.126+ 扩展覆盖范围。

配置排查

命令	作用
`/doctor`	安装、settings、MCP、context
`claude --safe-mode`	禁用 CLAUDE.md/skills/plugins/hooks/MCP/auto-memory
`claude --bare`	极简脚本模式（非 safe-mode）
`/debug`	会话内开 debug
`claude --debug "api,mcp"`	分类 debug
`/bug`	上报 Anthropic

Settings 不生效：查优先级 Local > Project > User；Managed 覆盖；命令行临时覆盖。

Hooks 不触发：matcher、if 条件、Managed allowManagedHooksOnly、plugin 是否启用。

功能特定

功能	排查
Auto mode 不在 Shift+Tab	Team/Enterprise/API；admin 启用；Sonnet 4.6+ / Opus 4.6+；Bedrock/Vertex 需 `CLAUDE_CODE_ENABLE_AUTO_MODE=1` 且 Opus 4.7/4.8
`/schedule` 不可用	GrowthBook/telemetry 被 `DISABLE_TELEMETRY` 等禁用
Computer Use	macOS CLI、Pro/Max、v2.1.85+、claude.ai 认证、交互会话、`/mcp` 启用 computer-use
Background	macOS protected 文件夹需 Files and Folders 权限；`.claude/worktrees/` 堆积用 `git worktree list` 清理
Fable 5 不可用	v2.1.170+；`/model fable`；ZDR 环境可能隐藏

性能调优清单

日常 Sonnet，规划 Opus/Fable，轻量 Haiku
Effort：简单任务 low/medium
并行 worktree 无关任务
Explore subagent 代替主会话翻文件
长会话定期 /compact

获取帮助

/doctor → /feedback
GitHub issues
问 Claude：「why did X fail?」——内置文档检索

资料来源：Troubleshooting、Troubleshoot installation、Debug configuration