Claude Code Fallback Models 完整教學 — 主模型過載時自動換一台繼續跑

先別急著問這功能能幹嘛。先看一個瞬間。

你掛了一個 background agent 在跑重構，自己跑去倒咖啡。就在你離開的那 30 秒，Anthropic 的 Opus 流量尖峰來了，你的請求撞上一個 529 overloaded 錯誤——伺服器在說「我現在忙不過來，等等」。過去，這一撞，你那個背景任務就直接死了，回來只看到一行紅字躺在那。

fallbackModel 這個 v2.1.166 加進來的設定，要處理的就是這 30 秒裡發生的事。但要真的搞懂它，最好的方式不是先聽它的功能清單，而是把那一瞬間慢動作拆開來看：當 529 回來的時候，Claude Code 心裡到底在跑什麼判斷。

把過載的那一刻拆成慢動作

想像你打電話叫披薩，最常去那家店線路忙線。你有兩種人。一種會掛掉、坐在那生氣、等十分鐘再重撥同一個號碼。另一種手邊貼了一張紙條，上面照順序寫了三家店的電話——第一家忙線，立刻撥第二家。

沒設 fallback 的 Claude Code 是第一種人。請求撞上 529，它就停在那，要嘛報錯收場，要嘛傻等。設了 fallbackModel 之後，它變成第二種人：主模型回傳過載，它不問你、不停下來，當場拿起那張紙條，把同一個請求原封不動丟給清單上的下一個模型。

關鍵在「同一個請求」這四個字。它不是重新開始一輪對話，不是把你的 context 洗掉重來，而是把當下這一筆要送出去的東西，換一台模型送。對你來說，理想情況下你根本不會察覺——背景那台 worker 只是悄悄從 Opus 降到了 Sonnet，活還在幹。

那張紙條最多可以寫三個號碼。也就是說，fallback 鏈最多三層：主模型過載 → 第一備援也過載 → 第二備援。實務上很少撐到第三層，因為設計這條鏈的訣竅，就是挑一些「不太可能同時塞車」的模型——你不會三家披薩店都選同一條街上的。

它到底會在哪些情況翻紙條

拆到這裡會冒出一個很自然的問題：是不是「只要主模型出任何錯」它都會去翻紙條？

不是。這裡有個刻意的設計分界，值得記住。

會觸發 fallback 的，核心是「過載或暫時不可用」這一類——伺服器忙、模型暫時連不上。後來還擴充了兩種：一是當 API 丟回一個「沒預料到、而且重試也沒用」的錯誤時，它會在 fallback 模型上把這一輪重跑一次；二是當你指定的主模型「根本找不到」（model not found）時，它會直接切到備援模型，而且這個 session 剩下的時間都用備援跑。

但有一類錯誤它故意不翻紙條：認證錯誤（auth）、用量限制（rate-limit）、請求太大（request-size）、傳輸層錯誤——這些它會讓你當場看到，不會往下 cascade。

這個設計很值得想一下「為什麼」。假設你的 API key 填錯了，這是 auth 錯誤。如果這時候它還傻傻地往下翻紙條，會發生什麼事？同一把錯的 key，第一家拒絕、第二家拒絕、第三家還是拒絕——你不是把問題解決了，你只是把「失敗一次」變成「失敗三次」，然後 debug 的時候還得從三層噪音裡撈出真正的原因。所以它的判準很乾脆：能靠換一台解掉的（塞車），才翻紙條；換誰都解不掉的（key 錯了、額度爆了），直接攤開給你看。

拆完了，現在才講怎麼設

懂了上面的機制，設定就只是一行的事。它有兩種寫法。

臨時用，直接掛在啟動指令上：

1	claude --model claude-opus-4-8 --fallback-model claude-sonnet-4-6

這行的意思是：主力用 Opus 4.8，撞牆就退到 Sonnet 4.6。值得一提的是，--fallback-model 這個 flag 以前只在 print（非互動）模式有效，v2.1.166 之後互動式 session 也吃這個設定了。

想長期生效，寫進設定檔。全域的放 ~/.claude/settings.json，專案層級的放專案根目錄的 .claude/settings.json，加一個 fallbackModel 欄位，填一條照優先序排好的清單（最多三個）。一條合理的鏈，是從最強的模型往下排到比較快、比較輕、比較不會塞車的——Opus 退到 Sonnet，再退到 Haiku，差不多就是這個味道。

還有一個容易被忽略但很實用的點：/bg 跟 detach 現在會把 --fallback-model 一起保留下來。這正好回到開頭那個倒咖啡的場景——背景的 worker 撞到過載時，會默默降到備援模型繼續跑，而不是趁你不在的時候無聲無息地死掉。

這個機制能推廣到哪裡

把這套「過載就換一台、但認證錯就攤開」的邏輯抽出來看，它其實不只是 Claude Code 的一個小設定，而是任何一個會依賴外部服務的系統都該有的姿態：分清楚「重試能救的暫時性失敗」和「重試只會放大噪音的根本性失敗」，對前者準備好退路，對後者乾脆地報錯。你寫自己的服務在呼叫第三方 API 時，這條分界線同樣成立。

如果你想把這條學習線往下接：下一步可以去看 OTEL 那個 fallback_triggered 指標，把它接進你的監控——它會告訴你「到底多常撞到過載」。當這個數字開始變高，那不只是「該設 fallback」的訊號，更是「你的主力模型選擇或用量規劃該重新算一次」的訊號。退路是底線，但一直在用退路，代表正門早就該修了。