更換 API key 或切換提供商，聽起來像改一個值。它失敗的原因更簡單：同一份憑證存在於四個地方，而每個工具讀取這些地方的優先順序，你未必想過。如果你來這裡是想知道如何在 Claude Code 裡更換 API key，或者如何在 cc-switch 裡為不同的編碼 agent 切換提供商，機制都能歸結為三個問題。這個值存在哪個層面？還有哪些地方仍指向舊值？你的會話歷史會怎樣？本指南針對 Claude Code、Codex CLI 和 CC Switch 回答這些問題，並且不重複首次配置的內容。
憑證可能存在的四個地方
動手改之前，先定位你真正要做的是哪一種變更。更換 key、切換提供商、切換賬號看起來相似，觸及的卻是不同層面。輪換一個在同一臺機器上被多個編碼 agent 共用的 API key 是最難的情況，因為它會牽動其中不止一個。
Shell 環境變數。寫在 shell profile 或終端裡的 export。它們只對其被設定的那個終端會話生效，這就是為什麼某次改動昨天看著生效、今天又不行了。
工具配置檔案。Claude Code 設定檔案裡的env塊；Codex 的config.toml。這些檔案會持久儲存，並且常常以取決於具體變數的方式壓過 shell 裡的值，因為優先順序是按變數對逐個判定的，而不是隻看來源層級。
憑證檔案。Codex 把憑證儲存在auth.json，位於它的主目錄內。切換提供商時經常會改config.toml，卻讓這個檔案仍指向舊賬號，這就是經典的“我換了，但它還顯示我原來的登入”報告。
切換器配置檔。像 CC Switch 這樣的管理器會儲存整套提供商配置，並把對應的那一套寫進各個工具。此時憑證住在管理器裡，問題就變成了哪個配置檔在生效。
到底該不該為廉價切換做架構，本身就是一個取捨，我們在聚合層與直連裡比較過。本文假設你今天就要動手改點什麼。
無論它在哪裡，都假設它可能洩漏；衛生清單把隔離步驟集中在一處。
Claude Code：如何更換 API key 與切換端點
Claude Code 的文件對閘道器模式規定得很精確，照做就好，別猜。端點放在ANTHROPIC_BASE_URL中；對 String AI 這樣的平臺，它就是站點根地址，末尾不帶/v1。憑證變數取決於閘道器簽發的是什麼，官方的接入指南講得很清楚：ANTHROPIC_AUTH_TOKEN用於 bearer token 形式的憑證，ANTHROPIC_API_KEY用於 API key，而apiKeyHelper用於從 vault 或 SSO 流程獲取輪換憑證的命令。放錯變數的憑證會隨一個閘道器不讀的 header 發出，請求以 401 失敗；遇到這種情況，換到正確的變數再重試。
變更過程中有兩個細節容易踩坑。第一，閘道器憑證優先於已儲存的 claude.ai 登入：用ANTHROPIC_AUTH_TOKEN時會立即生效，而用ANTHROPIC_API_KEY時，在互動模式下會先提示一次請求批准，之後才生效。第二，層面很重要。CLI 讀取 shell 變數和設定檔案，但 VS Code 擴充套件是在它自己的使用者設定裡配置的；而且按同一份文件，Slack 和雲端會話始終使用 Anthropic 的 API，不屬於閘道器部署的一部分：在雲端會話的環境配置裡設定的閘道器變數不會被應用。如果有人說他本地的改動在網頁端毫無作用，這就是文件給出的原因，不是 bug。
在哪裡設定這個值，決定了它能存活多久：shell export 只活一個終端會話，設定檔案則在 Claude Code 執行的每個地方持續生效。設定系統還會在會話進行中重新載入若干類改動，包括像apiKeyHelper這樣的憑證 helper，所以通過 helper 輪換無需重啟即可生效；而另一個終端窗口裡過期的 shell export 會悄悄把舊值留住。
Codex CLI：如何切換提供商與輪換憑證
實踐中，Codex CLI 的切換提供商要動兩個檔案，而不是一個。提供商定義放在config.toml裡，位於[model_providers.<name>]之下，欄位包括base_url、wire_api和requires_openai_auth；憑證則單獨儲存在auth.json中，形式為OPENAI_API_KEY。String AI 的平臺文件在欄位層面展示了它的形態，base URL 以/v1結尾；動手改之前，值得開啟官方配置參考看看當前的鍵列表：例如參考文件指出，wire_api只接受responses這一個受支援的值，而放在專案本地.codex/config.toml裡的提供商鍵會被忽略，以使用者級配置為準。最後這一點，解釋了一整類“我改了，但什麼都沒發生”的報告。
切換的規則是：在同一次操作裡同時改config.toml和auth.json。只改 base URL，舊賬號的憑證還留在原處；只改憑證，舊端點還留著。又因為 CLI 在啟動時讀取配置，已開啟的會話必須重啟才能拿到新值，這也正是平臺配置指南讓你寫完檔案之後要做的事。
CC Switch：一鍵切換提供商，並保留會話歷史
CC Switch 的存在，讓這件事從“改檔案”變成“做管理”。它是一款面向主流編碼 agent 的跨平臺桌面管理器，覆蓋 Claude Code、Codex、OpenCode、OpenClaw、Grok Build、Hermes Agent 等；倉庫明確說明了首次啟動時會發生什麼：它會把現有的 Claude Code、Codex、Gemini CLI 和 Grok Build 配置匯入為一個名為default的提供商，併為這些工具各加一個官方提供商，因此已配置的內容不會丟失。
在此之上，切換被設計成一個動作：提供商預設填好那些顯而易見的欄位，Projects 功能則儲存整套配置——提供商，以及（對 Claude Code 和 Codex 而言）MCP、skills 和 prompt 檔案——於是整份配置可以從主頁頂部的專案切換器一次性換過去。如果你要在裡面把 String AI 接成一個提供商，平臺的文件在欄位層面描述了 Universal Provider 表單：名稱、base URL、你的 API key 和一個預設模型，之後是一次 Health Check，在你依賴它之前先確認連線可用。細節都在官方的CC Switch 倉庫裡，關於當前行為，也應當以該工具自己的文件為準。
用一次最小請求驗證改動
任何改動之後，都別急著一頭扎進你最大的專案。先發一個小請求，這正是五步快速入門在首次呼叫時用的同一套紀律。確認三件事：
- 請求確實走了新端點。在 Claude Code 裡，用
/status的輸出就能看出當前生效的是閘道器憑證還是已儲存的登入；在平臺側，用量記錄裡應當出現這筆請求，並掛在你預期的賬號和 key 上。 - 會話仍然可用。開一個新會話，問點無關緊要的問題。如果舊會話行為異常，那就是該重啟工具的訊號，而不是繼續改配置。
- 沒有混用的憑證。在一臺有多個層面的機器上，檢查那些你沒碰過的地方：另一個終端的 export、一個設定檔案、一個切換器配置檔、一個編輯器擴充套件。混用的配置是“這個視窗行、那個視窗不行”最常見的原因。
動手之前，先給你即將改動的檔案和變數做個快速快照。兩分鐘的複製，決定了糟糕的改動會變成一次回滾，還是耗掉一個下午。
編碼 agent 的會話歷史遷移
編碼 agent 的會話歷史遷移，是沒人願意為它留時間的那一步，而誠實的起點是：會話儲存歸各個工具自己管。換提供商或換 key 是憑證層面的變更，它本身不會重寫會話存放的位置。按 CC Switch 的 README，它的 Session Manager 正是為這個缺口存在的：可以從一個地方瀏覽、搜尋並恢復每個工具的對話歷史；README 也把邊界說在前面，指出目前還不支援恢復 OpenClaw 和 Hermes 的會話，所以在圍繞它做規劃之前，先看當前的限制。就 Codex 而言，平臺的配置說明描述了一個面向舊版基於 OAuth 會話的可選遷移指令碼，其中還提到：這類會話在切換提供商後可能暫時顯示為丟失，而實際上並未被刪除；說明要求你先確認配置，執行前先預覽。
切換期間的安全做法是：在新憑證下的新會話表現正常之前，保持舊配置完好；在工具自己的文件給出別的說法之前，把舊會話當作只讀歷史。憑證方面沒有任何東西能保證歷史會被帶過去；那隻由工具的儲存層決定，而用一個會話做測試，比任何指南都更快給出答案。
排查：症狀、層面、修法
下表把常見故障對應到最可能負責的層面。
| 症狀 | 檢查 | 修法 |
| --- | --- | --- |
| 切換後仍是舊賬號 | 優先順序與殘留 | 檢查其他終端視窗、設定檔案、切換器配置檔、編輯器擴充套件；某個窗口裡過期的 export 會在那裡覆蓋你的新值 |
| 換 key 後返回 401 | 憑證變數型別 | bearer token 應放在ANTHROPIC_AUTH_TOKEN；API key 應放在ANTHROPIC_API_KEY；換過來再重試 |
| 每個請求都 404 | base URL 的路徑約定 | OpenAI 相容客戶端需要帶/v1路徑；Claude Code 的 base URL 用站點根地址，不帶這一段 |
| 找不到模型 | 模型標識 | 用平臺文件裡當前的模型列表，而不是憑記憶的名字 |
| 本地可用，Slack 或雲端會話不可用 | 文件寫明的限制 | 雲端介面使用 Anthropic 的 API，會忽略閘道器變數；圍繞它做規劃，而不是跟它較勁 |
| 用量與預期不符 | 配置檔未生效 | 用/status或管理器確認，然後到平臺的用量記錄裡核對請求本身 |
接下來讀什麼
- 完全從零開始配置。從一把 key 通用於多個編碼工具開始，那是首次配置的內容，本文有意不重複。
- 確認端點支援什麼。用相容性清單來核對你所依賴的層面。
- 把賬目對齊。 用量與成本歸因是你在切換之後確認請求和花費落在預期位置的方法。
一次只改一個層面，用一個小請求驗證，並在新配置真正答話之前保留舊配置。