Claude Code 自动化与排错
Claude Code 自动化与排错
调试配置
3 分钟阅读
调试你的配置
诊断为什么 CLAUDE.md、设置、钩子、MCP 服务器或技能没有生效。用 /context、/doctor、/hooks 和 /mcp 查看实际加载了什么。
当 Claude 忽略了一条指令，或你配置的某个功能没有出现时，原因通常是该文件没有加载、它从与你预期不同的位置加载，或另一个文件覆盖了它。本指南展示如何检查 Claude Code 实际加载了什么，以便你能缩小范围，判断是哪种情况。
关于安装、身份验证和连接性问题，请改为参阅故障排查安装与登录。
查看加载进上下文的内容
/context 命令会按类别（系统提示词、记忆文件、技能、自定义子智能体及其各自加载的来源、MCP 工具和对话消息）展示占用当前会话上下文窗口的每一项内容。先运行它，确认你的 CLAUDE.md、规则或技能描述是否确实存在。
要查看某个特定类别的详情，可以接着使用专门的命令：
| 命令 | 显示内容 |
|---|---|
/memory | 哪些 CLAUDE.md 和规则文件已加载，以及自动记忆条目 |
/skills | 来自项目、用户和插件来源的可用技能 |
/hooks | 当前生效的钩子配置 |
/mcp | 已连接的 MCP 服务器及其状态 |
/permissions | 当前生效的、已解析的允许和拒绝规则 |
/doctor | 安装体检：安装健康状况、无效的设置文件、未使用的扩展，以及同一目录中重名的子智能体，并提出修复建议 |
/debug [issue] | 为该会话启用调试日志，并提示 Claude 用日志输出和设置路径进行诊断 |
/status | 当前生效的设置来源，包括统一管理设置是否生效 |
如果 /memory 中缺少某个记忆文件，请对照CLAUDE.md 文件如何加载检查它的位置。子目录的 CLAUDE.md 文件会在 Claude 用 Read 工具读取该目录中的某个文件时按需加载，而不是在会话启动时加载。
如果 /memory 确认该文件已加载，但 Claude 仍未遵循某条特定指令，问题很可能出在该指令的写法，而不是它是否加载。CLAUDE.md 非常适合用来传达你会告诉新团队成员的那类指导，例如项目约定、构建命令，以及文件应该放在哪里。
当一条指令模糊到可以有多种解读、两个文件给出相互矛盾的方向，或该文件已经长到个别规则得不到足够关注时，遵循度就会下降。撰写有效的指令介绍了能保持高遵循度的具体性、篇幅和结构模式。
检查已解析的设置
设置会在统一管理、用户、项目和本地范围之间合并。统一管理设置一旦存在就总是生效。在其余范围中，更接近的范围会覆盖更宽泛的范围，顺序是本地、然后项目、然后用户。有些设置也可以通过命令行标志或环境变量设置，它们充当另一层覆盖。当某个设置似乎没有生效时，通常是因为你设置的值被另一个范围或某个环境变量覆盖了。
运行 /doctor 检查你的配置和安装。它会报告发现的内容，包括无效的设置文件、重复的安装和未使用的扩展，然后提出修复方案，只在你确认后才应用。在 v2.1.205 之前，/doctor 会打开一个只读的诊断界面，按 f 会把报告发给 Claude 修复。
在终端中，claude doctor 会打印只读的安装和设置诊断信息，而不会启动一个会话。
运行 /status 查看当前生效的设置来源，包括统一管理设置是否生效。关于对于某个键哪个范围生效，请参阅范围如何相互作用。
检查 MCP 服务器
运行 /mcp 查看每个已配置的服务器、其连接状态，以及你是否已为当前项目批准它。一个服务器可能定义正确，却仍不提供工具，常见原因有以下几种：
.mcp.json中的项目范围服务器需要一次性批准。如果该提示被关闭了，该服务器会保持禁用状态，直到你在/mcp中批准它。- 一个启动失败的服务器会在
/mcp中显示为失败。command或args中的相对文件路径是常见原因，因为它们会相对于你启动 Claude Code 所在的目录解析，而不是相对于.mcp.json的位置。 - 一个显示为已连接、但列出零个工具的服务器已经成功启动，但没有返回工具列表。在
/mcp中选择Reconnect。如果数量仍为零，运行claude --debug mcp查看该服务器的 stderr 输出。
关于配置位置和范围规则，请参阅MCP。
检查钩子
运行 /hooks 列出当前会话中注册的每个钩子，按事件分组。如果你定义的某个钩子没有出现，说明它没有被读取到：钩子应放在设置文件中的 "hooks" 键下，而不是一个独立的文件中。
如果该钩子出现了，但没有触发，通常是匹配器的问题。检查是否有以下错误：
matcher字段是一个用|匹配多个工具名称的单一字符串，例如"Edit|Write"。用,分隔是等效的，因此"Edit,Write"匹配相同的工具。在 v2.1.191 之前，逗号会被当作正则表达式求值，导致该匹配器永远不匹配，因此如果你还没有升级到 v2.1.191，请使用|。- 一个拼写错误的工具名称会导致该匹配器什么都不匹配，钩子因此静默失败。
- 一个数组值是一种模式错误：Claude Code 会显示一条设置错误提示，并拒绝整个用户、项目或本地设置文件，
claude doctor会报告这次校验失败，该文件中的任何钩子都不会出现在/hooks中。在统一管理设置中，只有那个无效条目会被剔除，该文件中的其他钩子仍会生效。
对 settings.json 的编辑会在短暂的文件稳定延迟之后，在正在运行的会话中生效。你不需要重启。如果保存几秒钟后 /hooks 仍显示旧的定义，再运行一次 /hooks 刷新视图。
如果 /hooks 显示了该钩子，但它仍然没有触发，下一步是实时观察钩子的评估过程。用 claude --debug hooks 启动一个会话，并触发该工具调用。调试日志会记录每个事件、检查了哪些匹配器，以及该钩子的退出码和输出。关于日志格式，请参阅调试钩子；关于常见的失败模式，请参阅钩子故障排查。
用一份干净的配置进行测试
从 claude --safe-mode 开始，它会启动一个关闭所有自定义配置的会话，包括 CLAUDE.md、技能、插件、钩子、MCP 服务器，以及自定义命令和智能体。身份验证、模型选择、内置工具和权限仍正常工作。如果问题在安全模式下消失，说明原因就是这些配置之一；使用上面的针对性检查来找出是哪一个。安全模式仍会应用来自你组织的统一管理钩子和设置策略。统一管理的插件、技能、CLAUDE.md 和 MCP 服务器都会被关闭。
如果问题在安全模式下仍然存在，或你的设置本身值得怀疑，可以对照一个不从你常规配置中加载任何内容的会话进行比较。让 CLAUDE_CONFIG_DIR 指向一个空目录，绕过 ~/.claude 下的一切，并从一个没有 .claude 文件夹、.mcp.json 或 CLAUDE.md 的目录启动，这样项目配置也会被跳过。
这个干净的会话没有用户或项目设置、钩子、MCP 服务器、插件或记忆。
- 如果你的组织部署了统一管理设置，它仍会生效，因为它存放在
~/.claude之外的一个系统路径中 - 在 Linux 和 Windows 上，你会被要求重新登录，因为凭据存储在配置目录下
- 在 macOS 上，凭据存储在密钥链中，会延续到这个干净的会话中
如果问题在这里消失了，说明原因存在于你真正的 ~/.claude 或项目 .claude 文件中的某处。逐一重新引入它们（通过把文件复制进临时目录，或从你的项目启动），找出是哪一个。如果问题在这个干净会话中仍然存在，说明原因在你用户和项目配置之外。运行 /status 检查统一管理设置是否生效，查找影响 Claude Code 的环境变量，然后参阅故障排查。
检查常见原因
大多数配置方面的意外情况，都能追溯到一小部分位置和语法规则。在假定是 bug 之前，先检查以下这些：
| 症状 | 原因 | 修复方法 |
|---|---|---|
| 钩子从不触发 | matcher 是一个 JSON 数组而不是字符串 | 用一个带 | 的单一字符串匹配多个工具，例如 "Edit|Write"。参阅匹配器模式。 |
| 钩子从不触发 | matcher 在 v2.1.191 之前的版本上使用 , 作为分隔符 | Claude Code v2.1.191 或更高版本会把 , 当作与 | 一样的列表分隔符。更早的版本会把逗号当作字面字符处理，因此 "Edit,Write" 什么都不匹配。请改用 |，或升级 Claude Code。 |
| 钩子从不触发 | matcher 值是小写的，例如 "bash" | 匹配区分大小写。工具名称是首字母大写的：Bash、Edit、Write、Read。 |
| 钩子从不触发 | 钩子定义在一个独立文件中，而不是 settings.json 中 | 项目或用户配置没有独立的钩子文件。请在 settings.json 中的 "hooks" 键下定义钩子。只有插件会加载一个独立的 hooks/hooks.json。参阅钩子配置。 |
| 全局设置的权限、钩子或 env 被忽略 | 配置被添加到了 ~/.claude.json 中 | ~/.claude.json 保存的是应用状态和界面开关。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 用 Read 工具读取该目录中的某个文件时加载，而不是在启动时，也不是在那里写入或创建文件时。参阅CLAUDE.md 文件如何加载。 |
子智能体忽略 CLAUDE.md 中的指令 | 内置的 Explore 和 Plan 智能体会跳过 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 钩子，或用沙箱获得硬性保证。 |
相关资源
关于每个配置层面的完整参考，请参阅专门的页面：