---
title: "登录与认证"
description: "Claude Code 登录不是只有订阅账号。个人用 Claude.ai，团队可用 Teams、Enterprise、Console、Bedrock、Vertex AI 或 Microsoft Foundry。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

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

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

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

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

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

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

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

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

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

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

## 2. 第一次登录怎么走

<Steps>

<Step>

### 启动 Claude Code

在项目目录里跑：

```bash
claude
```

第一次启动会自动打开浏览器。

</Step>

<Step>

### 浏览器登录 Claude.ai

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

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

</Step>

<Step>

### 远程或隔离环境：手动复制 login code

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

这常见于几种场景：

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

</Step>

<Step>

### 验证或重新登录

确认当前认证状态：

```text
/status
```

退出并重新登录：

```text
/logout
```

</Step>

</Steps>

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

## 3. 哪类账号可以用 Claude Code

官方 [Authentication](https://code.claude.com/docs/en/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。

> [!WARNING]
> **不要混用概念**：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 最小配置：

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

Vertex AI 最小配置：

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

Microsoft Foundry 最小配置：

```bash
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource
```

Foundry 还可以用 API key：

```bash
export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key
```

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

```bash
az login
```

> [!CAUTION]
> **云接入不是新手默认路径**：除非公司明确要求走 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 和各种缓存。

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

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

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

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

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

这解释了一个常见坑：

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

```bash
export ANTHROPIC_API_KEY=old-disabled-key
```

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

回到订阅登录：

```bash
unset ANTHROPIC_API_KEY
unset ANTHROPIC_AUTH_TOKEN
```

再看：

```text
/status
```

> [!TIP]
> **排障口诀**：认证不对，先看 `/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 提醒）。

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

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

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

```bash
claude setup-token
```

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

```bash
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`。

> [!CAUTION]
> **长期 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 凭据。

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

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

<details id="glossary">
<summary><b>本篇术语速查表</b></summary>

- **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 的身份认证体系。

</details>

## 官方来源

- [Authentication](https://code.claude.com/docs/en/authentication)
- [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install)
- [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock)
- [Google Vertex AI](https://code.claude.com/docs/en/google-vertex-ai)
- [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry)

## 接下来去哪

<Cards>
  <Card href="/docs/claude-code/official/00-getting-started/platforms" title="选择平台与集成" description="登录完成后，下一步判断 CLI、Desktop、IDE、Web、Mobile 和团队集成应该怎么选。" />
  <Card href="/docs/claude-code/official/00-getting-started/install" title="安装和更新 Claude Code（上一篇）" description="认证问题很多时候其实是安装路径、PATH 或混装问题。先确认安装入口清晰。" />
  <Card href="/docs/claude-code/official/01-core-capabilities/settings" title="配置 Claude Code" description="团队认证常常要配 settings、managed settings 和环境变量。核心配置篇会继续展开。" />
</Cards>

如果只记一个判断：**认证排障先看当前生效凭据，不要只看自己“以为登录的是哪个账号”；`/status` 比猜更可靠。**
