本页目录12
- 认证优先级从高到低：云服务商环境变量 → `ANTHROPIC_AUTH_TOKEN` → `ANTHROPIC_API_KEY` → `apiKeyHelper` 脚本 → `CLAUDE_CODE_OAUTH_TOKEN` → 订阅 OAuth
- 凭据存储因平台而异：macOS 用 Keychain；Linux 存 `~/.claude/.credentials.json`（权限 `0600`）；Windows 存 `%USERPROFILE%\.claude\.credentials.json`
- `apiKeyHelper` 默认在 5 分钟后或收到 HTTP 401 时刷新；超过 10 秒未返回则显示警告；可用 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 自定义间隔
- CI/脚本环境可用 `claude setup-token` 生成有效期 1 年的 `CLAUDE_CODE_OAUTH_TOKEN`，需 Pro/Max/Team/Enterprise 订阅，Bare 模式（`--bare`）不读取此变量
- `apiKeyHelper`、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 仅对终端 CLI 生效，Claude Desktop 和 Web 端仅用 OAuth，不调用上述方式
- 同时拥有订阅且设置了 `ANTHROPIC_API_KEY` 时 API Key 优先；若 Key 所属组织已禁用则认证失败，运行 `unset ANTHROPIC_API_KEY` 可回退；`/status` 确认当前生效方式
本文是对官方参考页 Authentication 的中文整理，完整与最新内容以原文为准：https://code.claude.com/docs/en/authentication
登录 Claude Code
安装完成后在终端运行 claude，首次启动自动打开浏览器进行登录。若浏览器未自动打开，按 c 复制登录链接后手动粘贴到浏览器。
在 WSL2、SSH 会话、容器等环境中浏览器可能无法回调本地服务器，此时浏览器显示登录码，将其粘贴到终端 Paste code here if prompted 处即可。
退出并重新认证：在 Claude Code 提示符输入 /logout。登录问题参见 authentication troubleshooting 文档。
支持的账户类型
| 账户类型 | 适用场景 | 认证方式 |
|---|---|---|
| Claude Pro / Max 订阅 | 个人用户 | 用 Claude.ai 账户登录 |
| Claude for Teams | 团队成员 | 用管理员邀请的 Claude.ai 账户登录 |
| Claude for Enterprise | 有安全合规要求的大型组织 | 用管理员邀请的 Claude.ai 账户登录 |
| Claude Console | 偏好 API 计费的组织 | 用 Console 凭据登录 |
| Amazon Bedrock | 使用 Bedrock 的组织 | 设置环境变量，无需浏览器登录 |
| Google Vertex AI | 使用 Vertex AI 的组织 | 设置环境变量，无需浏览器登录 |
| Microsoft Foundry | 使用 Foundry 的组织 | 设置环境变量，无需浏览器登录 |
团队认证方式
Claude for Teams / Enterprise
| 方案 | 特性 | 适用对象 |
|---|---|---|
| Claude for Teams | 协作功能、管理工具、集中账单；自助订阅 | 小型团队 |
| Claude for Enterprise | 在 Teams 基础上增加 SSO、域名捕获、基于角色的权限、合规 API、托管策略配置 | 有安全合规要求的大型组织 |
设置步骤：
- 订阅 Claude for Teams 或联系销售购买 Claude for Enterprise
- 在管理后台邀请团队成员
- 成员安装 Claude Code 并用 Claude.ai 账户登录
Claude Console 认证
适合偏好 API 计费的组织。可通过 Settings → Members → Invite 批量邀请用户，或配置 SSO。
用户角色说明：
| 角色名称 | 权限 |
|---|---|
Claude Code | 仅可创建 Claude Code API 密钥 |
Developer | 可创建任意类型 API 密钥 |
用户完成步骤： 接受 Console 邀请 → 检查系统要求 → 安装 Claude Code → 用 Console 账户凭据登录。
云服务商认证
适用于使用 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 的团队。按各自文档设置好环境变量后，用户安装 Claude Code 直接运行 claude，无需浏览器登录。
凭据管理
凭据存储位置
| 操作系统 | 存储路径 | 说明 |
|---|---|---|
| macOS | macOS Keychain（加密） | 系统级安全存储 |
| Linux | ~/.claude/.credentials.json | 文件权限 0600；若设置了 CLAUDE_CONFIG_DIR，则存于该目录下 |
| Windows | %USERPROFILE%\.claude\.credentials.json | 继承用户目录访问控制，默认限当前用户；若设置了 CLAUDE_CONFIG_DIR，则存于该目录下 |
claude 通过 /login 和 /logout 管理 .credentials.json。若需路由到自定义 API 端点，设置 ANTHROPIC_BASE_URL 环境变量。
支持的认证类型： Claude.ai 凭据、Claude API 凭据、Azure Auth、Bedrock Auth、Vertex Auth。
关键环境变量
| 环境变量 | 作用 | 默认值 / 备注 |
|---|---|---|
ANTHROPIC_API_KEY | Anthropic API 密钥，作为 X-Api-Key 头发送 | 交互模式需一次性审批，记住选择；非交互模式（-p）直接使用 |
ANTHROPIC_AUTH_TOKEN | Bearer Token，作为 Authorization: Bearer 头发送 | 适用于 LLM 网关/代理 |
ANTHROPIC_BASE_URL | 自定义 API 端点 URL | 用于代理路由 |
CLAUDE_CODE_OAUTH_TOKEN | 长效 OAuth Token（由 claude setup-token 生成） | 有效期 1 年；适用于 CI/脚本 |
CLAUDE_CODE_USE_BEDROCK | 启用 Amazon Bedrock 认证 | 设置后优先级最高 |
CLAUDE_CODE_USE_VERTEX | 启用 Google Vertex AI 认证 | 设置后优先级最高 |
CLAUDE_CODE_USE_FOUNDRY | 启用 Microsoft Foundry 认证 | 设置后优先级最高 |
CLAUDE_CONFIG_DIR | 覆盖 Claude Code 配置目录路径 | 影响 .credentials.json 存储位置（Linux / Windows） |
CLAUDE_CODE_API_KEY_HELPER_TTL_MS | apiKeyHelper 自定义刷新间隔（毫秒） | 默认：5 分钟后或收到 HTTP 401 时刷新 |
apiKeyHelper 配置项
apiKeyHelper 是 settings.json 中的配置项，值为一个 Shell 脚本路径，脚本的标准输出被作为 API Key 使用，适用于动态凭据或轮转 Token（如从保险库获取短期令牌）。
| 属性 | 说明 | 默认值 |
|---|---|---|
| 刷新触发条件 | 经过指定时间后，或收到 HTTP 401 响应 | 5 分钟 |
| 自定义刷新间隔 | 设置 CLAUDE_CODE_API_KEY_HELPER_TTL_MS（毫秒） | — |
| 慢速警告阈值 | 超过此时间未返回则在提示栏显示已耗时警告 | 10 秒 |
| 适用范围 | 仅终端 CLI 会话 | Claude Desktop 和 Web 端不调用 |
apiKeyHelper、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN仅对终端 CLI 会话生效。Claude Desktop 和云端会话仅使用 OAuth，不调用apiKeyHelper也不读取 API Key 环境变量。
认证优先级
多种凭据同时存在时，Claude Code 按以下顺序选择（序号越小优先级越高）：
| 优先级 | 凭据来源 | 发送方式 / 适用场景 |
|---|---|---|
| 1 | 云服务商环境变量：CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX / CLAUDE_CODE_USE_FOUNDRY | 路由至对应云服务商 |
| 2 | ANTHROPIC_AUTH_TOKEN 环境变量 | Authorization: Bearer 头；适用于 LLM 网关/代理 |
| 3 | ANTHROPIC_API_KEY 环境变量 | X-Api-Key 头；直连 Anthropic API |
| 4 | apiKeyHelper 脚本输出 | 动态/轮转凭据 |
| 5 | CLAUDE_CODE_OAUTH_TOKEN 环境变量 | 长效 Token；CI/脚本环境 |
| 6 | /login 订阅 OAuth 凭据 | 默认方式；Pro / Max / Team / Enterprise 订阅用户 |
注意事项：
- 若同时拥有有效订阅且设置了
ANTHROPIC_API_KEY，API Key 审批后优先生效。若该 Key 所属组织已禁用或过期，将导致认证失败。运行unset ANTHROPIC_API_KEY可回退到订阅认证。 - 运行
/status可确认当前生效的认证方式。 - Claude Code on the Web 始终使用订阅凭据，沙盒环境中的
ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN不会覆盖。 - 在
/config中使用「Use custom API key」开关可更改之前对 API Key 的审批决定。
生成长效 Token（CI/脚本场景）
适用于 CI 流水线、脚本等无法进行浏览器登录的环境，使用 claude setup-token 命令生成长效 OAuth Token：
claude setup-token
命令引导完成 OAuth 授权后将 Token 打印到终端（不自动保存），需手动复制并设置环境变量：
export CLAUDE_CODE_OAUTH_TOKEN=your-token
| 属性 | 说明 |
|---|---|
| 有效期 | 1 年 |
| 订阅要求 | 需要 Pro、Max、Team 或 Enterprise 订阅 |
| 权限范围 | 仅限推理（inference），不可建立 Remote Control 会话 |
| Bare 模式限制 | --bare 模式不读取 CLAUDE_CODE_OAUTH_TOKEN，请改用 ANTHROPIC_API_KEY 或 apiKeyHelper |
| Web 端限制 | Claude Code on the Web 始终使用订阅凭据，CLAUDE_CODE_OAUTH_TOKEN 在该环境下无效 |