Claude Code (官方 CLI) 通過兩個環境變數指向我方閘道器, 直接使用全部 Claude / Bedrock 模型
POST /v1/messages
Claude Code 是 Anthropic 官方的命令列 AI 助手, 預設走 `api.anthropic.com`. 把它指向**我方閘道器** (`api.router.ai`) 後, 立即獲得平臺的全部 Claude 模型 + 統一計費 + 多模型混合路由能力, 0 程式碼改動. ## 一、兩個核心環境變數 中轉站配置 Claude Code **只要這兩個變數**: | 變數 | 值 | 作用 | |---|---|---| | `ANTHROPIC_BASE_URL` | `https://api.router.ai` | 閘道器根地址. **填到根域名即可, 不要加 `/v1` 也不要加 `/v1/messages`** | | `ANTHROPIC_AUTH_TOKEN` | `sk-你的 token` | 平臺代理 token, 作為 `Authorization: Bearer xxx` 傳送 | > ⚠️ **不要用 `ANTHROPIC_API_KEY`** — 那個會發 `x-api-key` 頭, 我方閘道器只認標準 `Authorization: Bearer`. > ⚠️ **`/v1` 不要加** — Claude Code HTTP client 內部自動 append `/v1/messages` 到 BASE_URL. 加了 `/v1` 會導致請求拼成 `/v1/v1/messages` 命中 404 (依據 Anthropic 官方 LLM Gateway 文件). --- ## 二、三種配置方式 (任選一種) ### 方式 1 · 臨時環境變數 (測試推薦, 最快) ```bash export ANTHROPIC_BASE_URL=https://api.router.ai export ANTHROPIC_AUTH_TOKEN=sk-你的token claude ``` 只在當前終端會話生效, 關掉就沒了, 適合**先驗證能不能通**. --- ### 方式 2 · 寫進 shell 配置 (永久, 最常用) **macOS** (預設 zsh): ```bash cat >> ~/.zshrc <<'EOF' export ANTHROPIC_BASE_URL=https://api.router.ai export ANTHROPIC_AUTH_TOKEN=sk-你的token EOF source ~/.zshrc ``` **Linux** (bash): ```bash cat >> ~/.bashrc <<'EOF' export ANTHROPIC_BASE_URL=https://api.router.ai export ANTHROPIC_AUTH_TOKEN=sk-你的token EOF source ~/.bashrc ``` **Windows PowerShell**: ```powershell $env:ANTHROPIC_BASE_URL = "https://api.router.ai" $env:ANTHROPIC_AUTH_TOKEN = "sk-你的token" ``` 要永久生效, 寫進 `$PROFILE` 或在「系統環境變數」里加. --- ### 方式 3 · 寫進 Claude Code 配置檔案 (推薦, 不汙染全域性) 編輯 `~/.claude/settings.json` (沒有就新建): ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.router.ai", "ANTHROPIC_AUTH_TOKEN": "sk-你的token" } } ``` 這種方式**只對 Claude Code 生效**, 不會影響你其他工具的 ANTHROPIC_* 變數, 長期推薦. --- ## 三、模型名對映 (按需) 我方閘道器預設透傳 Claude Code 發的 model 名 (例如 `claude-sonnet-4-5-20250929` / `claude-opus-4-7`). 如果你想**強制覆蓋**預設模型 (例如全部預設調成 Haiku 省錢), 加這三個變數: ```bash export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7 export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5-20250929 export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001 ``` 平臺支援的 Claude 模型完整列表見 **模型廣場 → Claude 系列**. 模型名錯會上游返 400, 客戶端可見原始錯誤. --- ## 四、驗證生效 啟動後輸入 `/status` 命令, 應看到: ``` Base URL: https://api.router.ai Auth: Bearer sk-...**** Model: claude-... ``` 如果 Base URL 仍是 `api.anthropic.com`, 說明環境變數沒生效, 檢查方式: 1. 重新開啟終端 (shell 配置改了要 source) 2. `echo $ANTHROPIC_BASE_URL` 確認值是根域名 (**不帶 /v1**) 3. 方式 3 的 settings.json 檢查 JSON 語法是否正確 --- ## 五、常見坑速查 | 現象 | 原因 | 修法 | |---|---|---| | 404 / `Not Found` 含路徑 `/v1/v1/messages` | `BASE_URL` 多加了 `/v1` 字尾 → SDK 再 append `/v1/messages` 拼成雙 `/v1` | 去掉 `/v1`, 只保留根域名 | | 仍走官方 / 401 / `please log in` | `~/.claude/.credentials.json` 殘留 OAuth token, 優先順序高於環境變數 | 刪掉該檔案: `rm ~/.claude/.credentials.json` | | `model not found` 類錯誤 | 客戶端發的 model 名不在我方支援列表 | 用上面的 `ANTHROPIC_DEFAULT_*_MODEL` 強制對映, 或檢查模型廣場 | | `401 Unauthorized` | token 配錯或過期 | cloud admin 後臺 → 令牌管理, 重新生成 | | `429 / 限流` | token RPM/TPM 超限 | 後臺調整 token 限流配置 或 切到更高額度 token | | 流式響應不工作 | 中間代理 (Cloudflare 自建 / 公司防火牆) buffer SSE | 直接連 `api.router.ai` 不走中間代理 | | 所有請求 422 | curl 測試時 prompt 含裸換行 (Claude Code SDK 不會撞這個) | 用 SDK 而不是手擼 curl | --- ## 六、完整一鍵指令碼 (複製貼上版) ```bash # 1. 配置 (一次性) mkdir -p ~/.claude cat > ~/.claude/settings.json <<'EOF' { "env": { "ANTHROPIC_BASE_URL": "https://api.router.ai", "ANTHROPIC_AUTH_TOKEN": "sk-在這裡貼你的token" } } EOF # 2. 清理可能殘留的 OAuth (跳到 Step 3 如果是新機器) rm -f ~/.claude/.credentials.json # 3. 啟動 + 驗證 claude # 進入 Claude Code 後: # /status — 應看到 Base URL = https://api.router.ai # 你好 (隨便一句中文測試) — 應正常返回 ``` --- ## 七、跟官方帳號共存 希望**保留官方帳號但臨時切到我方**? 用方式 1 臨時變數, 退出終端後自動回到官方. 或者維護兩個 settings 檔案: ```bash # 切到我方 ln -sf ~/.claude/settings.router.json ~/.claude/settings.json # 切回官方 ln -sf ~/.claude/settings.official.json ~/.claude/settings.json ``` --- ## 八、可觀測性 平臺後臺為每次 Claude Code 呼叫記錄: - 請求 + 響應 token 數, 耗時, 命中模型 - usage / cache_read_tokens / cache_creation_tokens (Claude prompt cache 透明跟隨) - 流式 chunk 數, TTFB, 完整響應內容 (合規審計需要) 代理 portal 可在「**計費流水**」 / 「**聊天呼叫**」 看到全部歷史. --- ## 九、技術細節 (按需瞭解) Claude Code 啟動時會請求 `${ANTHROPIC_BASE_URL}/v1/models` 探測可用模型. 呼叫時請求 `${ANTHROPIC_BASE_URL}/v1/messages` (流式 / 非流式) 和可能的 `${ANTHROPIC_BASE_URL}/v1/messages/count_tokens` (token 估算). 我方閘道器三個端點都已實現, 相容 Anthropic 官方協議.
200 — 成功