文件
ANTHROPIC_BASE_URL
用來將 Claude Code 與 Anthropic SDK 指向 api.anthropic.com 以外端點的環境變數 — 完整變數參考、各客戶端設定方式,以及幾乎所有故障都源自的兩個常見問題。
ANTHROPIC_BASE_URL 會告訴 Anthropic SDK 與 Claude Code 要將 API 請求傳送至哪個主機,取代預設的 https://api.anthropic.com。請將它設為不含路徑的來源站點,客戶端會自行附加 /v1/messages,並搭配 ANTHROPIC_AUTH_TOKEN 使用;此 Token 會成為 Authorization: Bearer 標頭。
# The origin only — no trailing /v1, no trailing slash.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...之後請開啟新的終端機:Claude Code 與 SDK 會在程序啟動時讀取這些變數,因此已在執行中的工作階段仍會使用舊端點。
https://api.kunavo.com/v1 會使請求送往 /v1/v1/messages,所有呼叫都會回傳 404。OpenAI SDK 的慣例正好相反,其 base_url 中確實需要包含 /v1 — 這項差異是此處最常見的設定錯誤。每個變數及其用途
Claude Code 會讀取的完整清單請見Anthropic 的環境變數參考。重新導向端點時,以下變數最重要。
| 變數 | 值 | 控制項目 |
|---|---|---|
ANTHROPIC_ | https://api. | 所有請求傳送至的來源站點。不含路徑,也不加結尾斜線。 |
ANTHROPIC_ | sk-kn-… | 以 Authorization: Bearer 傳送的憑證。閘道需要使用此變數。 |
ANTHROPIC_ | sk-ant-… | 以 x-api-key 標頭傳送的憑證,是 api. |
ANTHROPIC_ | claude-sonnet-5 | Claude Code 用於對話的主要模型。 |
ANTHROPIC_ | claude-opus-5-5 | opus 別名背後所使用的模型(/ |
ANTHROPIC_ | claude-sonnet-5 | sonnet 別名背後所使用的模型(/ |
ANTHROPIC_ | claude-haiku-4-5 | Claude Code 用於自身背景呼叫的低成本模型 — 除了快取之外,最能大幅降低成本的因素。 |
GET /v1/models 即時取得。各客戶端設定方式
Claude Code
將匯出指令放在 Claude Code 啟動時使用的 shell 設定檔中,然後開啟新的終端機。安裝方式和工作流程都不需要變更。
# ~/.zshrc (or ~/.bashrc) — applies to every Claude Code session.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
# Pin models this endpoint serves. Claude Code's default and its opus/sonnet
# aliases follow Anthropic's newest models, which may not be served here —
# unpinned, those calls 404.
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5在 Claude Code 中執行 /status,確認目前工作階段使用的端點。逐步說明(包含產生金鑰的位置):在 Claude Code 設定 API 金鑰。
Anthropic SDK(Python / TypeScript)
SDK 會讀取相同的環境變數,也可以將兩項設定傳入建構函式;當同一個程序需要連線至多個端點時,這種做法很實用。
from anthropic import Anthropic
# The Anthropic SDK appends /v1/messages, so pass the origin — not .../v1.
client = Anthropic(
base_url="https://api.kunavo.com",
auth_token="sk-kn-...", # sets the Authorization: Bearer header
)
msg = client.messages.create(
model="claude-sonnet-5",
max_tokens=512,
messages=[{"role": "user", "content": "Say hi"}],
)
print(msg.content[0].text)OpenAI SDK — 另一種慣例
如果你的程式已使用 OpenAI 格式,就完全不需要 ANTHROPIC_BASE_URL。將 base_url 指向 OpenAI 相容路徑 — 這次要包含 /v1 — 然後透過 /v1/chat/completions 呼叫相同的 Claude 模型。
from openai import OpenAI
# The OpenAI SDK is the other convention: it wants the /v1 in the base_url.
client = OpenAI(
api_key="sk-kn-...",
base_url="https://api.kunavo.com/v1",
)
r = client.chat.completions.create(
model="claude-sonnet-5",
messages=[{"role": "user", "content": "Say hi"}],
)
print(r.choices[0].message.content)Cline、Roo Code、Kilo Code、Cursor
編輯器代理程式大多在各自的介面中提供相同的兩項設定,而非透過環境變數:一個「base URL」或「custom endpoint」欄位,以及一個 API 金鑰欄位。規則不變:Anthropic 樣式的供應商使用不含 /v1 的來源站點,並將金鑰填入 API 金鑰欄位。各客戶端逐步操作指南:Cline、Roo Code、Kilo Code。
確認是否設定成功
一個 curl 請求就能同時驗證 base URL 和憑證。若收到 200 與 JSON 主體,表示兩者都正確。
# 200 and a JSON body means the base URL and the token are both right.
curl -sS https://api.kunavo.com/v1/messages \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "content-type: application/json" \
-d '{"model":"claude-haiku-4-5","max_tokens":16,
"messages":[{"role":"user","content":"ping"}]}'
# In Claude Code, /status shows the endpoint the session is actually using.故障排除
| 症狀 | 原因 | 修正方法 |
|---|---|---|
| 每個請求都回傳 404 | /v1 留在 ANTHROPIC_ 結尾 | 只設定來源站點。客戶端會自行附加 /v1/ |
| 401 / invalid x-api-key | 端點使用 Bearer Token 驗證,但憑證設為 ANTHROPIC_ | 改用 ANTHROPIC_ — 完整了解兩者差異 |
| 仍連到 api. | 在工作階段啟動後才匯出變數,或將變數設在 shell 不會讀取的設定檔中 | 開啟新的終端機;在啟動用戶端的同一個 shell 中,以 echo $ANTHROPIC_ |
| 404 model_ | 端點未提供該模型 ID | 將 ANTHROPIC_ 設為 GET /v1/models 中的模型 ID |
| Claude Code 顯示額度餘額不足 | 請求已送達端點,費用計入金鑰,而非訂閱 | 這是預期行為 — 請儲值,或取消設定 Token 以恢復使用方案。請參閱額度不足 |
這對 Pro 或 Max 訂閱的影響
只要設定了憑證變數,Claude Code 就會向該金鑰計費,而非已登入的訂閱:方案限制不再適用,使用費會計入金鑰持有人名下。訂閱本身不受影響;移除變數並開啟新的終端機後,Claude Code 就會恢復使用該方案。兩者不會合併計算,費用的計算方式請見Claude Code 定價。
接下來
常見問題
什麼是 ANTHROPIC_BASE_URL?
ANTHROPIC_BASE_URL 是一個環境變數,用來告訴 Anthropic SDK 與 Claude Code 要將 API 請求傳送至哪個主機,而非預設的 https://api.anthropic.com。請將它設為不含路徑的來源站點,客戶端會自行附加 /v1/messages,並搭配 ANTHROPIC_AUTH_TOKEN 使用;此 Token 會成為 Authorization: Bearer 標頭。任何相容 Anthropic 的端點都可使用;在 Kunavo 上,值為 https://api.kunavo.com。
ANTHROPIC_BASE_URL 要包含 /v1 嗎?
不用。ANTHROPIC_BASE_URL 只接受來源站點,例如 https://api.kunavo.com,而不是 https://api.kunavo.com/v1,因為 Anthropic SDK 與 Claude Code 會自行附加 /v1/messages 路徑。加入 /v1 會使請求送往 /v1/v1/messages,並回傳 404。OpenAI SDK 的慣例正好相反,其 base_url 確實需要包含 /v1,因此同一個閘道會依呼叫它的客戶端而有兩種不同的寫法。
ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 有什麼差異?
ANTHROPIC_AUTH_TOKEN 會將憑證放在 Authorization: Bearer 標頭中傳送;ANTHROPIC_API_KEY 則會將憑證放在 api.anthropic.com 預期的 x-api-key 標頭中傳送。使用 Bearer Token 驗證的閘道需要 ANTHROPIC_AUTH_TOKEN;變更 ANTHROPIC_BASE_URL 後,改設 ANTHROPIC_API_KEY 是最常見的 401 原因。請擇一設定,不要兩者都設;兩者同時存在時,行為取決於客戶端版本。
如何在 Claude Code 設定自訂 base URL?
在 Claude Code 啟動時使用的 shell 設定檔(~/.zshrc 或 ~/.bashrc)中匯出 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN,然後開啟新的終端機,讓變數傳遞給程式。Claude Code 會在啟動時讀取這些變數,因此已在執行中的工作階段仍會使用舊端點。在 Claude Code 中執行 /status,確認目前工作階段使用的端點。
設定 ANTHROPIC_BASE_URL 會停用我的 Claude Pro 或 Max 訂閱嗎?
只要設定了 ANTHROPIC_AUTH_TOKEN 這類憑證變數,Claude Code 就會向該金鑰計費,而非已登入的訂閱,因此 Pro 和 Max 方案的限制不再適用,使用費會計入金鑰持有人名下。訂閱本身不受影響,也不會取消;移除變數並開啟新的終端機後,Claude Code 就會恢復使用該方案。