Claude Code 登录用订阅还是 API Key？

Claude Code 会话使用的是哪个凭据？

Claude Code 登录有两种方式。您可以使用 claude.ai 上的 Claude 订阅账户登录，也可以通过 Anthropic Console 组织进行身份验证。后者会将每个 token 的费用计入该组织的 API（应用程序编程接口）余额。请在运行中的会话内执行 /status，查看当前使用的是哪种方式：Status 选项卡会为您登录的账户显示 Login method 行；如果凭据由 API key 提供，还会额外显示 API key 行。

工具是否包含在您的套餐中是另一个问题，答案见Claude Code 是否包含在 Claude Pro 订阅中；Claude API 的 key 身份验证机制见Claude API 身份验证如何工作。下面只介绍前两者未涵盖的内容：会话实际选择了哪个凭据，以及如何更改该凭据。

以下行为来自 Anthropic 的 Claude Code 身份验证文档，文档查阅日期为 31 August 2026。Claude Code 经常发布新版本，其中一些行为要求达到最低版本，因此在认定计算机出现故障前，请先运行 claude --version。

可共用同一邮箱地址的两个账户

claude.ai 账户和 platform.claude.com 上的 Claude Console 账户是不同的账户。它们可以使用同一个邮箱地址，但仍是彼此独立的登录账户，余额也分别属于不同组织。创建其中一个账户不会自动创建另一个账户。购买 Max 计划不会为 Console 组织增加额度，而为 Console 组织充值也不会增加您的计划额度。

余额不同，是因为两者采用不同的计费模式。订阅账户的登录凭据使用计划内的用量额度，该额度按滚动的 5 小时窗口和每周窗口重置，并且与 Claude 网页版共用。Console 凭据则按 token 向组织计费，权威数据以 Console usage 页面为准。实际工作中两种方式的成本差异，请参阅按 token 付费与订阅付费的比较。

其中一种账户类型完全无法使用订阅登录方式。Anthropic 列出的可登录账户包括 Pro 或 Max 订阅、Claude for Teams 或 Enterprise 席位、Claude Console 账户以及云服务提供商账户。免费 claude.ai 账户不在此列，因此免费计划用户没有可用于登录的订阅凭据；免费 Claude 层级包含和不包含的内容也不适用于命令行工具。剩余的方式是使用具有 API 额度的 Console 组织，但这属于另一种形式的付费账户。

路径一：使用 Claude 订阅登录

在项目目录中运行 claude。首次启动时，它会打开浏览器窗口，让您使用绑定了订阅方案的 claude.ai 账户登录。

claude

在服务器上，有两种情况的处理方式不同。如果浏览器没有打开，请按 c 将登录 URL 复制到剪贴板，然后在您自己的计算机上将其粘贴到浏览器中。如果该浏览器随后显示登录代码，而不是将您返回终端，请在提示输入代码时将其粘贴回终端。在 SSH（安全 Shell）、WSL2 和容器环境中，这种情况是正常的，因为浏览器无法访问 Claude Code 在远程计算机上启动的本地回调服务器。

登录完成后，请检查登录状态，不要直接假定登录已成功。启动会话并运行 /status。Status 选项卡会显示登录方式，以及它保存的组织和电子邮件地址。/login 会使用另一个账户重新执行登录流程，/logout 会删除已保存的凭据。退出登录也会重置首次运行设置状态，因此下次运行 claude 时，系统会再次引导您完成初始化。

在重建服务器或移交服务器时，了解凭据的保存位置很重要：

• Linux：~/.claude/.credentials.json，文件权限为 0600。
• macOS：加密的 Keychain。当 Keychain 拒绝写入时（例如在 SSH 会话中处于锁定状态），Claude Code 会回退到同一个 0600 文件。
• Windows：%USERPROFILE%\.claude\.credentials.json，由配置文件目录自身的访问控制限制为当前用户。
• 设置了 CLAUDE_CONFIG_DIR 的任何平台：文件会移动到该目录下，macOS Keychain 条目也会以此目录为关联对象，因此使用不同 CLAUDE_CONFIG_DIR 启动的会话会读取不同的凭据。

Claude Code 通过 /login 和 /logout 管理该文件。手动编辑该文件不是受支持的切换账户方式。

路径二：针对 Console 组织进行身份验证

Console 访问需要由管理员发起。管理员会在 Console 中依次进入 Settings、Members 和 Invite，然后邀请您加入。他们还会分配角色：Claude Code 角色只能创建 Claude Code API 密钥，而 Developer 角色可以创建任意密钥。随后，您在 /login 提示符处选择 Anthropic Console 账户。

从 Claude Code v2.1.242 开始，Console 提供两种登录路径，二者存储的内容不同。使用 Console 账户登录时，Claude Code 会保留该浏览器登录产生的 OAuth（开放授权）令牌，并将其存储为 Anthropic 配置文件，完全不会创建 API 密钥。Claude Code 会自动刷新该登录状态；刷新失败后，请求会失败，直到您再次登录。创建 API 密钥时，提示符会将其标记为 legacy。此操作会生成 Console 密钥，并将其与其他凭据一起存储。静态密钥不会自动刷新，因此在被撤销前会持续有效。这对构建服务器很有用，但在笔记本电脑上存在安全风险。

开始无密钥 Console 登录前，请取消设置 ANTHROPIC_API_KEY。如果设置了此变量，Claude Code 会完全跳过登录提示，而是要求您批准它找到的密钥。

您不一定总能选择登录方式。在以下情况下，Claude Code 会直接创建密钥而不询问：会话使用云提供商运行；任何设置文件设置了 forceLoginOrgUUID，或将 forceLoginMethod 固定为 "claudeai" 或 "console"；或者计算机上存在托管设置源，但 Claude Code 无法读取该源。这些属于管理员决策。如果您始终看不到无密钥选项，请联系负责管理设备的人员。/status 还会输出一行 Setting sources，列出会话加载的所有设置文件；如果有适用于您的托管源，它也会显示该源。

您首次针对 Console 组织验证 Claude Code 身份时，Console 会为其创建一个名为 "Claude Code" 的工作区。该工作区用于集中跟踪 Claude Code 的支出，您无法在其中创建 API 密钥。

登录后为何 ANTHROPIC_API_KEY 具有更高优先级

Claude Code 不会询问您希望使用哪种凭据。它会按固定顺序检查各个来源，并使用找到的第一个凭据。根据 2026 年 8 月的文档，该顺序如下：

1. 云服务提供商凭据，在设置了 CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX 或 CLAUDE_CODE_USE_FOUNDRY 时使用。
2. ANTHROPIC_AUTH_TOKEN，作为 Authorization: Bearer 请求头发送，用于使用 bearer token 进行身份验证的网关。
3. ANTHROPIC_API_KEY，作为 X-Api-Key 请求头发送。
4. 设置文件中指定的 apiKeyHelper 脚本的输出。
5. CLAUDE_CODE_OAUTH_TOKEN，来自 claude setup-token 的长期令牌。
6. Anthropic 配置文件和联合身份验证凭据。
7. 由 /login 写入的订阅凭据。

您的订阅登录凭据位于最后。因此，只要进程环境中的任意位置导出了 ANTHROPIC_API_KEY，它的优先级就高于您登录的账户。此时，会话会向 Console 组织计费，而您以为它使用的是自己的订阅计划。这不是故障。该顺序完全按照文档中的定义执行，因此不会显示警告。

有两个细节很容易导致这个问题被忽略。在交互式会话中，Claude Code 会询问一次是否使用找到的密钥，并记住您的选择。因此，您一个月前做出的选择今天仍然有效。在使用 -p 的非交互模式下，完全不会显示提示；只要密钥存在，就始终会使用它。-p 就是 cron 作业或 CI（持续集成）步骤运行时使用的模式，因此无人值守的作业正是最容易长时间使用错误凭据而不被发现的场景。

您可以在会话中快速进行可视化检查。在设置 ANTHROPIC_API_KEY 时，/config 会显示“使用自定义 API 密钥”切换开关。该开关仅在变量已设置时存在，因此看不到该开关就表示环境干净。

服务器上的残留密钥

导出的密钥可能存在于多个位置，而不只是 shell 配置文件中：

• ~/.bashrc、~/.bash_profile、~/.profile 或 ~/.zshrc。每个新登录 shell 都会读取这些文件。
• systemd 单元通过 Environment= 或 EnvironmentFile= 设置的环境变量。任何作为服务运行的进程都可能受到影响。
• tmux 服务器会保留其启动时的环境副本。您今天打开的窗格可能继承一个上周从配置文件中删除的变量，因为 tmux 服务器在修改配置前就已运行。
• 容器镜像或 CI 作业定义。变量可能在 shell 内无法读取的文件之外设置。
• Claude Code 设置文件中的 env 部分。它是普通的设置项，并遵循正常的设置优先级。

在进行其他排查前，先检查这些位置：

[ -n "$ANTHROPIC_API_KEY" ] && echo "ANTHROPIC_API_KEY is set" || echo "not set"
env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_)' | cut -d= -f1
grep -n 'ANTHROPIC_API_KEY' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc 2>/dev/null
tmux show-environment 2>/dev/null | grep ANTHROPIC
grep -n 'ANTHROPIC_API_KEY\|apiKeyHelper' ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

第二条命令会按设计通过 cut，因此只输出变量名，不会把密钥值显示在可能被共享或录制的屏幕上。第一条命令用于确定问题：如果它显示变量已设置，那么您从此 shell 启动的下一个 claude 会使用该密钥。如果这五处都没有输出，则不存在环境凭据，因此从此处启动的会话会回退到您的 /login 凭据。

对于运行 Claude Code 的服务，请添加 systemctl cat your-unit.service | grep -i environment，因为单元文件会设置自己的环境变量，并且不会读取 shell 配置文件。

将会话从一个凭据切换到另一个凭据

要切回您的订阅：

unset ANTHROPIC_API_KEY
[ -n "$ANTHROPIC_API_KEY" ] && echo "still set" || echo "clear"
claude

等待 clear，然后在新会话中运行 /status，并确认 API key 行已消失。在 shell 中取消设置该变量不会影响已经运行的 Claude Code 进程，因为进程会保留启动时获得的环境。请重启会话。

然后从设置该变量的文件中删除 export，否则下一个登录 shell 会再次设置它。在 tmux 中，tmux set-environment -u ANTHROPIC_API_KEY 会清除该变量，使会话中此后打开的窗格不再继承它；已经打开的窗格仍保留各自的副本。

要反向切换，请在环境中设置 ANTHROPIC_API_KEY，或者运行 /login 并选择 Console 账户。要完全清除已存储的登录信息，请运行 /logout。使用无密钥方式登录 Console 后，/logout 会删除并撤销该登录写入的凭据。

如果 /status 仍与预期不符，请运行 claude doctor。该命令会列出 Claude Code 拒绝的设置项，从而发现未能解析的设置文件；此类文件根本不会生效。

无浏览器时进行身份验证

claude setup-token 会打开与 /login 相同的浏览器授权流程，并将有效期一年的 OAuth 令牌输出到终端。

claude setup-token

它不会将令牌保存到任何位置，因此令牌出现后请立即复制。将令牌设置为需要使用它的计算机上的 CLAUDE_CODE_OAUTH_TOKEN。该令牌使用您的订阅进行身份验证，因此订阅必须是 Pro、Max、Team 或 Enterprise 计划，并且令牌只能用于模型请求。Bare 模式不会读取该令牌，因此传递 --bare 的脚本需要 ANTHROPIC_API_KEY 或 apiKeyHelper。

这里同样需要注意优先级。如果 CLAUDE_CODE_OAUTH_TOKEN 位于 shell 配置文件中，运行 /login 会将当前会话切换到新的登录状态；在您移除该变量之前，每个新会话都会再次读取它。

如果您的组织通过 Amazon Bedrock、Google Cloud 或 Microsoft Foundry 运行推理，这些凭据位于优先级最高的位置，整个过程不会进行浏览器登录。相关配置是另一项工作，详见让 Claude Code 通过 Bedrock 或 Vertex 运行。

VPS（虚拟专用服务器）上的长期会话最容易出现这些问题，因为启动会话的 shell 可能在数月前就已配置，此后从未重启。在 tmux 中的 VPS 上运行 Claude Code介绍了这类配置的会话管理。

检查每个凭据实际消耗的资源

在订阅登录中，/usage会显示套餐用量条，以及各项用量的消耗明细。其中 Session 区块的美元金额，是根据 token 数量和公开单价在本地计算得出的估算值，主要面向 API 用户，不能视为账单。订阅用户应查看用量条，而不是美元金额。

对于 Console 凭据，重要数据位于 Console 中：使用量页面用于查看支出，Claude Code dashboard 用于查看每位成员的数据。终端中打印的任何内容都不是该账单的权威数据。

如果您工作时套餐用量条始终不动，说明环境凭据的优先级更高。这个现象是当前使用了错误凭据的最可靠信号；跟踪 Claude Code 会话的消耗会进一步介绍如何测量。如果用量条先移动后停止，说明您已达到套餐上限；Claude 用量限制和重置窗口的工作方式对此有详细说明。

故障模式与排查重点

所有功能正常，但计划用量始终不变。 当前正在使用环境凭据。/status 显示一行 API key，上面的 shell 检查也显示了该变量。

订阅状态正常，但请求失败。 属于已停用或已过期 Console 组织的密钥优先级高于您的登录凭据。运行 unset ANTHROPIC_API_KEY，启动新会话，然后再次检查 /status。

启动时警告登录凭据即将过期。 近期版本会在 /login 凭据将在 3 天内过期时发出警告，随后 /status 会将登录行显示为已过期状态，并显示其中保存的组织和电子邮件地址。运行 /login 进行续期。该警告不会阻止请求，因此很容易被忽略，直到无人值守的会话无法继续处理请求。

apiKeyHelper 运行缓慢或失败。 Claude Code 默认每 5 分钟重新运行一次该辅助程序，可通过 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 调整。单次运行超过 10 秒时，提示栏会显示通知。无论辅助程序因出错还是超时未返回密钥，连续 3 次尝试内的请求都会失败。

凭据正确，但组织不正确。 一个电子邮件地址可能属于两个组织。/status 会显示完成身份验证的组织，因此应读取该行，不要假定当前会话进入了哪个组织。

FAQ

如何判断 Claude Code 当前使用的是哪个账户？

在会话中运行 /status。Status 标签页会为您登录的账户显示一个 Login method 行；如果由 API key 提供凭据，还会添加一个 API key 行。如果选择了 Anthropic 配置文件或 federation 凭据，则会用 Profile 行替换登录行。在会话外，检查 shell 中是否设置了 ANTHROPIC_API_KEY，即可判断是否存在优先级高于登录凭据的环境凭据。

为什么我的 Claude Pro 或 Max 订阅被忽略了？

因为环境凭据的优先级更高。Claude Code 按固定顺序使用找到的第一个凭据，而 /login 订阅凭据的优先级最低，排在云提供商变量、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY、apiKeyHelper 和 CLAUDE_CODE_OAUTH_TOKEN 之后。运行 unset ANTHROPIC_API_KEY，启动新会话，然后使用 /status 确认。接着从设置该变量的 shell 配置文件、systemd unit、tmux 环境或容器定义中删除该 export，否则它会在下一个登录 shell 中再次出现。

可以使用免费 Claude 账户运行 Claude Code 吗？

不可以。Anthropic 列出的可用于登录的账户类型包括 Pro 或 Max 订阅、Claude for Teams 或 Enterprise seat、Claude Console 账户，以及云提供商。免费的 claude.ai 账户不属于这些类型，因此没有可供其存储的订阅凭据。订阅之外的付费替代方案是使用带有 API credit 的 Claude Console 组织，按 token 计费；即使使用相同的 email address，这也是独立的账户。

我的 claude.ai 账户和 Console 账户共用一个余额吗？

不共用。即使两者使用相同的 email address，它们仍是具有独立计费的独立账户。订阅用量消耗计划额度，该额度与 Web 版 Claude 共用，并按滚动的 five hour window 和 weekly window 重置。Console 用量按 token 向组织计费，并显示在 Console usage 页面中。向其中一个账户充值不会影响另一个账户。

如何在无头服务器上为 Claude Code 进行身份验证？

有两种方式。通过 SSH 运行 claude，然后在您自己的机器上完成浏览器登录：按 c 复制 URL，在浏览器中登录；如果浏览器显示代码而不是自动重定向，再将代码粘贴回终端。或者在有浏览器的机器上运行 claude setup-token，复制它输出的 one-year token，然后在服务器上将其设置为 CLAUDE_CODE_OAUTH_TOKEN。该 token 需要 Pro、Max、Team 或 Enterprise plan，并且只能发起模型请求，因此使用 --bare 的脚本需要 API key 或 apiKeyHelper。