Claude Code 自訂基底網址出現「API Error: 401 authentication_error」— 所有原因

這裡的 401 與你的憑證或基底網址有關，絕不是模型問題 — 模型問題會回傳 404，並在訊息中指出模型名稱。只要在一次 curl 中辨識這項差異，就能解決大多數問題。

錯誤

terminal

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Missing or invalid API key"}}

原因與解決方法一覽

原因	解決方法
應設定 ANTHROPIC_AUTH_TOKEN 卻設定了 ANTHROPIC_API_KEY	第三方基底網址請使用 AUTH_TOKEN；API_KEY 會觸發一次性核准提示。
基底網址包含 /v1 路徑	只設定來源 — Claude Code 會自行附加 /v1/messages。
金鑰已撤銷，或帳戶已遭停權	兩者都會回傳 401，不會回傳 403。請建立新金鑰並檢查帳戶。
Messages 端點不提供的模型	這會回傳指出模型名稱的 404，而不是 401 — 因此需要採取不同的修正方式。

列印三個變數，並確認基底網址不含路徑

最常見的原因就在這裡。基底網址必須是來源，不得包含 /v1 或結尾路徑，因為用戶端會自行附加端點。以 /v1 結尾的基底網址會產生對 /v1/v1/messages 的請求。

check-env.sh

env | grep -E '^ANTHROPIC_(BASE_URL|AUTH_TOKEN|API_KEY|MODEL)='

# Right: https://api.kunavo.com
# Wrong: https://api.kunavo.com/v1

以兩種方式直接呼叫端點

Kunavo 的 /v1/messages 接受 x-api-key 或 Authorization: Bearer 任一種憑證，因此 Claude Code 不需要在前面加上外掛程式或代理伺服器。如果 curl 成功而 CLI 失敗，問題就在你的 Shell 環境，而不在伺服器。

probe.sh

curl -s https://api.kunavo.com/v1/messages   -H "x-api-key: $ANTHROPIC_AUTH_TOKEN"   -H "anthropic-version: 2023-06-01"   -H "content-type: application/json"   -d '{"model":"claude-sonnet-5","max_tokens":8,
       "messages":[{"role":"user","content":"hi"}]}'

# Same call, other header style — both are accepted:
#   -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

取消設定不使用的變數

如果同時設定 ANTHROPIC_API_KEY 與 ANTHROPIC_AUTH_TOKEN，可能會採用錯誤的那一個。取消設定 ANTHROPIC_API_KEY、啟動新的 Shell 後再試一次 — Shell 設定檔中的舊 export 會持續存在，其他修正都可能因此失效。

如果狀態是 404，請停止除錯金鑰

如果 404 訊息中列出模型名稱，表示憑證已獲接受，但模型字串未獲接受。請改為修正 ANTHROPIC_MODEL；金鑰本身沒有問題。在全新設定中，通常的原因是沒有指定模型：Claude Code 會傳送其內建預設值，也就是最新的 Opus，而 Kunavo 可能尚未提供該模型；而 /model sonnet 會要求 Sonnet 5.5，Kunavo 不提供該模型——請將 ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL 和 ANTHROPIC_DEFAULT_SONNET_MODEL 設定為 GET /v1/models 回傳的 ID。

如果你透過 Kunavo 呼叫

Kunavo 的 401 可縮小為五種原因：Authorization: Bearer 或 x-api-key 中沒有收到金鑰；金鑰不含 sk-kn- 前綴；它是 Kunavo 從未簽發的 sk-kn- 金鑰（輸入錯誤或貼上時遭截斷）；金鑰已撤銷；或帳戶已遭停權。這些情況都不會回傳 403，因此僅憑狀態碼就能判斷所屬類別 — 而有效金鑰若指向 Messages 端點不提供的模型，會回傳訊息中標出模型名稱的 404，而不是 401。這就是完整的診斷樹。

常見問題

為什麼我的金鑰在 curl 中有效，在 Claude Code 中卻無效？

幾乎總是因為 Shell 設定檔中設定了第二個變數，或基底網址包含路徑。端點接受兩種標頭格式，因此差異不在標頭。

ANTHROPIC_AUTH_TOKEN 還是 ANTHROPIC_API_KEY？

第三方基底網址使用 AUTH_TOKEN — 會立即使用。API_KEY 會先觸發一次性核准提示，這常被誤認為失敗。

Claude 訂閱涵蓋自訂基底網址嗎？

不涵蓋。訂閱只能驗證到供應商自己的端點；將 CLI 指向其他地方，就必須使用該端點的憑證，並由該端點計費。