跳轉到主要內容

快速開始

本指南將協助你在幾分鐘內使用由 AIHubMix 提供的 Claude Code。

1. 安裝 Claude Code

本機安裝

前三種為官方原生安裝方式,安裝後會在背景自動更新。WinGet 和 Homebrew 安裝不會自動更新,需要定期執行 winget upgrade Anthropic.ClaudeCode 或 brew upgrade claude-code。

使用 npm 安裝

需要 Node.js 22 或更高版本

2. 配置 AIHubMix API

若要透過 Anthropic 相容 API 接入 AIHubMix 的模型服務,需要配置以下環境變數。
  1. 將 ANTHROPIC_BASE_URL 設為 https://aihubmix.com
  2. 將 ANTHROPIC_AUTH_TOKEN 設為從 AIHubMix 平台 取得的 API Key
  3. 將 ANTHROPIC_MODEL 設為模型列表中支援的 Claude 模型,例如 claude-sonnet-5-5。
AIHUBMIX_API_KEY 只是占位符,請替換成你自己的真實 Key(通常以 sk- 開頭)。如果原樣寫入,Claude Code 會把它當成真正的 Key,並返回 401 invalid key: AIHUBMIX_API_KEY。
  1. 在終端機中執行以下命令,查看預設 Shell 類型。
  1. 根據 Shell 類型設定環境變數,命令如下:
  1. 在終端機中執行下列命令,使環境變數生效。
  1. 開啟新的終端機,執行下列命令,查看環境變數是否生效。
如果你準備透過 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。 Claude Code 首次啟動時提示登入或繼續配置的終端機畫面 請按以下順序檢查:
  1. 確認上一步的最小請求可以返回 2。
  2. 確認 ANTHROPIC_AUTH_TOKEN 寫在 Claude Code 啟動時就能讀取的位置:終端機環境變數,或 ~/.claude/settings.json 的 env。寫入 ~/.zshrc 等配置檔後,需要開啟新的終端機再執行 claude。只寫在專案目錄的 .claude/settings.json 或 .claude/settings.local.json 中時,要等首次引導和信任資料夾確認完成後才生效,因此首次啟動仍會進入登入畫面。
  3. 檢查 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL 是否被舊的全域環境變數覆蓋。
修改後在終端機中重新執行 claude。

(可選)更多配置模型的方式

Claude Code 支援以下模型配置方式,按優先級從高到低排列,優先級高的配置會覆蓋優先級低的配置。
  1. 對話期間: 執行 /model <模型名稱> 命令切換模型,所選模型會儲存為之後新會話的預設模型。只想切換目前會話時,輸入 /model 開啟模型列表,在目標模型上按 s。設定了 ANTHROPIC_MODEL 時,新會話仍使用該變數指定的模型。
  1. 啟動 Claude Code 時: 執行 claude --model <模型名稱> 指定模型。適用於單次會話。
  1. 設定環境變數 ANTHROPIC_MODEL: 適用於全域生效。
  1. 在 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。
也可以把 AIHubMix 的配置統一寫進 ~/.claude/settings.json 的 env 中,示例如下:
將 <AIHUBMIX_API_KEY> 替換為你自己的真實 Key。儲存後需要重新啟動 Claude Code,再輸入 /model 查看目前會話可切換的模型。

如何透過 CC Switch 配置?

  1. 執行 CC Switch,先在左側選擇 Claude Code,再點擊「新增供應商」。
CC Switch 首頁中點擊新增供應商入口的畫面
  1. 在預設列表中選擇「AiHubMix」。請確認目前配置的是 Claude Code 側的 Provider。
CC Switch 供應商預設列表中選擇 AiHubMix 的畫面
  1. 在「API Key」欄中填寫你的真實密鑰。
CC Switch AiHubMix 配置表單中填寫 API Key 的畫面
  1. 向下捲動到「模型對應」,在 Sonnet、Opus、Haiku 三列的「顯示名稱」和「實際請求模型」中分別填寫 claude-sonnet-5-5、claude-opus-5-5、claude-haiku-5-5,其餘列留空;「備用模型」填寫 claude-sonnet-5-5。點擊「新增」儲存設定,之後可在 Claude Code 中透過 /model 切換這些模型。
    CC Switch 模型對應中填寫 Claude 模型 ID 的畫面
  2. 返回首頁,點擊「AiHubMix」卡片右側的 ▷ 按鈕(切換)。卡片顯示「使用中」即表示 Claude Code 已改用該供應商。
CC Switch 首頁中 AiHubMix 顯示為使用中的畫面
Claude Code 終端機中使用 /status 命令查看目前模型
Tip: 終端機開啟 Claude Code 後,輸入 /status 可查詢模型 ID,輸入 /model 可選擇配置的其他模型
如果 CC Switch 提示「偵測到系統環境變數衝突」,請優先處理 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL。這些全域變數會覆蓋目前 Provider 配置;其中 ANTHROPIC_AUTH_TOKEN=AIHUBMIX_API_KEY 這類占位符值會直接導致認證失敗。確認不再需要全域變數後,可在 CC Switch 中刪除衝突項,或手動刪除系統/使用者環境變數,然後重新啟動終端機。

如何透過 VS Code 外掛配置?

  1. 執行 VS Code,安裝外掛。
VS Code 擴充套件市場中安裝 Claude Code 外掛的畫面
  1. 按下 Ctrl + Shift + P(或 Cmd + Shift + P),輸入 Settings 開啟設定。
VS Code 命令面板中開啟 Settings 設定頁的畫面
  1. 搜尋 Claude Code,找到 Claude Code: Environment Variable -> Edit in settings.json。
VS Code 設定中搜尋 Claude Code 環境變數配置項的畫面
  1. 在 claudeCode.environmentVariables 中填入 AIHubMix 相關資訊,並將 claudeCode.disableLoginPrompt 設為 true,跳過外掛的登入提示。
VS Code settings.json 中配置 Claude Code 環境變數的示例

常見問題

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 模型。
在 Windows 上還要檢查使用者環境變數或系統環境變數中是否保留了舊值:
如果你使用 CC Switch 管理配置,建議刪除這些全域 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。
  1. 確認 Claude 安裝路徑。官方安裝腳本會把 claude 安裝到以下位置:
  • macOS / Linux:~/.local/bin/claude
  • Windows:%USERPROFILE%\.local\bin\claude.exe
在終端機執行:
如果看到 claude 檔案,表示安裝成功,只是 PATH 未配置。
  1. 將安裝目錄加入 PATH:
  1. 驗證是否生效。執行:
若能看到 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。具體操作可參考本文檔重新配置。

更多資源

祝你使用愉快! 最後更新:2026年10月20日