Claude Code 安全模式：找出出错的配置

同一台电脑上，别的项目都好好的，只有这个仓库，Claude Code 一调用工具就出错。你新开了一个会话，问题消失了一会儿，过了几轮又冒出来。项目里有 CLAUDE.md、几个 Skill、两个 Hook、一个插件，还连着三个 MCP 服务器，谁都有嫌疑。

这时最容易做的事是挨个关掉、挨个删掉，或者干脆换一个干净的配置目录重来。问题消失了，可你说不出是哪一项引起的，下次还会再遇到。更麻烦的是，重开会话后暂时正常，很容易被当成已经修好。

可靠的做法是一次对照实验：

• 先用 claude --safe-mode 启动，看问题在停用全部定制内容后还在不在；
• 问题消失，就回到普通模式，一次只恢复一类定制，跑同一个最短复现；
• 哪一类恢复后问题重现，再在这一类里继续缩小；
• 找到原因并修正后，沿最初失败的路径重走一遍，确认原来的检查也恢复了。

全程保留原配置，每次只改变一个条件，实验结论才站得住。

01 安全模式能排除什么

如果问题只在某个项目发生，而且无法判断是 CLAUDE.md、Skill、插件、Hook 还是 MCP 导致，可以启动：

claude --safe-mode

Claude Code 的 CLI 参考文档列出了它停用的范围：CLAUDE.md、Skill、插件、Hook、MCP 服务器、自定义命令和代理、输出风格、workflow、自定义主题和快捷键、状态栏、LSP 服务器以及自动记忆都不加载；认证、模型选择、内置工具和权限照常工作。

排查配置的官方文档补充了一点：安全模式仍会应用组织托管的 Hook 和设置策略，托管的插件、Skill、CLAUDE.md 和 MCP 服务器则会关闭。所以问题在安全模式下依旧存在，还要考虑托管策略、权限或认证这几层。

02 一次只恢复一类

问题在安全模式下消失后，范围已经缩小，具体是哪项还没定。官方文档的原话是：问题在安全模式下消失，说明原因在被关闭的那些项里，再用对应项目的检查方法去找。

回普通模式，一次只恢复一类，再跑最短复现：

1. CLAUDE.md
2. Skills
3. Hooks
4. 插件
5. MCP

哪类恢复后重现，就再缩小到一组 Hook 等具体内容。每次比较时，只改变一个关键条件。最短复现怎样写、症状怎样归层，见Claude Code 出问题时的分层排查方法。

03 对照时保留原配置

对照全过程保留原配置。临时配置目录或干净工作目录可能同时改变认证、发现路径和环境，不能当作只改了一个变量。记录每次变化及保留的条件，再解释实验能缩小到哪个范围。

官方文档也把“完全不带自己配置”的测试放在安全模式之后：问题在安全模式下依然存在，或者你怀疑设置文件本身有问题时，才在一个空目录里，用全新的 CLAUDE_CONFIG_DIR 加 --setting-sources user 启动一次，看问题会不会跟过来。这一步一次改变了配置目录、项目设置和工作目录好几个条件，结论只能说明“问题和你自己的配置有没有关系”，说明不了具体是哪一项。

04 重开会话暂时正常，问题可能还在

会话恢复工具各管一件事：

这些工具能帮你整理会话。如果配置错误仍然存在，就回到配置去修。开头那次“新开会话好了一会儿”，可能只是旧会话里的长上下文被清掉了，触发问题的那个 Hook 或 MCP 服务器还在，等对应事件再次发生，问题就回来了。重开以后暂时正常，还不能说明根因已经解决。

05 沿原失败路径验证修复

修复后，重复最初记录的最短复现步骤。一次只保留必要修改，并确认：

1. 原来的错误不再出现。
2. 预期行为确实发生，没有被静默跳过。
3. 日志中没有取代原错误的新故障。
4. 修复在新会话或重新启动后仍然有效。
5. 没有通过放宽权限、关闭检查等方式引入更大风险。

第 2 条和第 5 条最容易被忽略。关闭报错的 Hook 可能同时移除了检查：错误提示没了，原本要拦的写入也不拦了。只有原来的拦截或格式化恢复，并产生预期结果，才能确认这条路径已修复。如果最后查到的是一个同名 Skill 盖住了项目版本，修正和验收的方法见自定义 Skill 不显示或调到旧版的排查方法。

安全模式帮你把嫌疑范围缩小，一次恢复一类帮你找到具体那一项，沿原路径复测帮你确认真的修好了。原来该拦的拦住了、该格式化的格式化了，这条路径就真正恢复了。