文件

文件

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 標頭。

~/.zshrc
# 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 會在程序啟動時讀取這些變數,因此已在執行中的工作階段仍會使用舊端點。

請勿在 ANTHROPIC_BASE_URL 中加入 /v1。 Anthropic 客戶端會自行附加路徑,因此 https://api.kunavo.com/v1 會使請求送往 /v1/v1/messages,所有呼叫都會回傳 404。OpenAI SDK 的慣例正好相反,其 base_url 中確實需要包含 /v1 — 這項差異是此處最常見的設定錯誤。

每個變數及其用途

Claude Code 會讀取的完整清單請見Anthropic 的環境變數參考。重新導向端點時,以下變數最重要。

變數值控制項目
ANTHROPIC_BASE_URLhttps://api.kunavo.com所有請求傳送至的來源站點。不含路徑,也不加結尾斜線。
ANTHROPIC_AUTH_TOKENsk-kn-…以 Authorization: Bearer 傳送的憑證。閘道需要使用此變數。
ANTHROPIC_API_KEYsk-ant-…以 x-api-key 標頭傳送的憑證,是 api.anthropic.com 預期的格式。請設定此變數或上方的 Token,勿同時設定。
ANTHROPIC_MODELclaude-sonnet-5Claude Code 用於對話的主要模型。
ANTHROPIC_DEFAULT_OPUS_MODELclaude-opus-5-5opus 別名背後所使用的模型(/model opus)。Claude Code 本身的預設值是最新的 Opus,因此請將其固定為該端點提供的模型。Opus 5.5 需要 Claude Code v2.1.280 或更新版本。
ANTHROPIC_DEFAULT_SONNET_MODELclaude-sonnet-5sonnet 別名背後所使用的模型(/model sonnet)。此別名預設要求 Sonnet 5.5,因此請將其固定為該端點提供的 Sonnet 模型。
ANTHROPIC_DEFAULT_HAIKU_MODELclaude-haiku-4-5Claude Code 用於自身背景呼叫的低成本模型 — 除了快取之外,最能大幅降低成本的因素。
模型名稱必須是端點實際提供的模型。將端點指向閘道,卻保留閘道未提供的模型 ID,是第二常見的故障;這會顯示為 404 model_not_found,而非驗證錯誤。Kunavo 的模型 ID 列於模型頁面,也可透過 GET /v1/models 即時取得。

各客戶端設定方式

Claude Code

將匯出指令放在 Claude Code 啟動時使用的 shell 設定檔中,然後開啟新的終端機。安裝方式和工作流程都不需要變更。

~/.zshrc
# ~/.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 會讀取相同的環境變數,也可以將兩項設定傳入建構函式;當同一個程序需要連線至多個端點時,這種做法很實用。

anthropic_sdk.py
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 模型。

openai_sdk.py
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_BASE_URL 結尾只設定來源站點。客戶端會自行附加 /v1/messages。
401 / invalid x-api-key端點使用 Bearer Token 驗證,但憑證設為 ANTHROPIC_API_KEY改用 ANTHROPIC_AUTH_TOKEN — 完整了解兩者差異
仍連到 api.anthropic.com在工作階段啟動後才匯出變數,或將變數設在 shell 不會讀取的設定檔中開啟新的終端機;在啟動用戶端的同一個 shell 中,以 echo $ANTHROPIC_BASE_URL 確認。
404 model_not_found端點未提供該模型 ID將 ANTHROPIC_MODEL 設為 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 就會恢復使用該方案。