快速開始
本指南將協助你在幾分鐘內使用由 AIHubMix 提供的 Claude Code。1. 安裝 Claude Code
本機安裝
winget upgrade Anthropic.ClaudeCode 或 brew upgrade claude-code。
使用 npm 安裝
需要 Node.js 22 或更高版本2. 配置 AIHubMix API
若要透過 Anthropic 相容 API 接入 AIHubMix 的模型服務,需要配置以下環境變數。- 將
ANTHROPIC_BASE_URL設為https://aihubmix.com - 將
ANTHROPIC_AUTH_TOKEN設為從 AIHubMix 平台 取得的 API Key - 將
ANTHROPIC_MODEL設為模型列表中支援的 Claude 模型,例如claude-sonnet-5-5。
- macOS
- Windows
- 在終端機中執行以下命令,查看預設 Shell 類型。
- 根據 Shell 類型設定環境變數,命令如下:
- 在終端機中執行下列命令,使環境變數生效。
- 開啟新的終端機,執行下列命令,查看環境變數是否生效。
如果你準備透過 CC Switch 管理 Claude Code,建議不要再額外設定全域
ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL。系統或使用者環境變數可能覆蓋 CC Switch 寫入的 Provider 配置,導致介面中選了正確 Provider,但 Claude Code 實際仍使用舊 Key 或舊模型。3. 驗證配置是否生效
完成環境變數或 CC Switch 配置後,建議先用一次最小請求確認 Key、模型和 Anthropic 相容接口都可用,再啟動長會話。200 且內容為 2,表示 AIHubMix Key 與 Claude 模型可用。接著可以執行:
2 即表示 Claude Code 端到端配置成功。
4. 開始使用
完成配置後,進入你的工作目錄,在終端機執行claude 命令開始使用 Claude Code。
Not logged in · Please run /login,或進入 Anthropic 登入選項,說明 Claude Code 沒有讀取到 AIHubMix 的 Key。

- 確認上一步的最小請求可以返回
2。 - 確認
ANTHROPIC_AUTH_TOKEN寫在 Claude Code 啟動時就能讀取的位置:終端機環境變數,或~/.claude/settings.json的env。寫入~/.zshrc等配置檔後,需要開啟新的終端機再執行claude。只寫在專案目錄的.claude/settings.json或.claude/settings.local.json中時,要等首次引導和信任資料夾確認完成後才生效,因此首次啟動仍會進入登入畫面。 - 檢查
ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL是否被舊的全域環境變數覆蓋。
claude。
(可選)更多配置模型的方式
Claude Code 支援以下模型配置方式,按優先級從高到低排列,優先級高的配置會覆蓋優先級低的配置。- 對話期間: 執行
/model <模型名稱>命令切換模型,所選模型會儲存為之後新會話的預設模型。只想切換目前會話時,輸入/model開啟模型列表,在目標模型上按s。設定了ANTHROPIC_MODEL時,新會話仍使用該變數指定的模型。
- 啟動 Claude Code 時: 執行
claude --model <模型名稱>指定模型。適用於單次會話。
- 設定環境變數
ANTHROPIC_MODEL: 適用於全域生效。
- 在
settings.json配置檔中永久設定: 在 Claude Code 的使用者配置檔(如~/.claude/settings.json,Windows 為C:\Users\%USERNAME%\.claude\settings.json)或專案級配置中寫入model欄位,可分別進行使用者級或專案級的永久配置。設定了ANTHROPIC_MODEL時,model欄位不生效。
ANTHROPIC_DEFAULT_FABLE_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 用於指定 fable、opus、sonnet、haiku 四個別名對應的模型 ID,不參與上面的優先級。主對話始終使用目前選定的模型。
ANTHROPIC_DEFAULT_FABLE_MODEL:fable別名對應的模型。ANTHROPIC_DEFAULT_OPUS_MODEL:opus別名對應的模型,opusplan在 Plan 模式下也使用該模型。ANTHROPIC_DEFAULT_SONNET_MODEL:sonnet別名對應的模型,opusplan在 Plan 模式以外使用該模型。ANTHROPIC_DEFAULT_HAIKU_MODEL:haiku別名對應的模型,Claude Code 的背景任務也使用該模型。
同一個變數同時寫在終端機環境變數和
settings.json 的 env 中時,以 settings.json 中的值為準。如果終端機裡設定的模型沒有生效,請檢查 settings.json 的 env 中是否寫了 ANTHROPIC_MODEL。~/.claude/settings.json 的 env 中,示例如下:
<AIHUBMIX_API_KEY> 替換為你自己的真實 Key。儲存後需要重新啟動 Claude Code,再輸入 /model 查看目前會話可切換的模型。
如何透過 CC Switch 配置?
- 執行 CC Switch,先在左側選擇 Claude Code,再點擊「新增供應商」。

- 在預設列表中選擇「AiHubMix」。請確認目前配置的是 Claude Code 側的 Provider。

- 在「API Key」欄中填寫你的真實密鑰。

- 向下捲動到「模型對應」,在 Sonnet、Opus、Haiku 三列的「顯示名稱」和「實際請求模型」中分別填寫
claude-sonnet-5-5、claude-opus-5-5、claude-haiku-5-5,其餘列留空;「備用模型」填寫claude-sonnet-5-5。點擊「新增」儲存設定,之後可在 Claude Code 中透過/model切換這些模型。
- 返回首頁,點擊「AiHubMix」卡片右側的 ▷ 按鈕(切換)。卡片顯示「使用中」即表示 Claude Code 已改用該供應商。

Tip: 終端機開啟 Claude Code 後,輸入 /status 可查詢模型 ID,輸入 /model 可選擇配置的其他模型
如何透過 VS Code 外掛配置?
- 執行 VS Code,安裝外掛。

- 按下
Ctrl + Shift + P(或Cmd + Shift + P),輸入Settings開啟設定。

- 搜尋
Claude Code,找到Claude Code: Environment Variable->Edit in settings.json。

- 在
claudeCode.environmentVariables中填入 AIHubMix 相關資訊,並將claudeCode.disableLoginPrompt設為true,跳過外掛的登入提示。

常見問題
Q:提示 401 認證錯誤怎麼辦?
401 表示請求沒有通過認證,但具體原因要看完整錯誤訊息:
no key provided:請求中沒有 Key。開啟 Claude Code,輸入/status,確認Anthropic base URL一行為https://aihubmix.com,並且Auth token或API key一行顯示了ANTHROPIC_AUTH_TOKEN等變數名稱。invalid key: AIHUBMIX_API_KEY:通常表示把示例占位符原樣寫入了環境變數。請在 AIHubMix 控制台重新複製真實 Key,並更新ANTHROPIC_AUTH_TOKEN。this key is not enabled:請求已到達 AIHubMix,但目前 Key 尚未啟用或沒有調用權限。請在 AIHubMix 控制台 檢查該 Key 是否啟用、是否過期、是否有額度,並確認它可以調用你選擇的 Claude 模型。
ANTHROPIC_* 變數,讓 CC Switch 目前 Provider 接管配置。
注意:/v1/models 可能在無有效 Key 時也能返回模型列表,因此不能用它判斷 Key 是否可用。請參考上文「驗證配置是否生效」中的最小消息請求;如果返回 200 且內容為 2,表示 Key 與模型可用,再重新啟動 Claude Code 或透過 CC Switch 重新啟動即可。
Q:提示 400 Incorrect model ID 或 Bad request (400) 怎麼辦?
這通常表示請求格式已到達供應商側,但模型 ID 不正確、模型名稱與接口不匹配,或目前 Key 沒有調用該模型的權限。請在 AIHubMix 模型列表 中重新複製完整模型 ID,確認沒有手動拼寫、大小寫或系列名稱錯誤。
如果你透過 CC Switch 配置,請回到對應 Provider,更新模型 ID 後儲存,並重新啟動 Claude Code。如果仍然報錯,可先換用模型列表中確認可用的 Claude 模型完成健康檢查,再切換到目標模型。
Q:macOS 中安裝成功後仍然報錯:zsh: command not found: claude
這是因為 Claude CLI 已安裝,但其可執行目錄未加入系統 PATH。
- 確認 Claude 安裝路徑。官方安裝腳本會把
claude安裝到以下位置:
- macOS / Linux:
~/.local/bin/claude - Windows:
%USERPROFILE%\.local\bin\claude.exe
- 將安裝目錄加入 PATH:
- 驗證是否生效。執行:
claude 路徑及版本號,表示安裝成功。
Q:Claude Code 無法連接 Anthropic 服務
升級到最新版本的 Claude Code 後,若出現無法連接 Anthropic 服務或認證失敗的情況,請先檢查認證變數是否配置正確。Claude Code 支援兩個認證變數:ANTHROPIC_AUTH_TOKEN 透過 Authorization: Bearer 請求頭發送 Key,ANTHROPIC_API_KEY 透過 x-api-key 請求頭發送 Key,AIHubMix 兩種方式均可使用,本文檔統一使用 ANTHROPIC_AUTH_TOKEN。具體操作可參考本文檔重新配置。
