把 Claude Code 接到 9Router，不是複製一段設定就結束；客戶端、9Router Provider 與目標模型名稱必須一致。遇到 401、404 或「模型不可用」時，應先分層定位，而不是反覆更換 API key。
設定前先確認三件事
- 9Router 服務已啟動，且可開啟本機管理介面。
- 已在 9Router 新增 Provider，且其金鑰與連線正常。
- 記下 9Router 提供給 OpenAI-compatible 客戶端的 Base URL、API key，以及可用模型或 Combo 名稱。
Claude Code 只應請求 9Router 的 Base URL；要發往哪個 Provider、哪個模型，交給 9Router 的路由規則處理。安裝與背景可先看 9Router 使用教學。
建議的接入順序
先在 9Router 建立單一 Provider 的測試路由，再讓 Claude Code 指向此路由。確認可完成一次簡單對話後，再加入 fallback、多帳號或本機模型。
設定時重點核對：
- Base URL 是否為 9Router 的 OpenAI-compatible endpoint，而非上游廠商位址；
- API key 是否由目前的 9Router 執行個體簽發；
- Claude Code 填寫的模型名是否與 9Router 模型或 Combo 名完全一致；
- 修改環境變數或設定後，終端與 Claude Code 是否已重新啟動。
不要把上游 Provider 的 key 散落在多個專案設定。將其保留在 9Router，Claude Code 只保存本機路由器所需的最小憑據，遷移與撤銷更容易。
常見錯誤怎麼排查
401 或 Unauthorized
先確認請求確實到達本機 9Router，再檢查 API key。若管理面板可登入但客戶端仍為 401，通常是客戶端用了錯誤 key，或 Base URL 指向另一個執行個體。
404 或 endpoint not found
多半是 Base URL 多寫或少寫路徑。不要憑感覺拼接 /v1；以 9Router 目前頁面或文件顯示的 OpenAI-compatible 位址為準，並用最簡單的請求驗證。
model not found
先查看 9Router 模型清單。Provider 原始模型名、自訂別名和 Combo 名可能不同；Claude Code 應填寫路由器暴露的名稱。
請求可送出但總是 fallback
查看第一優先 Provider 的狀態、餘額或配額、模型權限與請求日誌。fallback 是保底機制，不應取代修復首選模型失敗原因。
保留最小測試設定
複雜路由上線前，保存一份「一個 Provider、一個模型、無 fallback」的測試設定。日後出問題時先回到此基線：基線正常表示故障在路由規則；基線也失敗則繼續檢查網路、憑據或 Provider。
若問題發生在 Claude Code 的安裝、權限或專案環境，可繼續看 Claude Code 多專案記憶與 Hooks。
總結
9Router 與 Claude Code 的接入重點是：Base URL 指向路由器、模型名符合路由器、上游邏輯留在路由器。依「連通性—驗證—模型名—路由規則」順序檢查，通常可避免多數設定問題。
一套容易排錯的設定模型
可將呼叫鏈畫成四層：Claude Code → 9Router endpoint → Provider → 實際模型。每層只回答一件事：客戶端是否交給路由器、路由器是否接受憑據、規則是否選中 Provider、Provider 是否可呼叫模型。日誌與測試也應依這四層分開保存。
例如，先在 Claude Code 使用固定模型名；接著在 9Router 讓該名稱只對應一個 Provider。穩定後，再將模型名改為 Combo 並加入第二個 Provider。不要讓 Claude Code 直接感知多個上游名稱，否則每個專案又會累積難以維護的設定。
用最小請求驗證，不直接跑長任務
每完成一層設定，就做一次低成本驗證：
- 用 9Router 健康檢查或管理介面確認服務在監聽。
- 用一個無工具呼叫的簡單請求確認 API key 與模型名。
- 在 Claude Code 中讓它解釋目前目錄的一小段文字，驗證客戶端收到回應。
- 最後才測試讀檔、執行測試、長上下文或平行 Agent。
長任務會混入網路、工具權限、上下文與重試等變數。將最小請求保存在排障筆記中，換電腦或升級後也能重用。
路由規則怎樣設計更穩
將「預設模型」與「高成本模型」分開。預設模型處理一般問答、格式整理與低風險修改；複雜推理、程式碼審查或長上下文時，再明確選用更強模型。這能避免不必要成本，也方便從日誌觀察哪些任務真正需要升級。
fallback 觸發條件也應保守：網路錯誤、明確配額錯誤或 Provider 不可用可以切換；模型回答不理想不應立刻自動重試多個 Provider。後者會放大 token 消耗，並使結果難以重現。
部署與憑據安全清單
- 不要將 9Router 暴露在沒有存取控制的公網位址。
DATA_DIR、備份與日誌可能含 Provider 資訊，應按敏感設定處理。- 不要把上游金鑰寫入儲存庫、截圖或 Claude Code 專案說明檔。
- 升級前備份設定；升級後先以最小請求測試，再恢復正式路由。
FAQ：每個專案都要設定 9Router 嗎？
通常不用。客戶端層級環境變數或管理工具可讓多個專案共用 endpoint；只有某個儲存庫確實需要專用模型、權限或帳務隔離時，專案級設定才有意義。
FAQ：本機模型為何常常 fallback？
先查看服務日誌中的顯存不足、上下文超限、併發排隊或模型名不符。將本機模型作為主路由前，應以真實任務長度連續驗證，而非只測一句短提示。