Claude Code 可以只用 API 密钥、不订阅吗？

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 中密钥的身份验证机制，请参阅Claude API 身份验证的工作方式。下面只介绍这两部分未涵盖的内容：会话实际选择了哪个凭据，以及如何更改凭据。

以下行为来自 Anthropic 的 Claude Code 身份验证文档，文档查阅日期为 10 October 2026。Claude Code 经常发布新版本，其中一些行为要求达到最低版本，因此请先运行 claude --version，再判断您的机器是否出现故障。

两个可以使用同一电子邮箱地址的账户

claude.ai 账户与 platform.claude.com 上的 Claude Console 账户是不同的账户。它们可以使用相同的电子邮箱地址，但仍属于独立的登录凭据，拥有各自的余额，并隶属于不同的组织。创建一个账户并不会自动创建另一个。为 Console 组织充值不会增加您订阅计划的额度。

上述情况有一个例外，截至 2026 年 10 月 10 日，该例外情况如下：Max 5x 和 Max 20x 计划现在包含每月 API 额度（分别为每月 100 美元和 200 美元），Team 计划则获得共享额度。这些额度仅在您从 claude.ai 的账单设置中关联 Console 组织后才会计入该组织，且这些额度不涵盖 Claude Code 的费用。Anthropic 的平台文档明确 Claude Code 不在涵盖范围内，其帮助中心仅排除了使用关联组织 API 密钥的 claude -p 运行，因此，如果交互式会话计费至仅持有此类额度的组织，则会因 Credit balance too low 而失败。

余额差异源于计费模式的不同。订阅登录使用计划的用量限额，该限额在滚动五小时窗口和每周窗口内重置，且该限额与网页版 Claude 共享。Console 凭据按组织内的 Token 用量计费，权威数据位于 Console 使用情况页面。这种差异在实际工作中的成本影响是 按 Token 付费与按订阅付费的对比 的主题。

有一种账户类型完全无法使用订阅路径。Anthropic 列出的可登录账户包括：Pro 或 Max 订阅、Claude for Teams 或 Enterprise 席位、Claude Console 账户、云服务商，以及云网关（即由贵组织运行并使用 /login 进行企业级 SSO 单点登录的自托管 Claude 应用网关）。免费的 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 会话中 Keychain 处于锁定状态），Claude Code 会回退到相同的 0600 文件。通过 Console 登录并创建 API key 不会使用此回退机制，必须等到 Keychain 可写后才能成功。
• 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 key，Developer 角色可以创建任意 key。随后，您在 /login 提示符处选择 Anthropic Console 账户。

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

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

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

您首次使用 Console 组织对 Claude Code 进行身份验证时，Console 会为其创建一个名为 "Claude Code" 的工作区。创建该工作区是为了集中跟踪 Claude Code 的支出，而且您无法在其中创建 API key。

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

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

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 配置文件和联合身份凭据，即 ant CLI 及 Workload Identity Federation 使用的凭据。
7. /login 写入的订阅凭据。

该列表前后存在两个例外。当您在 ANTHROPIC_PROFILE 中指定配置文件、设置联合身份变量，或当前配置文件属于 Workload Identity Federation 配置文件时，该配置文件的优先级为第 6 位。处于 user_oauth 模式的当前配置文件，也就是由 ant auth login 或无密钥 Console 登录写入的配置文件，其优先级低于可用的 /login 凭据。已登录的 Claude apps 网关会话完全不属于该列表，其优先级高于列表中的所有来源，包括云服务提供商变量。当管理员托管的设置要求通过网关登录时，Claude Code 会跳过其他来源，并要求您通过 /login 登录。

这两个例外都无法使订阅凭据优先于导出的密钥。在没有网关的情况下，第 1 位到第 5 位的所有来源都优先于您登录的账户。因此，只要进程环境中的任意位置导出了 ANTHROPIC_API_KEY，它就会被优先使用；此时会向 Console 组织计费，而您可能以为使用的是自己的订阅方案。这不是故障。程序只是按照文档规定的顺序执行，因此不会发出警告。

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

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

在服务器上查找残留密钥

导出的密钥可能存在于比 shell 配置文件更多的位置：

• ~/.bashrc、~/.bash_profile、~/.profile 或 ~/.zshrc，每个新的登录 shell 都会读取这些文件。
• systemd 单元通过 Environment= 或 EnvironmentFile= 设置的环境，用于任何作为服务运行的程序。
• 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 会使用该密钥。如果这 5 个位置都没有输出，则不存在环境凭据，因此从此处启动的会话会回退到您的 /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 数量和公开价格计算得出。如果管理员在托管设置中配置了 modelPricing 表，则会按组织的合同价格计算，此时 Total cost 行会说明这一点。无论哪种情况，都应将其视为面向 API 用户的估算值，而不是账单。订阅用户应关注用量条，而不是金额。

对于 Console 凭据，应以 Console 中的数据为准：在 usage 页面查看支出，在 Claude Code dashboard 查看每位成员的用量。在终端中显示的任何内容都不是该账单的权威数据。

如果用量条在工作期间始终不变，可能是环境凭据优先生效，/status 可以确认这一点。例外情况是用量条本来就已满：订阅会话可以在包含的用量额度用尽后继续使用 usage credits，Anthropic 会按标准 API 价格计费，而用量条在此期间保持不变。除此之外，用量条不变通常最明确地表明当前使用了错误的凭据；跟踪 Claude Code 会话的实际支出会进一步介绍如何测量这些支出。如果用量条先变化后停止，则说明已达到计划上限；Claude 用量限制和重置时间窗口的工作方式对此有详细说明。

故障模式及检查项

所有功能都正常，但计划用量始终不变。 通常是某个环境凭据正在生效：/status 会显示一个 API key 行，上面的 shell 检查会显示该变量。如果两者都没有显示，而用量条已达到上限，则当前会话已切换到按量计费额度，费用按标准 API 定价计算，可在 claude.ai 的 Settings，然后是 Usage 中查看。

订阅状态正常，但请求仍然失败。 某个属于已停用或已过期 Console 组织的密钥优先级高于您的登录凭据。运行 unset ANTHROPIC_API_KEY，启动新会话，然后再次检查 /status。如果错误提示无效 API 密钥，修复 Claude Code 的无效 API 密钥错误详细介绍了这种情况，包括为什么再次运行 /login 也无法清除该错误。

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

apiKeyHelper 运行缓慢或失败。 Claude Code 默认每五分钟重新运行一次该辅助程序，可通过 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 调整；如果一次运行超过十秒，提示栏中会显示通知。无论是发生错误还是超时，只要辅助程序未返回密钥，就会在三次尝试内导致请求失败。

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

FAQ

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

在会话中运行 /status。Status 选项卡会为已登录的账户显示 Login method 行；如果凭据由 API key 提供，还会显示 API key 行。如果改为使用 Anthropic profile 或 federation credential，Profile 行会替代登录行。在会话外，检查 shell 中是否设置了 ANTHROPIC_API_KEY，即可判断是否存在优先级高于登录凭据的环境凭据。

为什么 Claude Pro 或 Max 订阅没有生效？

因为环境凭据的优先级高于订阅凭据。Claude Code 按固定顺序使用它找到的第一个凭据，/login 订阅凭据的优先级低于云服务商变量、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY、apiKeyHelper、CLAUDE_CODE_OAUTH_TOKEN，以及通过 ANTHROPIC_PROFILE 或 federation 变量选择的 Anthropic profile 或 federation credential。只有处于 user_oauth 模式的活动 profile 优先级低于它，而已登录的 Claude apps gateway 会高于整个列表。运行 unset ANTHROPIC_API_KEY，启动新会话，然后通过 /status 确认。随后从设置该变量的 shell profile、systemd unit、tmux 环境或容器定义中删除该 export，否则它会在下一个 login shell 中重新出现。

我可以将 Claude Code 与免费的 Claude 账户配合使用吗？

不可以。Anthropic 列出的登录账户类型包括 Pro 或 Max 订阅、Claude for Teams 或 Enterprise seat、Claude Console 账户、云服务商，以及 Cloud gateway。Cloud gateway 是通过 /login 使用企业 SSO 登录的自托管 Claude apps gateway。免费的 claude.ai 账户不属于这些类型，因此 Claude Code 无法为其存储订阅凭据。订阅之外的付费方案是使用带有 API credit 的 Claude Console organization，并按 token 计费。即使两者使用相同的电子邮件地址，它们仍是不同的账户。

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

不共用。即使两者使用相同的电子邮件地址，它们仍是独立账户，计费也彼此分开。订阅用量会消耗套餐额度，该额度与 Web 版 Claude 共用，并按滚动 5 小时窗口和每周窗口重置。Console 用量按 token 向 organization 计费，并显示在 Console usage 页面中。向其中一个账户充值不会影响另一个账户。唯一可选的关联方向是从套餐关联到 Console：Max 或 Team 套餐可以将每月 API credits 发送到你从 claude.ai 关联的 Console organization，但这些 credits 不能用于 Claude Code。

如何在无头服务器上验证 Claude Code？

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