主题
调试你的配置
用 /context、/doctor、/hooks、/mcp 等命令排查为何配置没生效。
是什么
当 Claude 忽略某条指令，或你配置的功能没有出现时，原因通常是文件没加载、从你预期之外的位置加载了，或被另一个文件覆盖了。本指南教你检查 Claude Code 实际加载了什么，从而缩小到底属于哪种情况。
这一页专注于 CLAUDE.md、settings、hooks、MCP servers、skills 等配置层面的诊断；安装、认证、连通性问题应改看 Troubleshoot installation and login。
怎么工作
- 先运行 /context：它按类别（system prompt、memory 文件、skills、MCP tools、对话消息）显示当前会话占用上下文窗口的全部内容，用来确认 CLAUDE.md、rules、skill 描述是否真的存在。
- 按类别深入：/memory 看哪些 CLAUDE.md 和 rules 加载了；/skills 看可用 skills；/agents 看子代理；/hooks 看激活的 hook；/mcp 看 MCP server 状态；/permissions 看当前生效的 allow/deny 规则。
- 用 /doctor 校验配置文件，暴露无效键或 schema 错误；报告问题时按 f 把诊断发给 Claude 一起排查。用 /status 查看哪些 settings 来源生效（含 managed settings 是否启用）。
- 检查 MCP：/mcp 列出每个 server 的连接状态与是否已在本项目获批；连上但 0 个 tool 时选 Reconnect，仍为 0 则运行 claude --debug mcp 看 stderr。
- 检查 hooks：/hooks 按事件列出已注册的 hook；hook 出现但不触发时多半是 matcher 问题，可用 claude --debug hooks 启动会话并触发工具调用，实时观察 hook 评估、匹配过程、退出码和输出。
- 对照纯净配置：把 CLAUDE_CONFIG_DIR 指向空目录以绕过 ~/.claude，并从没有 .claude/.mcp.json/CLAUDE.md 的目录启动；若问题消失，逐个把文件加回以定位根因。
- 记住 settings 的合并优先级：managed 始终最高，其余按 local > project > user 由近及远覆盖，命令行 flag 和环境变量再叠加一层覆盖。
怎么配置 / 用法
bash
# 对照纯净配置：绕过 ~/.claude 与项目配置
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
# MCP 连上却返回 0 个 tool 时，查看 server 的 stderr 输出
claude --debug mcp
# hook 出现在 /hooks 却不触发时，实时观察 hook 评估
claude --debug hooks会话内诊断命令：/context /memory /skills /agents /hooks /mcp /permissions /doctor /debug [issue] /status
什么时候用
- Claude 忽略了某条你写在 CLAUDE.md 里的指令，想确认它是否真的加载了。
- 配置的 hook、MCP server、skill 没有出现或不生效，要定位是没加载、加载位置错了还是被覆盖。
- 怀疑某个 settings 值被其他 scope 或环境变量覆盖。
- 配置处于未知状态、定向检查无法定位时，需要用纯净配置对照法逐步排查。
限制 / 坑
- 本页只覆盖配置诊断；安装、认证、command not found、PATH 等问题应看 Troubleshoot installation and login。
- 纯净会话仍会应用组织部署的 managed settings（位于 ~/.claude 之外的系统路径）。
- 纯净会话在 Linux/Windows 上需重新登录（凭据存于配置目录）；macOS 凭据在 Keychain，可沿用。
- /memory 确认文件已加载但指令仍不被遵守时，问题在指令写法而非加载本身，本页不替你重写指令。
硬事实速查（12 条）
- /context 应最先运行，确认 CLAUDE.md/rules/skill 描述是否在上下文中。
- 子目录的 CLAUDE.md 是按需加载：仅当 Claude 用 Read 工具读取该目录下文件时才加载，会话启动时不加载。
- settings 优先级：managed 最高，其余 local > project > user，命令行 flag 与环境变量再叠加覆盖。
- .mcp.json 里的 project 级 server 需一次性审批；审批提示被关掉后 server 保持禁用，需从 /mcp 审批。
- command 或 args 用相对路径是 MCP server 启动失败的常见原因，应改用绝对路径；PATH 上的 npx/uvx 可直接用。
- hook 必须定义在 settings.json 的 hooks 键下，没有独立的 hooks 文件；只有 plugin 才用单独的 hooks/hooks.json。
- matcher 是单个字符串，用 | 匹配多个工具名（如 Edit|Write）；写成数组是 schema 错误，hook 条目会被丢弃。
- matcher 匹配区分大小写，工具名首字母大写：Bash、Edit、Write、Read；写成 bash 会静默失败。
- ~/.claude.json 存的是应用状态和 UI 开关；permissions、hooks、env 应放在 ~/.claude/settings.json，两者是不同文件。
- settings.local.json 覆盖 settings.json，两者都覆盖 ~/.claude/settings.json。
- skill 必须放成文件夹加 SKILL.md（如 .claude/skills/name/SKILL.md）；frontmatter 含 disable-model-invocation: true 时 Claude 不会自动调用。
- settings.json 不读取 mcpServers 键；project server 放仓库根的 .mcp.json，user 级用 claude mcp add --scope user。