<!-- title: 认证入门：登录、密钥与额度查看 -->

## 认证入门：跑通 Claude Code 的登录、密钥与额度

## 概述

本教程面向第一次安装 Claude Code 的零基础用户，只解决一件事：**如何让 Claude Code 合法地"连上"账号并开始工作，且看得懂自己花了多少额度**。学完你将掌握三种认证方式的区别、Claude 账号登录与 API 密钥的完整配置流程、订阅制与按量计费的差异，以及"额度去哪了"的排查方法。适用人群：从未登录过、卡在认证报错、或刚拿到 API Key 不知道往哪填的新手。

## 前置条件

- **Node.js 18 或更高版本**（在终端运行 `node -v` 应显示 `v18.x` 以上；推荐 LTS 版本）
- 一个可用的终端：macOS 的 Terminal/iTerm、Windows 的 PowerShell 或 WSL、Linux 的任意 shell
- 任一 Anthropic 身份：
  - 一个 Claude **Pro / Max 订阅账号**（含 claude.ai 邮箱登录），或
  - 一个 **Anthropic API Key**（在 Claude Console 生成），或
  - 企业 SSO / 云厂商凭证（Bedrock、Vertex，本教程仅作提示）
- 浏览器（首次登录需要完成 OAuth 跳转）

如果你连 Node 都没装，先去 nodejs.org 装 LTS 版，本教程不展开。

## 一、先搞清"三条路"：三种认证方式对比

Claude Code 不是只有一个入口。启动后它怎么"知道你是谁"，取决于你选择了下面三条路中的哪一条。理解这一步，能省掉后面 80% 的认证报错。

| 方式 | 谁给额度 | 计费模型 | 适合谁 |
|------|---------|---------|--------|
| **Claude 账号登录**（Pro/Max）| 订阅套餐包 | 月费固定，用量受套餐窗口限制 | 个人日常开发 |
| **API Key** | Console 充值额度 | 按 token 量计费 | 超额用户、自动化、CI |
| **企业 SSO / 云厂商** | 公司或云账户 | 由企业/云厂商结算 | 团队、合规环境 |

一个关键冷知识：**当环境变量 `ANTHROPIC_API_KEY` 存在时，Claude Code 会优先走 API Key 这条路**，而忽略你登录过的 Claude 账号。很多新手"明明登录了却报额度不足"，根因就是 shell 里残留了一个旧 key。记住这条规则，后面排查会很快。

## 二、步骤一：安装 Claude Code

打开终端，执行全局安装：

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

安装完成后验证：

```bash
claude --version
```

**预期结果**：返回一串版本号，如 `1.x.x`。

**常见问题**：

- *权限报错 `EACCES`*：不要 `sudo`，改用 Node 版本管理器（nvm）重装 Node，或把 npm 全局目录指到用户目录。
- *`command not found: claude`*：全局 bin 路径不在 `PATH` 里。运行 `npm config get prefix` 找到前缀，把其下的 `bin` 加入 `PATH`。
- *公司网络装不上*：配置 npm 镜像或代理后重试。

## 三、步骤二：Claude 账号登录（Pro / Max 订阅）

这是最省心的方式，适合刚订阅了 Pro 或 Max 的个人用户。

1. **先清掉可能残留的 API Key**（重要）：

   ```bash
   unset ANTHROPIC_API_KEY          # macOS / Linux
   # PowerShell 用户用：Remove-Item Env:ANTHROPIC_API_KEY
   ```

2. **在任意目录启动**：

   ```bash
   claude
   ```

3. **选择登录方式**：交互界面提示时选「Claude 账号订阅」(Log in with Claude)。终端会显示一个 URL 和一串验证码。
4. **浏览器跳转**：复制 URL 到浏览器打开，粘贴验证码，确认授权。浏览器提示成功后回到终端。
5. **回到终端**：自动完成登录，进入对话界面。

**预期结果**：终端进入 Claude Code 交互界面，左下角或 `/status` 显示已登录的账号与套餐。

**常见问题**：

- *浏览器打开了但没反应*：检查验证码是否完整复制（含前后空格会失败）。
- *登录后仍提示要 API Key*：99% 是 `ANTHROPIC_API_KEY` 还在环境里，回到第 1 步 `unset`，并检查 `~/.zshrc` / `~/.bashrc` 是否导出了它。
- *反复跳转 OAuth*：清空浏览器对 `claude.ai` 的 cookie 后重试。

## 四、步骤三：API Key 认证（按量计费）

当你的订阅额度用尽、或需要在 CI / 服务器上无头运行时，就走 API Key。

1. **生成 Key**：浏览器打开 Claude Console → Settings → API keys → Create Key。复制后妥善保存，**离开页面后无法再看到明文**。
2. **设置环境变量**：

   ```bash
   export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
   ```

   想持久化就写入 shell 配置：

   ```bash
   echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"' >> ~/.zshrc
   source ~/.zshrc
   ```

3. **用 settings.json 管理**（推荐给需要在多项目间切换密钥的人）。编辑 `~/.claude/settings.json`：

   ```json
   {
     "env": {
       "ANTHROPIC_API_KEY": "sk-ant-xxxxxxxx"
     }
   }
   ```

   也可以在项目根目录建 `.claude/settings.local.json` 存项目专属 key（**记得加入 `.gitignore`，切勿提交到 Git**）。

4. **验证**：再次启动 `claude`，执行 `/status`，应显示 API Key 模式与剩余额度。

**常见问题**：

- *`Invalid API key`*：检查是否多复制了空格、或把两个 key 拼接了。
- *Key 生效了但额度不足*：Console 账户需要先充值（Add credits）。
- *多人共用一台机器*：各自用项目级 `settings.local.json`，不要全局共用一把 key。

## 五、步骤四：看懂计费与额度

这是新手最容易踩坑的地方——"我都不知道自己花了多少"。

### 订阅制（Pro / Max）

- **不是无限用**。Pro 额度很小，适合试用；Max（如 5× / 20× 档位）才是日常主力。
- 额度按 **滚动时间窗口** 计算（典型为 5 小时滚动窗 + 每周上限）。接近上限会预警，超了就暂停到窗口重置。
- **上下文越大消耗越快**：把整个大仓库塞进会话，额度会肉眼可见地往下掉。

### 按量计费（API Key）

- 按 **token** 计费，输入与输出分别计价，不同模型档位价格不同（Sonnet 档与 Opus 档差数倍）。
- **Opus 档做长会话，烧钱很快**；日常优先用更经济的模型档。
- 没有硬性用量上限，但有账户消费上限（可在 Console 调整）。

### 怎么看额度

- **交互界面内**：用 `/status` 或 `/cost` 查看当前会话累计消耗。
- **Console 后台**：登录 console 查看用量曲线、剩余额度、账单明细。
- **经验法则**：如果你每月的 API 花费稳定低于订阅价，订阅更划算；如果经常撞订阅上限，迁到 API Key 更省心。

## 六、步骤五：切换账号与密钥管理

实际工作中你会在"账号登录"和"API Key"之间反复横跳，记住这条主线：**环境变量优先级最高**。

- 从 API Key **切回** 账号登录：

  ```bash
  unset ANTHROPIC_API_KEY
  claude /login        # 在交互界面里重新走 OAuth
  ```

- 从账号登录 **切到** API Key：设置好 `ANTHROPIC_API_KEY` 后直接启动即可。
- **多个项目用不同 key**：靠项目级 `.claude/settings.local.json` 覆盖全局设置，互不污染。
- **安全**：定期在 Console 轮换 key，删除不再使用的旧 key；任何含 key 的文件都不要进 Git。

## 七、认证排查清单（贴在显示器边）

- [ ] `claude --version` 能跑？→ 不能就先修 Node/安装。
- [ ] `ANTHROPIC_API_KEY` 是否残留？→ 想用账号登录就 `unset`。
- [ ] `/status` 显示的是预期的账号/模式吗？
- [ ] Console 里 key 是否还有效、账户是否欠费？
- [ ] 是否在公司网络里？代理/防火墙可能拦截 OAuth 跳转。
- [ ] 报错 `rate limit` / `quota exhausted`？→ 不是认证错，是额度用完，参考第五节。

## 八、实战案例：一个"认证自检"小项目

目标：写一个最小脚本，验证当前认证方式、消耗极少量 token，确认链路通畅。

1. 新建目录并进入：

   ```bash
   mkdir cc-auth-check && cd cc-auth-check
   ```

2. 启动 Claude Code 并让它做一件几乎不花钱的事：

   ```bash
   claude
   ```

3. 在交互界面输入：

   > 请读取当前目录（一个空目录），创建一个 `auth-check.txt`，里面写一句"认证成功 + 当前时间"。只做这一件事，不要多余操作。

4. **预期结果**：Claude Code 生成 `auth-check.txt`。整个过程只产生几千 token，几乎不消耗额度。

5. 执行 `/cost` 确认本次会话花费（订阅制通常显示 0 美元，按量制显示几分钱级别）。

6. **断网/换 key 后重跑**：故意 `unset ANTHROPIC_API_KEY` 再不重新登录，会看到认证失败的报错——这正是你要学会识别的错误形态。

这个练习的价值不在产物，而在于让你亲手把"认证→调用→计费→排错"四步走通一遍。

## 工作流程图

```text
flowchart TD
    A[启动 claude] --> B{环境里有 ANTHROPIC_API_KEY?}
    B -- 有 --> C[走 API Key 认证<br/>按 token 计费]
    B -- 无 --> D[/login OAuth 登录]
    D --> E[走订阅套餐额度<br/>Pro/Max 窗口限制]
    C --> F[/status 验证]
    E --> F
    F --> G{报错?}
    G -- 认证失败 --> H[查密钥/清残留/查网络]
    G -- 额度不足 --> I[Console 充值或换更经济档]
    G -- 正常 --> J[开始干活]
    H --> A
    I --> F
```

## 延伸阅读

- Claude Code 官方认证文档：`code.claude.com/docs/en/authentication`
- Claude Platform 的 API Key 与工作区管理：`platform.claude.com/docs/en/manage-claude/authentication`
- 订阅定价与套餐上限：`anthropic.com/pricing`
- 在 Stack Overflow 上用已有 API Key 跑 Claude Code 的社区讨论（含 `unset` 解法）
- Microsoft Foundry / 云厂商环境下配置 Claude Code 的官方指引

## 训练营适用性评估

- **适合类型**：面向个人开发者与企业新人的"入门 Day 1"训练营、AI 编程工具上手课、企业内部 Claude Code 推广培训。
- **预计教学时长**：1.5–2 小时（含实操认证自检与排错演练）。
- **难度**：低。无前置编程要求，会复制粘贴命令即可。
- **建议配套**：本节作为"开场认证篇"，后续可衔接配置文件（settings 四层）、权限管理、第一个真实项目等主题，形成完整 Day-1 上手闭环。
- **讲师注意点**：务必现场演示"`unset` 前后 `/status` 的变化"，这是学员最容易混淆的点；准备好一个可公开演示的测试 Key 或测试账号，避免学员用生产 Key 练手。

## 参考来源

1. [Authentication — Claude Code Docs](https://code.claude.com/docs/en/authentication) — 官方认证方式总览，含 Claude 账号登录与 API Key 直连说明
2. [Authentication — Claude Platform Docs](https://platform.claude.com/docs/en/manage-claude/authentication) — API Key 创建、工作区（workspaces）按项目隔离密钥的官方指引
3. [Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/) — 涵盖 Max 订阅、API Key、企业 SSO 三条认证路径的对照说明
4. [How do I use Claude Code with an existing Anthropic API Key? — Stack Overflow](https://stackoverflow.com/questions/79629224/) — 社区实践：用已有 API Key 替代 `/login` 流程及常见踩坑
5. [Configure Claude Code for Microsoft Foundry](https://learn.microsoft.com/en-us/azure/foundry/foundry-models/how-to/configure-claude-code) — 云厂商/企业环境下用 Claude Code 接入托管模型的配置参考

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