> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> 在 Claude Code 中接入 AIHubMix：使用單一 API Key 跨供應商呼叫模型，並統一管理路由與計費。

## 快速開始

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

### 1. 安裝 Claude Code

#### 本機安裝

<CodeGroup>
  ```shellscript macOS theme={null}
  curl -fsSL https://claude.ai/install.sh | bash
  ```

  ```shellscript Windows theme={null}
  irm https://claude.ai/install.ps1 | iex
  ```
</CodeGroup>

#### 使用 npm 安裝

需要 [Node.js 18 或更高版本](https://nodejs.org/en/download/)

```shellscript theme={null}
npm install -g @anthropic-ai/claude-code
```

### 2. 配置 AIHubMix API

若要透過 Anthropic 相容 API 接入 AIHubMix 的模型服務，需要配置以下環境變數。

1. 將 `ANTHROPIC_BASE_URL` 設為 `https://aihubmix.com`
2. 將 `ANTHROPIC_AUTH_TOKEN` 設為從 [AIHubMix 平台](https://console.aihubmix.com/token) 取得的 API Key
3. 將 `ANTHROPIC_MODEL` 設為[模型列表](https://aihubmix.com/models)中支援的 Claude 模型，例如 `claude-sonnet-4-5`。

<Warning>
  `AIHUBMIX_API_KEY` 只是占位符，請替換成你自己的真實 Key（通常以 `sk-` 開頭）。如果原樣寫入，Claude Code 會把它當成真正的 Key，並返回 `401 invalid key: AIHUBMIX_API_KEY`。
</Warning>

<Tabs>
  <Tab title="macOS">
    1. 在終端機中執行以下命令，查看預設 Shell 類型。

    ```shellscript theme={null}
    echo $SHELL
    ```

    2. 根據 Shell 類型設定環境變數，命令如下：

    <CodeGroup>
      ```shellscript Zsh theme={null}
      # 將 <AIHUBMIX_API_KEY> 替換為你從 AIHubMix 平台取得的真實 Key
      echo 'export ANTHROPIC_BASE_URL="https://aihubmix.com"' >> ~/.zshrc
      echo 'export ANTHROPIC_AUTH_TOKEN="<AIHUBMIX_API_KEY>"' >> ~/.zshrc
      echo 'export ANTHROPIC_MODEL="claude-sonnet-4-5"' >> ~/.zshrc
      ```

      ```shellscript Bash theme={null}
      # 將 <AIHUBMIX_API_KEY> 替換為你從 AIHubMix 平台取得的真實 Key
      echo 'export ANTHROPIC_BASE_URL="https://aihubmix.com"' >> ~/.bash_profile
      echo 'export ANTHROPIC_AUTH_TOKEN="<AIHUBMIX_API_KEY>"' >> ~/.bash_profile
      echo 'export ANTHROPIC_MODEL="claude-sonnet-4-5"' >> ~/.bash_profile
      ```
    </CodeGroup>

    3. 在終端機中執行下列命令，使環境變數生效。

    <CodeGroup>
      ```shellscript Zsh theme={null}
      source ~/.zshrc
      ```

      ```shellscript Bash theme={null}
      source ~/.bash_profile
      ```
    </CodeGroup>

    4. 開啟新的終端機，執行下列命令，查看環境變數是否生效。

    ```shellscript theme={null}
    echo $ANTHROPIC_BASE_URL
    test -n "$ANTHROPIC_AUTH_TOKEN" && echo "ANTHROPIC_AUTH_TOKEN is set"
    echo $ANTHROPIC_MODEL
    ```
  </Tab>

  <Tab title="Windows">
    在 Windows 中，可以透過 CMD 或 PowerShell 將 AIHubMix 的 Base URL 和 [API Key](https://console.aihubmix.com/token) 設為環境變數。

    <Tabs>
      <Tab title="CMD">
        1. 在 CMD 中執行以下命令，設定環境變數。

        ```shellscript theme={null}
        REM 將 <AIHUBMIX_API_KEY> 替換為你從 AIHubMix 平台取得的真實 Key
        setx ANTHROPIC_AUTH_TOKEN "<AIHUBMIX_API_KEY>"
        setx ANTHROPIC_BASE_URL "https://aihubmix.com"
        setx ANTHROPIC_MODEL "claude-sonnet-4-5"
        ```

        2. 開啟新的 CMD 視窗，執行以下命令，檢查環境變數是否生效。

        ```shellscript theme={null}
        if defined ANTHROPIC_AUTH_TOKEN echo ANTHROPIC_AUTH_TOKEN is set
        echo %ANTHROPIC_BASE_URL%
        echo %ANTHROPIC_MODEL%
        ```
      </Tab>

      <Tab title="PowerShell">
        1. 在 PowerShell 中執行以下命令，設定環境變數。

        ```shellscript theme={null}
        # 將 <AIHUBMIX_API_KEY> 替換為你從 AIHubMix 平台取得的真實 Key
        [Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "<AIHUBMIX_API_KEY>", [EnvironmentVariableTarget]::User)
        [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://aihubmix.com", [EnvironmentVariableTarget]::User)
        [Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "claude-sonnet-4-5", [EnvironmentVariableTarget]::User)
        ```

        2. 開啟新的 PowerShell 視窗，執行以下命令，檢查環境變數是否生效。

        ```shellscript theme={null}
        if ($env:ANTHROPIC_AUTH_TOKEN) { "ANTHROPIC_AUTH_TOKEN is set" }
        echo $env:ANTHROPIC_BASE_URL
        echo $env:ANTHROPIC_MODEL
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

<Note>
  如果你準備透過 CC Switch 管理 Claude Code，建議不要再額外設定全域 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_MODEL`。系統或使用者環境變數可能覆蓋 CC Switch 寫入的 Provider 配置，導致介面中選了正確 Provider，但 Claude Code 實際仍使用舊 Key 或舊模型。
</Note>

### 3. 驗證配置是否生效

完成環境變數或 CC Switch 配置後，建議先用一次最小請求確認 Key、模型和 Anthropic 相容接口都可用，再啟動長會話。

<CodeGroup>
  ```bash macOS/Linux theme={null}
  curl https://aihubmix.com/v1/messages \
    -H "content-type: application/json" \
    -H "anthropic-version: 2023-06-01" \
    -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
    -d '{
      "model": "claude-sonnet-4-5",
      "max_tokens": 16,
      "messages": [{"role": "user", "content": "1+1，只輸出答案"}]
    }'
  ```

  ```powershell Windows theme={null}
  curl.exe https://aihubmix.com/v1/messages `
    -H "content-type: application/json" `
    -H "anthropic-version: 2023-06-01" `
    -H "x-api-key: $env:ANTHROPIC_AUTH_TOKEN" `
    -d "{\"model\":\"claude-sonnet-4-5\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"1+1，只輸出答案\"}]}"
  ```
</CodeGroup>

如果返回 `200` 且內容為 `2`，表示 AIHubMix Key 與 Claude 模型可用。接著可以執行：

```bash theme={null}
claude -p "1+1，只輸出答案" --model claude-sonnet-4-5
```

返回 `2` 即表示 Claude Code 端到端配置成功。

### 4. 開始使用

完成配置後，進入你的工作目錄，在終端機執行 `claude` 命令開始使用 Claude Code。

```bash theme={null}
$ cd /path/your-project
> claude
```

如果啟動後看到 `Not logged in · Please run /login`，或進入 Anthropic 登入選項，通常表示 Claude Code 沒有讀取到可用的 AIHubMix 配置，或首次引導尚未完成。請先確認上一步最小請求可返回 `2`，並檢查 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_MODEL` 是否被舊的全域環境變數覆蓋。確認 Key 可用後，如仍進入登入流程，可按以下步驟跳過首次引導：

<img src="https://mintcdn.com/aihubmix/HZpz50Qb6hBBcBVb/public/cn/cc-7.jpg?fit=max&auto=format&n=HZpz50Qb6hBBcBVb&q=85&s=0d1309bcea8f4170809d104bc2b380a6" alt="Claude Code 首次啟動時提示登入或繼續配置的終端機畫面" width="1622" height="438" data-path="public/cn/cc-7.jpg" />

1. 定位使用者主目錄下的 `.claude.json` 檔案，具體路徑如下：
   * macOS / Linux: `~/.claude.json`
   * Windows: `C:\Users\%USERNAME%\.claude.json`
2. 設定 `hasCompletedOnboarding` 欄位的值為 `true`

```json theme={null}
{
  "hasCompletedOnboarding": true
}
```

3. 儲存檔案，然後在終端機中重新執行 `claude`。

#### （可選）更多配置模型的方式

Claude Code 支援以下模型配置方式，**按優先級從高到低排列**，優先級高的配置會覆蓋優先級低的配置。

1. **對話期間：** 執行 `/model <模型名稱>` 命令切換模型。適用於臨時切換模型。

```text theme={null}
/model claude-sonnet-4-5
```

2. **啟動 Claude Code 時：** 執行 `claude --model <模型名稱>` 指定模型。適用於單次會話。

```text theme={null}
claude --model claude-sonnet-4-5
```

3. **設定環境變數**：可按任務複雜度配置不同級別的模型，Claude Code 會根據任務類型自動選擇合適的模型。

```shellscript theme={null}
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
```

其中：

* `ANTHROPIC_DEFAULT_OPUS_MODEL`：用於複雜推理、架構設計等高難度任務。
* `ANTHROPIC_DEFAULT_SONNET_MODEL`：用於程式碼編寫、功能實作等日常任務。
* `ANTHROPIC_DEFAULT_HAIKU_MODEL`：用於語法檢查、檔案搜尋等簡單任務。

4. **在 `settings.json` 配置檔中永久設定**：在 Claude Code 的使用者配置檔（如 `~/.claude/settings.json`，Windows 為 `C:\Users\%USERNAME%\.claude\settings.json`）或專案級配置中寫入模型配置信息。

<Note>
  **兜底配置：** 如果前面的 `/model`、啟動參數、環境變數或 CC Switch 配置沒有生效，或 Claude Code 仍讀取舊模型，可直接編輯 `settings.json`。下面示例同時設定 `ANTHROPIC_MODEL` 和頂層 `model`，並保留 Opus、Sonnet、Haiku 三個槽位的模型名稱。
</Note>

```json theme={null}
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "<AIHUBMIX_API_KEY>",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_NAME": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "gemini-3.5-flash",
    "ANTHROPIC_MODEL": "gpt-5.5"
  },
  "model": "gpt-5.5"
}
```

將 `<AIHUBMIX_API_KEY>` 替換為你自己的真實 Key。儲存後需要重新啟動 Claude Code，再輸入 `/models` 查看目前會話可切換的模型。

## 如何透過 CC Switch 配置？

1. 執行 CC Switch，先在左側選擇 **Claude Code**，再點擊「新增供應商」。

<img src="https://mintcdn.com/aihubmix/l2uHw7hd14guDu0f/public/cn/cc-1.jpg?fit=max&auto=format&n=l2uHw7hd14guDu0f&q=85&s=257b71ad7c6f876ac31147b7fd81f169" alt="CC Switch 首頁中點擊新增供應商入口的畫面" width="2068" height="1370" data-path="public/cn/cc-1.jpg" />

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

<img src="https://mintcdn.com/aihubmix/l2uHw7hd14guDu0f/public/cn/cc-2.jpg?fit=max&auto=format&n=l2uHw7hd14guDu0f&q=85&s=16dcb0697fdbf6438d4452ff8c39e485" alt="CC Switch 供應商預設列表中選擇 AiHubMix 的畫面" width="2072" height="1376" data-path="public/cn/cc-2.jpg" />

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

<img src="https://mintcdn.com/aihubmix/qVeqJ54P7wCzwnj-/public/cn/cc-3.jpg?fit=max&auto=format&n=qVeqJ54P7wCzwnj-&q=85&s=30deb64e7737ba515d70b161ee19ea58" alt="CC Switch AiHubMix 配置表單中填寫 API Key 的畫面" width="2070" height="1372" data-path="public/cn/cc-3.jpg" />

4. 配置完成後，先使用 `claude-sonnet-4-5` 作為模型 ID，點擊「新增」儲存設定。確認健康檢查通過後，可在 Claude Code 中透過 `/models` 或 `/model` 切換其他 Claude 模型。
   <Frame>
     <img src="https://mintcdn.com/aihubmix/KvaXxbOiAML2UsXS/images/img_v3_02116_2b161aa5-e317-4cbb-800f-5933d520b55g.jpg?fit=max&auto=format&n=KvaXxbOiAML2UsXS&q=85&s=167988610ef93d855b40f8618f23f9e4" alt="AIHubMix 模型列表中複製 Claude 模型 ID 的畫面" width="3008" height="1632" data-path="images/img_v3_02116_2b161aa5-e317-4cbb-800f-5933d520b55g.jpg" />
   </Frame>
5. 返回首頁，在供應商列表中選擇「AiHubMix」，點擊「啟動」即可使用。

<img src="https://mintcdn.com/aihubmix/l2uHw7hd14guDu0f/public/cn/cc-5.jpg?fit=max&auto=format&n=l2uHw7hd14guDu0f&q=85&s=4e765832e55e9737c91e2b40bf127c5d" alt="CC Switch 首頁中選擇 AiHubMix 並點擊啟動的畫面" width="2068" height="1366" data-path="public/cn/cc-5.jpg" />

> <Frame>
>   <img src="https://mintcdn.com/aihubmix/mDZumr5HeEPTKpFC/images/image-68.png?fit=max&auto=format&n=mDZumr5HeEPTKpFC&q=85&s=a6dd56f69a939f0a6b174cefc371cee7" alt="Claude Code 終端機中使用 status 和 models 命令查看模型配置" width="1142" height="1068" data-path="images/image-68.png" />
> </Frame>
>
> Tip: 終端機開啟 Claude Code 後，輸入 <kbd> /status </kbd> 可查詢模型 ID，輸入 <kbd>/models </kbd> 可選擇配置的其他模型

<Warning>
  如果 CC Switch 提示「偵測到系統環境變數衝突」，請優先處理 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_MODEL`。這些全域變數會覆蓋目前 Provider 配置；其中 `ANTHROPIC_AUTH_TOKEN=AIHUBMIX_API_KEY` 這類占位符值會直接導致認證失敗。確認不再需要全域變數後，可在 CC Switch 中刪除衝突項，或手動刪除系統/使用者環境變數，然後重新啟動終端機。
</Warning>

## 如何透過 VS Code 外掛配置？

1. 執行 VS Code，安裝外掛。

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.44.03.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=7fd42add3df2e072c3d8d85eb19c785d" alt="VS Code 擴充套件市場中安裝 Claude Code 外掛的畫面" width="1958" height="724" data-path="images/iShot_2026-03-25_11.44.03.jpg" />
</Frame>

2. 按下 `Ctrl + Shift + P`（或 `Cmd + Shift + P`），輸入 `Settings` 開啟設定。

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.47.48.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=c7b448a36e1886a4a1cdc9103f3844f6" alt="VS Code 命令面板中開啟 Settings 設定頁的畫面" width="1772" height="976" data-path="images/iShot_2026-03-25_11.47.48.jpg" />
</Frame>

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

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.49.37.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=3f5a87bc619bcb552eb4ed78da6527b6" alt="VS Code 設定中搜尋 Claude Code 環境變數配置項的畫面" width="1940" height="1248" data-path="images/iShot_2026-03-25_11.49.37.jpg" />
</Frame>

4. 在 `claudeCode.environmentVariables` 中填入 AIHubMix 相關資訊。

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.53.07.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=9a1355dac10acd90f0834f2f091ac3a7" alt="VS Code settings.json 中配置 Claude Code 環境變數的示例" width="1156" height="304" data-path="images/iShot_2026-03-25_11.53.07.jpg" />
</Frame>

## [Wechat-Agent-SDK](https://github.com/AIhubmix/wechat-agent-sdk)

透過簡單的接口調用，一鍵將 Claude Code、Codex、Kimi 等主流 AI 智能體接入微信。支援 ACP 協議，純本機執行，無需伺服器、無需資料庫，內建斷點續傳、自動重連等企業級特性，讓你的 AI 助手輕鬆在微信中智能對話。

> 安裝地址：[https://github.com/AIhubmix/wechat-agent-sdk](https://github.com/AIhubmix/wechat-agent-sdk)

## 常見問題

### Q：提示 `401` 認證錯誤怎麼辦？

`401` 表示請求沒有通過認證，但具體原因要看完整錯誤訊息：

* `No token provided`：沒有傳入 Key。開啟 Claude Code，輸入 `/config`，找到 `Use custom API key` 選項，檢查 Token 是否已配置。
* `invalid key: AIHUBMIX_API_KEY`：通常表示把示例占位符原樣寫入了環境變數。請在 AIHubMix 控制台重新複製真實 Key，並更新 `ANTHROPIC_AUTH_TOKEN`。
* `this key is not enabled`：請求已到達 AIHubMix，但目前 Key 尚未啟用或沒有調用權限。請在 [AIHubMix 控制台](https://console.aihubmix.com/token) 檢查該 Key 是否啟用、是否過期、是否有額度，並確認它可以調用你選擇的 Claude 模型。

<img src="https://mintcdn.com/aihubmix/Sq3QhNkLGyt6npNr/public/cn/cc-6.png?fit=max&auto=format&n=Sq3QhNkLGyt6npNr&q=85&s=27b1369c8b3970c789b7585e060bde07" alt="Claude Code config 中檢查自訂 API Key 的畫面" width="1220" height="760" data-path="public/cn/cc-6.png" />

在 Windows 上還要檢查使用者環境變數或系統環境變數中是否保留了舊值：

```powershell theme={null}
[Environment]::GetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "User")
[Environment]::GetEnvironmentVariable("ANTHROPIC_BASE_URL", "User")
[Environment]::GetEnvironmentVariable("ANTHROPIC_MODEL", "User")
```

如果你使用 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 模型列表](https://aihubmix.com/models) 中重新複製完整模型 ID，確認沒有手動拼寫、大小寫或系列名稱錯誤。

如果你透過 CC Switch 配置，請回到對應 Provider，更新模型 ID 後儲存，並重新啟動 Claude Code。如果仍然報錯，可先換用模型列表中確認可用的 Claude 模型完成健康檢查，再切換到目標模型。

### Q：macOS 中安裝成功後仍然報錯：`zsh: command not found: claude`

這是因為 Claude CLI 已安裝，但其可執行目錄未加入系統 `PATH`。

1. 確認 Claude 安裝路徑。Claude Code 官方腳本通常安裝在以下目錄之一：

* `~/.claude/bin`
* `~/.local/bin`

在終端機執行：

```shellscript theme={null}
ls -l ~/.claude/bin
或
ls -l ~/.local/bin | grep claude
```

如果看到 claude 檔案，表示安裝成功，只是 PATH 未配置。

2. 將安裝目錄加入 PATH。根據實際安裝位置執行對應命令：

#### 情況 A：安裝在 `~/.claude/bin`

```shellscript theme={null}
echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

#### 情況 B：安裝在 `~/.local/bin`

```shellscript theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

3. 驗證是否生效。執行：

```text theme={null}
which claude
claude -v
```

若能看到 `claude` 路徑及版本號，表示安裝成功。

### Q：Claude Code 無法連接 Anthropic 服務

升級到最新版本的 Claude Code 後，若出現無法連接 Anthropic 服務或認證失敗的情況，通常是由於認證請求頭名稱已發生調整所致。新版本要求將請求頭由 `ANTHROPIC_API_KEY` 修改為 `ANTHROPIC_AUTH_TOKEN`，API Key 的值無需更換，僅需更新請求頭名稱並重新載入配置即可。具體操作可參考本文檔重新配置。

## 更多資源

* [Github](https://github.com/inferera/aihubmix/blob/main/packages/claude-code/README.md)
* [npm 套件](https://www.npmjs.com/package/@aihubmix/claude-code)
* [官方最佳實踐](https://www.anthropic.com/engineering/claude-code-best-practices)
* [官方配置指引](https://docs.anthropic.com/en/docs/claude-code/settings#settings-files)

祝你使用愉快！

最後更新：2026年6月10日