<!-- title: Claude Code 登录认证：四路首跑入门 -->

## 概述

很多新手把 Claude Code 装进终端，敲下 `claude`，结果卡在"请登录"这一步不知道选哪条路：用刚买的 Claude Max 订阅？用控制台的 API Key？还是公司配的 AWS Bedrock 凭证？选错不仅跑不通，还可能"以为在用订阅、实际在烧 API 额度"。本教程把登录认证这一入门第一关彻底讲透——覆盖订阅登录、API Key、Amazon Bedrock、Google Vertex 四条认证路径，并带你登录成功后跑通第一个项目。适用人群：零基础到进阶初学者、刚拿到企业账号的团队新成员、在 WSL2/SSH/容器里跑 Claude Code 卡在回调的开发者。

## 前置条件

- 已安装 Node.js 18 及以上，并可用 `npm install -g @anthropic-ai/claude-code` 完成安装（安装本身不是本篇重点，假定 `claude --version` 能输出版本号）。
- 一个待验证的来源凭证，四选一：Claude.ai 账号（Pro/Max/Teams/Enterprise）、Anthropic Console 的 API Key、AWS 账号（启用 Bedrock 模型访问）、或 Google Cloud 项目（启用 Vertex AI）。
- 一台能打开浏览器的本机；若在 WSL2/SSH/远程容器内，需准备好"手动回填登录码"的心理预期。
- 终端能执行 `claude`、`export`（Linux/macOS）或 `setx`（Windows PowerShell）等基础命令。

## 第一步：第一次输入 claude 会发生什么

安装完成后，在任意目录执行：

```bash
claude
```

预期结果：终端打印欢迎信息，随后尝试自动打开系统浏览器跳转到 Anthropic 登录页。如果你看到一行类似 `Waiting for authentication...` 的提示，说明 Claude Code 已经在本机起了一个**临时本地回调服务器**，等待浏览器登录后把凭证回传给它。

这一步的常见卡点不是"登录失败"，而是"浏览器打不开"或"打开了却回不来"。理解这个回调机制，是后面排错的基础。

## 第二步：选对认证方式——一张决策表

登录前先回答一个问题：**你想让 Claude Code 用谁的钱、谁的额度？** 这决定了你走哪条路。

| 你的场景 | 推荐认证方式 | 谁在计费 | 关键凭证 |
| --- | --- | --- | --- |
| 个人买了 Claude Pro/Max | 订阅登录（OAuth） | 订阅额度，不按 token 计费 | Claude.ai 账号 |
| 公司发了 Teams/Enterprise 账号 | 订阅登录（OAuth） | 企业订阅额度 | 被管理员邀请的账号 |
| 想精确控制成本、做脚本/CI | API Key | 按 token 实付计费 | `ANTHROPIC_API_KEY` |
| 企业合规要求数据走 AWS | Amazon Bedrock | AWS 账单 | AWS IAM + Bedrock |
| 企业合规要求数据走 GCP | Google Vertex AI | GCP 账单 | GCP 项目 + 服务账号 |

决策原则：**能用订阅就别用 API Key**（订阅是包月，API Key 是计件）；**有合规要求就走云提供商**（Bedrock/Vertex 数据不出云）。如果你只是个人开发者想快速跑通，订阅登录几乎总是最优解。

## 第三步：四套认证逐一手把手配置

### 3.1 路径一：订阅登录（Claude Pro/Max/Teams/Enterprise）

这是最省事的路径。执行 `claude` 后，浏览器会打开登录页，用你的 Claude.ai 账号登录并授权即可。授权成功后浏览器会自动跳回终端，显示登录成功。

**WSL2 / SSH / 容器里的高频坑：** 浏览器可能显示一串**登录码（login code）**而不是自动跳转回终端——这是因为浏览器无法访问 Claude Code 在你本机起的那个回调服务器。解决方法：在终端的 `Paste code here if prompted` 提示处，把这串登录码粘贴进去回车即可完成认证。

预期结果：终端显示 `Logged in as <你的邮箱>`，再次运行 `claude` 时不再要求登录。

常见问题与解决：

- **浏览器根本不弹**：在登录提示界面按 `c` 键，把登录 URL 复制到剪贴板，手动粘到你本机浏览器打开。
- **登录后仍然提示未认证**：检查系统时间是否准确（OAuth 对时间偏差敏感），并确认没有被代理拦截 `*.anthropic.com`。

### 3.2 路径二：API Key（Anthropic Console）

到 [console.anthropic.com](https://console.anthropic.com/) 创建一个 API Key，然后设置环境变量：

```bash
# macOS / Linux（写入 shell 配置以持久化）
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"' >> ~/.zshrc

# Windows PowerShell（用户级持久化）
setx ANTHROPIC_API_KEY "sk-ant-xxxxxxxxxxxxxxxx"
```

注意：**API Key 一旦设置，会覆盖订阅登录**。也就是说，如果你同时有保存的 OAuth 订阅凭证和这个环境变量，Claude Code 默认走 API Key，按 token 计费。这是"以为用订阅、实际烧额度"的头号元凶，务必心里有数。

安全建议：永远不要把含 Key 的命令写进提交到 Git 的脚本；用 `.env` + `.gitignore`，或借助系统密钥管理。验证设置是否生效：

```bash
echo "${ANTHROPIC_API_KEY:0:12}..."   # 只打印前缀，确认已注入
```

预期结果：打印出 `sk-ant-xxxx...` 前缀，说明环境变量已生效。

### 3.3 路径三：Amazon Bedrock

适合企业合规场景。前提是 AWS 账号已在 Bedrock 控制台启用 Claude 模型访问，并配置好 IAM 凭证（`aws configure` 或挂载 IAM Role）。然后：

```bash
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export ANTHROPIC_MODEL="us.anthropic.claude-sonnet-4-6-20250929-v1:0"

# 可选：自定义 Bedrock 端点（跨区域或 PrivateLink 时）
export ANTHROPIC_BEDROCK_BASE_URL="https://bedrock-runtime.us-east-1.amazonaws.com"
```

模型 ID 形如 `us.anthropic.claude-<版本>`，必须和你在 Bedrock 控制台申请访问权限的模型严格一致，否则会报模型未授权。

常见问题与解决：

- **AccessDeniedException**：去 Bedrock 控制台 Model access 页面，确认对应模型已申请并通过。
- **region 不匹配**：`AWS_REGION` 必须等于模型可用区域，跨区域推理需用 `us.` 前缀模型并设对 `ANTHROPIC_BEDROCK_BASE_URL`。

### 3.4 路径四：Google Vertex AI

```bash
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID="your-gcp-project-id"

# 一次性应用层凭证
gcloud auth application-default login
```

前提：GCP 项目已启用 Vertex AI、已申请 Claude 模型访问、`gcloud` 已登录。`ANTHROPIC_VERTEX_PROJECT_ID` 是计费项目，`CLOUD_ML_REGION` 决定推理区域和可用模型，两者配错会直接 404。

Microsoft Foundry 走类似逻辑（`CLAUDE_CODE_USE_FOUNDRY=1` 等），本文不展开，思路与 Bedrock/Vertex 一致：设开关、设区域、配服务凭证。

## 第四步：用三个命令验证与管理认证

登录/配置完成后，**永远先验证当前实际生效的是哪条路**，再开始干活：

```bash
claude            # 进入交互界面
> /status         # 查看当前账户、组织、生效的认证方式与模型
> /login          # 重新走登录流程（切换账号）
> /logout         # 清除保存的凭证
```

**认证优先级链**（Authentication precedence）：当多个凭证同时存在时，Claude Code 按固定顺序选择其一——一般规律是显式设置的环境变量（API Key / Bedrock flag / Vertex flag）优先于本地保存的 OAuth 订阅凭证。这意味着：**只要你设了 `ANTHROPIC_API_KEY`，订阅登录就被架空**。排查"为什么在烧 API 额度"时，第一反应就是 `env | grep -i anthropic` 看有没有遗留的环境变量，或在交互界面用 `/status` 确认当前账户类型。

## 第五步：登录成功后跑通第一个项目

认证通过只是上半场，下半场是让 Claude Code 真正在你的项目里干活。进入项目目录并初始化：

```bash
mkdir hello-claude && cd hello-claude
claude
```

在交互界面执行 `/init`，Claude Code 会扫描项目并生成 `CLAUDE.md`（项目记忆文件），随后你可以直接下一条自然语言指令：

```text
用 Python 写一个读取当前目录所有 .md 文件并统计字数的脚本，保存为 count_words.py，然后运行它。
```

预期结果：Claude Code 创建 `count_words.py`、执行、并在终端回显每个文件的字数统计。如果它能在不被反复打断的情况下完成"创建—执行—输出"闭环，就证明认证、文件读写、命令执行整条链路都通了。

如果你只想做最小验证、不想动文件，直接问一句"当前目录下有哪些文件？"能正常回答，就说明认证层已完全打通。

## 实战案例：认证+首跑自检清单

下面这个流程把上述步骤串成一个可复现的"开机自检"，适合每次在新机器/新环境配置后跑一遍：

```bash
# 1. 确认 CLI 就绪
claude --version

# 2. 选定认证方式（三选一，注释掉不用的）
#    方式A：订阅登录
#    方式B：API Key
export ANTHROPIC_API_KEY="sk-ant-xxxx"
#    方式C：Bedrock
# export CLAUDE_CODE_USE_BEDROCK=1 AWS_REGION=us-east-1

# 3. 排查遗留凭证（避免优先级链劫持你的订阅）
env | grep -iE "ANTHROPIC|CLAUDE_CODE_USE|AWS_REGION|CLOUD_ML" || echo "无云凭证环境变量"

# 4. 非交互验证认证与模型可用性
claude -p "回复一个字：通"   # 期望输出"通"

# 5. 验证通过后，初始化项目记忆
claude /init
```

第 4 步的 `claude -p "..."` 是**无头模式（headless）**一次性问答，最适合用来做认证自检——它不会进入交互界面，认证有问题会直接报错退出，认证成功则返回模型回答。把这一行加入你的环境配置脚本，新机器开机就能秒验认证状态。

## 工作流程图

下面这张图把"选认证方式 → 配置 → 验证 → 首跑"的决策链画清楚：

```text
flowchart TD
    A[执行 claude] --> B{有合规/数据驻留要求?}
    B -- 否 --> C{按量计费 or 包月?}
    C -- 包月 --> D[订阅登录 OAuth]
    C -- 按量/脚本/CI --> E[设置 ANTHROPIC_API_KEY]
    B -- 是,AWS --> F[设置 CLAUDE_CODE_USE_BEDROCK=1]
    B -- 是,GCP --> G[设置 CLAUDE_CODE_USE_VERTEX=1]
    D --> H[浏览器登录 / 回填登录码]
    E --> I[env 注入并持久化]
    F --> J[IAM + 区域 + 模型 ID]
    G --> K[gcloud + 项目 + 区域]
    H --> L[/status 验证生效账户]
    I --> L
    J --> L
    K --> L
    L --> M{claude -p 自检通过?}
    M -- 否 --> N[排查优先级链/网络/区域]
    N --> L
    M -- 是 --> O[/init 初始化 + 下指令首跑]
    O --> P[✅ 认证+首跑闭环完成]
```

优先级链的"劫持"关系则可以这样理解：

```mermaid
flowchart LR
    A[ANTHROPIC_API_KEY?] -- 已设置 --> W[走 API Key 计费]
    A -- 未设 --> B[CLAUDE_CODE_USE_BEDROCK?]
    B -- 1 --> X[走 Bedrock]
    B -- 否 --> C[CLAUDE_CODE_USE_VERTEX?]
    C -- 1 --> Y[走 Vertex]
    C -- 否 --> Z[走保存的订阅 OAuth]
    Z --> Q[订阅额度]
```

（具体顺序以你所用版本 `claude --version` 对应的官方文档为准，`/status` 是判断实际生效路径的唯一可靠依据。）

## 常见问题 FAQ

**Q1：我明明登录了订阅，为什么 `/status` 显示在用 API？**
检查环境变量里有没有遗留的 `ANTHROPIC_API_KEY`。`unset ANTHROPIC_API_KEY` 后重启终端，再 `/status` 确认。

**Q2：WSL2 里浏览器打不开登录页怎么办？**
登录界面按 `c` 复制 URL，粘到 Windows 侧浏览器打开；若浏览器只给一串 code，把它粘回终端的 `Paste code here if prompted` 处。

**Q3：Bedrock 报 ModelAccessDenied？**
到 Bedrock 控制台 → Model access → 申请对应模型访问权限并等待通过；同时核对 `ANTHROPIC_MODEL` 的 ID 与区域前缀（如 `us.`）。

**Q4：想在 CI 里无人值守跑 Claude Code，用哪种认证？**
不要用 OAuth（没有浏览器）。用 API Key，或用云提供商的服务凭证（IAM Role / Workload Identity），并配合 `/login` 生成的长时效 token（long-lived token）写入 CI secret。

**Q5：切换账号后旧额度还在被用？**
`/logout` 清除本地凭证，再确认环境变量没残留，最后 `/login` 用新账号登录。

**Q6：四条路能不能同时配好按需切？**
可以，但通过环境变量切换而非全量常驻。建议写几个 shell 函数（如 `cc-sub`、`cc-api`、`cc-bedrock`）分别 `export`/`unset` 对应变量，避免优先级链互相劫持。

## 延伸阅读

- [Claude Code 官方认证文档](https://code.claude.com/docs/en/authentication) — 四套认证与优先级链的权威说明。
- [Claude Code on Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock) — IAM、模型 ID、跨区域配置细节。
- [Authentication: API Keys, Subscriptions, and SSO（Developer Toolkit）](https://developertoolkit.ai/en/claude-code/quick-start/authentication/) — 四种凭证选错的后果与实操。
- [Claude Code on Claude Max Plan: OAuth Token vs API Key（2026）](https://lalatenduswain.medium.com/claude-code-on-claude-max-plan-understanding-oauth-token-vs-api-key-authentication-in-2026-96a6213d2cde) — 2026 年 OAuth 与 API Key 的细微差别。
- [How to Install Claude Code: Complete Setup Guide（2026）](https://www.nxcode.io/resources/news/install-claude-code-setup-guide-2026) — 安装到首跑的完整 2026 指南。

## 训练营适用性评估

- **新人入门训练营**：高度适配，本篇正是"装好之后第一件事"。建议教学时长 60–90 分钟（含四套认证各跑一遍 `claude -p` 自检）。
- **企业落地训练营**：适配 Bedrock/Vertex 两路，可删减订阅/API Key 章节，聚焦 IAM 配置与合规，建议 45 分钟。
- **自动化/DevOps 训练营**：聚焦第 4 条 FAQ 的 CI 无头认证与长时效 token，建议 30 分钟工作坊。
- **前置依赖**：学员需先完成"Claude Code 安装"模块；本篇是其直接下游，建议紧接开设。

## 参考来源

1. [Authentication — Claude Code Docs](https://code.claude.com/docs/en/authentication) — 官方认证方式总览、登录回调机制、认证优先级链与长时效 token。
2. [Claude Code on Amazon Bedrock — Claude Code Docs](https://code.claude.com/docs/en/amazon-bedrock) — Bedrock 环境变量（`CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BEDROCK_BASE_URL`、`AWS_REGION`）与 IAM 配置。
3. [Authentication: API Keys, Subscriptions, and SSO — Developer Toolkit](https://developertoolkit.ai/en/claude-code/quick-start/authentication/) — 订阅/API Key/SSO 三类凭证的选择与踩坑。
4. [Claude Code on Claude Max Plan: OAuth Token vs API Key Authentication in 2026 — Medium](https://lalatenduswain.medium.com/claude-code-on-claude-max-plan-understanding-oauth-token-vs-api-key-authentication-in-2026-96a6213d2cde) — 2026 年 OAuth token 与 API key 的差异与切换。
5. [How to Install Claude Code: Complete Setup Guide (2026) — nxcode.io](https://www.nxcode.io/resources/news/install-claude-code-setup-guide-2026) — 安装到 API Key 设置的 2026 完整指南。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)