<!-- title: 首次认证配置：四套登录实测 -->

## 概述

本教程面向零基础开发者，聚焦 Claude Code 最容易被忽视、却决定后续一切体验的第一步——**身份认证配置**。很多人装完就直接跑，结果撞上"账号登录还是填 API Key""公司要统一走 AWS 怎么办""为什么明明订阅了还在扣 API 费"等坑。学完你将能：独立判断四套认证方式的适用场景、完成首次配置、跑通第一个项目，并理解认证优先级这一最容易踩雷的机制。

## 前置条件

- **运行环境**：macOS、Linux 或 Windows（建议 WSL2），Node.js 18 及以上
- **账号其一**（四选一即可，不强求全部）：
  - 一个 Claude.ai 账号（Pro 或 Max 订阅，用于账号登录）
  - 一个 Anthropic Console 账号（用于生成 API Key，按量计费）
  - 一个开通 Amazon Bedrock 模型访问权限的 AWS 账号
  - 一个启用 Vertex AI 的 Google Cloud 项目
- **终端工具**：任意现代终端（iTerm2、Windows Terminal、WSL 等）
- **可选**：AWS CLI（`aws`）、Google Cloud SDK（`gcloud`）、Git

> 提示：如果你只是个人尝鲜，准备一个 Claude.ai 订阅账号或一个 API Key 就足够；如果是团队/企业场景，重点看 Bedrock 与 Vertex 两节。

---

## 第零步：安装与自检

Claude Code 官方推荐用 npm 全局安装（也可用原生安装包，零依赖）：

```bash
npm install -g @anthropic-ai/claude-code
```

安装完成后先做一次版本自检，确认二进制在 PATH 中：

```bash
claude --version
# 预期输出类似：1.x.x (Claude Code)
```

**预期结果**：终端打印出版本号，说明 CLI 就绪。若提示 `command not found`，多半是 npm 全局 bin 目录未加入 PATH，可在 macOS/Linux 用 `npm config get prefix` 找到目录并追加到 `~/.zshrc` 或 `~/.bashrc`。

**常见问题**：部分企业网络下 npm 走代理会装到错的位置。可改用原生安装脚本（curl 一行），它不依赖 Node 与 npm，适合受限环境。

---

## 第一步：理解四套认证方式

Claude Code 并非"一种登录方式"，而是支持四种并行的认证通道。选错通道，轻则多花钱，重则直接连不上。先用一张表建立全局认知：

| 方式 | 谁出钱 | 适合人群 | 是否需要密钥管理 | 企业友好度 |
|------|--------|----------|------------------|------------|
| Claude.ai 账号登录 | 个人订阅费 | 个人开发者、尝鲜 | 否（OAuth） | 低 |
| Anthropic API Key | 按 token 量计费 | 个人开发者、脚本自动化 | 是（需保管 sk-ant） | 中 |
| Amazon Bedrock | AWS 账单 | 企业团队、统一计费 | 走 AWS 凭证 | 高 |
| Google Vertex AI | GCP 账单 | 企业团队、GCP 用户 | 走 GCP 凭证 | 高 |

接下来逐个实操。

---

## 方式一：Claude.ai 账号登录（最简单）

这是绝大多数个人用户的默认路径。前提是你已有 Claude Pro（约 $20/月）或 Max 订阅。

**操作步骤**：

1. 在项目目录或任意目录下启动：
   ```bash
   claude
   ```
2. 首次启动会弹出交互提示，选择通过浏览器登录（OAuth 流程）。
3. 浏览器自动打开 Anthropic 授权页，确认授权后回到终端，提示登录成功。
4. 验证登录状态：
   ```bash
   /status
   ```
   或退出后用 `/login` 重新登录、`/logout` 登出。

**预期结果**：终端进入 Claude Code 交互界面，`/status` 显示当前账号与套餐额度信息。

**常见问题**：
- **浏览器打不开**：在 SSH 远程服务器或无图形界面环境下，OAuth 回调会卡住。此时改用方式二（API Key）更省心，或在本地登录后通过环境变量携带凭证。
- **额度用尽**：订阅额度按 5 小时滚动窗口计算，用完会临时限流，等待窗口重置即可，无需额外付费。

**优点**：零密钥、零配置，开箱即用。
**缺点**：额度受订阅档位限制，不适合高强度自动化批量任务。

---

## 方式二：Anthropic API Key（最灵活）

API Key 走 console.anthropic.com 生成的密钥，按实际 token 用量计费，适合脚本、CI、以及需要精确控制成本与并发场景。

**操作步骤**：

1. 登录 [Anthropic Console](https://console.anthropic.com)，在 API Keys 页面创建一个新密钥，形如 `sk-ant-...`，**只显示一次，务必复制保存**。
2. 设置环境变量（推荐写入 shell 配置文件持久化）：
   ```bash
   export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"
   ```
3. 或写入 Claude Code 的设置文件 `~/.claude/settings.json`，避免密钥出现在进程列表里：
   ```json
   {
     "env": {
       "ANTHROPIC_API_KEY": "sk-ant-xxxxxxxxxxxx"
     }
   }
   ```
4. 重新启动 `claude`，输入 `/status` 确认走的是 API 通道。

**预期结果**：Claude Code 用该 Key 作为 `X-Api-Key` 鉴权，调用直接计入 API 账单。

**常见问题（关键！）**：
- **"我订阅了 Pro，为什么还在扣 API 费？"** 这是社区最高频的疑问。原因在于：**只要环境里存在 `ANTHROPIC_API_KEY`，它的优先级高于账号登录**，于是所有调用都走 API 计费，订阅额度根本没被用到。解决方法是 `unset ANTHROPIC_API_KEY` 或从 settings.json 删除该字段，让账号登录重新生效。
- **密钥泄露**：切勿把 Key 写进代码仓库或截图。建议用环境变量管理工具，并定期在 Console 轮换密钥。

**优点**：并发与成本完全可控，适合自动化。
**缺点**：需要自行保管密钥、自行监控用量，无封顶保护。

---

## 方式三：Amazon Bedrock（企业首选之一）

Bedrock 让 Claude 调用走 AWS 内部网络，计费与权限统一并入 AWS 账号体系，非常适合团队统一管理，无需每个人单独订阅。

**操作步骤**：

1. 在 AWS 控制台进入 Bedrock，在目标区域（如 `us-east-1` 或 `us-west-2`）**申请 Claude 模型访问权限**（Model access），通常几分钟到几小时审批通过。
2. 配置 AWS 凭证（三选一）：
   ```bash
   # 方式A：长期凭证
   aws configure
   # 方式B：SSO 单点登录（企业常用）
   aws sso login --profile my-profile
   # 方式C：IAM 角色（EC2/ECS 上运行时自动获取，无需配置）
   ```
3. 设置 Bedrock 相关环境变量：
   ```bash
   export CLAUDE_CODE_USE_BEDROCK=1
   export AWS_REGION=us-east-1
   # 跨区域推理（推荐，可用更高端模型与更高配额）
   export ANTHROPIC_MODEL="us.anthropic.claude-sonnet-4-20250514-v1:0"
   ```
   或写入 `~/.claude/settings.json`：
   ```json
   {
     "env": {
       "CLAUDE_CODE_USE_BEDROCK": "1",
       "AWS_REGION": "us-east-1",
       "ANTHROPIC_MODEL": "us.anthropic.claude-sonnet-4-20250514-v1:0"
     }
   }
   ```
4. 也可用 OAuth 式登录绑定 Bedrock 凭证：启动 `claude` 后执行 `/bedrock-login`。
5. 启动 `claude`，`/status` 确认走 Bedrock 通道。

**预期结果**：调用经 Bedrock 端点完成，账单出现在 AWS Cost Explorer 的 Bedrock 项下。

**常见问题**：
- **`AccessDeniedException`**：模型访问权限未开通，或所选区域不支持该模型。回到 Bedrock 控制台核对 Model access 状态。
- **凭证过期**：当 Claude Code 检测到 AWS 凭证过期（本地时间戳或 Bedrock 返回过期信号），会提示重新登录；SSO 用户重跑 `aws sso login` 即可。可在 settings 里配置自动刷新。
- **模型名带不带 `us.` 前缀**：带前缀走跨区域推理（Cross-Region Inference），配额更高、更稳定；不带则固定单区域。生产环境建议带。

**优点**：企业级计费与权限治理、走 AWS 内网、可对接 IAM/SSO。
**缺点**：初始配置链路较长，需要 AWS 基础。

---

## 方式四：Google Vertex AI（GCP 用户首选）

Vertex AI 与 Bedrock 对位，把 Claude 调用纳入 Google Cloud 计费与权限体系。

**操作步骤**：

1. 在 GCP 创建项目、启用结算功能，并在 API 库中**启用 Vertex AI API**。
2. 确认目标区域有 Claude 模型配额（如 `us-east5`、`europe-west1`）。
3. 配置应用默认凭证：
   ```bash
   gcloud auth application-default login
   ```
4. 设置环境变量：
   ```bash
   export CLAUDE_CODE_USE_VERTEX=1
   export CLOUD_ML_REGION=us-east5
   export ANTHROPIC_VERTEX_PROJECT_ID=你的GCP项目ID
   ```
   或写入 settings.json：
   ```json
   {
     "env": {
       "CLAUDE_CODE_USE_VERTEX": "1",
       "CLOUD_ML_REGION": "us-east5",
       "ANTHROPIC_VERTEX_PROJECT_ID": "my-gcp-project"
     }
   }
   ```
5. 启动 `claude`，`/status` 确认走 Vertex 通道。

**预期结果**：调用经 Vertex AI 端点完成，账单出现在 GCP 的 Vertex AI 项下。

**常见问题**：
- **`PERMISSION_DENIED`**：服务账号或用户缺少 `aiplatform.endpoints.predict` 权限，需在 IAM 中授予 Vertex AI User 角色。
- **配额不足**：在 GCP 配额页为对应区域/模型申请提额。
- **区域不支持**：并非所有 GCP 区域都上了 Claude，需对照官方支持矩阵选区域。

**优点**：与现有 GCP 架构（BigQuery、Cloud Run 等）天然打通。
**缺点**：需要 GCP 基础，模型可用区域较少。

---

## 关键机制：认证优先级与切换

四种方式可同时配置，但**同时存在时谁先生效**是重中之重。按官方行为，判定优先级大致如下（从高到低）：

1. **Bedrock 标志**（`CLAUDE_CODE_USE_BEDROCK=1`）——置顶则强制走 AWS。
2. **Vertex 标志**（`CLAUDE_CODE_USE_VERTEX=1`）——置顶则强制走 GCP。
3. **`ANTHROPIC_API_KEY`** 环境变量——存在则走 API 计费，**会"压住"账号订阅**。
4. **Claude.ai 账号登录**——以上都没有时的默认回退。

实践建议：**同一台机器最好只启用一条通道**，避免优先级打架。切换通道时，先 `unset` 旧的变量或清掉 settings.json 里对应字段，再设新的，最后用 `/status` 复核。这套"清旧—设新—复核"的三步法，能消除 90% 的"明明配了却不生效"的玄学问题。

---

## 第二步：实战案例——跑通第一个项目

配置好任意一种认证后，我们用一个最小项目验证全链路。以下示例用 Node.js（Claude Code 本身就是 TS 写的，对 JS 生态最熟）。

**1. 建项目目录并初始化**：
```bash
mkdir hello-claude && cd hello-claude
git init
npm init -y
```

**2. 启动 Claude Code**：
```bash
claude
```

**3. 用自然语言下达第一个任务**（在交互界面输入）：
```
帮我创建一个 src/index.js，实现一个函数 fib(n) 返回第 n 个斐波那契数，
并配上 src/index.test.js 用 Node 内置 node:test 写 3 个测试用例。
然后运行 npm test，把结果修到全绿。
```

**预期结果**：
- Claude Code 自动创建 `src/index.js` 与 `src/index.test.js`；
- 自动在 `package.json` 的 `scripts` 里加 `"test": "node --test src"`；
- 自动运行 `npm test`，输出类似：
  ```
  ✔ fib(0) === 0
  ✔ fib(1) === 1
  ✔ fib(10) === 55
  3 tests passed
  ```

**4. 让它做一次提交**（确认无误后）：
```
把这些改动提交，commit message 用 "feat: add fib function and tests"
```

至此，"认证 → 配置 → 读项目 → 改代码 → 跑测试 → Git 提交"的完整闭环跑通，说明你的认证通道是健康的。

---

## 工作流程图

下面这张决策图展示如何根据自身情况选对认证方式：

```mermaid
flowchart TD
    Start[开始：装好 Claude Code] --> Q1{谁来付费?}
    Q1 -->|个人订阅费| A1[方式一：Claude.ai 账号登录]
    Q1 -->|按 token 自费| A2[方式二：Anthropic API Key]
    Q1 -->|公司云账单| Q2{公司主用哪家云?}

    Q2 -->|AWS| A3[方式三：Amazon Bedrock]
    Q2 -->|Google Cloud| A4[方式四：Google Vertex AI]

    A1 --> S1[claude 启动 → OAuth → /status 复核]
    A2 --> S2[设置 ANTHROPIC_API_KEY → /status 复核]
    A3 --> S3[aws 凭证 + CLAUDE_CODE_USE_BEDROCK → /bedrock-login]
    A4 --> S4[gcloud ADC + CLAUDE_CODE_USE_VERTEX → /status 复核]

    S1 --> Verify[跑通第一个项目]
    S2 --> Verify
    S3 --> Verify
    S4 --> Verify

    Verify --> Check{调用是否正常计费?}
    Check -->|是| Done[✅ 认证闭环完成]
    Check -->|否，疑似优先级打架| Fix[清旧变量 → 设新 → /status 复核]
    Fix --> Verify
```

---

## 常见问题速查表

| 现象 | 可能原因 | 解决办法 |
|------|----------|----------|
| 订阅了 Pro 却扣 API 费 | `ANTHROPIC_API_KEY` 优先级高于账号 | 删除该变量或 unset，重登账号 |
| Bedrock 报 AccessDenied | 模型访问未开通/区域不支持 | Bedrock 控制台开通 Model access，换区域 |
| Vertex 报 PERMISSION_DENIED | IAM 缺 aiplatform 权限 | 授予 Vertex AI User 角色 |
| OAuth 在服务器卡住 | 无图形界面/无浏览器 | 改用 API Key 或本地登录 |
| `command not found: claude` | npm 全局 bin 未在 PATH | 加 `$(npm bin -g)` 到 PATH，或用原生安装 |
| 频繁限流 | 订阅滚动窗口耗尽 | 等待窗口重置，或升级档位/改 API Key |

---

## 延伸阅读

- **官方认证文档**（权威优先级与变量说明）：`code.claude.com/docs/zh-CN/authentication`
- **Bedrock 配置详解**：`code.claude.com/docs/zh-CN/amazon-bedrock`
- **Vertex AI 配置详解**：`code.claude.com/docs/zh-CN/google-vertex-ai`
- **快速开始 Quickstart**（含原生安装一行命令）：`code.claude.com/docs/zh-CN/quickstart`
- **国产/第三方模型接入**：通过 `~/.claude/settings.json` 配置自定义端点（如智谱 GLM Coding Plan），可作为账号登录之外的补充通道

> 进阶方向：认证跑通后，下一步可学习 **settings.json 分层配置（用户级/项目级/本地级）** 与 **MCP 服务器接入**，把外部工具挂进来。

---

## 训练营适用性评估

- **适合训练营类型**：AI 编程入门营、企业 AI 工具落地营、DevOps 效能提升营
- **教学时长**：建议 1.5～2 课时（含动手实操）；纯讲授约 45 分钟
- **难度定位**：★☆☆☆☆（零基础友好，但 Bedrock/Vertex 两节可作选修，按学员背景裁剪）
- **实操产出**：每位学员完成一种认证配置并跑通第一个项目，提交一个含测试的小仓库
- **差异化建议**：个人学员聚焦方式一、二；企业班重点演练方式三或四，并配合 IAM/SSO 真实账号做权限治理演练

---

## 参考来源

1. [身份验证 - Claude Code Docs](https://code.claude.com/docs/zh-CN/authentication) — 官方四种认证方式与优先级权威说明
2. [Amazon Bedrock 上的 Claude Code - Claude Code Docs](https://code.claude.com/docs/zh-CN/amazon-bedrock) — Bedrock 环境变量、凭证刷新与 `/bedrock-login` 官方流程
3. [Google Vertex AI 上的 Claude Code - Claude Code Docs](https://code.claude.com/docs/zh-CN/google-vertex-ai) — Vertex AI 先决条件、IAM 与区域配额配置
4. [快速开始 - Claude Code Docs](https://code.claude.com/docs/zh-CN/quickstart) — 官方安装与首个任务 Quickstart
5. [Claude Code 配置秘钥的完整指南：六种认证方式及差异详解](https://blog.csdn.net/m0_37988015/article/details/161275292) — 社区对认证优先级与"订阅却被扣 API 费"问题的实战拆解

> [!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)