AGTCloud API Docs
文件指南API Reference整合與資源更新與幫助

CC-Switch

使用 CC-Switch 管理和切換 AGTCloud 設定。

CC-Switch 是跨平台的本機設定管理工具，可以為 Claude Code、Codex 等程式開發工具儲存多個 Provider，並將目前啟用的設定寫入相應工具的設定檔。透過它可以在 AGTCloud 和其他已儲存設定之間切換，無需每次手動編輯檔案。

本教學只介紹 Claude Code 與 Codex 的應用程式專屬 Provider。請求會由對應程式開發工具直接傳送到 AGTCloud，不啟用 CC-Switch 的 Local Proxy、Failover、協議轉換或 Universal Provider。

切換操作會修改本機工具設定

CC-Switch 會更新 Claude Code 或 Codex 的即時設定檔。首次使用前，請確認現有設定已經被正確匯入，並在新增 AGTCloud 前匯出一份備份。

準備工作

開始前，請確認你已經：

  • 安裝並完成 Claude Code 或 Codex 的基本啟動；
  • 註冊並登入 AGTCloud；
  • 在 API Keys 頁面建立 AGTCloud API Key；
  • 從模型廣場複製目前 API Key 可見、且支援目標工具協議的模型 ID；
  • 準備一個不包含敏感程式碼和正式環境憑證的測試專案。

Claude Code 應選擇支援 Anthropic Messages 的模型；Codex 應選擇支援 OpenAI Responses 的模型。MODEL_ID 是需要替換的預留位置，不是實際模型名稱。

下載並安裝 CC-Switch

只從 CC-Switch 官方網站 或 GitHub Releases 取得安裝套件。任何要求為 CC-Switch 本身儲值、付費或提交登入憑證的網站和用戶端都不是官方管道。

  • 一般安裝選擇 GitHub Releases 中目前版本的 Windows MSI；
  • 不希望安裝時可以選擇 Windows Portable ZIP；
  • Portable 版本解壓後執行 CC-Switch.exe；
  • 如果 Windows 阻止執行，請先檢查檔案來源和數位簽章，不要關閉系統安全功能。

CC-Switch 負責管理設定，但不會替代 Claude Code 或 Codex 本身。請先確保目標程式開發工具能夠正常啟動。

首次啟動與備份

檢查自動匯入結果

首次啟動時，CC-Switch 會嘗試匯入本機已有的 Claude Code、Codex 等設定。分別開啟對應應用程式頁面，確認原有官方設定或自訂 Provider 已經顯示在清單中。

保留原有 Provider

不要刪除自動匯入的官方設定。後續需要退出 AGTCloud 時，可以重新啟用該 Provider 恢復原來的連線方式。

匯出資料備份

進入 設定 → 進階 → 資料管理，使用目前版本提供的匯出功能儲存備份。備份檔案可能包含 API Key 和其他敏感 Provider 資訊，請儲存在可信任位置，不要上傳到倉庫或公開雲端硬碟。

本教學不要求直接編輯設定檔

CC-Switch 會負責寫入相應工具的設定。不要為了套用其他平台的範例而覆蓋 ~/.claude/settings.json、~/.codex/auth.json 或 ~/.codex/config.toml。

新增 AGTCloud Provider

在頂部選擇需要設定的應用程式，點選右上角的新增按鈕，然後使用“應用程式專屬供應商”中的自訂設定。Claude Code 和 Codex 使用不同協議與 Base URL，應分別建立 Provider。

開啟 Claude Code Provider 頁面

在 CC-Switch 頂部選擇 Claude Code，點選新增供應商，選擇“自訂”或目前版本對應的自訂 Provider 入口。

填寫連線資訊

欄位填寫內容
Provider NameAGTCloud
Base URLhttps://api.agtcloud.cn
API Keyyour-api-key
Primary ModelMODEL_ID
Authentication使用 API Key，不使用 ANTHROPIC_AUTH_TOKEN

Base URL 只填寫本頁顯示的 API Origin，不追加 /v1。Claude Code 會自行請求 /v1/messages。

處理模型映射

如果目前版本顯示 Haiku、Sonnet、Opus 角色映射，首次可以將三個角色都映射到同一個已確認支援 Anthropic Messages 的 MODEL_ID。只有掌握多個模型的真實能力時，再分別設定不同模型。

儲存但暫不啟用代理

儲存 Provider。不要開啟 Local Proxy、Failover、協議轉換或其他進階路由功能。

使用 API Key 驗證

AGTCloud 的 Claude Code 設定使用 ANTHROPIC_API_KEY 對應的 API Key 驗證。不要複製其他平台使用 ANTHROPIC_AUTH_TOKEN 或 Bearer Token 的設定。

啟用並驗證設定

啟用 AGTCloud

回到對應應用程式的供應商清單，點選 AGTCloud 卡片上的“啟用”。確認卡片顯示“目前啟用”或目前版本中的等效狀態。

重新載入目標工具

  • Claude Code 通常可以檢測設定變化，但建議新開一個工作階段進行驗證；
  • Codex 需要關閉目前終端機視窗，再重新開啟終端機並啟動 Codex。

不要使用已經傳送過請求的舊工作階段判斷切換是否成功。

檢查目前設定

在目標工具中執行：

/status

核對 Provider、Base URL、驗證來源和模型 ID。Claude Code 不應顯示重複 /v1；Codex 的 Base URL 應以單一 /v1 結尾。

發起唯讀測試

在包含 README.md 的安全測試專案中輸入：

請讀取 README.md，並用三點概括專案用途。不要修改任何檔案。

能夠正常傳回結果，且沒有發生未授權修改，說明基本連線已經建立。本步會產生正常的 API 用量。

使用系統匣快速切換

CC-Switch 在系統匣中為不同應用程式提供獨立的 Provider 清單。在系統匣圖示上按滑鼠右鍵，進入 Claude 或 Codex 子選單，再選擇需要啟用的 Provider。

系統匣切換只是另一種設定入口，不要求啟用 Local Proxy。切換 Codex 後仍應重新開啟終端機。

切回原有設定

  1. 在 CC-Switch 中開啟 Claude Code 或 Codex 頁面；
  2. 找到首次啟動時匯入的官方 Provider；
  3. 點選“啟用”；
  4. Claude Code 新開工作階段確認恢復，Codex 重新開啟終端機確認恢復。

Claude Code 和 Codex 的 Provider 相互隔離。切換 Claude Code 不會自動修改 Codex，反之亦然。

常見問題

現象優先檢查處理方式
找不到合適的安裝套件下載來源、作業系統和處理器架構只從 ccswitch.io 或官方 GitHub Releases 取得目前版本
原有 Provider 沒有出現首次匯入結果和原工具設定路徑先確認 Claude Code 或 Codex 已經安裝並存在設定，再重新開啟 CC-Switch
啟用時提示無法寫入設定檔權限和佔用狀態關閉正在執行的目標工具，檢查使用者設定目錄權限後重試
傳回 401API Key 內容和驗證方式使用有效 API Key；Claude Code 不要使用 ANTHROPIC_AUTH_TOKEN
傳回 403Key 狀態、帳戶權限和模型權限在控制台檢查目前 API Key 與模型可用範圍
傳回 404Base URL、重複 /v1、完整 Endpoint 和模型 IDClaude Code 使用 https://api.agtcloud.cn；Codex 使用 https://api.agtcloud.cn/v1，不要填寫完整請求路徑
模型清單無法載入/v1/models 支援、網路和 API Key從模型廣場複製目前 Key 可見的完整模型 ID 後手動填寫
Claude Code 仍使用舊設定Provider 啟用狀態和舊工作階段快取確認 AGTCloud 卡片為目前啟用，然後新開 Claude Code 工作階段並執行 /status
Codex 仍使用舊設定終端機是否重新啟動關閉目前終端機視窗，重新開啟終端機後再啟動 Codex
一般對話成功但工具呼叫失敗模型協議和工具呼叫能力為 Claude Code 選擇支援 Anthropic Messages 與工具呼叫的模型；為 Codex 選擇支援 Responses 的模型
Base URL 變成 /v1/v1應用程式類型與 URL 填寫方式Claude Code 刪除 /v1；Codex 只保留一個 /v1

遇到無法定位的問題時，請記錄目標工具、請求時間、API Base URL、模型 ID、HTTP 狀態和去識別化錯誤資訊，然後檢視錯誤與疑難排解。不要提交完整 API Key 或 CC-Switch 資料備份。

安全建議

  • 不要把 API Key 放入截圖、記錄、倉庫或共享設定；
  • CC-Switch 資料匯出可能包含敏感 Provider 資訊，應作為憑證備份妥善儲存；
  • 只從官方管道下載安裝 CC-Switch，不要向第三方用戶端提交平台登入憑證；
  • 首次驗證使用安全測試專案，並保持 Claude Code、Codex 的操作審核開啟；
  • API Key 疑似洩漏時，立即在控制台停用或刪除，然後建立新 Key。

下一步

整合與資源

查找第三方工具整合、SDK、開發工具和移轉資料。

Claude Code

在 Claude Code 中設定和使用 AGTCloud。

本頁目錄

準備工作下載並安裝 CC-Switch首次啟動與備份檢查自動匯入結果保留原有 Provider匯出資料備份新增 AGTCloud Provider開啟 Claude Code Provider 頁面填寫連線資訊處理模型映射儲存但暫不啟用代理開啟 Codex Provider 頁面填寫連線資訊取得或手動填寫模型儲存標準 Provider啟用並驗證設定啟用 AGTCloud重新載入目標工具檢查目前設定發起唯讀測試使用系統匣快速切換切回原有設定常見問題安全建議下一步