401 authentication_error／invalid x-api-key 錯誤——依序檢查什麼

幾乎所有 401 都有四種原因，而只有其中一種是「金鑰錯了」。其他三種情況下金鑰完全有效——因此重新建立金鑰通常只是浪費力氣。

錯誤

resposta (HTTP 401)

{
  "type": "error",
  "error": { "type": "authentication_error",
             "message": "invalid x-api-key" }
}

原因與解決方法一覽

原因	解決方法
對主機使用了錯誤的標頭	Anthropic 讀取 x-api-key；大多數相容 OpenAI 的閘道則讀取 Authorization: Bearer。同一個值放在錯誤的標頭中，抵達時會被視為不存在。
遺留的環境變數仍然存在	Shell 設定檔中被遺忘的 ANTHROPIC_API_KEY，可能會覆蓋您剛剛 export 的金鑰。
更換基礎 URL 卻沒有更換憑證	指向另一個主機，不會讓原供應商的金鑰在該主機上變得有效。主機與憑證必須一起更換。
金鑰中有空格、換行或引號	從 PDF 或聊天內容複製時，常會帶入不可見字元。請確認字串長度。

確認環境實際包含的內容

在變更任何設定前，先查看執行應用程式的同一個 Shell 中的變數。令人意外的是，許多案例同時定義了兩個來自不同供應商的憑證。

conferir.sh

for v in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL; do
  printf '%-22s [%s] tamanho=%s\n' \
    "$v" "$(printenv "$v" | cut -c1-10)" "$(printenv "$v" | wc -c)"
done

在應用程式外測試憑證

直接發送請求，可以區分「主機拒絕金鑰」與「應用程式沒有傳送金鑰」。如果 curl 能運作而程式碼不能，問題就不在憑證。

testar.sh

curl -s -o /dev/null -w 'status=%{http_code}\n' \
  "$ANTHROPIC_BASE_URL/v1/models" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

# 200 -> credencial boa; investigue a aplicação
# 401 -> credencial ou cabeçalho errados para este host

區分 401、403 與 402

401 是「我不知道你是誰」：憑證未被接受。403 是「我知道你是誰，但你沒有權限」：已完成驗證，但不具備權限。402 是「我知道你是誰，但餘額不足」。只有 401 需要透過修改憑證來解決。

如果你透過 Kunavo 呼叫

Kunavo 會在 Authorization: Bearer 與 x-api-key 中讀取 sk-kn- 金鑰，而基礎 URL 是網站來源，後面不能帶任何路徑。使用 Claude Code 時，請使用 ANTHROPIC_AUTH_TOKEN 搭配 ANTHROPIC_BASE_URL，因為該 Token 不依賴 ANTHROPIC_API_KEY 所要求的一次性核准；並請明確移除 ANTHROPIC_API_KEY——這個變數中的舊值，是工作階段看似已設定卻仍遭拒絕的最常見原因。驗證步驟請參閱驗證文件.

常見問題

重新建立金鑰能解決問題嗎？

只有在金鑰確實已被撤銷時才有用。在其他三種常見原因——標頭錯誤、舊變數、基礎 URL 已更換——新金鑰也會完全相同地失敗。

401 可能是餘額不足嗎？

不是。餘額不足會回傳 402，並附上提到點數的訊息。401 一律與身分識別有關。

用 curl 可以運作，但我的程式失敗。為什麼？

幾乎總是因為程式讀取了另一個環境變數，或是在 export 尚未傳入的另一個 shell／容器中執行。請在程序內列印經遮罩的憑證以確認。