<!-- title: 三种登录方式配通Claude Code首个脚本 -->

## 概述

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

---

## 前置条件

| 项目 | 要求 | 说明 |
|------|------|------|
| 操作系统 | macOS 13+ / Windows 10 1809+ / Ubuntu 20.04+ / Debian 10+ / Alpine 3.19+ | x64 或 ARM64 均可 |
| 内存 | 4 GB 以上 | |
| 网络 | 需要联网 | 受 Anthropic 支持的国家/地区 |
| Shell | Bash、Zsh、PowerShell 或 CMD | 任一即可 |
| Git | 建议安装 | Claude Code 依赖 git 做版本感知，且你需要它来管理生成的代码 |
| 账号 | Claude 订阅（Pro/Max）**或** Anthropic Console 账号**或**云厂商授权 | 三选一，详见认证章节 |

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

---

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

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

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

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

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

---

## 第一步：安装 Claude Code

### 推荐方式——原生安装

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

**macOS / Linux / WSL：**

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

**Windows PowerShell：**

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

**Windows CMD（不是 PowerShell）：**

```cmd
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。

### 备选方式

```bash
# 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`。

### 验证安装

```bash
claude --version
```

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

### 常见问题

| 现象 | 原因 | 解决 |
|------|------|------|
| npm 报权限错误（EACCES） | npm 全局目录归属不对 | 调整 npm 全局目录所有权，**不要**用 sudo 跑 npm |
| Windows 上 `&&` 报 "not a valid statement separator" | 你在 PowerShell 但用了 CMD 命令 | 用 `irm ... \| iex` |
| `irm` 报 "not recognized" | 你在 CMD 但用了 PowerShell 命令 | 用 CMD 那行 |
| curl 报 `syntax error near unexpected token '<'` 或 403 | 安装命令被代理/重定向拦截 | 见官方 Troubleshoot installation 页对照修复 |
| 旧终端找不到 `claude` 命令 | PATH 未刷新 | 关闭终端，**新开一个**再试 |

---

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

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

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

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

```text
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 密钥。两者日后随时可切换。

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

在项目目录运行：

```bash
claude
```

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

```
/logout
```

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

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

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

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

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

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

Windows PowerShell：

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

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

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

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

| 系统 | 存储位置 | 保护方式 |
|------|----------|----------|
| macOS | 系统钥匙串（Keychain） | 系统级加密 |
| Linux | `~/.claude/.credentials.json` | 文件权限 `0600`（仅属主可读写） |
| Windows | `%USERPROFILE%\.claude\.credentials.json` | 继承用户目录的访问控制 |

如果你设了 `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

按需授予最小权限。

---

## 第三步：第一个项目

### 创建项目骨架

```bash
mkdir hello-claude
cd hello-claude
git init
claude
```

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

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

```markdown
# 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 生成，也可手动放进去对照）：**

```javascript
// 随机编程笑话 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);
  }
})();
```

**验证步骤：**

```bash
node index.js
```

预期输出（内容随机）：

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

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

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

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

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

---

## 整体工作流程图

```mermaid
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（按官方当前定价）。

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合的训练营类型 | AI 编程入门营、企业内部 Claude Code 推广营、新人 Onboarding 营 |
| 学员基础 | 零基础可用，会开终端、会装软件即可 |
| 建议教学时长 | 1.5–2 小时（含动手配通第一个项目） |
| 关键考核点 | 能独立完成"安装→认证→跑通笑话脚本"三步，并解释自己选了哪种登录方式及原因 |
| 常见踩坑高发区 | SSH/WSL 浏览器登录、npm 权限、凭据存储位置——建议讲师重点演示 |
| 进阶衔接 | 本营结束后可接 CLAUDE.md 进阶、权限配置、MCP、Hooks 等主题营 |

---

## 延伸阅读

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

---

## 参考来源

1. [Authentication - Claude Code Docs](https://code.claude.com/docs/en/authentication) — 官方认证方式总览：订阅/Console/云厂商/网关登录、凭据存储与 apiKeyHelper 轮换机制
2. [Advanced setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 官方安装：系统要求、原生安装推荐命令、Homebrew/WinGet/npm、Windows 与 Alpine 细节、自动更新策略
3. [Claude CLI Setup Guide — Install, Authenticate, and Build Your First Project](https://www.genai-mentor.ai/blog/claude-code-cli-setup/) — 三前置条件 + 一条安装命令 + 认证流程 + 第一个真实任务的实战 walkthrough
4. [Getting Started with Claude Code in 2026: Setup to First Commit](https://septimlabs.com/blog/getting-started-with-claude-code-2026) — 五步 onboarding（Install/Auth/CLAUDE.md/First Task/Cost Check）与 CLAUDE.md 五要素模板
5. [Install Claude Code CLI: 5-Minute Setup Guide (2026)](https://blakecrosley.com/blog/claude-code-quickstart) — 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 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)