當同一臺機器上存在多份 Claude Code 憑證時，這個工具既不猜、也不隨機：官方文件定義了一份明確的 Claude Code 認證優先順序順序，每個請求都由該清單上第一個適用的來源來服務。僅這一個事實，就解釋了這個生態裡最令人困惑的兩種報告。一種是訂閱使用者，他的請求卻一直走著一箇舊的 API key。另一種是設了新令牌的工程師，眼看著舊令牌持續獲勝，於是斷定工具壞了。本文逐層走一遍官方順序，覆蓋造成大部分困惑的三種衝突，最後給出一種確認實際在用哪份憑證、而不靠假設的方法。如果你還在配置階段而不是排查階段，請從首次配置指南開始；本文針對的是已經配置好、但行為不合預期的情形。
Claude Code 認證優先順序，逐層說明
下面的順序遵循官方認證頁面，它是權威來源，也是每逢這個話題重要時都該重新核對的頁面，因為細節的演進速度快過部落格文章。
- 雲提供商憑證。當設定了
CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX或CLAUDE_CODE_USE_FOUNDRY時，對應雲提供商的憑證路徑會先於本清單上的其他任何一項被選中。 ANTHROPIC_AUTH_TOKEN。以Authorization: Bearerheader 傳送。當你經由用 bearer token 而不是 Anthropic API key 認證的 LLM 閘道器或代理轉發時，就用這個變數。ANTHROPIC_API_KEY。以X-Api-Keyheader 傳送，用於拿 Claude Console 的 key 直接訪問 API。在互動模式下，你會被提示一次批准或拒絕這個 key，你的選擇會被記住；之後要改，用/config裡的自定義 API key 開關，它只在變數被設定時才出現。在非互動模式下，比如傳入了-p時，只要 key 存在就總會被使用。apiKeyHelper指令碼的輸出。用於動態或輪換憑證，例如從 vault 取來的短期令牌。CLAUDE_CODE_OAUTH_TOKEN。由claude setup-token生成的長效 OAuth 令牌，適用於無法使用瀏覽器登入的 CI 流水線和指令碼。這裡有個微妙之處：如果你在變數已設定的情況下執行/login，Claude Code 會把當前會話切到新的登入，但只要變數還在，每個新會話都會重新讀它——直到你把它從 shell profile 或設定檔案的env塊裡刪掉。- Anthropic 配置檔與聯邦憑證。由
antCLI 和 Workload Identity Federation 寫入的憑證。由ant auth login寫出的配置檔，只有你在ANTHROPIC_PROFILE中指定它時，才排在這一層；否則它排在/login之下。 - 來自
/login的訂閱 OAuth 憑證。Claude Pro、Max、Team 和 Enterprise 使用者的預設路徑。
編號清單之外還有兩點。第一，已登入的 Claude apps 閘道器會話屬於提供商選擇，而不是憑證：它排在雲提供商選擇之上，當它存在時，即便設定了雲提供商變數，CLI 也會用閘道器令牌認證，而 bearer token、API key、apiKeyHelper和配置檔都不會被使用。強制閘道器登入的受管設定行為類似：會話只使用閘道器登入，跳過其他憑證來源，並要求你用/login登入。第二，一個已批准的ANTHROPIC_API_KEY會壓過生效中的訂閱：文件指出，一旦你批准，Claude Code 就會使用那個 API key；當這個 key 屬於已被停用或已過期的組織時，就會產生認證失敗。執行unset ANTHROPIC_API_KEY會回退到訂閱。
三種衝突，先從 ANTHROPIC_AUTH_TOKEN 與 ANTHROPIC_API_KEY 說起
這份優先順序清單，把若干反覆出現的神秘現象變成一行答案。
衝突一：你登入了，但請求還是走 API key。這就是“Claude Code 登入不生效”的報告；而“Claude Code API key 不工作”是它的映象版本，發生在 key 早於訂閱的時候。兩者來自同一條規則：已批准的 API key 優先於/login會話，而/login不會替換一個已經在起作用的 API key。修法是機械的。執行/status看看哪個方式在生效；當登入和 API key 都配置了時，/status會標出那個未被使用的憑證。要回到訂閱，在當前 shell 裡 unset 這個變數，並從 shell profile 裡刪掉，然後重新啟動 Claude Code。錯誤參考覆蓋了同一個錯誤的計費形態：本想用訂閱，請求卻悄悄走了某個游離的 key。注意，這個變數也可能不在你的 profile 裡，而在設定檔案的env塊中。
衝突二：ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY同時被設定了。順序說了算：bearer token 排在 API key 之上，所以用的是面向閘道器的那份憑證，而apiKeyHelper的輸出只在其上方全部未設定時才起作用。如果你在遷移時把兩個都設了、又以為 key 會贏，這就解釋了結果，工具並沒有行為異常。
衝突三：你需要讓它在 CI 裡工作，而那裡沒有/login可用。Claude Code 在 CI 裡的 OAuth 令牌答案是CLAUDE_CODE_OAUTH_TOKEN，用claude setup-token生成；該命令會開啟與/login相同的瀏覽器授權流程，令牌列印到終端，不落盤，所以你需要自己把它複製進 CI 的金鑰儲存。在圍繞它做設計之前，有兩個邊界值得知道。該令牌以你的訂閱身份認證，且只能發起模型請求：它無法建立 Remote Control 會話，也無法拉取 claude.ai 的聯結器，不過你在本地配置的 MCP server 仍然可用。另外，如果你之後刪除了變數，記住每個新會話都會重新讀環境：只在當前 shell 裡“刪掉”的令牌，等於沒刪。相關的：在 bare 模式下，工具根本不讀CLAUDE_CODE_OAUTH_TOKEN，所以使用--bare的指令碼化執行，應當改用 API key 或apiKeyHelper來認證。圍繞這些選擇的無人值守流水線配置，見CI 指南。
如何判斷實際在用哪一份憑證
別猜，按清單機械地過一遍：
- 盤點環境。檢查相關變數都被設成了什麼，不只看 shell，也要看設定檔案裡的
env塊，那裡是過期憑證常見的藏身之處。 - 確認模式。互動式會話、非互動式
-p執行和 bare 模式執行讀取的來源並不相同；例如互動式批准提示和記住的選擇只存在於互動模式。 - 順著優先順序順序走。找到第一個適用於你環境的層級；那就是你的憑證，與你最近設定過什麼無關。
- 確認適用範圍。這些變數和 helper 作用於 CLI，以及包裹它的那些層面，包括 VS Code 擴充套件、Agent SDK 和 GitHub Actions。Claude Desktop 和雲端會話不讀它們：那些走 OAuth，唯一的例外是桌面會話執行第三方推理配置時（文件有記載）。雲端會話始終使用你的訂閱憑證，在雲端環境裡設定
ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN並不會覆蓋它們。
如果 HTTP 層面的症狀比機制更重要，錯誤碼指南映射了這些狀態碼；本文是 401 系列問題的根因伴侶篇。要把這些憑證指向某個相容服務，端點層面的背景在平臺的文件裡。如果你的目標是乾淨地更換或輪換憑證、而不是除錯它們，提供商切換指南載有那份清單。
速查表
| 憑證來源 | 適用範圍 |
| :- | :- |
| 雲提供商變數 / 閘道器會話 | CLI 及包裹它的層面；閘道器優先於雲提供商 |
| ANTHROPIC_AUTH_TOKEN | CLI、VS Code 擴充套件、Agent SDK、GitHub Actions；經閘道器時傳送 bearer token |
| ANTHROPIC_API_KEY | 同樣的層面；已批准的 key 優先於/login訂閱 |
| apiKeyHelper | 同樣的層面；只有其上全部未設定時才被讀取 |
| CLAUDE_CODE_OAUTH_TOKEN | CI 與指令碼；bare 模式下不讀 |
| 配置檔與聯邦 | CLI 登入；在 bare 模式、Claude Desktop 和雲端會話中不讀 |
| /login 訂閱 | 個人套餐的預設值；在雲端會話中無法覆蓋 |
兩個習慣能讓這張表保持有用。改動之前重新核對官方認證頁面，因為優先順序細節和覆蓋範圍恰恰是那種會被逐步細化的東西；以及用/status來確認結果，而不是想當然，因為它會點明當前生效的方式，並標出那個已配置但未被使用的來源。看得到憑證，又能用一份可引用的順序解釋它，比一臺塞滿 key 卻有一個在悄悄獲勝的機器，處境好得多。