概述

本教程面向零基础开发者，用不到 20 分钟把 Claude Code 从"听说过"变成"能跑通"。核心聚焦在多数新手卡住的环节——认证：订阅账号、API 密钥、云厂商三种登录方式怎么选、凭据到底存在哪、SSH/容器里浏览器打不开怎么办。最后用一个可运行的 Node.js 命令行小工具作为验证项目，跑通即代表环境配通。学完你将掌握：安装、认证决策、凭据安全、第一个项目落地。

前置条件

重要提示：从 2026 年起，官方已将原生安装（Native Install）列为推荐方式，npm 全局安装仍是可用回退路径。下文以原生安装为主线，npm 作为补充。

核心认知：Claude Code 不是聊天框

在动手之前，先纠正一个普遍误解。Claude Code 不是网页版那个对话框——它是一个运行在你终端里的智能体（agent）：能读你的文件系统、执行 bash 命令、编辑文件、运行测试，然后根据结果自己循环迭代，直到任务完成。

这个差异直接决定了你该怎么用它：

• ❌ 模糊指令："帮我搞一下我的项目" → 模型会到处乱翻、消耗 token、产出漂移
• ✅ 精确指令："给 src/api/users.ts 里的 createUser 函数加输入校验，并更新对应测试" → 直接产出可用结果

记住这条，后面写第一个任务时会用上。

第一步：安装 Claude Code

推荐方式——原生安装

原生安装会自动后台更新，让你始终停留在最新版本，无需手动 upgrade。

macOS / Linux / WSL：

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

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

Windows CMD（不是 PowerShell）：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

怎么区分自己在 PowerShell 还是 CMD？提示符带 PS C:\ 的是 PowerShell，只有 C:\ 的是 CMD。irm 报错说明你在 CMD；&& 报错说明你在 PowerShell。

备选方式

# Homebrew（注意：不会自动更新，需手动 brew upgrade）
brew install --cask claude-code          # 稳定通道，约滞后一周
brew install --cask claude-code@latest   # 最新通道

# WinGet（同样不会自动更新）
winget install Anthropic.ClaudeCode

# npm（经典方式，仍可用）
npm install -g @anthropic-ai/claude-code

两个 Homebrew cask 的区别：claude-code 跟稳定版（跳过有重大回退的版本），claude-code@latest 跟最新版。Alpine 等 musl 系发行版需先装 libgcc、libstdc++、ripgrep，并设 USE_BUILTIN_RIPGREP=0。

验证安装

claude --version

预期输出类似 claude-code 1.x.x。看到版本号即安装成功。

常见问题

第二步：认证（本文核心）

安装完只是装好了"引擎"，还要给它"加油"——也就是认证。这是新手最容易卡住的一步，下面拆透。

一、先做决策：用哪种登录方式？

Claude Code 支持多种认证方式，按你的身份选：

flowchart TD
    A[首次运行 claude] --> B{你是谁？}
    B -->|个人开发者| C{已订阅 Claude？}
    C -->|有 Pro/Max 订阅| D[浏览器登录 Claude.ai 账号]
    C -->|按量付费更划算| E[Console 生成 API Key<br/>设 ANTHROPIC_API_KEY]
    B -->|团队成员| F{公司怎么采购？}
    F -->|Teams/Enterprise 计划| G[用管理员邀请的 Claude.ai 账号登录]
    F -->|走 API 计费| H[Console 邀请<br/>分配 Claude Code 角色]
    B -->|走云厂商| I[设 Bedrock/Vertex/Foundry<br/>环境变量，无需浏览器]
    B -->|内网自建网关| J[/login 用企业 SSO 登录]

    D --> K[认证完成]
    E --> K
    G --> K
    H --> K
    I --> K
    J --> K

三种主流方式怎么选：

1. 订阅账号（最简单） —— 已有 Claude Pro/Max 的人首选。浏览器 OAuth 一次，按月固定费用，适合每天高频使用。
2. API 密钥（最灵活） —— 去 console.anthropic.com 充值后生成 key，按 token 量计费。适合想把花费绑定到具体项目、或在共享机器/CI 上使用。
3. 云厂商（最企业） —— 公司用 Amazon Bedrock / Google Vertex AI / Microsoft Foundry 时，设好环境变量即可，无需浏览器登录。

订阅 vs API 的判断标准：如果你愿意为不限量的日常使用每月固定付 $20–$100，选订阅；如果你想把用量挂在某个余额上、按项目结算，选 API 密钥。两者日后随时可切换。

二、浏览器登录（默认流程）

在项目目录运行：

claude

首次启动会自动打开浏览器让你登录。完成后凭据会保存到 ~/.claude/，后续无需重复登录。要切换账号或重新认证，输入：

/logout

三、SSH / 容器 / WSL 里浏览器打不开怎么办

这是远程开发最常见的坑。两个应急动作：

1. 复制登录链接 —— 当浏览器没自动弹出时，按 c 把登录 URL 复制到剪贴板，再手动粘到本地浏览器打开。
2. 粘贴登录码 —— 如果登录后浏览器显示一段 code 而不是自动跳回，把这段 code 粘到终端的 Paste code here if prompted 提示处。这种情况发生在浏览器无法访问 Claude Code 本地回调服务器时，WSL2、SSH 会话、容器里特别常见。

四、纯 API 密钥路径（无浏览器环境）

在 CI、headless 服务器、容器里没有浏览器，直接走环境变量：

export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"

Windows PowerShell：

$env:ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"

别把密钥写进代码或提交进 git。配合 .env + .gitignore，或用密钥管理服务。

五、一个多数人忽略的真相：凭据到底存在哪？

知道凭据存在哪，既是安全意识，也是排错前提。Claude Code 按操作系统分别存储：

如果你设了 CLAUDE_CONFIG_DIR 环境变量，凭据文件会改存在那个目录下。要走自定义 API 端点，设 ANTHROPIC_BASE_URL（不是改凭据文件）。

六、团队场景：密钥自动轮换（apiKeyHelper）

企业里 API key 不能明文长期存放，需要定期轮换。Claude Code 提供 apiKeyHelper 设置：指定一个 shell 脚本，让它返回 API key。默认每 5 分钟或收到 HTTP 401 时调用一次刷新；可用 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 自定义刷新间隔；脚本超过 10 秒未返回会弹出警告。

Console 团队邀请时还有两种角色可选，权限不同：

• Claude Code 角色 —— 只能创建 Claude Code 专用 API key
• Developer 角色 —— 可创建任意类型 API key

按需授予最小权限。

第三步：第一个项目

创建项目骨架

mkdir hello-claude
cd hello-claude
git init
claude

写 CLAUDE.md——给模型"项目说明书"

在项目根放一个 CLAUDE.md，是省 token、提质量的关键。没有它，模型会把 token 花在"猜上下文"上。一份最小但有效的 CLAUDE.md 应覆盖五点：技术栈、命令、规则、禁止项。示例：

# Project: hello-claude

## Stack
- Runtime: Node 20
- Tests: 内置 node:test

## Commands
- 运行: `node index.js`
- 测试: `npm test`

## Rules
- 所有输出使用中文注释
- 网络请求必须做超时和错误处理

## Do not
- 未经询问不要 npm install 新包
- 不要修改 .env 文件

下达一个精确任务

进入 Claude Code 后，粘贴下面这种有边界的任务（而不是"帮我做个项目"）：

创建一个 Node.js 脚本：从公开的 Joke API 获取一条随机编程笑话，
格式化打印到终端。要求做超时和错误处理，并写一份说明如何运行的 README。

模型会规划、生成 index.js 和 README.md、解释运行方式。任务完成即代表环境完全配通。

实战案例：可运行的"随机笑话"CLI 工具

把上面的任务展开成一个完整可跑的项目，作为认证配通的最终验证。

项目结构：

hello-claude/
├── index.js
├── README.md
└── package.json

index.js（你可以直接让 Claude Code 生成，也可手动放进去对照）：

// 随机编程笑话 CLI 工具
const https = require('https');

const URL = 'https://official-joke-api.appspot.com/jokes/programming/random';
const TIMEOUT_MS = 5000;

function fetchJoke() {
  return new Promise((resolve, reject) => {
    const req = https.get(URL, (res) => {
      let data = '';
      res.on('data', (chunk) => (data += chunk));
      res.on('end', () => {
        try {
          const json = JSON.parse(data);
          resolve(Array.isArray(json) ? json[0] : json);
        } catch (e) {
          reject(new Error('解析笑话失败：' + e.message));
        }
      });
    });
    req.on('error', reject);
    req.setTimeout(TIMEOUT_MS, () => {
      req.destroy(new Error(`请求超时（${TIMEOUT_MS}ms）`));
    });
  });
}

(async () => {
  try {
    const joke = await fetchJoke();
    console.log('\n🤣 编程笑话');
    console.log('问：' + joke.setup);
    console.log('答：' + joke.punchline + '\n');
  } catch (err) {
    console.error('❌ 获取失败：', err.message);
    process.exit(1);
  }
})();

验证步骤：

node index.js

预期输出（内容随机）：

🤣 编程笑话
问：为什么程序员喜欢暗色主题？
答：因为光会吸引 bug。

看到格式化输出，说明三件事同时成立：Node 环境 OK、网络出站 OK、Claude Code 配通且能产出可运行代码。

接着交给 Claude Code 做迭代增强（验证 agentic 循环）：

给 index.js 加 --count 参数，支持一次获取多条笑话；并补一个 package.json 的 bin 字段，
让我能全局安装后用 telljoke 命令调用。

模型会自动读文件、改代码、解释安装方式——这就是"智能体循环"在真实项目里的样子。

整体工作流程图

flowchart LR
    A[检查前置条件<br/>Node/Git/账号] --> B[原生安装<br/>install.sh / install.ps1]
    B --> C[claude --version<br/>验证]
    C --> D{认证方式}
    D -->|订阅| E1[浏览器 OAuth 登录]
    D -->|API Key| E2[设 ANTHROPIC_API_KEY]
    D -->|云厂商| E3[设 Bedrock/Vertex/Foundry 环境变量]
    E1 --> F[凭据存入<br/>Keychain / 0600 文件]
    E2 --> F
    E3 --> F
    F --> G[mkdir + cd + claude]
    G --> H[写 CLAUDE.md<br/>项目说明书]
    H --> I[下达精确任务]
    I --> J[模型规划+生成+迭代]
    J --> K[运行验证<br/>node index.js]
    K --> L[Console 查费用]

成本意识：第一次跑完务必看一眼 Console

Pro 订阅含月度 token 额度，覆盖中度个人使用。但如果你在大代码库、写大量测试、或在循环里跑，很容易触顶，需要补 API 额度。第一次几次会话后，去 Anthropic Console 实时看用量，校准你的使用强度。API 路径下大致量级：Sonnet 每 1K 输出 token 约 $0.003（按官方当前定价）。

训练营适用性评估

延伸阅读

• 官方 Authentication 文档（多账号类型、凭据存储、apiKeyHelper）
• 官方 Advanced setup（原生安装、版本管理、平台细节）
• 官方 Quickstart 与终端指南（首次会话引导）
• 第三方实战指南（genai-mentor、septimlabs 的 2026 配通 walkthrough）
• 官方 Troubleshoot installation and login（错误对照表）

参考来源

1. Authentication - Claude Code Docs — 官方认证方式总览：订阅/Console/云厂商/网关登录、凭据存储与 apiKeyHelper 轮换机制
2. Advanced setup - Claude Code Docs — 官方安装：系统要求、原生安装推荐命令、Homebrew/WinGet/npm、Windows 与 Alpine 细节、自动更新策略
3. Claude CLI Setup Guide — Install, Authenticate, and Build Your First Project — 三前置条件 + 一条安装命令 + 认证流程 + 第一个真实任务的实战 walkthrough
4. Getting Started with Claude Code in 2026: Setup to First Commit — 五步 onboarding（Install/Auth/CLAUDE.md/First Task/Cost Check）与 CLAUDE.md 五要素模板
5. Install Claude Code CLI: 5-Minute Setup Guide (2026) — npm 一条命令安装、认证、CLAUDE.md/权限/成本快速配通

[!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 等场景全覆盖。