调试配置问题
一句话
诊断为什么 CLAUDE.md、设置、hooks、MCP 服务器或技能未生效。
什么时候翻这页
- Claude 忽略了你配置的指令
- 某个配置的功能未按预期出现
- 需要确认配置文件是否正确加载
- 怀疑配置被其他文件覆盖
核心概念
- 配置加载问题：通常是因为文件未加载、从意外位置加载，或被其他文件覆盖
- 上下文窗口（context window）：Claude Code 会话中占用的所有内容，包括系统提示、内存文件、技能、MCP 工具和对话消息
- 设置优先级：managed > local > project > user，命令行标志和环境变量提供额外覆盖层
- MCP 服务器：需要项目级批准，相对路径可能导致启动失败
- Hooks：必须在 settings.json 的 "hooks" 键下定义，matcher 字段必须是字符串而非数组
怎么做
-
检查加载内容：使用
/context命令查看当前会话加载的所有内容 -
深入检查特定类别：
/memory- 查看加载的 CLAUDE.md 和规则文件/skills- 查看可用技能/agents- 查看配置的子代理/hooks- 查看活动的 hook 配置/mcp- 查看连接的 MCP 服务器状态/permissions- 查看当前生效的允许和拒绝规则/doctor- 查看配置诊断信息/status- 查看活跃的设置源
-
检查解析设置：运行
/status查看哪些设置源处于活动状态 -
检查 MCP 服务器：运行
/mcp查看每个配置的服务器及其状态 -
检查 Hooks：运行
/hooks列出当前会话注册的所有 hook -
测试干净配置：使用
CLAUDE_CONFIG_DIR指向空目录，排除所有常规配置
命令 / 配置速查
| 命令 | 功能 |
|---|---|
/context | 显示当前会话上下文窗口中的所有内容 |
/memory | 显示加载的 CLAUDE.md 和规则文件 |
/skills | 显示项目、用户和插件来源的可用技能 |
/agents | 显示配置的子代理及其设置 |
/hooks | 显示活动的 hook 配置 |
/mcp | 显示连接的 MCP 服务器及其状态 |
/permissions | 显示当前生效的允许和拒绝规则 |
/doctor | 显示配置诊断：无效键、模式错误、安装健康状态 |
/debug [issue] | 为会话启用调试日志 |
/status | 显示活跃的设置源 |
初学者易错点
- Hook 的 matcher 字段必须是字符串（如
"Edit|Write"），不能是 JSON 数组 - 工具名称区分大小写，如 "bash" 应为 "Bash"
- Hooks 必须在 settings.json 的 "hooks" 键下定义，不能在独立文件中
- 项目级 MCP 服务器需要一次性批准，如果提示被忽略，服务器将保持禁用状态
- 子目录中的 CLAUDE.md 文件在会话开始时不会加载，而是在 Claude 使用 Read 工具读取该目录中的文件时按需加载
相关词条
claude-directory- .claude 目录结构和配置文件位置settings- 设置优先级和完整键列表hooks- hook 事件名称、负载和调试输出格式mcp- MCP 服务器配置和批准流程permissions- 权限规则和配置方法troubleshoot-install- 安装和登录问题排查