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