认证入门：跑通 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% 的认证报错。

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

二、步骤一：安装 Claude Code

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

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

安装完成后验证：

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 再不重新登录，会看到认证失败的报错——这正是你要学会识别的错误形态。

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

工作流程图

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 — 官方认证方式总览，含 Claude 账号登录与 API Key 直连说明
2. Authentication — Claude Platform Docs — API Key 创建、工作区（workspaces）按项目隔离密钥的官方指引
3. Authentication: API Keys, Subscriptions, and SSO — 涵盖 Max 订阅、API Key、企业 SSO 三条认证路径的对照说明
4. How do I use Claude Code with an existing Anthropic API Key? — Stack Overflow — 社区实践：用已有 API Key 替代 /login 流程及常见踩坑
5. Configure Claude Code for Microsoft Foundry — 云厂商/企业环境下用 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 等场景全覆盖。