Claude Code 配置调试：五步定位配置不生效的原因

本文是对官方文档「Debug your configuration」的中文要点摘要，完整内容以原文为准：https://code.claude.com/docs/en/debug-your-config

排查思路

当 Claude 忽略某条指令，或某个功能未按预期生效时，根本原因通常只有三种：文件未加载、从非预期路径加载、或被其他配置覆盖。本指南按从浅到深的顺序提供排查路径。

第一步：用 /context 确认加载了什么

/context 展示当前会话上下文窗口的完整内容，包括系统提示、记忆文件、技能、MCP 工具等，是排查的起点。配套专项命令：

关键细节：子目录的 CLAUDE.md 不在会话启动时加载，而是在 Claude 用 Read 工具读取该目录文件时才按需加载。若 /memory 确认文件已加载但指令仍被忽略，问题通常在于指令写法（过于模糊、文件过长、存在冲突），而非加载机制本身。

CLAUDE.md 传达项目约定，让 Claude 做出好决策；permissions 和 hooks 是强制边界，无论 Claude 如何判断都会执行。两者解决不同问题，不要混用。

第二步：检查设置合并优先级

设置按 managed（托管）> local > project > user 的顺序合并，命令行参数和环境变量也构成额外覆盖层。某个设置未生效时，往往是被更高优先级的作用域悄悄覆盖了。

• /doctor 发现问题后按 f，可让 Claude 一起走查修复
• /status 查看哪些设置来源正在生效

第三步：排查 MCP 服务器

运行 /mcp 查看所有服务器状态，常见失败原因：

• 未审批：.mcp.json 中的项目级服务器需一次性手动审批，若审批提示被跳过则持续禁用，在 /mcp 中重新审批即可
• 相对路径：command/args 中的相对路径以启动 Claude Code 的目录为基准，而非 .mcp.json 所在位置，建议改用绝对路径
• 工具数为零：已连接但无工具时，先选 Reconnect；仍为零则用 claude --debug mcp 查看服务器 stderr 输出
• 环境变量未传递：settings.json 中的 env 不会传给 MCP 子进程，应在 .mcp.json 内为各服务器单独配置 env
• 配置位置错误：项目 MCP 配置放在仓库根目录的 .mcp.json，不是 .claude/ 目录内；settings.json 不读取 mcpServers 键

第四步：排查 Hooks

Hook 不触发的常见原因：

• matcher 写成了数组：应为单字符串，用 | 分隔多个工具名，如 「Edit|Write」
• 工具名大小写错误：匹配区分大小写，工具名首字母大写：Bash、Edit、Write、Read
• 放错文件：Hooks 必须写在 settings.json 的 hooks 键下，不存在独立的 hooks 配置文件（插件除外）

修改 settings.json 后无需重启，稍等即可生效。需要实时观察时，用 claude --debug hooks 启动会话，日志会记录每个事件、匹配结果和退出码。

第五步：干净环境对比测试

claude --safe-mode：禁用所有自定义项（CLAUDE.md、技能、插件、Hooks、MCP 服务器、自定义命令与子代理），认证、模型选择、内置工具和权限正常运行。注意例外：组织下发的托管设置仍会部分生效，因此策略配置的 Hooks 与状态栏即使在 safe-mode 下也会运行。若问题消失，说明原因在某项自定义配置中，再用第一步到第四步逐项缩小范围。

完全干净会话：将 CLAUDE_CONFIG_DIR 指向空目录，并从无 .claude、.mcp.json、CLAUDE.md 的目录启动：

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

此命令绕过 ~/.claude 下的所有用户配置和项目配置。若问题仍存在，原因在托管设置或环境变量中（托管设置位于 ~/.claude 之外的系统路径，因此仍会生效）。注意：Linux/Windows 会重新提示登录（凭据存于配置目录）；macOS 凭据在 Keychain，无需重新登录。

常见症状速查