认证配置

Claude Code登录问题通常由认证方式冲突、环境变量设置不当或网络连接异常引起。核心解决思路是明确当前生效的认证凭证并排除冲突。首先，在Claude Code终端运行/status命令，查看当前使用的认证类型（如OAuth、API Key或云凭证）。若登录失败，请检查浏览器是否正常弹出，或手动复制登录链接；若提示认证失败，请按优先级顺序检查是否存在冲突的环境变量（如ANTHROPIC_API_KEY），并使用unset命令清除。对于团队或企业用户，请确认账号已受管理员邀请并激活。系统性地遵循凭证优先级规则和故障排查步骤，能解决绝大多数登录问题。

Claude Code 支持多种认证方式，从个人订阅到企业 SSO 都有覆盖。

如果你正在排查 settings 相关问题，先记住一条：认证凭证和 settings 配置会同时影响 Claude Code 行为，但它们不是同一类东西。 模型、权限、statusline 写在 settings.json；账号登录、API Key、OAuth、长期 Token 则看本页。

基础登录

安装 Claude Code 后，在任意目录运行 claude。首次启动会打开浏览器登录窗口。

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

支持的账号类型：

账号类型	说明
Claude Pro/Max 个人订阅	用 claude.ai 账号登录，订阅地址：claude.com/pricing
Claude for Teams/Enterprise	用团队管理员邀请的 claude.ai 账号登录
Claude Console	用 Console 凭证登录（需管理员邀请）
云服务商	设置环境变量（Bedrock/Vertex/Foundry），无需浏览器登录

退出登录：在 Claude Code 提示符里输入 /logout。

---

团队认证方式

Claude for Teams / Enterprise（推荐）

最适合大多数团队，成员同时获得 Claude Code 和 Claude Web 权限，统一计费和管理。

Teams vs Enterprise：

特性	Teams	Enterprise
自助订阅	✅	-
团队协作 + 管理工具	✅	✅
SSO	-	✅
域名捕获	-	✅
基于角色的权限	-	✅
合规 API	-	✅
托管 policy 设置	-	✅

设置步骤：

1. 订阅 Claude for Teams 或联系销售购买 Enterprise
2. 在管理员仪表板邀请团队成员
3. 成员安装 Claude Code 并用 claude.ai 账号登录

Claude Console API 认证

适合偏好 API 计费方式的组织。

设置步骤：

1. 使用现有 Console 账号或创建新账号

2. 添加用户（两种方式）：

   • Console 后台批量邀请：Settings → Members → Invite
   • 设置 SSO

3. 分配角色：

   • Claude Code 角色：只能创建 Claude Code API key
   • Developer 角色：可以创建任意类型 API key

4. 每个被邀请的用户需要：

   • 接受 Console 邀请
   • 检查系统要求
   • 安装 Claude Code
   • 用 Console 账号登录

第三方云服务商

支持 Amazon Bedrock、Google Vertex AI、Microsoft Foundry，参见各自的配置文档：

• Amazon Bedrock
• Google Vertex AI
• Microsoft Foundry

配置好后，把环境变量和生成云凭证的操作指南分发给用户。

---

凭证管理

存储位置

平台	位置
macOS	加密的 macOS Keychain
Linux	~/.claude/.credentials.json（或 $CLAUDE_CONFIG_DIR/.credentials.json），权限 0600
Windows	~/.claude/.credentials.json，继承用户目录的访问控制

支持的认证类型

• Claude.ai 凭证
• Claude API 凭证
• Azure Auth
• Bedrock Auth
• Vertex Auth

自定义凭证脚本（apiKeyHelper）

apiKeyHelper 设置可以配置一个 shell 脚本，运行后返回 API key。适合动态或轮换凭证（如从 vault 获取短期 token）。

{
  "apiKeyHelper": "~/.claude/get-api-key.sh"
}

• 默认每 5 分钟或 HTTP 401 时调用一次
• 自定义刷新间隔：设置环境变量 CLAUDE_CODE_API_KEY_HELPER_TTL_MS
• 如果脚本超过 10 秒才返回，Claude Code 会在提示栏显示警告

apiKeyHelper、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 仅适用于终端 CLI 会话。Claude Desktop 和远程会话只使用 OAuth，不调用这些设置。

---

认证优先级

同时存在多种凭证时，Claude Code 按以下顺序选择（从高到低）：

1. 云服务商凭证：设置了 CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX 或 CLAUDE_CODE_USE_FOUNDRY 时优先使用，详见第三方集成
2. ANTHROPIC_AUTH_TOKEN 环境变量：作为 Authorization: Bearer 头发送，适合通过 LLM Gateway 或代理 路由时使用
3. ANTHROPIC_API_KEY 环境变量：作为 X-Api-Key 头发送，用于直接 Anthropic API 访问
   • 交互模式：首次使用时提示确认，选择会被记住；后续可在 /config 的"Use custom API key"切换
   • 非交互模式（-p）：有 key 时始终使用
4. apiKeyHelper 脚本输出：用于动态/轮换凭证，如从 vault 获取短期 token
5. CLAUDE_CODE_OAUTH_TOKEN 环境变量：通过 claude setup-token 生成的长期 OAuth token，适合 CI 流水线
6. 订阅 OAuth 凭证（/login）：Claude Pro、Max、Team、Enterprise 用户的默认方式

常见问题：如果有活跃的 Claude 订阅但同时设置了 ANTHROPIC_API_KEY，API key 优先。如果 key 所属的组织被禁用或过期，会导致认证失败。解决方法：unset ANTHROPIC_API_KEY，然后用 /status 确认当前使用哪种认证方式。

Claude Code Web 版始终使用订阅凭证。沙箱环境中设置的 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 不会覆盖 Web 版认证。

生成长期 Token

对于 CI 流水线、脚本或其他无法进行浏览器登录的环境，可以用 claude setup-token 生成一年有效期的 OAuth token：

claude setup-token

命令会引导你完成 OAuth 授权，并将 token 打印到终端（不会保存到任何地方）。复制后，在需要认证的环境中设置环境变量：

export CLAUDE_CODE_OAUTH_TOKEN=your-token

限制：

• 需要 Pro、Max、Team 或 Enterprise 订阅
• 仅限推理（Inference）权限，无法建立远程控制会话
• Bare 模式不读取 CLAUDE_CODE_OAUTH_TOKEN，如果脚本用了 --bare，请改用 ANTHROPIC_API_KEY 或 apiKeyHelper

---

下一步阅读

• settings.json 配置指南 — 配置权限、默认模型、statusline 和环境变量。
• 桌面应用快速入门 — 桌面版登录和 CLI 配置共用关系。
• JetBrains IDE 集成 — IDE 插件中的 Claude 命令路径、登录状态和 Diff 设置。
• 安装配置 — 安装步骤和系统要求。
• 第三方集成 — 企业部署概览。
• LLM Gateway — 通过代理路由 API 请求。
• 故障排查 — 认证问题排查。

登录问题排查与解决

遇到 Claude Code 无法登录或认证失败时，可遵循以下步骤系统性地排查问题。

1. 诊断当前认证状态

首先，在 Claude Code 终端中输入以下命令，了解当前生效的认证方式：

/status

输出将明确显示是使用 OAuth（个人/团队订阅）、API Key，还是 云服务商凭证。这是所有排查工作的起点。

2. 常见问题及解决方法

问题A：浏览器未自动打开登录页面

• 原因：终端环境或系统权限限制浏览器自动启动。
• 解决：启动 Claude Code 后，留意终端提示，按 c 键复制登录链接，手动粘贴至已安装的浏览器（如 Chrome、Edge）中打开。

问题B：提示“认证失败”或“无效凭证”

• 原因1：凭证优先级冲突。这是最常见原因。例如，您拥有 Claude Pro 订阅，但同时设置了 ANTHROPIC_API_KEY 环境变量。根据优先级规则，API Key 将覆盖 OAuth 登录，如果该 Key 无效或所属组织无权访问 Claude Code，便会失败。
• 解决：
  1. 在终端中运行 unset ANTHROPIC_API_KEY（或 unset ANTHROPIC_AUTH_TOKEN）以清除环境变量。
  2. 完全退出并重启 Claude Code，此时应触发浏览器 OAuth 登录。
  3. 若仍需使用自定义 API Key，可在登录后通过 /config 菜单中的“Use custom API key”选项切换。
• 原因2：订阅状态异常。个人或团队订阅已过期，或企业账号未被正确分配权限。
• 解决：登录 claude.ai 官网检查账户状态，或联系团队管理员确认权限。

问题C：团队/企业账号登录失败

• 原因：未成功接受邀请，或使用了错误的登录入口。
• 解决：
  • Claude for Teams/Enterprise：必须使用管理员通过邮箱邀请的 claude.ai 账号登录，而非自行注册的普通账号。
  • Console API 认证：确保已接受 Console 邀请，且账号拥有相应角色（Claude Code 角色或 Developer 角色）。

问题D：配置云服务商后无法登录

• 原因：设置了 CLAUDE_CODE_USE_BEDROCK 等变量后，Claude Code 将完全转向云认证，不会进行任何浏览器登录流程。
• 解决：
  1. 确认云凭证（如 AWS 的 ~/.aws/credentials）配置正确且未过期。
  2. 参考对应文档（Amazon Bedrock）检查必要权限。
  3. 如需切换回普通登录，需取消设置相关环境变量（如 unset CLAUDE_CODE_USE_BEDROCK）并重启 Claude Code。

3. 高级排查

• 查看详细日志：在启动 Claude Code 时添加 --verbose 标志，可以输出更详细的认证过程日志，帮助定位网络或协议层问题。
• 检查凭证文件：对于 Linux/Windows，检查 ~/.claude/.credentials.json 文件是否存在或损坏。可尝试备份后删除该文件，强制重新登录。
• 网络问题：确保终端可正常访问 claude.ai 及相关 API 端点。如有代理，请正确配置 HTTP_PROXY/HTTPS_PROXY 环境变量。

通过以上步骤，绝大多数登录问题都可以被定位和解决。如果问题依旧，请参考 故障排查 文档获取进一步支持。

常见问题

Q: Claude Code 登录时浏览器没有自动打开怎么办？

在启动Claude Code后，按键盘上的 c 键，即可复制登录URL，然后手动粘贴到浏览器中完成认证流程。

Q: Claude Code 一直提示认证失败或登录不上是什么原因？

最常见原因是多种认证凭证冲突。例如，设置了ANTHROPIC_API_KEY环境变量会优先于个人订阅OAuth登录。运行/status查看当前凭证，并用unset ANTHROPIC_API_KEY等命令清除冲突的环境变量。

Q: 团队账号无法登录 Claude Code 如何解决？

请确保你已接受团队管理员发出的邀请，并使用正确的claude.ai账号登录。如果使用Console API认证，需确认已被邀请至Console并拥有“Claude Code角色”或“Developer角色”。

Q: 如何检查 Claude Code 当前使用的是哪种登录方式？

在Claude Code的交互式终端中，直接输入命令 /status，系统会显示当前活跃的认证类型（例如：OAuth、API Key、Bedrock等）和对应的账号信息。

Q: 配置了云服务商（如Bedrock）后无法登录怎么办？

设置了CLAUDE_CODE_USE_BEDROCK等环境变量后，Claude Code会优先使用云凭证，不再走浏览器登录。请确保云凭证配置正确且未过期，并参考对应的云服务商配置文档进行排查。