Claude Code 復原：Safe Mode、/cd 與備援模型

代理程式實作指南：Ailoot 文件。

2026 年 6 月，Claude Code 有哪些變化？#

以前，Claude Code 開始出現異常時——例如轉圈一直停不下來、啟動時當機、代理程式忽略 CLAUDE.md 中的規則，或 hook 悄悄沒有執行——只有一種解法：手動註解 .claude/settings.json 的部分內容、逐一停用 MCP 伺服器，或在最糟的情況下刪除 ~/.claude 並重新安裝。在所述的一個案例中，~/.claude 被刪除，連同花了一個半小時建立的 MCP 伺服器設定也一起遺失。後來才發現，問題出在 CLAUDE.md 的一行內容，原本 10 秒就能找出來——但直到整個環境復原後才弄清楚。

2026 年 6 月，Anthropic 推出三種機制，改變了這種情況。以下簡要列出新增功能及時間：

以下將逐步說明每種機制，以及 Claude Code 工作階段出問題時的使用順序。

Claude Code 最常因為什麼出問題？#

在所述範例中，CLAUDE.md 起初只有 80 行，而且一個月都運作正常。到了第二個月，開始注意到 Claude 每週會有一次違反所有既定規則的情況：碰 .env、執行 git push --force、翻找 node_modules。這不是出於惡意——只是忘了。有一次 .gitignore 被刪除，當下也無法立刻看出原因。這類情況在CLAUDE.md 指南中有更詳細的說明。

CLAUDE.md 增長到 400 行以上時，就會開始悄悄造成問題：它在工作階段啟動時占用不少上下文視窗，重要指示也會被次要指示稀釋。Claude 形式上仍會讀取檔案，因此從外面看起來像是「規則都寫了，卻沒有作用」——這是規範內容過度膨脹的典型徵兆。

第二個常見來源是 hook。Claude Code hooks 有個 Anthropic 未特別強調的細節。

也就是說，Python hook 中的 sys.exit(1)（或任何符合 Unix 慣例、表示「發生錯誤」的結束代碼）不會停止 Claude。只有代碼 2 會阻擋操作。在所述案例中，hook 被當成「強制禁止」機制，但實際上它只記錄了警告，仍然放行操作。

第三個來源是 MCP 伺服器，它們也會以自己的方式出問題。

症狀通常都一樣：MCP 指令可以使用，卻回傳 failed，沒有追蹤堆疊。若要了解 MCP 設定以及如何使用 claude mcp add 新增伺服器，請參閱另一份指南。

第四個來源是三層式 settings.json 階層。你有 ~/.claude/settings.json（使用者層級）、專案根目錄中的 .claude/settings.json（專案層級）、.claude/settings.local.json（本機層級），也可能有企業管理員提供的受管理設定。這些設定會依優先順序規則合併。如果有人在專案層級加入 MCP 伺服器，而使用者層級已有啟動設定不同的類似項目，就會產生不易察覺的衝突，看起來像是「Claude Code 壞了」。

--safe-mode 如何運作？它會停用哪些項目？#

v2.1.169 changelog 中 Anthropic 的原文如下：

Anthropic 在模型設定文件中進一步說明：

這是診斷工具，不是「乾淨環境」。Safe mode 協助回答一個問題：問題出在 Claude Code 的預設行為，還是新增的自訂內容？這也是上下文工程的一部分——管理 Claude 在特定時刻能看到及看不到的內容。如果 safe mode 中一切正常，就可以透過二分搜尋檢查各層。如果仍然無法運作，問題就在安裝本身、授權、網路或基礎架構，此時適合查看 claude doctor 與記錄。

safe mode 會停用的項目（Anthropic 官方清單中的 5 個主要層級）：

• 所有層級的 CLAUDE.md（使用者／專案）
• 外掛
• Skills
• Hooks
• MCP 伺服器

仍可正常使用的項目：

• 授權（你的 OAuth 工作階段或 API 金鑰）
• 模型選擇（--model sonnet、--model opus）
• 內建工具（Read、Write、Bash、Grep 等）
• 權限
• Git 狀態
• 目錄名稱

有一個重要細節：safe mode 不會停用企業管理員設定的受管理設定或政策。如果你在團隊中工作，而 Bedrock GovCloud 或 MDM 設定提供了 availableModels，這些限制仍會生效——safe mode 只停用你的自訂內容，不會停用企業政策。

如何在 60 秒內隔離問題層並找出原因？#

以下是 Claude Code「不再聽話」時的診斷流程。下列所有指令至少需要 Claude Code v2.1.169。若版本較舊，請先更新（npm update -g @anthropic-ai/claude-code 或使用 Anthropic 原生安裝程式）。

1. 開啟問題發生時使用的同一個資料夾。
2. 執行 claude --safe-mode。
3. 如果順利啟動，請測試原本的要求。能正常運作嗎？那麼原因就在某一層。前往步驟 4。
4. 如果 safe mode 中仍有問題，不要動設定。先執行 claude doctor，檢查授權、版本和安裝衝突。

safe mode 順利啟動後，從最可能的原因開始，逐一啟用各層。根據所述經驗，順序如下：

1. CLAUDE.md。 不使用 safe mode 執行 claude，並暫時重新命名檔案：mv CLAUDE.md CLAUDE.md.bak。如果可以運作，原因就在該檔案。接著可進行二分搜尋：保留一半行數並檢查。
2. Hooks。 開啟 .claude/settings.json，暫時在 hooks 區段設定 []。重新啟動 claude。能運作嗎？那麼原因就在某個 hook。逐一啟用它們。
3. MCP 伺服器。 同樣地，在 ~/.claude.json 或 .claude/settings.json 中，暫時將 mcpServers 區段設為空物件，重新啟動並檢查。
4. Skills。 將 .claude/skills/ 移到暫存資料夾。啟動並檢查。

「暫時重新命名」的意思是診斷期間不刪除檔案。使用 mv 或 git stash，就能在確認該層並非原因時，透過一個指令復原所有內容。

如何使用 /cd 切換工作資料夾而不遺失上下文？#

6 月 8 日的 v2.1.169 changelog 寫道：

說明一下，為什麼這項功能有助於排除問題。假設你在專案資料夾 ~/work/myapp 中，而 Claude Code 的行為很奇怪。以前，要確認「它到底能不能運作？」唯一的方法就是關閉工作階段、移到其他資料夾，再重新啟動。上下文、歷史記錄和已暖機的提示快取都會遺失。現在可以這樣做：

# 在同一個工作階段中：
/cd ~/sandbox/test

Claude 會切換到新資料夾，並將其中的 CLAUDE.md（如果有）當成訊息讀取，而不是取代系統提示——也就是說，快取會保留。如果 ~/sandbox/test 中一切正常，就能確認問題出在 ~/work/myapp 的設定。

6 月 12 日，v2.1.176 修正了一個惱人的回歸問題——/cd 後直到完整重新啟動前，畫面都會顯示舊的 git 分支。如果你使用較舊的版本，可以更新，或在切換後的前幾則訊息中先忽略 git status——它稍後就會更新。

如何設定備援模型來處理 529 錯誤？#

在所述情境中，某個專案每週會用 Opus 執行一項長時間任務；10 分鐘後，API 回傳 529 Overloaded，工作階段便當掉。以前只能等待，或手動使用 --model sonnet 切換到 Sonnet，並失去所有已暖機的上下文。在採用 second-brain 架構的大型 business/ 資料夾中，這大約要花 20 分鐘。現在有了合適的機制。

官方文件中的原文如下：

另外，文件也說明了鏈結的運作方式：

有兩種設定方式。透過 CLI：

claude --fallback-model sonnet,haiku

透過 ~/.claude/settings.json：

{
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

速率限制另有一個細節。Anthropic 刻意不讓 429 錯誤進入備援鏈結，避免使用者切換到下一個模型來繞過要求上限。只有主模型過載、無法使用，或傳回不可重試的伺服器錯誤（例如 529 Overloaded）時，備援才會生效。速率限制則使用一般重試邏輯與退避機制。

還有一個細節：6 月 12 日，v2.1.174 修正了一項回歸問題，讓壓縮作業開始遵循 --fallback-model。如果長時間工作階段在服務過載時進行壓縮，在這項修正之前就不會呼叫備援模型。如果你會使用長時間工作階段（例如整夜執行 /compact、/loop），請更新到至少 v2.1.174。

如果原因是 CLAUDE.md、hook、MCP 或 skill，該如何修正？#

以下說明各層的具體策略。

如果原因是 CLAUDE.md

開啟檔案並檢查大小。根據所述經驗，作用中的 CLAUDE.md 請控制在 200 行以內；其餘內容移至專案旁的路由檔與支援文件中（完整 second-brain 結構請見 second brain 指南）。如果超過 400 行，幾乎可以確定是原因之一。處理步驟：

1. 建立備份：cp CLAUDE.md CLAUDE.md.full。
2. 改回精簡且可運作的範本。現成範本可在「如何設定 CLAUDE.md」指南中找到。
3. 重新啟動 Claude Code。檢查是否正常。
4. 如果正常，分批以 10–20 行的區塊恢復規則，每次恢復一個區塊後都進行檢查。
5. 找出導致行為異常的區塊。將它改寫成結束代碼正確的 hook（本 H2 下一小節會說明 hooks 的結束代碼）。

如果原因是 hook

首先要確認結束代碼是否正確。Claude Code hooks 的規則如下：

• 結束代碼 0 — 正常；操作會繼續。
• 結束代碼 1 — 發生錯誤，但不會阻擋。Claude 會像什麼事都沒發生一樣繼續執行。
• 結束代碼 2 — 會阻擋的錯誤。只有這個代碼會真正停止操作。

如果你在 shell hook 中寫了 sys.exit(1) 或 exit 1，以為這樣就能阻擋操作，那麼在 Claude Code 中，這個代碼只會像警告記錄一樣，不會停止操作。請改成 2。如需了解 hooks 的細節，以及如何避免這個陷阱，請參閱另一份指南。

第二個常見情況是 hook 在標準輸出上回傳無效 JSON。Claude Code 會將 hook 回應解析為 JSON；如果其中包含雜訊（記錄、進度標記、emoji），就會視為 hook 失敗，然後繼續執行操作。規則是：標準輸出只能放 JSON；其他內容一律送到標準錯誤輸出。

第三種情況是 hook 嘗試讀取 safe mode 隱藏的 ~/.claude/ 內容。這是正常可能發生的狀況；不要靠修補 hook 來處理，而是在開頭檢查 os.environ.get('CLAUDE_CODE_SAFE_MODE')，並以 0 結束。

如果原因是 MCP 伺服器

症狀：MCP 指令可以使用，卻在沒有明確追蹤堆疊的情況下回傳 failed。處理步驟：

1. 執行 claude mcp list——有哪些伺服器已定義？
2. 在 ~/.claude.json 中逐一停用伺服器：將索引鍵 claude-server-A 重新命名為 _claude-server-A（不刪除也能停用）。
3. 重新啟動 claude，檢查哪些呼叫可以正常運作。
4. 找到問題伺服器後，查看其記錄：claude mcp logs <name>。
5. 如果是第三方伺服器（例如 @modelcontextprotocol/server-postgres），請檢查是否有近期版本。MCP 生態系仍然動盪，Claude Code 更新經常會讓伺服器出問題。

如果你遇到「只有設定兩個 MCP 時才會在啟動時當機」，請在 safe mode 中停用 MCP，並比較行為。

如果原因是 skill

Skill 是 SKILL.md 加上 .claude/skills/<name>/ 中的程式碼。症狀包括 Claude 忽略 skill、在不適當時機套用 skill，或雖然套用了卻產生無用結果。處理步驟：

1. 開啟 SKILL.md。檢查描述——應該用 1–2 句明確說明何時使用。如果只寫「適用於所有事情的萬用輔助工具」，Claude 就無法判斷何時該呼叫它。
2. 檢查是否與 CLAUDE.md 矛盾。如果 CLAUDE.md 說「一律撰寫測試」，但 skill 描述說「用於不寫測試的快速原型」，兩者就有衝突。
3. 如果 skill 使用外部指令（npm、python、git），請確認它們位於全系統 PATH 中。Skill 所在的環境很精簡。

Safe mode 也失敗時：先診斷並保存狀態再修復#

移除使用者狀態不是診斷捷徑。以下檢查若仍無結論，保留證據並繼續調查。任何安裝修復都應先有已驗證備份，保留原帳戶與憑證庫身分。順序如下：

1. claude doctor — 自動診斷。Anthropic 在文件中寫道：

2. 檢查是否有互相衝突的安裝。 許多人會同時安裝 npm 全域版本和原生安裝程式版本：

3. 檢查 ANTHROPIC_API_KEY 是否攔截了你的 OAuth 工作階段。 這是「什麼都不能用，金鑰過期了」的常見原因：

解法：在目前的 shell 工作階段執行 unset ANTHROPIC_API_KEY，或從 ~/.zshrc／~/.bashrc 移除它。

4. 只修復診斷指出的安裝，先保存全部使用者狀態。 Safe mode 失敗或 doctor 無結論，不代表要刪資料。先停止所有 Claude 工作階段與其他寫入者，製作一致備份；保留相同 Unix 帳戶、HOME、作業系統憑證儲存與 Anthropic 帳戶，不更換金鑰或建立新身分。

下方備份範例僅適用 Linux GNU tar。macOS 或 Windows 應用保留該平台 ACL、延伸屬性、連結與中繼資料的備份工具，並先驗證還原，不能假設 GNU 專用旗標通用。封存含憑證與對話，必須私密保存於儲存庫外。

# Run as the same user who owns the Claude state, after stopping writers.
set -eu
umask 077
backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX")
set --
if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then
  set -- "$@" .claude
fi
if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then
  set -- "$@" .claude.json
fi
[ "$#" -gt 0 ] || exit 1
tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME"
sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256"
(cd "$backup_dir" && sha256sum -c claude-state.sha256)
mkdir "$backup_dir/restore-check"
tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
printf 'Verified recovery directory: %s\n' "$backup_dir"

全部指令都必須成功。封存包含整個既有 .claude（含忽略／未追蹤工作階段及外掛狀態）與 .claude.json，不只 Git 設定。若路徑是符號連結，或資料另有設定位置，先停止並將解析後目標納入同一份已驗證備份；只封存連結不會保存目標。封存不含 macOS Keychain 或其他外部憑證庫，應原樣保留這些身分。

只有診斷明確指出舊本機安裝衝突時，才將該安裝移到私有復原目錄，不刪設定或工作階段：

# Use the verified backup_dir from the previous block.
if [ -d "$HOME/.claude/local" ]; then
  mv "$HOME/.claude/local" "$backup_dir/legacy-local"
fi

npm 安裝也只有在診斷為衝突、且確定保留原生版時才移除。接著用官方原生安裝器，不刪 .claude 或 .claude.json：

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

Windows 原生安裝指令如下：

irm https://claude.ai/install.ps1 | iex

還原另行處理。 再次停止寫入者，確認封存雜湊，依前述方法解壓到空白復原目錄並成功比對。若需還原移開的舊安裝，先確認 $HOME/.claude/local 不存在，再將 $backup_dir/legacy-local 移回確切路徑。只從驗證解壓還原診斷涉及的設定檔，先保存目前替代檔，不要盲目覆蓋整個樹。工作階段、MCP 與原始身分仍保留；只有 Git 快照不包含忽略／未追蹤對話、憑證或檔案系統中繼資料。

Claude Code 出問題時，哪些事不該做？#

診斷前不要更換金鑰

「授權無法運作」的問題有 90% 是 ANTHROPIC_API_KEY 攔截了訂閱、hook 的 UI 錯誤，或 MCP 失敗。輪替金鑰不會修好這些問題，反而會造成另一個小時的停機：你得撤銷舊金鑰、發出新金鑰、用它重新簽署 CI，並更新正式環境中的變數。先執行 claude --safe-mode。可以運作嗎？那麼問題就在自訂內容，完全不必動金鑰。

safe mode 之前不要完整重設

safe mode 只要 1 秒就能提供隔離環境。刪除 .claude 可能摧毀工作階段、MCP 設定及其他未追蹤狀態。先診斷、驗證私有備份，再只對確定相關的安裝或設定層採可逆移動。

不要因 hook 的 UI 錯誤而慌張

在修正任何內容前，先透過寫入 stderr 的記錄或明確的 print，確認 hook 是否真的有執行，不要只依賴畫面上的指示。

修正邏輯前不要提高 hook 的結束代碼

阻擋型 hook 沒有阻止操作時，很容易就把它改成 exit 2，然後以為問題解決了。這個修補確實有效，但會掩蓋另一個問題：如果它一個月都沒有發揮作用，那麼 hook 原本應禁止的操作全都已經通過。先檢查 git 記錄，找出究竟有哪些內容漏了過去，再加上阻擋機制。否則現在才關上門，也無法抹去之前發生的事。

沒有 safe mode 作為保障時，不要編輯正式環境的 CLAUDE.md

在所述案例中，你編輯了 CLAUDE.md，Claude 開始行為異常，執行 git diff 後才發現當晚也有人把 MCP 伺服器和 hook 加進了儲存庫。你以為是自己的修改造成問題，還原之後 Claude 仍然行為異常。規則是：執行 git revert 之前，先執行 claude --safe-mode。如果 safe mode 中問題仍然存在，就與你的修改無關，不必還原。

不要相信「Claude 會自己修好 MCP」

常見的情況是：你請 Claude「替 MCP 伺服器加入某個工具」，Claude 重寫了原本正常運作的設定，導致一切出問題，接著花好幾個回合除錯自己造成的損害，過程中還耗盡工作階段配額。MCP 壞掉時，請手動取得設定，不要交給代理程式處理。它的工具組合中也有部分功能依賴 MCP，而 MCP 壞了，診斷者本身也就壞了。

修復後接下來該做什麼？#

分析完事件後，不要立刻回去工作。先新增預防措施，避免事件再次發生。second brain（具有專案結構的 business/ 資料夾）和 CLAUDE.md 可能花上好幾小時建立，手動復原也很困難——這就是充分的理由。最低限度的設定如下：

1. 在 ~/.claude/settings.json 中設定 permissions.disableBypassPermissionsMode: "disable"——從架構上禁止 bypass 模式，讓意外執行的 --dangerously-skip-permissions 無法生效。
2. 為 Read(./env*)、Bash(git push --force)、Write(./node_modules/**) 設定 hooks——這些操作必須以規則明確攔截，而不能只靠期望。
3. 為長時間自主執行（/loop、/schedule）設定 sandbox。
4. 在 /compact 中設定自己的規則，決定要從上下文中捨棄什麼，避免 Claude 把自己耗盡。

完整的四層防護方案請見「如何設定 Claude Code，避免它在夜間破壞你的專案」指南。一份指南說明執行 /loop 前如何預防，另一份則說明 /loop 已經造成破壞後如何復原。兩者是一組合理的配套。

實作指南：Ailoot 文件。

更多資料與工具：Ailoot。