Claude Code API 金鑰——去哪裡取得、放在哪裡，以及錯誤變數為何會靜默失敗

Claude Code 有兩種不同的驗證方式，而你需要的方式會決定其餘所有設定。claude.ai 訂閱登入涵蓋 Pro 或 Max 方案內的使用量。API 金鑰則按 token 計費，不受方案上限限制。本指南涵蓋如何取得金鑰、確切放置位置、兩個憑證變數，以及為何選錯變數會造成無聲失敗，還有成功後如何控制費用。

你真的需要金鑰嗎？

開始前值得知道：設定金鑰會暫停你的訂閱。憑證變數啟用期間，Claude Code 會使用它，而不會使用已儲存的 claude.ai 登入；方案上限將不再適用，使用量會計入金鑰擁有者。取消設定後，Claude Code 會返回使用訂閱。

選項 1——Anthropic 第一方金鑰

1. 登入 console.anthropic.com（這是與 claude.ai 分開的帳戶）。
2. 在 Billing 下新增額度。API 採預付制，與任何訂閱分開——Pro 方案不會支付 API 費用。
3. 在 API Keys 下建立金鑰。它以 sk-ant- 開頭，且只會顯示一次。

export ANTHROPIC_API_KEY=sk-ant-...
# Then approve it once, interactively:
#   /config  ->  Use custom API key
claude

請注意該片段中的第二個步驟。ANTHROPIC_API_KEY 會在 x-api-key 標頭中傳送，且 Claude Code 使用前需要一次性互動核准。如果該提示曾被拒絕，之後金鑰會在完全不再提示的情況下被忽略——這看起來就像變數未被讀取。請在 /config → Use custom API key 下重新啟用。

選項 2——每 token 成本較低的金鑰

Claude Code 原生讀取 ANTHROPIC_BASE_URL，因此可連接任何提供 Anthropic Messages API 的端點——不需要外掛、代理伺服器或修改過的二進位檔。這是閘道支援的路徑，也是以較低價格使用相同 Claude 模型的方式：

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
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

ANTHROPIC_BASE_URL 僅為來源網址 — Claude Code 會自行附加 /v1/messages。請保留模型設定行：Claude Code 的內建預設模型及其 opus 別名都會解析為最新的 Opus；如果 Kunavo 尚未提供該模型，第一次請求就會回傳 404。opus 這一行會將模型固定為 Claude Opus 5.5，這需要 Claude Code v2.1.280 或更新版本（若使用較舊版本，請執行 claude update）。sonnet 別名會請求 Sonnet 5.5，而 Kunavo 並未提供此模型，因此若未設定 ANTHROPIC_DEFAULT_SONNET_MODEL，/model sonnet、opusplan 的執行階段，以及設為 sonnet 的子代理都會回傳 404。請先註冊並儲值 $10，再於控制台建立 sk-kn- 金鑰。無須支付月費，餘額也不會到期。

這大約比主線模型的定價低 30%。完整價格請參閱 Claude API 定價指南；Claude Code 定價會將此路徑與 Pro 和 Max 方案費用比較；完整設定，包括每項工作的模型路由，以及透過閘道時會有哪些變化，請參閱 Claude Code 路由器指南。如果尚未安裝 CLI，請從 安裝 Claude Code 開始。

金鑰實際放置的位置

兩個變數、兩個不同的 HTTP 標頭。若金鑰放在伺服器不讀取的標頭中，會以 401 失敗：

如果你不確定手上的金鑰屬於哪一種，請先使用 ANTHROPIC_AUTH_TOKEN，它不需要核准步驟。在 Kunavo 上，任一變數都能讓 Claude Code 取得模型清單，因為 /v1/models 會從任一標頭讀取金鑰。

Shell export 與設定檔

Shell export 只適用於該終端機及其子程序。從 Dock 啟動的編輯器看不到它，背景代理也看不到。若要永久設定，請改用 ~/.claude/settings.json 的 env 區塊——使用相同金鑰，且適用於 Claude Code 執行的所有位置。不要將金鑰放在專案的 .claude/settings.json 中；該檔案會提交並與所有複製儲存庫的人共用。

執行 /status 以確認目前使用的憑證。若出現命名你變數的 Auth token 或 API key 列，表示金鑰已啟用；若出現命名 claude.ai 帳戶的 Login method 列，表示金鑰未啟用。

無需編輯檔案即可輪替金鑰

如果憑證會按排程過期，或來自金庫，請將 apiKeyHelper 指向一個會輸出目前金鑰的命令：

#!/bin/bash
# Any command that prints the current key to stdout works.
vault kv get -field=api_key secret/claude-code

在設定檔中以 "apiKeyHelper": "~/bin/get-key.sh" 參照它。Claude Code 會將輸出快取五分鐘，並在 401 時重新執行；使用 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 調整此設定。該值會在兩個標頭中傳送，因此兩種方式都能運作。

讓費用可預測

代理式程式設計非常耗用 token——每個步驟都會重新傳送系統提示、工作歷史與新的檔案上下文。以下四件事比其他任何事情都更重要：

1. 將背景工作路由至 Haiku。 ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 涵蓋 Claude Code 自行產生的摘要與標題。只需一行設定，就能純粹節省費用；當工作分支擴大時尤其重要，這部分的價格詳見Claude Code 工作流程的成本。
2. 同一組兩個變數也會路由 Agent SDK。 它本身沒有 base URL 選項——它會啟動此 CLI 並直接傳遞你的環境，因此Agent SDK 程式完全依照上述設定進行路由。
3. 開始新工作，不要無限延長同一項工作。 每個步驟都會重新傳送上下文，因此長工作階段的成本呈平方級增長。至於主模型應選哪個層級，Opus 與 Sonnet 與 Haiku會以每項完成工作的成本，而非每 token 的成本進行分析。
4. 讓提示快取發揮作用。 快取輸入按輸入價格的 10% 計費，而原生 Messages API 路徑會原樣傳遞 cache_control（詳細資訊）。
5. 在控制台中為編輯器設定專用且有限額的金鑰，然後一週後查看使用量。每個金鑰的限額可以將失控迴圈變成有上限的迴圈。

疑難排解

常見問題