Claude Code 配置不生效怎么排查

这篇适合谁，读完能做到什么

适合已经配置过 Claude Code，却发现某条指令被忽略、钩子从不触发、MCP 服务器或技能不见了的人。读完这篇，你能在会话里查看实际加载了什么，找到覆盖你设置的那一层，用安全模式或干净配置隔离问题，并认出最常见的几条报错。

先看实际加载了什么

大多数「配置没生效」的情况，来自三种原因之一：文件没有加载，从另一个位置加载了，或者被另一个文件覆盖了^[1]。

先运行 /context。它列出上下文窗口里的全部内容，分为系统提示、系统工具、MCP 工具、自定义子代理、记忆文件、技能和对话消息。由此你能确认 CLAUDE.md、规则或技能描述到底有没有进入上下文^[1]。在全屏模式下，它会把逐项明细折叠起来，输入 /context all 即可展开^[1]。

想查看某一类内容，用对应的命令^[1]：

/memory：列出用户和项目两级的记忆文件位置，并可以直接在编辑器里打开。
/skills：列出来自项目、用户和插件的技能。
/hooks：列出当前生效的钩子配置。
/mcp：显示已连接的 MCP 服务器及其状态。
/permissions：显示当前生效的允许和拒绝规则。
/status：显示生效的设置来源，包括托管设置是否在起作用。
/doctor：检查安装状态和无效的设置文件，并给出修复建议，修改前会先询问。
/debug [问题]：为本次会话开启调试日志，并让 Claude 根据日志诊断问题。

子目录里的 CLAUDE.md 是按需加载的，不是会话开始时加载，所以不会出现在 /context 的明细里^[1]。

如果 /context 显示文件已经加载，Claude 仍然不遵守某条指令，问题多半出在指令本身的写法上。指令可以有多种理解、两个文件的要求互相冲突，或者文件太长导致单条规则被忽略的时候，遵守率都会下降^[1]。

CLAUDE.md 和权限解决的是不同问题。CLAUDE.md 告诉 Claude 项目是怎么运作的；权限和钩子则不管 Claude 怎么判断，都会强制执行限制。「我们这里一向这样做」写进 CLAUDE.md，「绝对不能发生」的事情交给权限或钩子^[1]。

找到覆盖你设置的那一层

设置会在托管、用户、项目和本地四个层级之间合并。托管设置先生效。其余层级中，离得近的覆盖离得远的，顺序是本地、项目、用户。命令行参数和环境变量构成另一层覆盖^[1]。设置看起来不起作用时，通常是另一层或某个环境变量写了不同的值^[1]。

在终端运行 claude doctor，可以不启动会话，直接打印只读的安装和设置诊断。在会话里运行 /status，可以看到哪些设置来源处于生效状态^[1]。

下面几个容易混淆的地方要留意^[1]：

~/.claude.json 保存的是应用状态和界面开关。permissions、hooks 和 env 应该写在 ~/.claude/settings.json 里，两者是不同的文件。
settings.local.json 覆盖 settings.json，而两者都会覆盖 ~/.claude/settings.json。

MCP 服务器不出现

运行 /mcp，可以看到所有已配置的服务器、连接状态，以及它们在当前项目里是否已被批准^[1]。服务器配置正确，也可能因为下面三种常见原因而没有任何工具^[1]：

写在 .mcp.json 里的项目级服务器需要批准一次。如果当时把提示关掉了，就在 /mcp 里批准它。
启动失败的服务器会显示为失败。command 或 args 里的相对路径是常见原因，因为它们是相对于你启动 Claude Code 的目录解析的，而不是相对于 .mcp.json 所在的位置。本地脚本请用绝对路径。
连上了但工具列表为零的服务器，需要重连。在 /mcp 里选择 Reconnect。如果数量仍是零，运行 claude --debug=mcp，并在 ~/.claude/debug/<会话 ID>.txt 的调试日志里查看服务器的标准错误输出^[1]。

项目级的 MCP 配置放在仓库根目录的 .mcp.json 里，服务器写在 mcpServers 键下，不要放进 .claude/ 目录。settings.json 根本不读取 mcpServers 键^[1]。

钩子从不触发

运行 /hooks，可以列出当前会话注册的全部钩子，并按事件分组。如果你写的钩子不在列表里，检查下面几点^[1]：

钩子要写在设置文件的 "hooks" 键下。单独的钩子文件不会被加载。
matcher 写成了 JSON 数组而不是字符串，Claude Code 会把这一条当作无效设置拒绝。如果这个数组位于 PreToolUse 或 PermissionRequest 下，同一文件里的其他钩子也都不会加载。
写在技能 frontmatter 里的钩子，要等技能在本次会话中被调用过，才会出现。

钩子出现在 /hooks 里却不触发，最常见的原因是 matcher^[1]：

同时匹配多个工具时，用一个字符串加 |，例如 "Edit|Write"。从 v2.1.191 起，逗号也可以。更早的版本把逗号当作普通字符，所以 "Edit,Write" 什么都匹配不到^[1]。
匹配区分大小写，工具名首字母大写：Bash、Edit、Write、Read。写成小写的 "bash" 永远不会匹配^[1]。
工具名拼错，matcher 就匹配不到任何东西，钩子会静默失败^[1]。

修改 settings.json 后，改动会在短暂延迟后应用到正在运行的会话，不需要重启。如果保存几秒后 /hooks 仍显示旧定义，再运行一次 /hooks^[1]。要查看每个事件和每个钩子的退出码，可以用 claude --debug 启动会话，然后触发一次工具调用^[1]。

用安全模式隔离问题

先试 claude --safe-mode。它启动的会话会关闭 CLAUDE.md、技能、插件、钩子、MCP 服务器、自定义命令和代理、输出样式以及快捷键设置；认证、模型选择、内置工具和权限则照常工作。组织下发的托管钩子和设置策略仍然生效^[1]。如果安全模式下问题消失了，原因就在被关掉的那些项目里，用上面对应的命令逐项检查即可^[1]。

要彻底排除你自己的设置，就用一个空目录加一个全新的配置目录：

mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty

CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user

--setting-sources user 会关闭 .claude/settings.json、CLAUDE.md 和 .mcp.json 等项目配置。首次启动会重新出现首次设置的界面，这说明干净的配置目录已经生效^[1]。如果问题消失了，就把你的文件一个一个复制回干净目录，找出让问题重现的那一个。如果问题依然存在，原因就在你的用户和项目配置之外^[1]。

常见报错

以下报错来自运行时错误参考，在命令行版本、桌面应用和云端会话中都适用^[2]。

**Not logged in · Please run /login**：没有可用的凭证。运行 /login。如果你想用环境变量认证，要确认 ANTHROPIC_API_KEY 已经设置并导出到启动 claude 的那个 shell 里^[2]。
**Invalid API key · Fix external API key**：ANTHROPIC_API_KEY 或 apiKeyHelper 给出的密钥被 API 拒绝。旧密钥可能来自 direnv 或 dotenv 插件加载的 .env 文件。在同一个 shell 里运行 env | grep ANTHROPIC 检查，或者取消该变量并运行 /login^[2]。
**Your apiKeyHelper script is failing**：辅助脚本报错退出、超时、没有输出，或者输出里夹杂了密钥以外的文字。Claude Code 会重试脚本最多两次，之后才显示这条消息。在 shell 里手动运行这个命令复现问题，并查看 /status 中最近一次失败的详情^[2]。运行 /login 没有用，因为只要这项设置存在，辅助脚本的输出就优先于已保存的登录^[2]。正常的辅助脚本只向标准输出打印密钥，一个可打印 ASCII 字符组成的令牌，最长 16,384 个字符，并以退出码 0 结束^[2]。
**API Error: 400 ... context_management: Extra inputs are not permitted**：网关很可能丢掉了启用测试字段的 anthropic-beta 请求头。升级 Claude Code、让网关转发这个请求头，或者在启动前设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 作为备用办法^[2]。
**Model 'claude-opus-9' not found**：Claude Code 无法确认这个模型存在。不带参数运行 /model，从账号可用的模型中选择；或者使用 sonnet 这类别名^[2]。
**tools.N.custom.input_schema: JSON schema is invalid**：某个 MCP 工具声明的 schema 不合法，API 会拒绝整个请求。数字是该工具在列表中的位置，不是工具名。删除或停用声明它的 MCP 服务器，并检查各服务器的日志^[2]。