当同一台机器上存在多份 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 却有一个在悄悄获胜的机器，处境好得多。