Claude Code 学习站
Mingyu's Library

学习站 / 实战 Tip / E · 配置与选型

出问题先跑这三个

CLAUDE.md 不生效、hook 不触发、MCP 没工具……别猜,先跑三条诊断命令,让 Claude Code 自己告诉你哪一环断了。

配置类问题的原因几乎总是三种之一:文件没载入、从别的位置载入了、或被另一层配置覆盖了。排障三板斧就是把这三种可能逐一排掉。

一句话结论

结论 按顺序跑:/doctor(自动体检安装与配置,提出修复)→ /context(看 CLAUDE.md、skills、MCP 工具到底载入了没)→ /mcp(查外部服务器连接与审批状态)。Claude Code 起不来时,改在终端跑 claude doctor;怀疑是某个插件/hook/MCP 拖慢或搞坏了会话,用 claude --safe-mode 裸跑对照。

做法步骤

  1. 第一板斧:/doctor,不知道哪坏了就先跑它。官方它做一次安装与配置体检:安装健康度、无效的 settings 文件、没用上的扩展、同目录重名的 subagent、以及 CLAUDE.md 里 Claude 本可自己推断的冗余内容(trim 检查需 v2.1.206+,当前最新版 2.1.222 已满足),发现问题会提出修复、经你确认才应用。如果 claude 根本起不动,在终端跑 claude doctor,不开会话打印只读诊断。顺手记录版本:claude --version 或会话内 /status——很多修复是版本门槛问题。
  2. 第二板斧:/context,确认「它到底载入了没」。官方它把当前会话占据上下文窗口的东西按类列出:系统提示、内置/MCP 工具、自定义 subagent 及其来源、memory 文件、skills、对话消息。你的 CLAUDE.md 不在 Memory files 列表里?那 Claude 根本看不见它——去查文件位置(子目录 CLAUDE.md 只在 Claude 读到那个目录的文件时才按需载入,不在启动时)。列表里有但 Claude 不照做?那是写法问题:指令太模糊、两个文件互相矛盾、或文件太长稀释了注意力,参见 CLAUDE.md 写太长被无视。
  3. 第三板斧:/mcp,查外部服务器。官方它列出每个已配置服务器的连接状态和项目审批状态。三个常见坑:项目级 .mcp.json 的服务器需要一次性审批,弹窗被关掉就一直禁用,在 /mcp 里补批;服务器启动失败常因 command/args 里写了相对路径(相对启动目录解析);显示已连接但 0 个工具,先选 Reconnect,还不行就 claude --debug mcp 看服务器的 stderr。
  4. 按症状接续:对症命令表。官方三板斧定位到大类后,用专项命令深挖:
    症状/疑点跑什么它告诉你
    hook 没触发/hooks,再 claude --debug hooks注册了哪些 hook;不在列表=没被读到(hooks 必须写在 settings.json 的 "hooks" 键下,没有独立 hooks 文件),在列表但不触发多半是 matcher 写错(区分大小写,多工具用 "Edit|Write")
    某条设置不生效/status + /permissions哪些设置来源在生效;常见坑:同键被 settings.local.json 覆盖,或配置误写进 ~/.claude.json(应写 ~/.claude/settings.json,是两个不同文件)
    记忆/指令问题/memory + /skills各作用域 memory 文件位置;skill 不出现常因文件放成 .claude/skills/name.md(应为 name/SKILL.md 目录结构)
    怀疑扩展搞鬼(卡顿/行为异常)claude --safe-mode禁用全部自定义(CLAUDE.md/skills/plugins/hooks/MCP)裸跑;问题消失=某个扩展是元凶,再用上面的专项命令定位
    怀疑用户级配置本身坏了CLAUDE_CONFIG_DIR=/tmp/claude-clean claude指向空配置目录完全绕开 ~/.claude;问题还在=原因在配置之外
  5. 还没头绪,把问题交给 Claude。官方会话内 /debug [问题描述] 会开启本会话的 debug 日志并让 Claude 结合日志与设置路径自行诊断;性能类问题(高 CPU/内存、卡死)另见官方 troubleshooting 页,常用解法是 /compact 缩上下文和重启会话(claude --resume 不丢对话)。

可直接抄的 prompt

我的 Claude Code 配置好像没生效。症状:<填写,例如「CLAUDE.md 里的规则被无视」/
「PostToolUse hook 没触发」/「MCP 服务器连上了但没有工具」>。

请按官方排障顺序帮我诊断:
1. 先让我跑 /doctor 和 /context,我把输出贴给你;
2. 根据输出判断属于哪种情况:文件没载入、从别的位置载入、还是被其他
   作用域覆盖(managed > local > project > user);
3. 如果载入正常但行为不对,检查是不是指令写法问题(模糊/冲突/过长);
4. 涉及 hooks 或 MCP 时,再让我补跑 /hooks 或 /mcp;
5. 最后给出具体修复步骤,并注明每一步预期看到什么。

来源与最后核实日期