## 概述
本教程面向零基础开发者，解决 Claude Code 入门阶段最容易被忽视却最致命的一环——**认证方式的选择与配置**。学完你将能：区分订阅制与 API 密钥制的本质差异、按需选择三种认证方式、完成原生安装与环境诊断、并让 Claude Code 真正读懂你的第一个项目而不是一上来就改崩代码。
## 前置条件
- 一台主流操作系统设备：macOS 13+、Ubuntu 20.04+/Debian 10+、Windows 10 1809+（强烈建议用 WSL）、或 Alpine 3.19+
- 内存 4GB 以上；Windows 用户需先装好 Git for Windows
- 一个可用的认证身份：Anthropic 账号（Pro/Max 订阅）或 Anthropic Console 的 API Key，二者有其一即可
- 基础终端操作能力（会 `cd`、`mkdir` 即可）
---
## 一、为什么认证方式是新手第一道坎
很多人装 Claude Code 失败，根子不在安装命令，而在认证这一步没理清。Claude Code 跑起来需要回答五个问题：**用哪个账号或平台调用、请求发到哪个接口、调用哪个模型、额度从哪里扣、有没有权限用这个模型**。认证方式决定了前四个。
Claude Code 官方文档明确了一条优先级规则：当你设置了 `ANTHROPIC_API_KEY` 环境变量后，它会作为 `X-Api-Key` 请求头发送，并**优先于** Claude Pro、Max、Team 或 Enterprise 订阅生效。这意味着——你以为是订阅在跑，其实是 API Key 在跑；你以为切回了订阅，其实环境变量还在偷偷接管。新手九成的"配了不生效""切了不切换"都栽在这条优先级上。
理解了这条规则，三种认证方式的定位就清晰了：
| 方式 | 适合谁 | 计费 | 是否需管 Key |
|------|--------|------|--------------|
| 订阅（Pro/Max） | 个人日常开发 | 月费，5小时滚动窗口 | 否，OAuth 登录 |
| Console API Key | 脚本/CI/固定配额 | 按量计费（按 token） | 是 |
| Teams/Enterprise | 团队、企业 | 合约 + SSO/合规 | 管理端下发 |
一条记忆口诀：**个人要省心用订阅，机器要稳定用 Key，团队要管控走企业。**
---
## 二、第一步：选择并安装 Claude Code
### 2.1 原生安装（推荐）
原生安装无需 Node.js，支持后台自动更新，是 2026 年的推荐路径：
```bash
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
```
### 2.2 npm 安装（已有 Node 环境）
若你已装 Node.js（建议 v18+），可直接走 npm：
```bash
# 国内可先换镜像加速
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code
```
另外也支持 `brew install --cask claude-code`（macOS）与 `winget install Anthropic.ClaudeCode`（Windows，需手动升级）。
### 2.3 装完先体检
```bash
claude doctor
```
`claude doctor` 会检查环境与安装状态——Node 版本、网络连通、认证状态、配置文件是否合法。**这一步比直接 `claude` 盲跑省下大量排错时间。** 预期输出是一张绿勾清单；任何红叉都指向具体问题。
常见问题与解决：
- **`command not found: claude`**：原生安装的路径未进 `PATH`。按 `claude doctor` 提示把对应 bin 目录加入 shell 配置（`~/.zshrc` 或 `~/.bashrc`）后 `source` 生效。
- **npm 全局装完仍找不到**：检查 `npm bin -g` 输出路径是否在 `PATH` 中。
- **Windows 提示脚本执行受限**：PowerShell 执行 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` 后重试。
---
## 三、第二步：三种认证方式配置
### 方式一：订阅（Pro/Max，推荐个人）
在终端执行 `claude` 或 `claude auth login`，按提示完成浏览器 OAuth 登录，登录那个绑定了 Pro/Max 订阅的 Anthropic 账号即可。**无需单独管理 API Key**，额度与网页版 Claude 共享同一池子，按 5 小时滚动窗口计。
参考定价（以官方定价页为准）：
| 方案 | 价格（约） | 每5小时消息（约） | 说明 |
|------|-----------|-------------------|------|
| Pro | $20/月 | ~45 条 | IDE 中仅 Sonnet，不可用 Opus |
| Max 5x | $100/月 | ~225 条 | 所有环境可用 Opus |
| Max 20x | $200/月 | ~900 条 | 最高优先级 |
要点：**5 小时窗口从第一条消息起算**，不是自然日；网页 Claude 与 Claude Code 共享额度；想在 IDE 里用 Opus 必须 Max。
### 方式二：Anthropic Console API Key（脚本/CI/固定配额）
获取路径：进入 Anthropic Console → 注册登录 → 完成验证 → Account Settings → API Keys → 创建 Key → 复制保存。可用 Workspaces 区分不同用途的 Key 并控制支出。
配置有三种粒度，从临时到持久：
```bash
# 临时：仅当前终端窗口有效
export ANTHROPIC_API_KEY="sk-ant-..."
claude
# 持久（zsh）
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc
# 持久（bash）
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc
```
Windows PowerShell：
```powershell
# 临时
$env:ANTHROPIC_API_KEY="sk-ant-..."
claude
# 永久（注意：仅对新开窗口生效！）
setx ANTHROPIC_API_KEY "sk-ant-..."
# 然后务必重开一个 PowerShell 窗口再测试
```
**新手最常踩的坑**：`setx` 执行后立即在旧窗口运行发现不生效——`setx` 只对新开的终端生效。
### 方式三：Teams/Enterprise 与第三方后端
企业用户通过 Claude for Teams/Enterprise 管理端配置团队账单、SSO、合规策略，或对接 Amazon Bedrock、Google Vertex AI、Microsoft Foundry 等云厂商。
对于处于网络受限地区、官方账号与支付经常卡住的开发者，可选的工程化方案是配置 `ANTHROPIC_BASE_URL` 指向一个兼容 Anthropic 协议的接口端点（如 OpenRouter），再配对应的 Token。其本质是让 Claude Code 把请求转发到指定地址：
```json
// ~/.claude/settings.json
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "sk-or-v1-xxxxxx",
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
"ANTHROPIC_MODEL": "anthropic/claude-sonnet-4.6"
},
"includeCoAuthoredBy": false
}
```
切到第三方后端前，建议先 `claude auth logout` 清除本地订阅凭据，避免认证混淆。
### 配置作用域与优先级
Claude Code 的配置分四个作用域，优先级从低到高：
| 作用域 | 路径 | 说明 |
|--------|------|------|
| User | `~/.claude/settings.json` | 当前用户全局，不随项目走 |
| Project | `.claude/settings.json` | 项目内共享，可提交 Git |
| Local | `.claude/settings.local.json` | 仅本机，通常 gitignore |
| Managed | 系统/策略下发 | 企业统一策略，不可覆盖 |
**优先级：User < Project < Local < 命令行 < Managed。** 一个典型项目级配置：
```json
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": ["Bash(npm run *)", "Read(~/.zshrc)"],
"deny": ["Read(./.env)", "Read(./secrets/**)"]
}
}
```
`permissions.allow/deny` 精确控制允许执行哪些 Bash 命令、允许读取哪些路径——这是把"驯服权限"前置到配置层的关键。
---
## 四、第三步：第一个项目（先分析，后动手）
**新手最大的失误是配完认证立刻拿大项目测试，导致上下文爆炸、请求超时。** 正确姿势是分三阶：
### 4.1 新建测试目录验证连通
```bash
mkdir claude-test && cd claude-test
claude
```
进入交互界面后先问最简单的问题：
```
帮我创建一个 Python hello world 示例，并解释代码。
```
预期：Claude 生成 `hello.py` 并逐行解释。能正常回复，说明认证与网络打通。
### 4.2 测试轻量代码任务
```
写一个 JavaScript 函数，判断字符串是否为空。
```
### 4.3 进入真实项目，先只读分析
```bash
cd your-project
claude
```
进入后**先下禁令**：
```
先不要修改代码，帮我看一下这个项目目录结构，并说明主要模块作用。
```
让 Claude 先建立对项目的整体认知，再逐步深入。配合 `/context` 查看它当前知道哪些文件，用 `/clear` 在换任务时清空上下文，用 `/compact` 在对话变长时压缩省 token。
### 4.4 用 CLAUDE.md 固化项目规范
在项目根目录或 `.claude/` 下放一个 `CLAUDE.md`，写清构建命令、架构约定、代码风格。Claude Code 每轮会话都会读取它——这是把"项目记忆"从口头重复变成配置的关键文件。仅本机的偏好放 `CLAUDE.local.md`。
---
## 五、实战案例：从零配通并让 Claude 读懂一个真实项目
目标：在一台 WSL Ubuntu 上，用 API Key 方式配通 Claude Code，并让它读懂一个 Python Flask 小项目，输出模块依赖图说明。
### 步骤 1：原生安装并体检
```bash
curl -fsSL https://claude.ai/install.sh | bash
claude doctor
```
### 步骤 2：配置 API Key（持久化）
```bash
echo 'export ANTHROPIC_API_KEY="sk-ant-你的Key"' >> ~/.bashrc
source ~/.bashrc
# 验证生效
echo $ANTHROPIC_API_KEY
```
### 步骤 3：连通性测试
```bash
mkdir claude-test && cd claude-test
claude
# 问：帮我创建一个 Python hello world 示例，并解释代码。
```
确认正常后退出。
### 步骤 4：进入真实项目，先分析
```bash
cd ~/my-flask-app
claude
```
输入：
```
先不要修改代码。请扫描项目目录结构，列出主要模块，
并说明 app.py、models/、routes/ 之间的调用关系，
最后用文字描述一张模块依赖关系图。
```
### 步骤 5：固化规范
在项目根创建 `CLAUDE.md`，写入：
```markdown
# 项目规范
- 技术栈：Python 3.11 + Flask
- 启动：flask --app app run --debug
- 测试：pytest tests/
- 风格：函数必须有 docstring，禁止裸 except
- 禁止修改 migrations/ 下已生成文件
```
### 步骤 6：权限护栏（可选但推荐）
在 `.claude/settings.json` 配置：
```json
{
"permissions": {
"allow": ["Bash(pytest *)", "Bash(flask *)", "Read(**.py)"],
"deny": ["Read(./.env)", "Read(./secrets/**)", "Bash(rm -rf *)"]
}
}
```
这样即便 Claude 想动 `.env` 或执行危险命令，也会被拦下。
### 步骤 7：开始结对编程
```
基于 CLAUDE.md 的规范，给 routes/auth.py 的登录函数补上 docstring，
并为它写一个 pytest 用例，不要改动现有逻辑。
```
至此，你完成了从认证决策、安装、配置、连通验证到真实项目落地的完整闭环。
---
## 整体工作流程
```mermaid
flowchart TD
A[开始:决定认证方式] --> B{需要固定配额/CI/脚本?}
B -- 是 --> C[方式二:API Key
Console生成Key]
B -- 否 --> D{个人日常开发?}
D -- 是 --> E[方式一:订阅OAuth
Pro或Max]
D -- 团队/企业 --> F[方式三:Teams/Enterprise
Bedrock/Vertex/Foundry]
C --> G[配 ANTHROPIC_API_KEY
环境变量或settings.json]
E --> H[claude auth login
浏览器OAuth]
F --> I[管理端SSO/策略下发]
G --> J[claude doctor 诊断]
H --> J
I --> J
J --> K{环境正常?}
K -- 否 --> L[排查:网络/Key/权限/PATH]
L --> J
K -- 是 --> M[新建测试目录
mkdir claude-test]
M --> N[问简单问题验证连通]
N --> O{回复正常?}
O -- 否 --> L
O -- 是 --> P[进入真实项目
先分析不改代码]
P --> Q[编写CLAUDE.md项目规范]
Q --> R[配置permissions权限护栏]
R --> S[开始结对编程]
```
---
## 六、常见问题排查
- **设了 Key 却仍走订阅**：`ANTHROPIC_API_KEY` 优先级最高。想用订阅必须先 `unset ANTHROPIC_API_KEY`（或删除 settings.json 里的 env 配置）。用 `echo $ANTHROPIC_API_KEY` 确认是否真的生效。
- **请求超时**：常见原因是 Base URL 写错（填成了网页地址而非 API 地址）、终端网络不通、模型名不支持、上下文过大、接口高峰拥堵。先用小问题测试，别一上来分析整库。
- **Key 无效或认证失败**：检查是否多复制了空格、Key 是否过期/被删、是否把官方 Key 和第三方 Base URL 混用。
- **Windows 配置不生效**：`setx` 只对新窗口生效，重开终端；仍不行则去系统环境变量手动添加。
- **VS Code 终端读不到变量**：完全关闭 VS Code 再重开，让终端重新加载环境变量。
- **想看当前到底用哪条认证**：会话内输入 `/status` 查看当前 API 地址与模型信息。
## 延伸阅读
- Claude Code 官方文档（安装、设置、命令全参考）：`docs.anthropic.com/en/docs/claude-code`
- Anthropic Console（生成 API Key、Workspaces、用量）：`console.anthropic.com`
- 官方定价页（订阅方案与 5 小时窗口细则）：`anthropic.com/pricing`
- Claude Code GitHub 仓库（release notes 与配置指南）：`github.com/anthropics/claude-code`
- 进阶：学会认证后，下一步可深入 CLAUDE.md 项目记忆体系、`/permission` 权限模式、以及 `-p` 无头模式接 CI
## 训练营适用性评估
- **适用类型**：零基础开发者入门营、AI 编程工具上手营、企业新员工 Onboarding 营。本教程是任何 Claude Code 系列课程的"地基课"——认证配不通，后面所有 Skill/MCP/Agent 内容都无从谈起。
- **教学时长**：建议 1.5–2 小时。其中概念讲解（认证优先级、三方式对比）30 分钟，动手安装与配置 45 分钟，实战案例走查 30–45 分钟。
- **前置衔接**：可作为系列第一课；后续可自然过渡到"权限驯服""CLAUDE.md 项目记忆""MCP 工具开发"等主题。
- **考核点**：学员能独立说明订阅与 Key 的优先级关系、完成 `claude doctor` 全绿、让 Claude 成功读懂一个陌生项目并输出结构说明（而非直接改代码）。
## 参考来源
1. [Claude Code 完全指南：安装、配置、认证与 OpenRouter 接入 — ZhiJun Blog](https://blog.zhijun.io/posts/claude-code-guide) — 系统要求、原生/npm 安装、三种认证方式、配置作用域与优先级、订阅定价表、OpenRouter 接入的完整参考
2. [Claude Code API Key 怎么获取和配置？ — 青蛙博客](https://qingwa.blog/2026/05/19/claude-code-api-key/) — API Key 优先级规则、Console 获取流程、跨平台环境变量配置、settings.json 用法与常见排错
3. [Claude Code 配置秘钥的完整指南：六种认证方式及差异详解 — CSDN](https://blog.csdn.net/m0_37988015/article/details/161275292) — 从个人到企业的认证体系与优先级顺序梳理
4. [Claude Code API 配置：订阅登录还是 API key，怎么选、怎么切 — w3cschool](https://www.w3cschool.cn/aicodingguide/claude-code-api-configuration.html) — 订阅与 API Key 的选择决策与切换方法
5. [Claude Code 官方文档 — Anthropic](https://docs.anthropic.com/en/docs/claude-code) — 安装、settings.json、权限与环境变量的权威定义来源
> [!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 等场景全覆盖。
