Skip to main content
当 Claude 忽略了一条指令或你配置的功能没有出现时，通常是因为文件没有加载、从你预期之外的位置加载，或者被另一个文件覆盖了。本指南展示了如何检查 Claude Code 实际加载了什么，以便你能够缩小范围。 对于安装、身份验证和连接问题，请参阅故障排除安装和登录。

​
查看加载到上下文中的内容

/context 命令会显示当前会话中占用上下文窗口的所有内容，并按类别细分：系统提示词、系统工具、MCP 工具、自定义子代理（及其各自的加载来源）、记忆文件、skill 以及对话消息。请首先运行此命令，以确认您的 CLAUDE.md、规则或 skill 描述是否已加载。/context 中的 skill 部分还包括 随附 skill，而 /skills 不会列出这些内容。 如需查看特定类别的详细信息，请继续使用相应的专用命令： 如果某个记忆文件未出现在 /context 的细分列表中，请对照CLAUDE.md 文件的加载方式检查其位置。子目录中的 CLAUDE.md 文件是按需加载的，而不是在会话开始时加载，因此它们不会出现在该细分列表中。 如果 /context 确认文件已加载，但 Claude 仍未遵循某条特定指令，那么问题很可能在于指令的编写方式，而非是否已加载。CLAUDE.md 非常适合用于提供您会给新团队成员的那类指导，例如项目约定、构建命令以及文件应放置的位置。 当指令含糊到可以有多种理解方式、两个文件给出相互冲突的指示，或者文件变得过长以致单条规则得到的关注减少时，遵循度就会下降。编写有效的指令介绍了有助于保持高遵循度的具体性、篇幅和结构模式。
CLAUDE.md 和权限解决的是不同的问题。CLAUDE.md 告诉 Claude 您的项目如何运作，以便其做出良好的决策。权限和 hook 则无论 Claude 做出何种决定都会强制执行限制。请将 CLAUDE.md 用于”我们这里是这样做的”这类内容。对于安全边界以及任何绝不能发生的事情，即您需要的是保证而非指导的情况，请使用权限或 hook。

​
检查已解析的设置

设置在托管、用户、项目和本地范围内合并。当存在时，托管设置总是优先。在其余的中，更接近的范围按本地、项目、用户的顺序覆盖更广泛的范围。某些设置也可以由命令行标志或环境变量设置，它们充当另一个覆盖层。当设置似乎不适用时，你设置的值通常被另一个范围或环境变量覆盖。 要查找无效的设置文件，请从终端运行 claude doctor。它打印只读安装和设置诊断，而不启动会话。要进行完整检查，同时提议修复并在应用前询问，请在会话内运行 /doctor。 运行 /status 来查看哪些设置源是活跃的，包括是否启用了托管设置。要了解 Claude Code 对给定键使用哪个范围，请参阅设置优先级。

​
检查 MCP 服务器

运行 /mcp 来查看每个配置的服务器、其连接状态以及你是否为当前项目批准了它。服务器可以定义正确但仍然不提供工具，原因有几个常见的：
  • .mcp.json 中的项目范围服务器需要一次性批准。如果提示被关闭，服务器将保持禁用状态，直到你从 /mcp 批准它。
  • 启动失败的服务器在 /mcp 中显示为失败。command 或 args 中的相对文件路径是一个常见原因，因为它们相对于你启动 Claude Code 的目录而不是 .mcp.json 的位置进行解析。
  • 显示为已连接但列出零个工具的服务器已成功启动但没有返回工具列表。从 /mcp 选择重新连接。如果计数保持为零，运行 claude --debug=mcp 并在 ~/.claude/debug/<session-id>.txt 的调试日志中读取服务器的 stderr。
对于配置位置和范围规则，请参阅 MCP。

​
检查 hook

运行 /hooks 来列出当前会话注册的每个 hook，按事件分组。如果您定义的 hook 没有出现，说明 Claude Code 没有加载它。请检查以下原因：
  • 该 hook 定义在独立文件中。hook 应位于设置文件中的 "hooks" 键下。
  • matcher 值是数组而不是单个字符串。在您启动交互式会话时以及在 claude doctor 中，Claude Code 会将该条目列为无效设置。如果该数组位于 PreToolUse 或 PermissionRequest 下，该文件中的其他 hook 也都不会加载。
如果 hook 出现但没有触发，匹配器通常是原因。检查它是否有这些错误：
  • matcher 字段是一个使用 | 来匹配多个工具名称的单个字符串，例如 "Edit|Write"。, 分隔符是等效的，所以 "Edit,Write" 匹配相同的工具。在 v2.1.191 之前，逗号会进入正则表达式评估，匹配器永远不会匹配，所以如果您尚未使用 v2.1.191，请使用 |。
  • 拼写错误的工具名称会产生一个不匹配任何内容的匹配器，所以 hook 会无声地失败。
当您编辑 settings.json 时，更改在短暂的文件稳定延迟后在运行的会话中生效，即使您在会话启动后创建了文件或项目的 .claude/ 文件夹。您不需要重新启动。在 v2.1.257 之前，Claude Code 没有检测到在会话启动后创建的 .claude/ 文件夹中的编辑。 如果保存后几秒钟 /hooks 仍然显示旧定义，再次运行 /hooks 来刷新视图。 如果 /hooks 显示 hook 但它仍然没有触发，下一步是实时观察 hook 评估。使用 claude --debug 启动会话并触发工具调用。调试日志记录每个事件、检查了哪些匹配器以及 hook 的退出码和输出。有关日志格式，请参阅调试 hook，有关常见失败模式，请参阅hook 故障排除。

​
针对干净配置进行测试

首先使用 claude --safe-mode，它会启动一个禁用您的自定义内容的会话，包括：
  • CLAUDE.md
  • Skill、插件和 hook
  • MCP 服务器
  • 自定义命令和 Agent
  • 自定义输出样式
  • 自定义快捷键
身份验证、模型选择、内置工具和权限正常工作。如果问题在安全模式下消失，则说明原因已缩小到您关闭的某一项。要找出具体是哪一项，请使用该项对应的检查，例如查看加载到上下文中的内容、检查 MCP 服务器或检查 hook。 安全模式仍然应用来自您组织的托管 hook 和设置策略。托管插件、skill、CLAUDE.md 和 MCP 服务器会被关闭。 如果问题在安全模式下仍然存在，或您的设置本身可疑，请启动一个不包含您任何自有配置的会话，检查问题是否仍然出现。
1

创建一个空目录并切换到该目录

在没有运行 Claude Code 会话的 shell 中，创建该目录并进入其中：
2

使用干净的配置目录启动 Claude Code

在同一个 shell 中，将 CLAUDE_CONFIG_DIR 设置为一个新目录以替代 ~/.claude，并传入 --setting-sources user 以关闭项目配置，例如 .claude/settings.json、CLAUDE.md 和 .mcp.json：
该变量仅对本次启动生效。
首次启动时，您会再次经历首次运行设置屏幕，这表明干净配置目录已生效。托管设置仍然适用；如果您使用 claude.ai 账户登录，连接器仍会加载。
3

重现问题

在干净会话中重复触发问题的操作：
  • 问题消失：原因在您的用户或项目配置中。将 ~/.claude.json 和 ~/.claude 中的文件逐个复制到 ~/claude-clean/config。如果没有任何文件使问题重新出现，请在同一个 shell 中进入您的项目目录，并在不带 --setting-sources user 的情况下启动 Claude Code。在 Bash 或 Zsh 中，运行 CLAUDE_CONFIG_DIR=~/claude-clean/config claude。在 PowerShell 中，该变量仍处于设置状态，因此运行 claude 即可。
  • 问题仍然存在：原因在您的用户和项目配置之外。在会话中运行 /status 以检查托管设置，检查您的 shell 中的环境变量，然后参阅故障排除。

​
检查常见原因

大多数配置意外可以追溯到一小组位置和语法规则。在假设存在错误之前检查这些： 有关每个配置表面的完整参考，请参阅专用页面：