Claude Code 串接 AIXHUB

本指南會將 Claude Code 命令列用戶端連到 AIXHUB 所路由的 Anthropic 相容模型。先以暫時環境變數測試，再送出一個唯讀請求；確認成功後，才把設定寫入使用者層級檔案。

完成目標

完成本指南後，你會得到以下結果：

1. 透過官方安裝程式安裝 Claude Code 命令列用戶端。
2. 在單一終端機中測試 AIXHUB，不先變更永久設定。
3. 儲存完整的使用者層級 settings.json。
4. 在 AIXHUB 用量核對一筆唯讀請求。
5. 保留明確的復原方式，必要時能回到原始設定。

系統需求

• 使用 PowerShell 的 Windows，或使用 Bash、zsh 的 macOS/Linux。macOS 通常預設使用 zsh 作為互動式 Shell。
• 能以目前使用者身分安裝軟體，並從終端機執行 claude。
• AIXHUB 帳號、一組 AIXHUB API 金鑰，以及從模型路由複製的 Anthropic 相容模型 ID。本指南需要模型 ID 時一律使用 panel-model-id。
• 編輯前先備份既有的 Claude Code 使用者設定檔。

Claude Code 會從下列位置讀取使用者設定：

• Windows：%USERPROFILE%\.claude\settings.json
• macOS 與 Linux：~/.claude/settings.json

安裝

macOS 與 Linux

執行官方安裝命令：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

執行官方 PowerShell 安裝命令：

irm https://claude.ai/install.ps1 | iex

安裝後開啟新的終端機，確認可執行檔已加入 PATH：

claude --version

請先修正安裝或 PATH 問題，再加入 AIXHUB 設定。這樣可以清楚區分用戶端安裝失敗與供應端設定失敗。

AIXHUB 設定

先在目前終端機測試

在 macOS 或 Linux 中，請依目前使用的 Shell 選擇對應區塊。macOS 通常預設使用 zsh。兩種方式都不會回顯金鑰，也不會把真實值寫入 Shell 歷程。

Bash

read -r -s -p "AIXHUB API key: " AIXHUB_KEY
printf '\n'
export ANTHROPIC_BASE_URL="https://api.aixhub.org"
export ANTHROPIC_AUTH_TOKEN="$AIXHUB_KEY"
export ANTHROPIC_API_KEY="$AIXHUB_KEY"
export ANTHROPIC_MODEL="panel-model-id"
unset AIXHUB_KEY

zsh

read -r -s "AIXHUB_KEY?AIXHUB API key: "
printf '\n'
export ANTHROPIC_BASE_URL="https://api.aixhub.org"
export ANTHROPIC_AUTH_TOKEN="$AIXHUB_KEY"
export ANTHROPIC_API_KEY="$AIXHUB_KEY"
export ANTHROPIC_MODEL="panel-model-id"
unset AIXHUB_KEY

Windows PowerShell 先以 SecureString 讀取，再透過 NetworkCredential 轉成目前 PowerShell 工作階段使用的環境變數，最後移除暫存 PowerShell 變數：

$secureKey = Read-Host "AIXHUB API key" -AsSecureString
$plainKey = [System.Net.NetworkCredential]::new("", $secureKey).Password
$env:ANTHROPIC_BASE_URL = "https://api.aixhub.org"
$env:ANTHROPIC_AUTH_TOKEN = $plainKey
$env:ANTHROPIC_API_KEY = $plainKey
$env:ANTHROPIC_MODEL = "panel-model-id"
Remove-Variable plainKey, secureKey

Claude Code 的 ANTHROPIC_BASE_URL 必須是完整的 https://api.aixhub.org。不要附加 /v1，因為用戶端會自行加入 Anthropic API 路徑。兩個 Token 變數使用同一組 AIXHUB API 金鑰，ANTHROPIC_MODEL 則固定使用 panel-model-id。

這些環境變數只在目前終端機工作階段有效。測試完成後關閉該工作階段，即可清除其中的金鑰與模型變數。

儲存使用者層級設定

暫時測試成功後，先備份既有設定檔，再把以下 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"
  }
}

Windows 使用 %USERPROFILE%\.claude\settings.json，macOS 或 Linux 使用 ~/.claude/settings.json。合併既有檔案時，請保留其他最上層屬性、維持有效 JSON 語法，並在儲存後重新啟動所有執行中的 Claude Code。

首次使用

切換到小型測試專案，以明確模型啟動用戶端，首次請求先不要授予寫入權限：

claude --model panel-model-id

命令列旗標與 ANTHROPIC_MODEL 現在都指定 panel-model-id，不要依賴互動式預設值。接著交付這個範圍明確的工作：

請以唯讀方式查看目前目錄，不要變更任何檔案。只回覆 OK。

核准任何權限要求前，先閱讀其內容。首次測試不需要修改檔案、不需要執行會改變狀態的 Shell 命令，也不需要存取測試專案以外的位置。

驗證

成功時應看到以下實際輸出：

OK

接著開啟 AIXHUB 用量，確認出現一筆使用 panel-model-id 的 Anthropic 相容請求。核對時間是否與測試一致、啟動命令與 ANTHROPIC_MODEL 是否選到相同模型，並確認請求並非直接送到官方 Anthropic 帳號。

疑難排解

401 或驗證失敗

• 確認啟動 Claude Code 的同一個終端機或 settings.json 中，ANTHROPIC_AUTH_TOKEN 與 ANTHROPIC_API_KEY 都取得目前同一組 AIXHUB API 金鑰；檢查時不要顯示任何 Token 值。
• 不要使用 AIXHUB 控制台密碼，也不要使用官方 Anthropic 帳號 Token。
• 變更環境變數後重新啟動 Claude Code；已啟動的 Claude Code 不會取得稍後才加入的 Shell 變更。

模型無法使用或 model not found

從模型路由重新複製完整模型 ID；把 ANTHROPIC_MODEL 設為 panel-model-id，再以 claude --model panel-model-id 啟動，並確認該路由支援 Anthropic 相容請求。不要縮短 ID，也不要自行猜測版本字尾。

Claude Code 仍連到官方 Anthropic

在啟動 Claude Code 的終端機中檢查 ANTHROPIC_BASE_URL 與 ANTHROPIC_MODEL，但不要顯示兩個 Token 變數；同時檢查實際載入的 settings.json。Base URL 必須是 https://api.aixhub.org，不能含 /v1。重試前，完整關閉終端機工作階段、編輯器整合與背景 Claude Code 工作。

其他設定優先套用

暫時 Shell 變數、使用者設定、受管理設定與編輯器整合都可能提供四個 ANTHROPIC_* 名稱。移除過期值或讓各處保持一致，包含 ANTHROPIC_MODEL，再重新啟動 Claude Code。若收到 403、429、502 或 503，請參考錯誤代碼，區分存取、速率與上游服務失敗。

升級與復原

升級前後都檢查版本：

claude --version
claude update
claude --version

若目前版本不支援 claude update，請重新執行上方同一個官方安裝命令。重新安裝不需要變更 AIXHUB 設定。

若要復原，請先關閉 Claude Code，再還原 settings.json 備份；也可以只從 env 物件刪除 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 與 ANTHROPIC_MODEL。若曾把四個變數加入 Shell 設定檔，也要一併移除，並關閉暫時終端機工作階段以清除其中的環境變數。開啟新的終端機並執行 claude --version，之後再選擇其他供應端。

安全注意事項

• sk-your-key 只是秘密值的替代文字。切勿提交真實值、貼進提示內容，或放入支援記錄。
• 把 settings.json 保留在使用者設定檔目錄，不要放進專案；作業系統支援檔案權限時，僅允許目前使用者讀取。
• 暫時測試請透過上方不回顯提示輸入金鑰；切勿把真實值直接寫入會被 Shell 歷程保留的命令。
• 為 Claude Code 建立專用 AIXHUB API 金鑰，撤銷時才不會影響其他用戶端。
• 若金鑰出現在終端機歷程、螢幕擷取畫面、修補內容或共用記錄中，請立即輪替。
• 即使已核對網路路由，面對不熟悉的專案仍要逐次檢視工具權限。

官方資料

• Claude Code 安裝說明
• Claude Code 設定說明

最後核對：2026-07-14