调试你的配置

CLAUDE.md、设置、hooks、MCP 服务器或 skills 没生效时的排查方法：用 /context、/doctor、/hooks、/mcp 看实际加载了什么，用 safe mode 对照，以及常见原因速查表。

当 Claude 忽略某条指令，或你配置的功能没出现时，原因通常是：文件没加载、从你没想到的位置加载、或被另一个文件覆盖。本页教你检查 Claude Code 实际加载了什么。安装、认证和连接问题见「故障排查」页。

看什么被加载进了上下文

/context 显示当前会话上下文窗口里的所有东西，按类别分解：系统提示、系统工具、MCP 工具、自定义子智能体（含各自来源）、记忆文件、skills 和对话消息。先运行它确认你的 CLAUDE.md 或其他文件是否真的加载了。要看某一类的细节，用对应命令：

命令	显示
`/memory`	用户和项目范围的记忆文件位置，可在编辑器里打开，另有自动记忆文件夹和开关
`/skills`	项目、用户和插件来源的可用 skills
`/hooks`	生效的 hook 配置
`/mcp`	已连接的 MCP 服务器及状态
`/permissions`	当前生效的 allow / deny 规则
`/doctor`	配置体检：安装健康度、无效的设置文件、未使用的扩展、同一目录里重名的子智能体、已提交的 `CLAUDE.md` 中 Claude 可从代码库推导的内容，并提出修复建议
`/debug [issue]`	开启会话的调试日志，并提示 Claude 用日志输出和设置路径来诊断
`/status`	生效的设置来源，包括托管设置是否在起作用

如果某个记忆文件没出现在 /context 里，检查它的位置是否符合 CLAUDE.md 的加载规则：子目录里的 CLAUDE.md 是 Claude 用 Read 工具读取该目录里的文件时按需加载的，不是会话开始时加载。

如果 /context 确认文件已加载但 Claude 仍不遵循某条指令，问题多半在指令怎么写而不是有没有加载：指令含糊到可以多种解读、两个文件相互冲突、文件长到每条规则得到的注意力变少，都会降低遵循度。

CLAUDE.md 和权限解决不同的问题。CLAUDE.md 告诉 Claude 你的项目如何运作，让它做出好决策；权限和 hooks 无论 Claude 怎么决定都强制执行限制。「我们这里是这样做的」用 CLAUDE.md，安全边界用权限或 hooks。

检查生效的设置

设置在托管、用户、项目和本地范围间合并。存在托管设置时它最先应用；其余范围里，离得近的覆盖宽的，顺序是本地、项目、用户。有些设置还可以被命令行标志或环境变量设置。

想找无效的设置文件，从终端运行 claude doctor：它只读地打印安装和设置诊断，不启动会话。想要同时提出修复并在应用前询问的完整体检，在会话里运行 /doctor。/status 显示哪些设置来源生效。

检查 MCP 服务器

/mcp 列出每个已配置服务器、连接状态，以及你是否批准了它用于当前项目。服务器定义正确却不提供工具，常见原因：

.mcp.json 里的项目级服务器需要一次性批准；提示被关掉后，服务器保持禁用，直到你在 /mcp 里批准
启动失败的服务器在 /mcp 里显示为 failed；command 或 args 里的相对文件路径是常见原因，因为它们相对于你启动 Claude Code 的目录解析，而不是 .mcp.json 所在位置
显示已连接但工具数为零，说明启动成功但没返回工具列表：在 /mcp 里选 Reconnect；仍为零就运行 claude --debug=mcp，到 ~/.claude/debug/<session-id>.txt 里读服务器的 stderr

检查 hooks

/hooks 列出当前会话注册的每个 hook（按事件分组）。你定义的 hook 不出现，说明没被读到：hooks 放在设置文件的 "hooks" 键下，不是独立文件。hook 出现但不触发，通常是 matcher 的问题：

matcher 是单个字符串，用 | 匹配多个工具名，如 "Edit|Write"；, 分隔等价（v2.1.191 之前逗号会落到正则求值，永远匹配不到，所以不确定版本时用 |）
工具名拼错会产生什么都匹配不到的 matcher，hook 静默失败
写成数组是 schema 错误：Claude Code 显示设置错误通知并拒绝整个用户、项目或本地设置文件，claude doctor 会报告校验失败，该文件里的 hook 都不会出现在 /hooks 里

编辑 settings.json 后，变更在短暂的文件稳定延迟后对运行中的会话生效，无需重启。若几秒后 /hooks 仍显示旧定义，再运行一次 /hooks 刷新。仍不触发就用 claude --debug 启动并触发该工具调用，调试日志会记录每个事件、检查了哪些 matcher、hook 的退出码和输出。

用干净配置对照

先试 claude --safe-mode：它启动一个禁用所有自定义内容（CLAUDE.md、skills、插件、hooks、MCP 服务器、自定义命令和智能体）的会话；认证、模型选择、内置工具和权限照常工作。问题在 safe mode 里消失，就说明原因在你的自定义内容里。

如果问题在 safe mode 里仍存在，或怀疑设置本身，就和一个不从你常规配置加载任何东西的会话对比：把 CLAUDE_CONFIG_DIR 指向空目录，绕过 ~/.claude 下的一切，并从没有 .claude 文件夹、.mcp.json 等的目录启动：

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

干净会话没有用户或项目设置、hooks、MCP 服务器、插件或记忆；首次启动会看到首次运行的设置界面（从主题选择开始），说明干净配置目录生效了。注意：组织部署的托管设置仍会应用（它们从配置目录之外读取），你需要重新登录。如果问题在这里消失，原因在你真实的 ~/.claude 或项目 .claude 文件里，逐个重新引入来定位。

常见原因速查

症状	原因	修复
Hook 从不触发	`matcher` 是 JSON 数组而不是字符串	用单个字符串，用 `\|` 匹配多个工具，如 `"Edit\|Write"`
Hook 从不触发	matcher 值是小写，如 `"bash"`	匹配区分大小写，工具名首字母大写：`Bash`、`Edit`、`Write`、`Read`
Hook 从不触发	hooks 定义在独立文件而不是 `settings.json`	项目或用户配置没有独立的 hooks 文件，放在 `settings.json` 的 `"hooks"` 键下；只有插件加载单独的 `hooks/hooks.json`
全局设置的权限或 hooks 被忽略	配置加到了 `~/.claude.json`	`~/.claude.json` 存应用状态和 UI 开关；`permissions`、`hooks`、`env` 属于 `~/.claude/settings.json`，这是两个不同的文件
`settings.json` 的某个值似乎被忽略	同一个键在 `settings.local.json` 里也有	`settings.local.json` 覆盖 `settings.json`，二者都覆盖 `~/.claude/settings.json`
Skill 不出现在 `/skills`	skill 文件在 `.claude/skills/name.md` 而不是文件夹里	用文件夹，里面放 `SKILL.md`：`.claude/skills/name/SKILL.md`
Skill 出现但 Claude 从不调用	frontmatter 有 `disable-model-invocation: true`，或描述与你的措辞不匹配	看 `/skills` 里的标记：「user-only」表示 Claude 不会自行触发
子目录 `CLAUDE.md` 的指令似乎被忽略	子目录文件按需加载，不在会话开始时	在 Claude 用 Read 读取该目录文件时才加载，写入或创建文件时不会
子智能体忽略 `CLAUDE.md`	内置 Explore 和 Plan 智能体跳过 `CLAUDE.md`；自定义子智能体与主对话一样加载，除非定义里设了 `omitClaudeMd`	对 Explore 或 Plan，把指令重述在你的委派提示里
会话结束时的清理逻辑从不运行	没配置 `SessionEnd` hook	在 `settings.json` 里加 `SessionEnd` hook
`.mcp.json` 里的 MCP 服务器从不加载	文件在 `.claude/` 下，或服务器放在顶层 `servers` 键下（像 VS Code 的 `mcp.json`）而不是 `mcpServers`	项目 MCP 配置放在仓库根的 `.mcp.json`，服务器在 `mcpServers` 键下
在 `settings.json` 的 `mcpServers` 下添加的服务器从不出现	`settings.json` 不读取 `mcpServers` 键	项目服务器定义在仓库根的 `.mcp.json`，用户范围的用 `claude mcp add --scope user`
项目 MCP 服务器添加后不出现	一次性批准提示被关掉了	运行 `/mcp` 查看状态并批准
MCP 服务器从某些目录启动失败	`command` 或 `args` 用了相对文件路径	本地脚本用绝对路径；`PATH` 上的可执行文件如 `npx`、`uvx` 可以直接用
MCP 服务器启动时缺少预期的环境变量	服务器配置条目里没设置，并且不在 Claude Code 传给 stdio 服务器的环境里	在服务器的 `.mcp.json` 条目里设置每个服务器的 `env`
`Bash(rm *)` 的 deny 规则没拦住 `/bin/rm` 或 `find -delete`	Bash 规则匹配字面命令字符串，而不是底层可执行文件	用 PreToolUse hook 或沙箱获得硬保证