本节目标

  1. 熟练使用内置诊断命令:/doctor、/status、/cost、/mcp

  2. 掌握 --debug、--verbose、--bare 三种调试模式的适用场景

  3. 学会排查 API 层面的问题:网络、认证、速率限制

  4. 掌握配置诊断方法:文件优先级、Hook 冲突、Skill 激活失败

  5. 识别和解决上下文问题:Token 溢出、响应截断、质量退化

  6. 了解 claude-doctor 和 mcp-inspector 第三方排障工具

核心知识点

内置诊断命令

Claude Code v2.1.x 提供了四个内置诊断命令,覆盖 80% 的常见问题排查:

/doctor —— 全面健康检查

最常用的诊断命令。一次性检查所有子系统的健康状态:

/doctor
​
输出示例:
=== Claude Code 健康检查 ===
​
✅ CLI 版本: 2.1.3 (最新)
✅ Node.js: v20.11.0 (满足 v20+ 要求)
✅ 网络连接: api.anthropic.com (延迟 45ms)
✅ 认证: API Key 有效 (org-xxxxx)
⚠️ 配置: 加载了 8 个文件,无语法错误
   (提示: CLAUDE.local.md 中有 1 条规则与项目 CLAUDE.md 冲突)
✅ Hooks: 4 个已注册,最近执行均成功
✅ MCP: 3 个 Server 运行中,0 个异常
⚠️ 上下文: 当前使用 142K / 200K tokens (71%)
   (建议: 上下文使用超过 70%,即将压缩)
⚠️ Git: 9 个未跟踪文件,建议清理
✅ Skills: 12 个已安装,3 个当前会话激活

/status —— 当前会话状态

快速查看当前会话的运行状态:

/status
​
输出示例:
=== 会话状态 ===
​
会话 ID: sess_8f3a2b1c
启动时间: 2026-05-26 14:32 UTC
运行时长: 23 分钟
模型: claude-sonnet-4-20250514
上下文用量: 142K / 200K (71%)
工具调用: 47 次 (Write: 12, Edit: 8, Bash: 15, Read: 10, Grep: 2)
Hooks 触发: 20 次 (0 次阻止)
MCP 调用: 5 次 (GitHub: 3, Playwright: 2)
Sub-agents 启动: 2 次 (均已完成)
Plan Mode: 未激活

/cost —— Token 和费用统计

查看当前会话和累计的 API 使用情况:

/cost
​
输出示例:
=== Token 用量与费用 ===
​
当前会话:
  输入 tokens: 128,500
  输出 tokens: 15,200
  总计 tokens: 143,700
  估算费用: $0.46
​
当月累计:
  输入 tokens: 2,340,000
  输出 tokens: 187,000
  总计 tokens: 2,527,000
  估算费用: $8.12
​
模型使用分布:
  Sonnet: 78% ($6.33)
  Haiku: 18% ($0.73)
  Opus: 4% ($1.06)

/mcp —— MCP Server 状态

检查所有 MCP Server 的运行状态:

/mcp
​
输出示例:
=== MCP Server 状态 ===
​
✅ github (PID: 28471, 运行 23 分钟)
  工具数: 24 | 资源数: 3 | 调用: 15 次
✅ playwright (PID: 28492, 运行 23 分钟)
  工具数: 18 | 资源数: 0 | 调用: 2 次
❌ postgres (未运行)
  错误: connect ECONNREFUSED 127.0.0.1:5432
  建议: 检查 PostgreSQL 服务是否已启动

调试模式

Claude Code 提供三种调试模式,分别对应不同的排查场景:

--debug —— 开发级详细日志

claude --debug

输出内容:

  • 每次 API 请求的完整 payload 和 response

  • 每个 Hook 的执行过程和结果

  • 每个工具调用的参数和返回值(压缩后的)

  • 上下文压缩的触发时机和压缩策略

  • MCP Server 的启动日志和通信内容

适用场景:

  • Hook 没有按预期触发

  • API 返回了意外的结果

  • MCP Server 连接异常

  • 怀疑上下文被不当压缩

--verbose —— 对话级详细输出

claude --verbose

输出内容:

  • AI 每一次"思考"的中间步骤

  • 工具选择的理由说明

  • 文件修改前的 diff 预览

  • 每个操作的成本估算

比 --debug 更易读,适合日常调试。

--bare —— 纯净模式

claude --bare

行为:

  • 禁用所有 Hooks

  • 跳过 CLAUDE.md 加载(只使用系统默认配置)

  • 禁用所有 Skills 的 auto_activate

  • 不加载 .mcp.json

适用场景:

  • 怀疑 Hook 或配置导致了异常行为

  • 需要排除配置问题的"回归基准测试"

  • 快速验证某个功能是否与配置无关

API 问题排查

API 层面的问题是最常见的故障源。三个核心排查维度:

1. 网络问题

# 测试 API 连接
curl -I https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"
​
# 预期返回: HTTP/2 200 或 401 (认证失败但网络通)
# 如果超时或 connection refused,检查:
# - 代理设置: echo $HTTP_PROXY $HTTPS_PROXY
# - 防火墙规则
# - VPN 连接状态

2. 认证问题

# 验证 API Key 格式
echo $ANTHROPIC_API_KEY | grep -E "^sk-ant-"
# 合法的 Key 以 sk-ant- 开头
​
# 验证 API Key 有效性
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"ping"}]}' \
  | jq '.error // "认证成功"'
​
# 常见认证错误:
# 401: API Key 无效或已过期
# 403: API Key 有效但无权访问该模型或组织
# 429: 速率限制,稍后重试

3. 速率限制问题

典型错误信息:
"Rate limit exceeded. Please try again in 30 seconds."
​
排查步骤:
1. 检查 /cost 查看当月用量是否接近限额
2. 降低并行度:减少 Sub-agents 数量
3. 使用更便宜的模型:将部分任务从 Sonnet 切换到 Haiku
4. 联系 Anthropic 提升速率限制(Tier 升级)

速率限制的层级:

Tier RPM (请求/分钟) TPM (Tokens/分钟) 升级条件
Tier 1 50 50,000 默认
Tier 2 1,000 100,000 消费 $100+
Tier 3 2,000 200,000 消费 $500+
Tier 4 4,000 400,000 消费 $1,000+

配置问题排查

最常见的配置类问题和排查方法:

问题 1:CLAUDE.md 规则没有生效

# 检查配置加载顺序
/doctor config
​
# 输出会显示加载的文件列表和合并后的最终配置
# 确认你的规则是否被后加载的规则覆盖了

排查步骤:

  1. 检查文件路径是否正确(区分大小写)

  2. 检查是否被 CLAUDE.local.md 中的同名规则覆盖

  3. 检查 .claude/rules/ 的路径匹配是否与你当前操作的文件匹配

  4. 使用 --bare 模式对比,确认确实是配置问题

问题 2:Hook 冲突

// 两个 Hook 可能在同一个事件上产生冲突
// 例如:PreCommit 中既有 lint 检查又有格式化
// 格式化修改了文件,lint 检查的是旧版本
​
// 解决:确保 Hook 按正确顺序执行
{
  "hooks": {
    "PreCommit": [
      { "command": "lint-staged", "description": "格式化" },
      { "command": "npm run lint", "description": "Lint 检查" },
      { "command": "npm test", "description": "测试" }
    ]
  }
}

问题 3:Skill 没有自动激活

# 检查 Skill 的 auto_activate_on 正则
/claude skills list
​
# 输出会显示每个 Skill 的激活条件
# 手动测试正则是否匹配:
echo "src/api/routes/user.ts" | grep -E "src/api/routes/.*\.ts"
# 如果 grep 不匹配,说明正则有问题
​
# 可以临时手动激活:
/skill-name

上下文问题排查

上下文问题是最难排查的一类,但有一些明显的信号:

信号 1:Token 溢出

症状:
- "Context limit exceeded" 错误
- 对话突然中断,之前的讨论内容"丢失"
- Claude Code 建议使用 /compact 压缩
​
诊断:
/status  → 查看 "上下文用量" 百分比
​
预防:
- 超过 70% 时主动使用 /compact
- 将大任务拆分为多个 Sub-agent
- 定期开启新会话(不要在一个会话中塞太多任务)

信号 2:响应截断

症状:
- AI 的回复在中间突然结束
- 代码块不完整,缺少后半部分
​
原因:
- max_tokens 参数设置过低
- 输出被系统截断
​
解决:
- 说 "继续" 让 AI 接着输出
- 调整 settings.json 中的 maxTokens 设置

信号 3:质量退化

症状:
- 回复变得啰嗦且抓不住重点
- 忘记了你前面说过的约束
- 反复提出你已经拒绝过的方案
​
原因:
- 上下文过长,超过 ~120K tokens 时(约 60% 窗口),模型注意力开始分散
- 上下文压缩损失了关键信息
​
解决:
- 使用 /compact 或开启新会话
- 在新会话开始时摘要性重述关键约束
- 使用 CLAUDE.md 固化重要规则(不会被压缩丢失)

第三方排障工具

claude-doctor

社区开发的 CLI 诊断工具,比 /doctor 更深入:

# 安装
npm install -g claude-doctor
​
# 运行全面诊断
claude-doctor
​
# 特定检查
claude-doctor --check config     # 配置语法和冲突检查
claude-doctor --check hooks      # Hook 执行测试
claude-doctor --check mcp        # MCP Server 连接测试
claude-doctor --check context    # 上下文健康度分析
​
# 生成诊断报告
claude-doctor --report > claude-health-report.md

mcp-inspector

MCP 调试专用工具:

# 安装
npm install -g @anthropic/mcp-inspector
​
# 启动 MCP Server 调试代理
mcp-inspector --server github
​
# 在浏览器中打开 http://localhost:5173
# 可以:
# - 查看 Server 注册的所有 Tools/Resources/Prompts
# - 手动测试每个 Tool 的调用和响应
# - 查看 Server 的实时日志
# - 模拟错误场景测试

实操步骤

步骤 1:运行全面健康检查

# 在 Claude Code 会话中
/doctor
​
# 在终端中
claude --doctor
​
# 如果使用 claude-doctor
claude-doctor --report

仔细阅读每一条警告和建议。不要只盯着红色的错误——黄色的警告往往才是问题的早期信号。

步骤 2:排查"AI 今天不太对"的问题

当感觉 Claude Code 输出质量下降时,系统化排查:

Step 1: /status → 查看上下文使用量和会话时长
  → 如果上下文 > 70% 或会话 > 45 分钟,考虑 /compact 或新会话
​
Step 2: /doctor → 查看配置加载和 Hook 状态
  → 确认没有新引入的配置冲突
​
Step 3: /cost → 查看模型使用分布
  → 确认没有意外切换到成本更低的模型
​
Step 4: 检查最近的 CLAUDE.md 修改
  → git log --oneline CLAUDE.md .claude/
  → 最近的配置变更可能引入了不合适的规则
​
Step 5: 使用 --bare 模式对比
  → claude --bare "做同样的任务"
  → 如果 bare 模式正常,说明是配置问题

步骤 3:调试 Hook 执行

# 1. 启动 debug 模式
claude --debug 2>&1 | grep -i hook
​
# 2. 在 debug 输出中查找:
#    [Hook:PreToolUse] Matched: Bash
#    [Hook:PreToolUse] Running: block-dangerous.mjs
#    [Hook:PreToolUse] Exit code: 0 → Allowed
#    [Hook:PreToolUse] Exit code: 2 → Blocked: "危险命令已拦截"
​
# 3. 如果 Hook 没有出现在日志中:
#    - 检查 settings.json 中的 matcher 是否正确
#    - 检查脚本路径是否正确
#    - 检查脚本是否有执行权限

步骤 4:排查 MCP Server 故障

# 1. 检查 MCP Server 状态
/mcp
​
# 2. 如果 Server 没有运行:
#    - 检查 .mcp.json 中的 command 和 args
#    - 手动运行命令测试: npx -y @anthropic/mcp-server-github
#    - 检查环境变量: echo $GITHUB_TOKEN
​
# 3. 如果 Server 运行但工具不可用:
#    - 检查 Server 的日志输出
#    - 使用 mcp-inspector 测试
​
# 4. 如果 Server 频繁崩溃:
#    - 检查系统资源: htop / Activity Monitor
#    - 检查 Node.js 版本: node --version
#    - 升级 Server 版本: npx -y @anthropic/mcp-server-github@latest

避坑指南

坑 1:把所有问题归结为"模型变笨了"

这是最常⻅的认知偏差。模型本身不会"突然变笨",问题的根因通常是:

  • 上下文过载(80% 的情况):对话太长,关键信息被稀释

  • 配置变更(15% 的情况):CLAUDE.md 或 Hook 的修改引入了冲突规则

  • API 问题(4% 的情况):网络延迟、速率限制导致响应质量下降

  • 实际模型问题(< 1% 的情况):模型更新引入的 regression

坑 2:/compact 之后不再同步关键约束

/compact 会压缩对话历史,如果你在对话中途口头约定了一些约束(没有写入 CLAUDE.md),压缩后这些约束可能被模糊化或丢失。

解决:关键约束写入 CLAUDE.md,而不是依赖对话记忆。

坑 3:--debug 日志淹没关键信息

debug 日志非常详细,一个 10 分钟的会话可能产生几千行输出。不要试图肉眼扫描:

# 过滤出关键信息
claude --debug 2>&1 | grep -E "(ERROR|WARN|Hook.*Blocked|MCP.*failed|rate.limit)"
​
# 只查看 Hook 相关日志
claude --debug 2>&1 | grep "\[Hook"
​
# 只查看 API 请求和响应
claude --debug 2>&1 | grep -E "(Request|Response)"

坑 4:在 --bare 模式下执行了破坏性操作

--bare 模式禁用了所有安全 Hook。如果你有关键的安全拦截器(如"禁止 rm -rf /"),在 bare 模式下这些不会生效。

建议:bare 模式只用于读操作和简单测试,不要在 bare 模式下执行 Bash 命令。

课后作业

作业 1:建立你的诊断检查清单

结合你的日常使用经验,创建一份个性化的诊断检查清单:

# Claude Code 问题排查检查清单
​
## 第一步:量化症状
- [ ] 运行 /status,记录上下文使用量: ___%
- [ ] 运行 /cost,记录模型分布: ___
​
## 第二步:排除故障
- [ ] 感觉输出质量下降 → 检查上下文是否 > 70%
- [ ] Hook 没有触发 → 运行 --debug 查看 Hook 日志
- [ ] MCP Server 不可用 → 运行 /mcp 查看状态
- [ ] 配置文件不生效 → 运行 /doctor config

作业 2:排查并解决一个真实问题

  1. 找出你最近使用 Claude Code 时遇到的一个问题

  2. 使用本章介绍的方法系统化排查

  3. 记录:

    • 问题的表面症状

    • 排查过程(使用了哪些命令和模式)

    • 根因定位

    • 解决方案

    • 预防措施(避免再次发生)

作业 3:安装和使用第三方排障工具

  1. 安装 claude-doctor 并运行完整诊断报告

  2. 安装 mcp-inspector 并测试你的 MCP Server

  3. 对比内置诊断和第三方工具的输出差异

  4. 确定哪些工具值得长期使用,整合到你的工作流中

总结

Claude Code 的问题排查遵循一个简单的原则:量化模糊感觉,排除变量干扰,定位根因,固化预防。

  • /doctor 是起点,不是终点。它给你全局视图,但具体问题需要深入排查

  • --debug 给了你显微镜,但不是所有问题都需要这个级别的细节

  • --bare 是控制变量法的终极工具——关掉一切配置,看问题是否依然存在

  • 上下文管理 是预防质量退化的最有效方法——不要等到 90% 才压缩,70% 就是信号

记住:一个好的排查习惯比任何工具都重要。每次遇到问题时,不要先说"今天 AI 不太行",先说"让我先跑个 /doctor 看看"。

# 编辑器
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

AI群演请就位—个人博客（六）

项目的开发任务是构建一个完整的游戏叙事系统前端，包含世界选择、角色创建、主对话和结局展示四大核心界面。目标是为玩家提供沉浸式的穿书体验，让每个选择都影响剧情走向和最终结局。此前我已经基本完成各个界面的实现，此次博客记录的工作內容主要是我针对各个界面进行功能完善和体验优化。模块关键技术主要完善内容世界选择CSS Grid、悬停预览预览浮层、选中动画、边界检测角色创建步骤表单、点数分配三步引导、属性分

avatar AtomGit开源社区
cover

统一视频接入与多品牌利旧：基于 Docker 与 GB28181/RTSP 的边缘计算 AI 视频中台架构设计与源码交付实践

avatar AtomGit开源社区
cover

Lancet Digit Health（IF=24.1）牛津大学：基于Transformer的心血管病预防性治疗人群筛选

avatar AtomGit开源社区