create: 2026-07-08

update: 2026-07-31

author: thinkycx

title: 【译】认证

description: Claude Code 支持多种认证方式：claude.ai 订阅、Console 账号、云服务商凭证和 Claude apps gateway。本文介绍登录流程、团队认证配置和凭证管理。

category: translation

tags: claude-code, translation

refs: https://code.claude.com/docs/en/authentication.md en-source/authentication.md

认证¶

登录 Claude Code 并为个人、团队和组织配置认证方式。

Claude Code 支持多种认证方式。 个人用户可用 claude.ai 账号登录，团队可使用 Claude for Teams/Enterprise、Claude Console、或 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 等云服务商。

登录 Claude Code¶

安装 Claude Code 后，在终端运行 claude。首次启动时会打开浏览器窗口进行登录。

如果已设置 ANTHROPIC_API_KEY 环境变量，Claude Code 会跳过登录提示，转而请求你确认是否使用该 key。

如果浏览器未自动打开，按 c 复制登录 URL 到剪贴板，然后粘贴到浏览器中。

如果浏览器显示登录码而非自动重定向，将其粘贴到终端的 Paste code here if prompted 提示处。这通常发生在 WSL2、SSH 会话和容器中，因为浏览器无法连接到 Claude Code 的本地回调服务器。

支持的账号类型：

账号类型	说明
Claude Pro 或 Max 订阅	用 claude.ai 账号登录。订阅地址 claude.com/pricing
Claude for Teams 或 Enterprise	用团队管理员邀请的 claude.ai 账号登录
Claude Console	用 Console 凭证登录。管理员需先邀请你
云服务商	使用 Amazon Bedrock、Google Cloud Agent Platform 或 Microsoft Foundry 时，运行 `claude` 前设置所需环境变量；或在登录提示时选择 3rd-party platform，启动 Bedrock 和 Vertex AI 的交互式配置向导。无需浏览器登录
Cloud gateway	组织运行自托管 Claude apps gateway 时，通过 `/login` 使用企业 SSO 登录。gateway 颁发的 token 是会话的唯一凭证

管理员可限制允许的登录方式和组织，详见限制登录到指定组织。

运行 /logout 注销并重新认证。注销也会重置首次启动的设置状态，下次运行 claude 时会重新引导你完成登录和设置流程。

登录遇到问题请参见认证故障排除。

限制登录到指定组织¶

通过管理配置强制用户只能登录到特定组织。 在管理配置中设置以下字段：

设置项	说明
`forceLoginMethod`	强制使用的登录方式。设为 `"claude-ai"` 表示仅允许 claude.ai 账号，设为 `"console"` 表示仅允许 Console 账号
`forceLoginOrgUUID`	限制用户只能登录到该组织 UUID。在 claude.ai 管理设置或 platform.claude.com 中获取组织 UUID

不同登录路径的限制行为：

登录路径	行为
终端 / VS Code / Agent SDK	登录流程仅显示指定方式，完成后验证组织匹配
`setup-token` / `install-github-app`	生成 token 时验证组织匹配
Gateway	Gateway 会话不受此限制影响

注意事项：

版本要求：需要 Claude Code v2.1.212 或更高版本
部署方式：通过设备管理工具（MDM）将配置推送到客户端。仅靠服务端管理配置不够，因为客户端启动时需在发起网络请求前读取此限制
API key / auth token 会话：设置了 forceLoginMethod 和 forceLoginOrgUUID 后，通过 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN 认证的会话也会被阻止
云服务商会话：不受此限制影响

配置团队认证¶

团队和组织可通过以下方式配置 Claude Code 访问：

Claude for Teams 或 Enterprise
Claude Console
Claude apps gateway：自托管 gateway，通过 IdP 登录并路由推理至配置的云服务商
Amazon Bedrock
Google Cloud Agent Platform
Microsoft Foundry

Claude for Teams 或 Enterprise¶

Claude for Teams 和 Claude for Enterprise 为组织提供最佳体验。 团队成员同时获得 Claude Code 和 Claude Web 访问权限，集中计费和团队管理。

Claude for Teams：自助计划，含协作功能、管理工具和计费管理。适合小团队。
Claude for Enterprise：增加 SSO、域名捕获、基于角色的权限、合规 API 和托管策略设置。适合有安全合规要求的大组织。

配置步骤：

订阅 Claude for Teams 或联系销售获取 Claude for Enterprise
从管理面板邀请团队成员
团队成员安装 Claude Code 并用 claude.ai 账号登录

Claude Console 认证¶

对于偏好 API 计费的组织，可通过 Claude Console 配置访问。

配置步骤：

使用现有 Console 账号或创建新账号
添加用户（两种方式）：
- Console 内批量邀请：Settings -> Members -> Invite
- 设置 SSO
分配角色：
- Claude Code 角色：用户只能创建 Claude Code API key
- Developer 角色：用户可创建任何类型的 API key
用户完成设置：接受邀请 -> 检查系统要求 -> 安装 Claude Code -> 用 Console 凭证登录

云服务商认证¶

使用 Amazon Bedrock、Google Cloud Agent Platform 或 Microsoft Foundry 的团队：

按照对应文档设置：Amazon Bedrock、Google Cloud Agent Platform 或 Microsoft Foundry
将环境变量和生成云凭证的说明分发给用户。管理配置中有更多细节
用户安装 Claude Code

凭证管理¶

Claude Code 安全地管理认证凭证：

存储位置：
macOS：存储在加密的 macOS Keychain 中
Linux：存储在 ~/.claude/.credentials.json，文件权限 0600
Windows：存储在 %USERPROFILE%\.claude\.credentials.json，继承用户配置文件目录的访问控制
如果设置了 CLAUDE_CONFIG_DIR 环境变量（Linux/Windows），.credentials.json 在该目录下
Claude Code 通过 /login 和 /logout 管理 .credentials.json。路由请求到自定义 API 端点请设置 ANTHROPIC_BASE_URL 环境变量
支持的认证类型：Claude.ai 凭证、Claude API 凭证、Microsoft Foundry Auth、Bedrock Auth、Vertex Auth 和 Claude apps gateway 会话 token
自定义凭证脚本：apiKeyHelper 设置可配置运行一个返回 API key 的 shell 脚本
刷新间隔：默认 apiKeyHelper 在 5 分钟后或 HTTP 401 响应时被调用。设置 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 环境变量自定义刷新间隔
慢 helper 提示：如果 apiKeyHelper 超过 10 秒返回 key，Claude Code 在提示栏显示警告。如果经常看到此提示，检查凭证脚本是否可优化
Helper 失败：当脚本退出时报错、超时或无输出时，请求会在三次尝试内以 "Your apiKeyHelper script is failing" 错误失败

apiKeyHelper、ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 适用于 CLI 及其封装的界面（VS Code 扩展、Agent SDK、GitHub Actions），但桌面会话运行第三方推理配置时除外——该场景使用配置自身的凭证。Claude Desktop 和云会话不调用 apiKeyHelper 也不读取这些环境变量：它们使用 OAuth，除非桌面会话运行组织分发的第三方推理配置。

续期即将过期的登录¶

登录凭证过期前 3 天，Claude Code 会在状态栏显示警告。 运行 /login 即可续期，无需注销。

过期前看到 "Login expiring soon" 警告时，运行 /login 完成续期
过期后会收到 "Login expired" 错误，同样运行 /login 重新认证
/status 会显示凭证是否已过期

认证优先级¶

多个凭证同时存在时，Claude Code 按以下顺序选择：

优先级	凭证	说明
1	云服务商凭证	设置了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY` 时
2	`ANTHROPIC_AUTH_TOKEN` 环境变量	作为 `Authorization: Bearer` header 发送。用于通过 bearer token 认证的 LLM gateway
3	`ANTHROPIC_API_KEY` 环境变量	作为 `X-Api-Key` header 发送。用于 Claude Console 的直接 API 访问。交互模式下首次使用会提示确认或拒绝，选择会被记住；之后可在 `/config` 中通过 "Use custom API key" 开关修改（仅在环境变量存在时显示）。非交互模式（`-p`）下，有 key 就直接使用
4	`apiKeyHelper` 脚本输出	用于动态或轮换凭证，如从 vault 获取的短期 token
5	`CLAUDE_CODE_OAUTH_TOKEN` 环境变量	由 `claude setup-token` 生成的长期 OAuth token。用于无法浏览器登录的 CI 管道
6	`/login` 的订阅 OAuth 凭证	Claude Pro、Max、Team 和 Enterprise 用户的默认方式

已登录的 Claude apps gateway 会话在此列表之外，属于服务商选择级别（类似 Bedrock / Vertex），优先级高于以上所有。gateway 会话存在时，CLI 使用 gateway token 认证，即使设置了 CLAUDE_CODE_USE_BEDROCK 等变量，bearer token、API key 和 apiKeyHelper 也不会被使用。

如果你有活跃的 Claude 订阅同时设置了 ANTHROPIC_API_KEY，API key 确认后优先使用。如果 key 属于已禁用或过期的组织可能导致认证失败。运行 unset ANTHROPIC_API_KEY 回退到订阅，用 /status 确认当前方式。

Claude Code on the Web 始终使用订阅凭证。沙箱环境中的 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 不会覆盖它们。

生成长期 token¶

对于无法进行交互式浏览器登录的 CI 管道、脚本等环境，用 claude setup-token 生成一年有效期的 OAuth token：

claude setup-token

该命令打开与 /login 相同的浏览器授权流程，在你于浏览器中批准访问后将 token 打印到终端。不会保存 token 到任何位置——复制并设置为 CLAUDE_CODE_OAUTH_TOKEN 环境变量：

export CLAUDE_CODE_OAUTH_TOKEN=your-token

此 token 使用你的 Claude 订阅认证，需要 Pro、Max、Team 或 Enterprise 计划。仅限模型推理用途，不能建立 Remote Control 会话，也不能获取 claude.ai 连接器。本地配置的 MCP 服务器仍然正常工作。

Bare mode 不读取 CLAUDE_CODE_OAUTH_TOKEN。如果脚本传入 --bare，请使用 ANTHROPIC_API_KEY 或 apiKeyHelper 认证。