Appearance
当 Claude Code 忽略指令或配置功能未生效时，先运行 /context 查看当前会话上下文，确认 CLAUDE.md、技能和 MCP 工具是否已加载。接着使用 /doctor 诊断配置错误，/status 查看生效的设置来源，/hooks 和 /mcp 检查钩子与服务器状态。常见原因包括：文件位于错误位置、多文件冲突、环境变量覆盖、钩子匹配器大小写错误或使用了 JSON 数组。如果怀疑背景配置干扰，可用 clean session 测试，逐层排除。
Claude Code 配置不生效排查方法
当 Claude 忽略一条指令，或者你配置的功能没有出现时，原因通常是文件没有加载、从与预期不同的位置加载，或者另一个文件覆盖了它。本文展示如何检查 Claude Code 实际加载了什么，从而定位问题。
安装、认证和网络连接问题，请参考 安装与登录故障排查。
查看上下文中加载了什么
/context 命令显示当前会话上下文窗口中的所有内容，按类别分开：系统提示、记忆文件、技能、MCP 工具和对话消息。先运行它，确认你的 CLAUDE.md、规则或技能描述是否存在。
如需某个类别的详细信息，再运行对应的专用命令：
| 命令 | 显示内容 |
|---|---|
/memory | 加载了哪些 CLAUDE.md 和规则文件，以及自动记忆条目 |
/skills | 项目、用户和插件来源的可用技能 |
/agents | 配置的子代理及其设置 |
/hooks | 当前的钩子配置 |
/mcp | 已连接的 MCP 服务器及其状态 |
/permissions | 当前生效的允许和拒绝规则 |
/doctor | 配置诊断：无效键、模式错误、安装健康检查 |
/debug [问题] | 为当前会话启用调试日志，并引导 Claude 根据日志输出和设置路径诊断问题 |
/status | 生效的设置来源，包括托管设置是否生效 |
如果 /memory 中缺少某个记忆文件，请检查它的位置与 CLAUDE.md 文件加载规则 是否一致。子目录下的 CLAUDE.md 文件只有在 Claude 用读取工具读取该目录下的文件时才会按需加载，而不是在会话启动时加载。
如果 /memory 确认文件已加载，但 Claude 仍然不遵守某条指令，那么问题很可能出在指令写法上，而不是加载与否。CLAUDE.md 适合用于你向新队友说明的指导，例如项目约定、构建命令和文件存放位置。
当指令过于模糊（可能被解释为多种方式）、两个文件给出了矛盾的方向，或者文件过长导致个别规则被忽视时，遵从度会下降。编写有效的指令 涵盖了保持高遵从度的具体性、大小和结构模式。
CLAUDE.md 和权限解决不同的问题。CLAUDE.md 告诉 Claude 你的项目如何运作，以便它做出好的决策。权限 和 钩子 则强制实施限制，无论 Claude 如何决策。用 CLAUDE.md 表达"我们这里这样做"。用权限或钩子处理安全边界和任何绝对不能发生的事，你需要的是保证而非指导。
检查已解析的设置
设置会从托管、用户、项目和本地多个范围合并。托管设置存在时始终优先。其余范围中，更接近的范围会覆盖更广的范围，顺序是本地 > 项目 > 用户。某些设置也可以通过命令行标志或环境变量设置，它们作为另一层覆盖。当某个设置似乎不生效时，你设置的值通常是被另一个范围或环境变量覆盖了。
运行 /doctor 来验证你的配置文件，找出无效键或模式错误。当 /doctor 报告问题时，按 f 键将诊断报告发送给 Claude，让它带你一步步修复。
运行 /status 查看哪些设置源处于活动状态，包括托管设置是否生效。要理解某个键哪个范围胜出，请参阅范围如何交互。
检查 MCP 服务器
运行 /mcp 查看每个配置的服务器、其连接状态，以及是否已为当前项目批准。一个服务器定义正确但仍不提供工具，常见原因有几个：
- 项目级范围的服务器（在
.mcp.json中）需要一次性批准。如果提示被关闭，服务器将保持禁用状态，直到你在/mcp中批准它。 - 无法启动的服务器会在
/mcp中显示为失败。command或args中的相对文件路径是常见原因，因为它们相对于你启动 Claude Code 的目录解析，而非.mcp.json的位置。 - 显示已连接但列出零个工具的服务器已成功启动，但没有返回工具列表。从
/mcp中选择重新连接。如果数量仍为零，运行claude --debug mcp查看服务器的 stderr 输出。
关于配置位置和范围规则，请参见 MCP。
检查钩子
运行 /hooks 列出当前会话注册的所有钩子，按事件分组。如果你定义的钩子没有出现，说明它没有被读取：钩子应放在设置文件的 "hooks" 键下，而不是独立的文件。
如果钩子出现了但不触发，通常是匹配器的问题。matcher 字段是一个字符串，用 | 匹配多个工具名，例如 "Edit|Write"。拼写错误的工具名会静默失败，因为匹配器永远不会匹配。数组值会导致模式错误：Claude Code 会显示设置错误通知，/doctor 会报告验证失败，该钩子条目会被丢弃，因此不会出现在 /hooks 中。
对 settings.json 的编辑会在短暂的文件稳定延迟后生效，无需重启。如果保存几秒后 /hooks 仍然显示旧定义，再次运行 /hooks 刷新视图。
如果 /hooks 显示钩子但仍不触发，下一步是观察钩子评估的实时过程。以 claude --debug hooks 启动一个会话，并触发工具调用。调试日志会记录每个事件、检查了哪些匹配器以及钩子的退出代码和输出。参见调试钩子了解日志格式，以及钩子故障排查了解常见失败模式。
用干净配置测试
如果定向检查无法隔离原因，或者你的配置处于未知状态，可以对比一个不加载任何通常配置的会话。将 CLAUDE_CONFIG_DIR 指向空目录以绕过 ~/.claude 下的所有内容，并从没有 .claude 文件夹、.mcp.json 或 CLAUDE.md 的目录启动，这样项目配置也会被跳过。
bash
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude干净会话没有用户或项目设置、钩子、MCP 服务器、插件或记忆。
- 如果组织部署了托管设置，它们仍然会生效，因为它们位于
~/.claude之外的系统路径 - 在 Linux 和 Windows 上，你会被要求重新登录，因为凭据存储在配置目录下
- 在 macOS 上，凭据在钥匙串中，会延续到干净会话
如果问题在此消失，原因在你的实际 ~/.claude 或项目 .claude 文件中。一次只引入一个文件（通过将文件复制到临时目录，或从你的项目启动），找出哪个文件引起问题。如果问题在干净会话中仍然存在，原因在你的用户和项目配置之外。运行 /status 检查是否生效了托管设置，查找影响 Claude Code 的环境变量，然后参见故障排查。
常见原因速查
大多数配置问题都源于少数位置和语法规则。在假设是 bug 之前，先检查以下内容：
| 症状 | 原因 | 修复 |
|---|---|---|
| 钩子从不触发 | matcher 是 JSON 数组而非字符串 | 使用单个字符串配合 | 匹配多个工具，例如 "Edit|Write"。参见匹配器模式。 |
| 钩子从不触发 | matcher 值是小写，例如 "bash" | 匹配区分大小写。工具名首字母大写：Bash、Edit、Write、Read。 |
| 钩子从不触发 | 钩子定义在独立文件中而非 settings.json | 项目和用户配置没有独立的钩子文件。在 settings.json 的 "hooks" 键下定义钩子。只有插件可以加载单独的 hooks/hooks.json。参见钩子配置。 |
| 全局设置的权限、钩子或 env 被忽略 | 配置添加到了 ~/.claude.json | ~/.claude.json 保存应用状态和 UI 切换。permissions、hooks 和 env 应放在 ~/.claude/settings.json。这是两个不同的文件。 |
settings.json 中的某个值似乎被忽略 | 同一键在 settings.local.json 中也设置了 | settings.local.json 覆盖 settings.json，两者都覆盖 ~/.claude/settings.json。参见设置优先级。 |
技能未出现在 /skills 中 | 技能文件位于 .claude/skills/name.md 而非文件夹内 | 使用包含 SKILL.md 的文件夹：.claude/skills/name/SKILL.md。 |
技能出现在 /skills 中但 Claude 从不调用它 | 技能 frontmatter 中有 disable-model-invocation: true，或其描述与你提问方式不匹配 | 检查 /skills 中的徽章："user-only" 标签表示 Claude 不会主动触发它。参见技能调用。 |
子目录 CLAUDE.md 中的指令似乎被忽略 | 子目录文件按需加载，而非会话启动时 | 它们会在 Claude 用读取工具读取该目录下的文件时加载，而非在启动时或在该目录写入/创建文件时。参见CLAUDE.md 文件如何加载。 |
子代理忽略 CLAUDE.md 指令 | 内置的 Explore 和 Plan 代理会跳过 CLAUDE.md。自定义子代理与主对话一样会加载 CLAUDE.md | 对于 Explore 或 Plan，在委托提示中重述指令。对于自定义子代理，将关键指令放在代理文件主体中，该主体将成为代理的系统提示。参见启动时加载的内容。 |
| 清理逻辑在会话结束时从不运行 | 未配置 SessionEnd 钩子 | 在 settings.json 中添加 SessionEnd 钩子。参见钩子事件列表。 |
.mcp.json 中的 MCP 服务器从不加载 | 文件在 .claude/ 下或使用了 Claude Desktop 的配置格式 | 项目 MCP 配置应放在仓库根目录下的 .mcp.json，而不是 .claude/ 内部。参见 MCP 配置。 |
在 settings.json 的 mcpServers 下添加的 MCP 服务器从不出现 | settings.json 不读取 mcpServers 键 | 在仓库根目录下的 .mcp.json 中定义项目服务器，或运行 claude mcp add --scope user 添加用户级服务器。参见 MCP 配置。 |
| 项目 MCP 服务器已添加但不出现 | 一次性批准提示被关闭了 | 项目级服务器需要批准。运行 /mcp 查看状态并批准。 |
| MCP 服务器在某些目录下启动失败 | command 或 args 使用了相对路径 | 本地脚本使用绝对路径。位于 PATH 中的可执行文件如 npx 或 uvx 可直接使用。 |
| MCP 服务器启动时缺少预期的环境变量 | 变量在 settings.json 的 env 中，该变量不会传播到 MCP 子进程 | 改为在 .mcp.json 中设置每服务器的 env。 |
Bash(rm *) 拒绝规则无法阻止 /bin/rm 或 find -delete | 前缀规则匹配的是命令字符串本身，而不是底层可执行文件 | 为每个变体添加显式模式，或使用 PreToolUse 钩子 或沙箱来获得硬保证。 |
相关资源
关于每个配置面的完整参考，请参见专用页面：
.claude目录参考：每个配置文件的位置及读取者- 设置：优先级顺序和完整键列表
- 钩子参考：事件名称、载荷和
--debug hooks输出格式 - MCP：服务器配置、批准和
/mcp输出 - 安装与登录故障排查：
command not found、PATH 和身份验证问题 - 故障排查：性能、挂起和搜索问题
常见问题
为什么 CLAUDE.md 里的指令没有生效？
先运行 /context 和 /memory 确认文件是否已加载。如果已加载，检查指令是否过于模糊、与其他文件冲突，或文件过长导致部分规则被忽视。子目录的 CLAUDE.md 只会在 Claude 用读取工具读取该目录下的文件时才会加载，会话启动时不会加载。对于 Explore 和 Plan 子代理，它们会跳过 CLAUDE.md，请在委托提示中重述指令。
Hooks 配置正确但不触发怎么办？
运行 /hooks 确认钩子是否出现。如果出现，检查 matcher 字段：必须是字符串（不能是数组），工具名首字母大写且区分大小写，例如 "Edit|Write"。如果钩子未出现，检查是否定义在 settings.json 的 "hooks" 键下，而不是独立文件。编辑后等待文件稳定延迟，再次运行 /hooks 刷新。如果仍不触发，用 claude --debug hooks 启动调试会话并触发工具调用，查看日志。
MCP 服务器显示已连接但没有工具怎么办？
运行 /mcp 确认服务器状态。如果显示已连接但工具数为零，选择重新连接。如果多次重连后仍为零，用 claude --debug mcp 查看服务器的 stderr 输出。确认 command 和 args 中的路径是绝对路径，或者可执行文件在 PATH 中。项目级服务器（在 .mcp.json 中）需要在 /mcp 中一次性批准，如果提示被关闭会保持禁用。