CC-Switch 串接 AIXHUB

CC-Switch 會管理桌面用戶端設定，也提供選用本機 Proxy。本指南使用原生 Anthropic Messages 與 OpenAI Responses 建立 AIXHUB 直接連線設定檔，因此 Needs Local Routing 維持關閉，CC-Switch 不會位於請求路徑。只有目標應用程式載入預期設定，而且 AIXHUB 留下相符記錄時，才算切換成功。

完成目標

你會：

1. 安裝適用於目前平台的官方標準 farion1231/cc-switch 發行版本。
2. 切換前備份目標檔案，並記錄原本啟用的設定檔。
3. 分別為 Claude Code 與 Codex 建立 AIXHUB 設定檔，而且各自使用專用金鑰。
4. 檢查 settings.json、config.toml，以及所選 Codex 相容設定是否保留或變更 auth.json，不只相信作用中標記。
5. 完成一筆唯讀或不呼叫工具的請求，再到 AIXHUB 用量核對時間、模型與成功狀態。
6. 復原時只處理本次變更擁有的欄位，同時保留不相關供應端、官方登入資料與後來新增的設定。

CC-Switch 不同版本可能重新命名控制項或調整目標分頁。本指南不虛構固定選單名稱，也不把內部資料庫格式當成穩定結構；目標應用程式的實際檔案與行為才是可觀察契約。

支援平台

只使用官方標準專案在 Releases 頁面發布的套件：

• Windows： Windows 10 以上；官方提供 x64 與 ARM64 MSI／可攜式檔案。
• macOS： macOS 12 以上；使用已由 Apple 簽署與公證的官方 macOS 檔案。
• Linux： Ubuntu 22.04+、Debian 11+、Fedora 34+ 或其他相容主流發行版；官方提供 x86_64 與 ARM64 AppImage、DEB 及 RPM。

若官方 release 沒有相容檔案，不要改用同名專案或非官方下載。資產名稱與安裝提示可能隨版本變更。

本指南涵蓋兩種 CC-Switch 目標：

部分 CC-Switch 版本可能顯示其他目標，但看到目標不代表已證明可以直接串接 AIXHUB。尤其在 AIXHUB 與該目標沒有記載相容自訂端點時，不要把 AIXHUB 金鑰填入 Gemini 或官方帳號設定檔。

安裝或開啟應用程式

1. 開啟官方標準 CC-Switch Releases 頁面。上述平台檔案與要求已依目前官方 release 核對；請選擇最新相容檔案，不要複製舊的直接網址。
2. 選擇符合目前作業系統與架構的發行檔案，再依作業系統正常流程安裝或開啟。
3. 記錄下載頁面顯示的 release tag。若已安裝版本有「關於」或版本畫面，請核對是否一致；該畫面位置可能隨版本變更。
4. 在 CC-Switch 寫入共用檔案前，完整關閉 Claude Code、Codex 桌面版、Codex CLI 與編輯器整合。

不要匯入其他人提供且未經檢查的設定檔。即使 CC-Switch 視窗隱藏秘密值，設定檔或備份仍可能包含 API 金鑰、目標路徑與供應端設定。

設定值

建立兩個 App-specific Provider 設定檔，不使用同一個 Universal Provider。以下兩處 sk-your-key 分別代表不同的專用 AIXHUB 金鑰；不可讓兩個目標共用同一個真實值。

從模型路由複製完整模型 ID。Claude Code 使用不含 /v1 的根 Base URL；Codex 使用剛好一個 /v1。Claude 設定檔與 Codex 設定檔不能互換。

目前上游流程是先選擇目標應用程式、按右上角 +、選擇 App-specific Provider，再新增 Custom 供應端。不同版本仍可能調整名稱與進階欄位位置，因此要依語意對應，並檢查下方實際產生的檔案。若已安裝版本無法表達所有必要值，請取消切換，改用專用 Claude Code 或 Codex CLI 指南。

設定 AIXHUB

保護原始狀態

建立或啟用設定檔前：

1. 完整關閉兩個目標應用程式及使用它們的編輯器整合。
2. 將每個既有目標檔案複製到儲存庫外具有唯一時間戳的備份，不可覆寫舊備份。
3. 記錄每個檔案原本是否不存在，並記錄每個目標原先啟用的 CC-Switch 設定檔。
4. 依下表建立受保護的欄位層級紀錄。秘密精確值只留在受保護的檔案備份，不要寫進筆記或螢幕擷取畫面。

目前版本把 CC-Switch 資料放在 ~/.cc-switch/，以 cc-switch.db 作為供應端單一事實來源，並在 ~/.cc-switch/backups/ 保留輪替資料庫備份。Settings -> Advanced -> Data Management 也提供匯出／匯入，而匯入會覆寫資料庫。這些只能當成額外復原資料；明確複製的目標檔案仍是復原依據，所有資料庫備份與匯出內容都必須視為秘密。

建立 Claude Code 設定檔

選擇 Claude Code、按右上角 +、選擇 App-specific Provider -> Custom，再填入設定值表格的 Claude 欄。API 格式維持 Anthropic Messages，本機路由保持關閉。檢查 JSON 預覽後按 Add；完成上述備份與預覽檢查前不要按 Enable。

切換後，使用者層級 Claude 設定必須包含或保留下列完整 env 物件：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aixhub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key",
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_MODEL": "panel-model-id"
  }
}

真實檔案可能有不相關的最上層屬性；CC-Switch 必須合併上述欄位，不可刪除其他屬性。兩個憑證變數使用同一組 Claude 專用 AIXHUB 金鑰；Codex 設定檔必須使用另一組真實金鑰。

建立 Codex 設定檔

選擇 Codex、按右上角 +、選擇 App-specific Provider -> Custom，再填入設定值表格的 Codex 欄。AIXHUB 提供原生 Responses，因此 Needs Local Routing 保持關閉。檢查產生的設定後按 Add；選擇並核對下方憑證投影模式前不要按 Enable。目前 CC-Switch 自訂供應端範本使用 custom 作為 Provider ID；實際 config.toml 必須包含：

model_provider = "custom"
model = "panel-model-id"

[model_providers.custom]
name = "AIXHUB"
base_url = "https://api.aixhub.org/v1"
wire_api = "responses"
requires_openai_auth = true

兩個最上層鍵必須位於所有 TOML 表格之前。保留不相關供應端與設定，而且這個設定檔只能有一個作用中的 [model_providers.custom] 表格。

目前版本會把設定檔 API 金鑰存入 CC-Switch 資料庫。若已安裝版本啟用切換時保留 Codex 官方驗證相容設定，切換第三方供應端時會保留 auth.json 的 ChatGPT 登入快取，並把金鑰投影到作用中供應端表格：

[model_providers.custom]
name = "AIXHUB"
base_url = "https://api.aixhub.org/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "sk-your-key"

auth.json 原本含有官方登入時，建議使用此模式。確認欄位存在時不可顯示實際值。成功切換後不要手動再加入 Token；投影與回填由 CC-Switch 管理。

若明確關閉該相容設定，已安裝版本可能改為把供應端驗證寫入 auth.json：

{
  "OPENAI_API_KEY": "sk-your-key"
}

只能選擇一種可觀察模式，不可要求兩者同時存在。切換前記錄 auth.json 是否含官方登入資料；切換後確認它保持完全不變且供應端 Bearer Token 已出現，或明確選擇的替換模式寫入上述 API Key 結構。若兩種結果都與預覽不符，請立即復原。

啟用一個目標設定檔

選擇供應端卡片並按 Enable，或從系統匣的目標子選單選擇供應端。這是會改變狀態的操作：它會寫入所選目標的即時設定。接受前先核對目標應用程式與設定檔名稱。

作用中標記只代表 CC-Switch 的本機狀態。開啟目標用戶端前，先檢查實際目標檔案，但不要顯示金鑰；確認 Base URL、模型、協定與所選憑證投影模式。若檔案預覽與實際檔案不一致，請停止並復原，不要反覆切換。

首次使用

一次只測試一個目標，並使用小型可丟棄目錄。

Claude Code

1. 啟用 AIXHUB - Claude Code，確認 settings.json 含有預期根網址與模型。
2. 完整重新啟動 Claude Code。
3. 啟動 claude；若用戶端顯示模型，確認為 panel-model-id，再送出以下範圍明確的請求：

不要呼叫工具、執行命令或變更任何檔案。只回覆 OK。

不要核准檔案寫入、會改變狀態的命令，或測試目錄以外的存取。

Codex

1. 關閉 Claude Code，啟用 AIXHUB - Codex，確認 model_provider = "custom" 與預期供應端表格。不可顯示 Bearer Token 或 API 金鑰，並確認所選模式是否應保持 auth.json 不變。
2. 完整重新啟動預定使用的 Codex 介面。
3. 啟動 codex 或開啟 Codex 桌面版；若畫面顯示模型，確認為 panel-model-id，再送出相同唯讀請求。

目標應用程式執行期間切換設定檔，可能讓目前執行個體繼續使用舊供應端。判斷結果前一定要重新啟動。

驗證

成功的目標請求應包含以下輸出：

OK

核對三個層次：

1. CC-Switch 狀態： 預定目標與 AIXHUB 設定檔顯示為作用中。
2. 目標狀態： 實際目標檔案含有預期值，而且重新啟動的用戶端會在可顯示時呈現預定模型。
3. AIXHUB 記錄： 在 AIXHUB 用量核對請求時間、panel-model-id 與成功狀態。只有用量實際顯示協定時才核對。

只有畫面回應不能證明路由。Claude Code 與 Codex 使用不同金鑰、Base URL、協定及檔案，必須分別完成驗證。

疑難排解

控制項或目標名稱不同

記錄已安裝 release tag，並與官方標準 release notes 比較。CC-Switch 不同版本可能調整目標位置或控制項名稱。不要匯入猜測的內部 JSON 形狀，也不要沿用其他版本的選單路徑；請依目標與欄位語意操作，再檢查實際目標檔案。

CC-Switch 顯示作用中，但用戶端仍使用舊供應端

完整關閉並重新啟動目標。確認 CC-Switch 變更的是正確作業系統使用者與目標檔案。Claude Code 請移除或對齊過期的暫時 ANTHROPIC_* 環境變數；Codex 請檢查 CODEX_HOME、測試專案及受信任上層目錄是否有 .codex/config.toml 覆寫。

Claude Code 回傳 401 或仍使用官方路由

確認 ANTHROPIC_BASE_URL 是不含 /v1 的完整 https://api.aixhub.org，兩個憑證變數都含有 Claude 專用金鑰，而且 ANTHROPIC_MODEL 是完整模型 ID。修正設定檔後重新啟動 Claude Code。

Codex 開啟官方登入或回傳 401

確認 model_provider = "custom"、requires_openai_auth = true 與 AIXHUB Base URL。保留官方驗證模式要確認作用中供應端有非空白 experimental_bearer_token，但不可輸出值，而且 auth.json 保持不變；替換模式則確認專用 OPENAI_API_KEY 完全依預覽寫入。不要用官方 ChatGPT 登入取代 AIXHUB 憑證。Codex 桌面版與 CLI 共用即時設定，因此必須重新啟動所有 Codex 介面。

請求回傳 404 或 API 版本重複

檢查所選目標。Claude 使用 https://api.aixhub.org；Codex 使用 https://api.aixhub.org/v1。Claude 設定不可附加 /v1，Codex 供應端不可移除 /v1，兩者都不可把 /v1/responses 放進 Base URL 欄位。

找不到模型

從模型路由重新複製完整模型 ID。讓 Claude 的 ANTHROPIC_MODEL、Codex 最上層 model 與設定檔模型欄位保持一致。不要把 AIXHUB 供應端名稱加入模型 ID。

切換後遺失不相關設定

停止 CC-Switch 與目標用戶端，不要再次切換。將目前檔案與受保護備份比較，只能使用本次操作的精確資料復原，並保留備份後新增的不相關欄位。這是設定寫入失敗，不是 API 錯誤。

若收到 403、429、502 或 503，請繼續參考錯誤代碼。

升級與復原

升級 CC-Switch 前，重新備份目標檔案並記錄作用中設定檔。只從官方標準 Releases 頁面安裝更新；新版本完成第一次切換與驗證前，保留先前 release tag，並重新檢查產生的檔案。

復原步驟：

1. 完整關閉 CC-Switch、Claude Code、Codex 桌面版、Codex CLI 與相關編輯器整合。
2. 只有原設定檔已知，而且預覽符合受保護原始紀錄時，才重新啟用該設定檔；否則使用精確目標檔案備份逐欄位復原。
3. Claude Code 請還原完整原始 env 物件。只有 AIXHUB env 欄位原始狀態記為 absent，而且目前值仍屬於本次操作時，才能移除；保留不相關最上層及後來新增的屬性。
4. Codex 請還原原本的 model_provider、model、完整供應端表格與供應端 Bearer Token 歸屬。只有切換確實變更 auth.json 時才還原該檔案；若官方登入快取原本被保留，就維持不變。欄位來源不明時請停止，不要刪除。
5. 只有切換離開 AIXHUB 設定檔，而且受保護紀錄確認該設定檔原本不存在時，才能從 CC-Switch 刪除。
6. 驗證還原後的 JSON 與 TOML，分別重新啟動目標，並在允許工具或寫入前確認已還原的供應端。
7. 確認沒有還原的設定檔或目標仍使用兩組專用 AIXHUB 金鑰後，才撤銷金鑰。

若目標檔案原本不存在，只有目前檔案仍精確等於本指南建立的最小設定，而且沒有後來狀態時，才能刪除整份檔案；否則請保留檔案並依上方欄位層級規則處理。

安全注意事項

• 每個 CC-Switch 目標設定檔使用不同的專用 AIXHUB 金鑰，才能分別輪替、撤銷及調查用量。
• CC-Switch 本機資料、匯出設定檔、目標檔案備份與螢幕擷取畫面都必須視為秘密，因為其中可能包含憑證。
• 備份不可放進儲存庫或雲端同步資料夾，除非已核准的加密秘密儲存政策涵蓋該位置。
• 不可顯示金鑰、貼進提示內容、提交，或放入 release 報告、螢幕擷取畫面、診斷與支援記錄。
• 每次切換前先檢查目標、Base URL、模型與產生檔案預覽。即使沒有發出 API 請求，切換設定檔仍會變更狀態。
• 限制目標檔案與備份只能由目前作業系統使用者讀取。若已安裝 CC-Switch 版本支援作業系統秘密儲存區，共用機器應優先使用。
• 金鑰外洩後立即輪替，只更新相符目標設定檔，再重做唯讀驗證。

官方資料

• CC-Switch 官方標準儲存庫
• CC-Switch 官方 releases
• CC-Switch 供應端手冊
• CC-Switch 設定檔說明
• Claude Code 設定
• Codex 設定參考

最後核對：2026-07-14