登录与认证

安装完成后，第一件事不是急着跑任务，而是确认 Claude Code 到底用哪一种身份在工作。订阅账号、API Key、企业云凭据同时存在时，真正生效的可能不是你以为的那一个。——翔宇

这一章用 12 分钟换什么：上一章把 Claude Code 装到了本机。这一章讲登录和认证：个人订阅怎么登录，团队和 Console 怎么开通，Bedrock / Vertex AI / Foundry 怎么接入，多个凭据同时存在时谁优先。

1. 先分清“登录”和“认证”

新手常把两件事混在一起：

登录：浏览器里授权 Claude Code 使用你的 Claude.ai 订阅。
认证：Claude Code 每次请求模型时，用哪一种凭据证明“我是谁、账单走哪里”。

大多数个人用户只有第一种：

claude
浏览器登录 Claude.ai
回到终端开始用

团队和企业用户可能同时有多种：

Claude.ai 订阅 OAuth
Claude Console API key（API 密钥）
Amazon Bedrock credentials（凭据）
Google Vertex AI credentials（凭据）
Microsoft Foundry credentials（凭据）
LLM gateway bearer token（网关令牌）
apiKeyHelper 动态脚本

第一性原理：认证不是“能不能打开 Claude Code”，而是“这次请求使用哪套身份、权限、账单和组织策略”。

2. 第一次登录怎么走

浏览器登录 Claude.ai

用 Claude.ai 账号登录后，浏览器通常会自动跳回终端，终端继续进入 Claude Code 会话。

如果浏览器没有自动打开，按 c 复制登录 URL，再粘贴到浏览器里登录。

如果浏览器显示 login code（登录码），而不是自动跳回终端，把 code 粘贴回终端的提示位置。

这常见于几种场景：

WSL2：浏览器和 Linux 环境之间 callback（回调）不通。
SSH：远程终端没有本地浏览器回调。
容器：容器里的本地 callback server（回调服务）浏览器访问不到。
远程开发机：浏览器在本机，Claude Code 在远端。

验证或重新登录

确认当前认证状态：

/status

退出并重新登录：

/logout

新手判断法：浏览器没跳回终端不一定是登录失败。只要页面给了 code（登录码），就复制回终端继续。

3. 哪类账号可以用 Claude Code

官方 Authentication 文档列了几类入口。

账号 / 接入方式	适合谁	怎么认证
Claude Pro / Max	个人开发者	Claude.ai 浏览器登录
Claude for Teams	小团队	管理员邀请后用 Claude.ai 登录
Claude for Enterprise	大组织 / 合规要求	SSO、域名捕获、RBAC、managed settings
Claude Console	API 计费和开发平台用户	Console 凭据和角色
Amazon Bedrock	AWS 企业环境	AWS 凭据 + 环境变量
Google Vertex AI	GCP 企业环境	GCP ADC + 环境变量
Microsoft Foundry	Azure 企业环境	API key 或 Entra ID + 环境变量

注意一个硬边界：Claude.ai 免费计划不包含 Claude Code 访问权限。

如果你是个人用户，优先用 Pro / Max 订阅登录。不要一开始就去折腾 API Key，除非你明确要按 API 计费或接网关。

选择认证入口时按这张表判断：

你的情况	优先选什么
个人学习或个人开发	Claude.ai OAuth，使用 Pro / Max
团队统一订阅和成员管理	Claude for Teams / Enterprise
按 API 计费或由开发平台分配 key	Claude Console
公司要求走 AWS / GCP / Azure	Bedrock / Vertex AI / Foundry

4. Team、Enterprise 和 Console 的区别

这三类看起来都像“团队用”，但管理方式不同：

Claude for Teams：订阅式团队管理，适合小团队协作和统一账单。
Claude for Enterprise：企业级管理，适合 SSO、域名、合规、组织策略。
Claude Console：API 平台管理，适合按 API / 开发平台方式分配访问。

Console 场景里，管理员需要先邀请用户，并分配角色：

Claude Code role：只能创建 Claude Code API keys。
Developer role：可以创建更多类型的 API key。

不要混用概念：Claude.ai 订阅登录和 Claude Console API key（API 密钥）是两条账单和权限路径。你有订阅，不代表环境里的 API key 就该保留。

5. 云供应商接入：不是浏览器登录

如果组织走 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry，认证就不靠 /login。

云供应商接入的共同点：

先按供应商开通 Claude 模型访问。
本机或 CI 环境先完成云 CLI / 默认凭据配置。
再设置 Claude Code 环境变量启用对应 provider（供应商）。
使用 provider 时，/login 和 /logout 通常会禁用，因为认证由云凭据处理。

Bedrock 最小配置：

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

Vertex AI 最小配置：

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

Microsoft Foundry 最小配置：

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource

Foundry 还可以用 API key：

export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

如果没设置 ANTHROPIC_FOUNDRY_API_KEY，Claude Code 会走 Azure SDK default credential chain（默认凭据链），常见本地方式是先：

az login

云接入不是新手默认路径：除非公司明确要求走 AWS / GCP / Azure，否则个人学习不要从云供应商认证开始。先用 Claude.ai 订阅登录，把基础工作流跑通。

6. 凭据存在哪里

Claude Code 会安全管理认证凭据：

macOS：加密的 macOS Keychain。
Linux：~/.claude/.credentials.json，权限 0600。
Windows：~/.claude/.credentials.json，继承用户 profile ACL。
自定义配置目录：$CLAUDE_CONFIG_DIR 下对应位置。

还有一个容易混淆的文件：~/.claude.json。官方 settings 文档说明，它会保存 OAuth session、MCP 配置、项目状态、allowed tools、trust settings 和各种缓存。

安全边界：不要把 .credentials.json、~/.claude.json、API key、OAuth token 提交进仓库。团队共享配置要写 project settings，不要共享个人凭据。

7. 多个凭据同时存在时，谁优先

这是认证章最重要的一节。

当多个凭据同时存在，Claude Code 按官方顺序选择：

云供应商凭据：CLAUDE_CODE_USE_BEDROCK / VERTEX / FOUNDRY。
ANTHROPIC_AUTH_TOKEN：LLM gateway / proxy 的 bearer token。
ANTHROPIC_API_KEY：Claude Console API key（API 密钥）。
apiKeyHelper：从 vault（密钥库）动态取短期 key。
CLAUDE_CODE_OAUTH_TOKEN：claude setup-token 生成的长期 token。
/login 订阅 OAuth：Pro / Max / Team / Enterprise 默认登录。

这解释了一个常见坑：

你明明有 Claude Max 订阅，但 shell 里还残留了一个失效的 API key。

export ANTHROPIC_API_KEY=old-disabled-key

一旦你批准使用这个 API key，它会优先于订阅 OAuth；这个批准会被 Claude Code 记住，下次启动仍然走 API key。要改回订阅，在 /config 里关掉 "Use custom API key" toggle，或先 unset 环境变量再启动。在 -p 非交互模式里，只要环境变量存在就会直接使用，不会问你。结果就是：你以为走订阅，实际上走了一个坏掉的 Console key。

回到订阅登录：

unset ANTHROPIC_API_KEY
unset ANTHROPIC_AUTH_TOKEN

再看：

/status

排障口诀：认证不对，先看 /status；订阅用户异常，先查 shell 里有没有 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN。

8. `apiKeyHelper` 适合什么

apiKeyHelper 是 settings（设置文件）里的一个配置：Claude Code 调用脚本，脚本返回 API key。

它适合：

公司用 vault（密钥库）管短期凭据。
API key 会定期轮换。
不希望把 key 放进环境变量。

它不适合：

新手个人登录。
把复杂 shell 脚本当万能认证入口。
每次调用都很慢的脚本。

官方说明里，apiKeyHelper 默认在 5 分钟后或 HTTP 401 时重新调用；需要自定义刷新间隔时，可以设置 CLAUDE_CODE_API_KEY_HELPER_TTL_MS。脚本超过 10 秒才返回时，Claude Code 会在提示栏显示 slow helper notice（慢 helper 提醒）。

不要把慢脚本塞进认证链：认证发生在请求路径上。helper 慢，会让每次模型请求都变慢或不稳定。

9. 长期 token：CI 和无浏览器环境

CI、脚本或无浏览器环境，可以生成一年期 OAuth token：

claude setup-token

命令会引导你完成 OAuth 授权，并把 token 打印到终端。它不会自动保存。你需要自己设置：

export CLAUDE_CODE_OAUTH_TOKEN=your-token

注意边界：

需要 Pro、Max、Team 或 Enterprise 计划。
作用域限于 inference（模型推理）。
不能建立 Remote Control session。
bare mode（裸模式）不读取 CLAUDE_CODE_OAUTH_TOKEN。
如果脚本使用 --bare，应改用 ANTHROPIC_API_KEY 或 apiKeyHelper。

长期 token 不是普通配置：它虽然方便，但仍然是凭据。放 CI secret，不要写进仓库、日志或示例文档。

10. Desktop、Web、Remote 和 CLI 不完全一样

认证还有一个容易误解的点：环境变量主要影响终端 CLI session。

官方认证文档明确说：

apiKeyHelper
ANTHROPIC_API_KEY
ANTHROPIC_AUTH_TOKEN

这些只作用于 terminal CLI sessions（终端 CLI 会话）。

Claude Desktop 和 remote sessions 使用 OAuth，不调用 apiKeyHelper，也不读取 API key 环境变量。

这意味着：

终端 claude：受环境变量和 CLI 凭据优先级影响。
Claude Code on the Web（网页版）：始终使用订阅凭据；即使 sandbox 环境里有 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN，也不会覆盖订阅。
Desktop / remote session：使用 OAuth。
云供应商模式：走对应云 provider 凭据。

不要拿 CLI 的环境变量解释所有入口：Web、Desktop、remote 和 CLI 的认证路径不同。排障时先确认你正在用哪个入口。

11. 常见登录问题

浏览器不自动打开：按 c 复制 URL。
浏览器给 login code：把 code 粘贴回终端。
OAuth error / invalid code：重新 /logout，再登录。
403 Forbidden：检查账号是否有 Claude Code 权限、地区是否支持。
有订阅但提示 API key 问题：检查 ANTHROPIC_API_KEY 是否残留。
Bedrock 找不到 credentials：确认当前 shell 的 AWS 凭据是否有效。
Vertex 找不到默认凭据：确认 ADC、项目 ID、CLOUD_ML_REGION 是否设置。
Foundry token chain 失败：先 az login 或设置 ANTHROPIC_FOUNDRY_API_KEY。

排障顺序也可以压成四步：

顺序	先看什么	常见处理
1	`/status`	确认当前到底走 OAuth、API key 还是云供应商
2	环境变量	有残留 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 就先 unset
3	订阅 OAuth	失效就 `/logout` 后重新登录
4	云供应商凭据	Bedrock / Vertex / Foundry 分别检查 AWS、GCP、Azure 凭据

12. 本章自检

试着用自己的话回答：

登录和认证有什么区别？对应 §1。
为什么 WSL、SSH、容器里经常要手动复制 login code？对应 §2。
Claude for Teams、Enterprise、Console 的区别是什么？对应 §4。
为什么有订阅时，残留的 ANTHROPIC_API_KEY 仍然可能导致认证失败？对应 §7。
CLAUDE_CODE_OAUTH_TOKEN 适合什么场景，为什么不能写进仓库？对应 §9。

过关标准：你能打开 /status，判断当前 Claude Code 正在使用哪种认证方式，并知道要回到订阅 OAuth 时该 unset 哪些环境变量。

本篇术语速查表

OAuth：授权登录，Claude.ai 订阅登录时使用的授权机制。
Claude.ai subscription：Claude 订阅，Pro、Max、Team、Enterprise 等订阅入口。
Claude Console：Claude 开发平台，API key、成员、角色和开发平台账单管理入口。
ANTHROPIC_API_KEY：Anthropic API Key，Console API key，作为 X-Api-Key header 发送。
ANTHROPIC_AUTH_TOKEN：Bearer token，常用于 LLM gateway / proxy 的 Authorization header。
apiKeyHelper：动态取 key 脚本，从 vault 或脚本动态返回 API key 的设置。
CLAUDE_CODE_OAUTH_TOKEN：长期 OAuth token，claude setup-token 生成的一年期 token。
Bedrock：Amazon Bedrock，AWS 上的 Claude 模型接入方式。
Vertex AI：Google Vertex AI，GCP 上的 Claude 模型接入方式。
Microsoft Foundry：Microsoft Foundry，Azure / Foundry 上的 Claude 模型接入方式。
ADC：Application Default Credentials，Google Cloud 默认凭据链。
Entra ID：Microsoft Entra ID，Azure 的身份认证体系。

登录与认证

1. 先分清“登录”和“认证”

2. 第一次登录怎么走

启动 Claude Code

浏览器登录 Claude.ai

验证或重新登录

3. 哪类账号可以用 Claude Code

4. Team、Enterprise 和 Console 的区别

5. 云供应商接入：不是浏览器登录

6. 凭据存在哪里

7. 多个凭据同时存在时，谁优先

8. `apiKeyHelper` 适合什么

9. 长期 token：CI 和无浏览器环境

10. Desktop、Web、Remote 和 CLI 不完全一样

11. 常见登录问题

12. 本章自检

官方来源

接下来去哪

选择平台与集成

安装和更新 Claude Code（上一篇）

配置 Claude Code

本页目录