概述

本教程面向零基础开发者，解决 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，团队要管控走企业。

二、第一步：选择并安装 Claude Code

2.1 原生安装（推荐）

原生安装无需 Node.js，支持后台自动更新，是 2026 年的推荐路径：

# 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：

# 国内可先换镜像加速
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 装完先体检

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 小时窗口从第一条消息起算，不是自然日；网页 Claude 与 Claude Code 共享额度；想在 IDE 里用 Opus 必须 Max。

方式二：Anthropic Console API Key（脚本/CI/固定配额）

获取路径：进入 Anthropic Console → 注册登录 → 完成验证 → Account Settings → API Keys → 创建 Key → 复制保存。可用 Workspaces 区分不同用途的 Key 并控制支出。

配置有三种粒度，从临时到持久：

# 临时：仅当前终端窗口有效
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：

# 临时
$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 把请求转发到指定地址：

// ~/.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 < Project < Local < 命令行 < Managed。 一个典型项目级配置：

{
  "$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 新建测试目录验证连通

mkdir claude-test && cd claude-test
claude

进入交互界面后先问最简单的问题：

帮我创建一个 Python hello world 示例，并解释代码。

预期：Claude 生成 hello.py 并逐行解释。能正常回复，说明认证与网络打通。

4.2 测试轻量代码任务

写一个 JavaScript 函数，判断字符串是否为空。

4.3 进入真实项目，先只读分析

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：原生安装并体检

curl -fsSL https://claude.ai/install.sh | bash
claude doctor

步骤 2：配置 API Key（持久化）

echo 'export ANTHROPIC_API_KEY="sk-ant-你的Key"' >> ~/.bashrc
source ~/.bashrc
# 验证生效
echo $ANTHROPIC_API_KEY

步骤 3：连通性测试

mkdir claude-test && cd claude-test
claude
# 问：帮我创建一个 Python hello world 示例，并解释代码。

确认正常后退出。

步骤 4：进入真实项目，先分析

cd ~/my-flask-app
claude

输入：

先不要修改代码。请扫描项目目录结构，列出主要模块，
并说明 app.py、models/、routes/ 之间的调用关系，
最后用文字描述一张模块依赖关系图。

步骤 5：固化规范

在项目根创建 CLAUDE.md，写入：

# 项目规范
- 技术栈：Python 3.11 + Flask
- 启动：flask --app app run --debug
- 测试：pytest tests/
- 风格：函数必须有 docstring，禁止裸 except
- 禁止修改 migrations/ 下已生成文件

步骤 6：权限护栏（可选但推荐）

在 .claude/settings.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 用例，不要改动现有逻辑。

至此，你完成了从认证决策、安装、配置、连通验证到真实项目落地的完整闭环。

整体工作流程

flowchart TD
    A[开始:决定认证方式] --> B{需要固定配额/CI/脚本?}
    B -- 是 --> C[方式二:API Key<br/>Console生成Key]
    B -- 否 --> D{个人日常开发?}
    D -- 是 --> E[方式一:订阅OAuth<br/>Pro或Max]
    D -- 团队/企业 --> F[方式三:Teams/Enterprise<br/>Bedrock/Vertex/Foundry]
    C --> G[配 ANTHROPIC_API_KEY<br/>环境变量或settings.json]
    E --> H[claude auth login<br/>浏览器OAuth]
    F --> I[管理端SSO/策略下发]
    G --> J[claude doctor 诊断]
    H --> J
    I --> J
    J --> K{环境正常?}
    K -- 否 --> L[排查:网络/Key/权限/PATH]
    L --> J
    K -- 是 --> M[新建测试目录<br/>mkdir claude-test]
    M --> N[问简单问题验证连通]
    N --> O{回复正常?}
    O -- 否 --> L
    O -- 是 --> P[进入真实项目<br/>先分析不改代码]
    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 — 系统要求、原生/npm 安装、三种认证方式、配置作用域与优先级、订阅定价表、OpenRouter 接入的完整参考
2. Claude Code API Key 怎么获取和配置？ — 青蛙博客 — API Key 优先级规则、Console 获取流程、跨平台环境变量配置、settings.json 用法与常见排错
3. Claude Code 配置秘钥的完整指南：六种认证方式及差异详解 — CSDN — 从个人到企业的认证体系与优先级顺序梳理
4. Claude Code API 配置：订阅登录还是 API key，怎么选、怎么切 — w3cschool — 订阅与 API Key 的选择决策与切换方法
5. Claude Code 官方文档 — Anthropic — 安装、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 等场景全覆盖。