Claude Code --safe-mode 怎么用：一个开关关掉 5 道防线，10 秒上手（2026）
升级到 Claude Code v2.1.169，第一感觉是老反射 /clear 不灵了。CLAUDE.md 过时、某个插件遮住了内置命令、MCP server 不响应、hook 在背后悄悄改 diff——这些场景下 /clear 只清会话，问题还在 config 里坐着。--safe-mode 就是为这种情况准备的 kill switch。
这篇讲清楚 --safe-mode 到底关掉了哪 5 层、什么场景用它而不是 /clear、Mac/Windows/WSL 怎么 10 秒内开起来，以及一套不用解释就能甩给同事的 3 步排错流程。
开了 safe mode 能做什么，做不了什么
先把边界划清楚再动手。
| 目标 | —safe-mode | /clear | 重装 |
|---|---|---|---|
| 关掉一份坏掉的 CLAUDE.md | ✅ | ❌ | ❌ |
| 关掉一个行为异常的插件 | ✅ | ❌ | 部分 |
| 关掉在背后改 tool 输出的 hook | ✅ | ❌ | ❌ |
| 关掉卡死的 MCP server | ✅ | ❌ | 部分 |
| 让模型看不见自带 Skills | ✅ | ❌ | ❌ |
| 清掉跑飞的会话上下文 | ❌ | ✅ | ❌ |
| 重置 API 凭证 | ❌ | ❌ | ❌ |
| 切换调用的模型 | ❌ | ❌ | ❌ |
| 清 slash 命令历史 | ❌ | ❌ | ❌ |
| 10 秒内搞定 | ✅ | ✅ | ❌ |
一句话规则：/clear 跑一两轮还没修好的问题，先 --safe-mode，再考虑卸东西。
什么时候用，什么时候别用
该用 safe mode
- 从 v2.1.16x 升到 2.1.169 之后 Claude Code 行为变了——升级是唯一变量，先把自定义全关掉确认下。
- 同事说”我这没事你这有 bug”——把你的 CLAUDE.md 和插件按住，看 bug 还在不在。
- 最近 24 小时装的插件或 MCP server 开始挡命令、抛错或者返回奇怪的 tool 输出——别急着卸，先隔离。
- Hook 在背后悄悄改 tool call，你不知道是哪一个——一把全关，一秒定位。
- 接手别人配好的开发机，想先看一眼”原版” CLI 是什么样，再决定要不要继承别人的 config。
别用 safe mode
- 只是想清上下文——用
/clear，别重启。 - 只是想换个模型——
ANTHROPIC_MODEL或用模型选择器，跟 safe mode 没关系。 - 怀疑 key/上游地址有问题——safe mode 不动
ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL，先查这俩。 - 想只关 5 个插件中的某一个——直接改 settings 或者卸掉那个插件，safe mode 是”全关或全开”，没有半开档位。
- 任务做到一半，会话上下文有价值——safe mode 会开一个全新空会话，半成品上下文会丢。
停止规则
如果开了 safe mode bug 还在，那问题不在你的自定义里。别再花时间删插件了，去查模型、网络、账号、上游 API。
—safe-mode 关掉的 5 道防线（v2.1.169 原话）
官方 v2.1.169 release notes 一句话讲完：start Claude Code with all customizations (CLAUDE.md, plugins, skills, hooks, MCP servers) disabled for troubleshooting。这 5 层每层对应一类常见故障模式。
| # | 防线 | 关掉了什么 | 最常见兜的坑 |
|---|---|---|---|
| 1 | CLAUDE.md | 项目根 + 父目录链 + ~/.claude/CLAUDE.md 全局 | 过期指令覆盖用户 prompt；团队规则相互打架 |
| 2 | 插件 | 插件目录里的所有条目，包括 marketplace 装的 | 插件遮住内置命令；插件冷启动崩溃 |
| 3 | Skills | ~/.claude/skills/ 下你自己加的。要把自带 Skills 也藏掉，再加 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1 | Skill 被错意图触发；Skill 发出错误的 tool call |
| 4 | Hooks | 你注册过的所有 hook 事件——约 30 种类型（完整列表见 hooks 官方文档）包括 PreToolUse、PostToolUse、UserPromptSubmit、Stop、Notification、SessionStart、SessionEnd、PreCompact、SubagentStart/Stop 等 | Hook 默默改 diff 或拦 tool call |
| 5 | MCP servers | 所有 MCP server，不管来自 settings、--mcp-config、IDE 配置还是企业策略 | MCP server 冷启动卡死；tool 名冲突；auth 死循环 |
它不关的东西：API key、配好的 base URL（所以 ofox 接入照旧）、ANTHROPIC_MODEL 里的模型名、会话历史文件、slash 命令快捷键、当前项目目录的信任弹窗。
第 1 道：CLAUDE.md——隐形的 system prompt 扩展
每次会话启动会从最多 3 个地方加载 CLAUDE.md：项目根目录、所有走到 / 的父目录、~/.claude/CLAUDE.md 全局。里面写的内容会在每次 user prompt 前注入。开了 safe mode，模型表现得像这些文件不存在。“同一个 prompt 今天和昨天行为不一样”——第一个该怀疑的就是 CLAUDE.md，多半是你或同事新加了一条规则把行为带偏了。
第 2 道：插件——第三方扩展面
插件住在 ~/.claude/plugins/（或你配的插件目录），能注册 slash 命令、拦 tool call、暴露 MCP server，甚至改写 prompt。Safe mode 直接跳过插件加载器，意味着冷启动崩溃的插件、遮住 /clear 这种内置命令的插件、在 Windows 上占文件锁的插件全部不出现。升级后行为异常的故障原因里，插件排第二，仅次于 CLAUDE.md。
第 3 道：Skills——用户加的自动关，自带的可选
~/.claude/skills/ 下你自己加的 skills 会被 safe mode 自动关掉。自带 skills、workflows、内置 slash 命令不会被 safe mode 单独关，需要再加 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1 环境变量或 disableBundledSkills: true 设置（也是 v2.1.169 新加的）。日常排错只开 safe mode 就行；怀疑内置 skill 抢了你自己的逻辑时，再叠 bundled-skills 标志。
第 4 道：Hooks——在背后改 tool call 的隐形手
Hook 在几十种事件上触发——PreToolUse、PostToolUse、UserPromptSubmit、Stop、Notification、SessionStart、SessionEnd、PreCompact、SubagentStart/Stop 等，覆盖 tool 调用、会话生命周期、异步事件。一个 hook 能改写模型的 tool 输入、阻止 tool 执行、吃掉输出，或者只是多打几行话。这层最难手动排查，因为 hook 的影响是沉默的、带外的。Safe mode 一把关掉所有 hook，是确认”是不是 hook 在吃我的 diff”最快的办法。
第 5 道：MCP servers——最长尾的面
MCP server 来源很多：settings 文件、--mcp-config 标志、IDE 配置，以及 v2.1.169 引入的企业级 allowedMcpServers/deniedMcpServers 策略。它们会冷启动卡死、tool 名撞车、陷入 auth 死循环，或者就是响应慢得没法用。一个标志关掉全部，让你能问”零 MCP 这个会话能跑通吗？“——这个问题平时很贵，因为大多数人配了 3-10 个 MCP server。
准备清单
- Claude Code ≥ v2.1.169（2026-06-08 发）。
claude --version查一下。如果显示 2.1.168 或更低，先升级：npm 装的跑npm install -g @anthropic-ai/claude-code，原生安装的跑官方 installer。 - 能设环境变量的终端：zsh、bash、fish、PowerShell、CMD、WSL 都行。
- API 凭证已配好：
ANTHROPIC_API_KEY（或同名的 ofox key）必须在。safe mode 关的是自定义，不是认证。 - （可选）能写 shell rc：如果要在整个排错会话里都用 safe mode，会设
CLAUDE_CODE_SAFE_MODE=1到~/.zshrc、~/.bashrc或 PowerShell$PROFILE。
7 步：开 safe mode + 排错收尾
第 1 步：确认版本是 v2.1.169 或更高
claude --version
# 期望：2.1.169（或更高）如果是旧版，按你的安装方式升级，然后重开终端确保 PATH 拿到的是新二进制。
第 2 步：一次性启动
macOS / Linux / WSL：
claude --safe-modeWindows PowerShell：
claude --safe-modeWindows CMD：
claude --safe-mode标志在所有系统上都一样，区别只在 shell 包装。打开的会话会跳过所有 CLAUDE.md、插件、Skills、Hooks 和 MCP server。
第 3 步：（备选）用环境变量持续整个排错会话
想让一个 shell 里的所有 claude 调用都走 safe mode——跨多个 pane 或 repo 排错时很有用：
macOS / Linux / WSL（bash、zsh）：
export CLAUDE_CODE_SAFE_MODE=1
claudeWindows PowerShell：
$env:CLAUDE_CODE_SAFE_MODE = 1
claudeWindows CMD：
set CLAUDE_CODE_SAFE_MODE=1
claude启动前先确认环境变量生效：
echo $CLAUDE_CODE_SAFE_MODE
# 期望：1第 4 步：确认 safe mode 真的开了
进会话后，发一个会触发 CLAUDE.md 里项目规则的 prompt。规则没生效，说明 safe mode 在跑。也可以列出加载的 MCP server，列表应该是空的。
第 5 步：干净退出 safe mode
一次性启动的，/quit 关掉，下次直接 claude 就行。
环境变量启动的，relaunch 前先 unset：
# macOS / Linux / WSL
unset CLAUDE_CODE_SAFE_MODE
# PowerShell
Remove-Item Env:CLAUDE_CODE_SAFE_MODE
# CMD
set CLAUDE_CODE_SAFE_MODE=然后检查 rc 文件（~/.zshrc、~/.bashrc、$PROFILE）有没有残留的 export，否则下次开 shell 又会重新启用。这是”已经关了 safe mode，几天后 Claude Code 还是不读 CLAUDE.md”最常见的原因。
第 6 步：3 步排错套路
Safe mode 确认 bug 在自定义里之后，用二分搜索缩小范围，别一口气全卸：
- 正常 relaunch，保留 CLAUDE.md 和插件，在 settings 里手动关掉 hooks 和 MCP。还能复现？如果能，凶手在 CLAUDE.md 或某个插件——通常是大体量、近期改动那层。
- 重新开启 hooks，MCP 还关着。还能复现？如果能，凶手是某个 hook。一个一个关 hook；v2.1.169 hook 按加载顺序求值，先关最近加的那个。
- MCP server 一个一个开。重新出现 bug 的那个就是嫌疑。每切一个 MCP 都重启会话——MCP server 在会话启动时缓存 tool 列表，不重启直接切会有假阴性。
大多数情况第 1 步或第 2 步就定位完了，第 3 步只在你跑很多 MCP server 时才用得到——大团队里这种情况越来越多。
第 7 步：给 bug tracker 留一份干净复现
定位到肇事层之后，再跑一次 safe mode，只把那一个坏掉的文件放回去。这样 bug 被精确隔离到一个自定义，能给出极紧的复现。复现内容两行就够：“加了 ~/.claude/plugins/foo/index.ts，safe mode 下行为是 A，把这个插件开回去行为变成 B。” Claude Code 维护者对这种格式响应最快。
配 safe mode 时的高频报错（按现象找）
| 现象 | 根因 | 修法 |
|---|---|---|
Unknown flag: --safe-mode | Claude Code 还是 v2.1.168 或更低 | 升到 v2.1.169+，重开终端让 PATH 拿到新二进制 |
| Safe mode “好像没生效”——CLAUDE.md 还在加载 | PATH 上有两个 claude 二进制，老的赢了 | Mac/Linux 跑 which claude，Windows 跑 where claude，删掉或改名老的那份 |
加了 flag 但 CLAUDE.md 还是加载 | 把 --safe-mode 跟 /clear 搞混了，你是在已经加载的会话里跑 /clear | 整个会话关掉（Ctrl-D 或 /quit），再带 flag 启动 |
| MCP server 还出现在 slash 命令列表里 | Windows 上 MCPB 插件缓存陈旧（v2.1.169 修过的已知坑） | 关掉会话，删 MCPB 插件缓存目录，带 --safe-mode 重启 |
claude -p 在 Windows 上加完 safe mode 后一直 hang | 不是 safe mode 的问题，是 v2.1.169 已修的 skill-scan 卡死 | 确认在 >=2.1.169；如果是，带 --verbose 输出去开 issue |
设了 CLAUDE_CODE_SAFE_MODE 但 = 两边带空格 | Bash 把 CLAUDE_CODE_SAFE_MODE =1 当命令而不是赋值 | 严格写成 export CLAUDE_CODE_SAFE_MODE=1，不留空格 |
| Safe mode 关掉了你的强制 pre-commit 签名 hook，commit 现在没签名 | 设计如此；safe mode 是为诊断不是为日常工作 | 要 push 的 commit 之前先退 safe mode；safe mode 留给只读排错 |
企业 allowedMcpServers 列表看起来”还在生效” | Safe mode 关的是 MCP server，不是策略 schema 解析器；策略文本还在 settings 里 | 把策略文件当成 safe mode 下的休眠状态——会解析但不会有 MCP server 跑起来 |
团队/多人协作配置
Safe mode 是团队收到 bug 报告时最干净的复现原语，写进 runbook。
共享排错别名
在团队 dotfiles repo 里塞一行，确保每个工程师入口一致：
# ~/.zshrc 或 ~/.bashrc，提交到团队 dotfiles repo
alias claude-triage='CLAUDE_CODE_SAFE_MODE=1 claude'同事报 bug，on-call 第一句话就是”跑 claude-triage，把复现贴出来”。一条命令，零上下文，零版本漂移。
排错决策矩阵
| Bug 表现 | 报告人跑 | 配置问题表现 | 上游问题表现 |
|---|---|---|---|
| Tool 输出像被改过 | claude-triage 后复现 | Bug 消失 → 凶手是 hook | Bug 还在 → 模型/API 问题 |
| Slash 命令被遮住 | claude-triage 后 /help | 内置命令回来了 → 是插件在遮 | 命令还是没有 → CLI bug |
| CLAUDE.md 规则被忽略 | claude-triage 后问只有那条规则才答对的问题 | 行为没变 → 你的 CLAUDE.md 本来就读不到（路径问题） | 只在 safe mode 下行为变 → CLAUDE.md 在加载但被覆盖 |
| MCP tool 报错 | claude-triage 后再试 | 没 MCP 也能跑通 → server 坏了 | 同样的错 → 不是 MCP 的事 |
CI/脚本里别带 safe mode
--safe-mode 是诊断标志，不是部署目标。别把它加到 CI 的 claude -p 或 claude agents 调用里——你会悄悄丢掉团队的 CLAUDE.md、hooks 和所有 MCP 集成。怀疑 CI 撞到自定义 bug 时，本地跑 safe mode 确认，然后修那个肇事自定义。CI YAML 里多一行 --safe-mode 就是一次等着发生的事故，把这标志留在能让人看见的地方。
新人入职
入职第一天给新工程师一个 5 分钟练习：跑 claude-triage，问跟正常模式下完全一样的问题，看差异。他走的时候就知道团队的自定义到底干了什么，而不是把 CLAUDE.md 当成”自动会发生的魔法”。
进阶：safe mode + disableBundledSkills + /cd 组合
v2.1.169 一共放出 3 个相关控制项，组合用很顺手。
--safe-mode + CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1
--safe-mode 关的是 ~/.claude/skills/ 下用户加的 skills。要让自带 skills、workflows 和内置 slash 命令也对模型不可见，就加 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1（或 settings 里 disableBundledSkills: true）。两个一起，模型看到的就是一个什么都没加的裸 CLI——想对比”原版模型行为” vs “你定制后的行为”时很有用。
CLAUDE_CODE_SAFE_MODE=1 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1 claudesafe mode + /cd
v2.1.169 还加了 /cd，能在不打断 prompt 缓存的前提下切会话的工作目录。跨多个 repo 排错时把两个组合起来：带 --safe-mode 启动一次，然后 /cd 在 repo 之间跳。冷启动成本只付一次，排错全程都在同一个模型上下文窗口里。
safe mode + ofox 上游
如果你通过 ofox 这类多 provider 网关接 Claude Code——也就是 ANTHROPIC_BASE_URL=https://api.ofox.ai/anthropic——safe mode 不动这条路由，本地自定义全部按住的同时上游照常工作。这种分离正是它的价值：能在不动上游凭证的前提下把”本地 config”这个变量摘干净。Safe mode 是唯一能让你 10 秒内得到”问题是我还是我装的所有东西”诚实答案的 CLI 标志。
排错完想深入用法，可以看 Claude Code 接 ofox 配置指南、Claude Code Hooks/Skills/Worktrees 防误删实战、Claude Code Token 优化 5 招——这三篇讨论的话题都建立在 safe mode 关掉的那 5 层自定义之上。
延伸阅读
- 想横向比一下 CLI，看 Claude Code vs Codex CLI vs Cursor vs DeepSeek TUI 对比，里面讲了各家的同类排错开关。
- 接 ofox 路径的全套配置见 Claude Code 接 ofox 配置指南。
- 想知道 hooks 怎么用来兜底破坏性命令、为什么
--dangerously-skip-permissions不推荐，看 Claude Code Hooks/Skills/Worktrees 防误删。
本文核实过的来源
- Anthropic Claude Code v2.1.169 release notes — github.com/anthropics/claude-code/releases/tag/v2.1.169（2026-06-11 核对）
- Claude Code 官方 changelog — code.claude.com/docs/en/changelog（2026-06-11 核对）
- ofox.ai Anthropic 兼容端点参考 — ofox.ai/docs（2026-06-11 核对）
- DevelopersIO v2.1.169 深度解读 — dev.classmethod.jp/en/articles/20260609-cc-updates-v2-1-169/（2026-06-11 核对）
