02. 安装与订阅

2.1 结论先行:三步上手

把 Claude Code 跑起来只需要三步,订阅按用量选:

装 Node.js 18+(推荐 20 LTS)——运行时依赖。
装 Claude Code——原生脚本(推荐)、Homebrew 或 npm 三选一。
认证——首次 claude 启动后选 Anthropic 账号登录(Pro/Max 订阅)或 API Key(按量付费)。

订阅选型一句话:轻度用选 Pro $20/月;重度编码选 Max $100(5x)或 $200(20x);脚本/CI 高吞吐或需精确控费走 API 按 token 付费。额度机制是 5 小时滚动窗口 + 周上限,不是月度配额。

macOS 上的最快路径(已有 Node.js):

bash

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

第一条装好 CLI,第二条进入交互会话并触发认证引导。下面逐步展开,每步给出命令、预期输出、验证方式与失败边界。

2.2 前置要求

运行时与平台

项	要求	说明
Node.js	18+,推荐 20 LTS	Claude Code v2.1.202+ 的硬性下限;18 以下会启动失败
平台	macOS / Linux / Windows	Windows 必须通过 WSL2 运行,原生 cmd/PowerShell 不在支持范围
网络	可访问 `claude.ai` 与 `api.anthropic.com`	受 GFW 限制的网络需要代理,见失败边界
Git	推荐安装	大量工作流依赖 `git diff`、`git status` 作为事实来源

验证 Node.js 版本

bash

node -v

预期输出(示例):

text

v20.18.0

验证:版本号 ≥ v18.0.0 即通过。推荐 v20.x LTS 或更高。

失败边界——版本不足或未安装:

text

zsh: command not found: node

或:

text

v16.20.0

处理方式是用版本管理器切换或安装。推荐 nvm(Node Version Manager),避免全局权限问题:

bash

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 重开终端或 source 配置后:
nvm install 20
nvm use 20
node -v   # 再次验证

Windows(WSL2)用户在 WSL 内执行同样的命令;不要在 Windows 侧装 Node.js 后再从 WSL 调用,路径与换行符会出问题。

2.3 三种安装方式

三种方式装出来的都是同一个 CLI,区别在依赖链与升级路径。推荐原生脚本:零依赖、自动处理二进制路径、升级最干净。Homebrew 适合已用 brew 管理工具链的 macOS 用户。npm 方式历史最久,但容易踩全局权限和路径问题。

方式一:原生脚本(推荐)

bash

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

预期输出(示例):

text

Downloading Claude Code...
Installing to /Users/mba/.local/bin/claude
Added /Users/mba/.local/bin to PATH (via ~/.zshrc)
Claude Code installed successfully.
Run `claude` to get started.

验证:

bash

claude --version

预期输出(示例):

text

2.1.202

版本号 ≥ 2.1.0 即通过。

失败边界:

网络失败 / curl 超时:curl: (28) Connection timed out。这是网络无法直连 claude.ai。处理:配置代理后重试——export https_proxy=http://127.0.0.1:7890 再执行脚本;或在可直连的环境中下载后离线执行。
PATH 未生效:装完仍报 command not found: claude。脚本会尝试写入 ~/.zshrc 或 ~/.bashrc,但当前 shell 未重载。处理:source ~/.zshrc 或重开终端;若仍未生效,手动 export PATH="$HOME/.local/bin:$PATH"。
升级:再次执行同一条脚本即覆盖升级;或进入会话后用 /update。

方式二:Homebrew

适合已用 brew 管理工具链的 macOS 用户,升级与卸载走 brew 统一流程。

bash

brew install claude-code

预期输出(示例):

text

==> Downloading https://ghcr.io/v2/homebrew/core/claude-code/manifests/2.1.202
==> Pouring claude-code--2.1.202.arm64_sonoma.bottle.tar.gz
==> Caveats
Claude Code is installed at /opt/homebrew/bin/claude
==> Summary
🍺  claude-code 2.1.202 already installed

验证:

bash

claude --version

失败边界:

Error: formulae ... not found:brew formula 索引过期。处理:brew update 后重试。
版本滞后:brew 版本可能落后官方几天到几周。需要最新版时回到方式一,或 brew upgrade claude-code。
Apple Silicon vs Intel:确保 brew 装在正确架构下。arch 确认;M 系列芯片不应混用 /usr/local/bin(Intel)与 /opt/homebrew/bin(ARM)。

方式三:npm 全局安装

历史最久的安装方式,适合已熟悉 npm 全局工具链的用户。

bash

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

预期输出(示例):

text

added 1 package in 3s

验证:

bash

claude --version

失败边界:

EACCES 权限拒绝:npm ERR! code EACCES。这是 npm 全局目录属主不是当前用户。不要用 sudo 安装(会引入权限与安全隐患)。处理:用 nvm 管理 Node.js(全局目录天然在用户家目录下),或修复 npm prefix:
bash
```
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code
```
全局路径未在 PATH:npm install -g 成功但 claude 找不到。用 npm config get prefix 查看全局安装位置,把其下的 bin 加入 PATH。
Node 版本不匹配导致的安装失败:engine 警告或 EBADENGINE。回到 2.2 节升级 Node.js。

三种方式对比

方式	依赖	升级	适用
原生脚本	零(自带二进制)	重跑脚本 / `/update`	默认推荐,隔离最干净
Homebrew	brew	`brew upgrade`	macOS 工具链统一管理
npm	Node.js + npm	`npm update -g`	已有 npm 全局工具链习惯

混装时注意:只保留一种安装源,避免两个 claude 二进制在 PATH 中互相覆盖。用 which -a claude 检查。

2.4 认证

首次执行 claude 会进入交互式认证引导:

bash

claude

引导会给出几个选项,不同版本的菜单文案略有差异,核心是三条路径:

路径一:Anthropic 账号登录(Pro / Max 订阅)

最常见的选择。浏览器会打开 claude.ai 授权页,登录后回到终端确认。认证完成后,CLI 使用订阅额度,不产生 API 费用。

适用:日常编码、个人开发者、已订阅 Claude Pro 或 Max 的用户。

注意:Pro 与 Max 的 Claude Code 额度与网页聊天共享,不是独立配额。重度使用 Agent 会消耗同一池子。

路径二:API Key(按量付费)

在引导中选择 API Key 方式,粘贴在 console.anthropic.com 生成的 Key(sk-ant-...);或预先设置环境变量:

bash

export ANTHROPIC_API_KEY="sk-ant-..."

建议写入 shell 配置(~/.zshrc)持久化,但不要把 Key 提交进任何仓库或日志。

适用:CI/CD、脚本自动化、需要精确控费、组织内部按用量结算、订阅额度不够时的补充。

路径三:Team / Enterprise

Team 方案需要管理员在 claude.ai/teams 创建组织并邀请成员,成员登录后自动归属组织。Enterprise 走 SSO 与合同制授权。

适用:团队统一计费、组织权限管理、企业合规要求(SSO、审计日志、数据驻留)。

验证认证是否成功:进入任意目录执行 claude,能正常进入交互会话且 /status 显示当前账号或 API Key 即通过。失败边界通常是网络不通(claude.ai / api.anthropic.com 不可达)或 Key 失效——前者配代理,后者在控制台重新生成。

2.5 订阅 tier 详解

截至 2026-07-08 核对,各档位如下。注意:市面流传的"Claude Code 单独计费 / 额度独立"是错误信息,Pro 与 Max 的 CC 额度与聊天共享。

档位	价格	Claude Code 支持	额度机制	适用场景
Pro	$20/月	含,额度与聊天共享	5h 滚动窗口 + 周上限	轻中度编码、个人学习
Max 5x	$100/月	含,5 倍 Pro 用量	同上,上限更高	日常重度 Agent 编码
Max 20x	$200/月	含,20 倍 Pro 用量	同上,上限最高	全天候 Agent 驱动开发
Team	$25/座/月	需升级 premium seat 才有 CC	团队共享池	团队协作、统一计费
Enterprise	定制	含,SSO + 审计	合同制	企业合规、大规模部署
API	按 token 付费	独立于订阅	无固定额度,按量结算	CI、脚本、精确控费

关键澄清:

Team $25/座默认不含 Claude Code,需要升级到 premium seat 才解锁 CC 权限。只买基础 Team 座位会发现 CLI 无法用订阅登录。
API 与订阅完全独立。同一个 Anthropic 账号可以同时有 Max 订阅(交互用)和 API Key(CI 用),两者计费分开,额度不互通。
Pro / Max 的 CC 额度与 claude.ai 聊天共享。在网页聊天里高强度对话会挤占 CC 可用额度,反之亦然。

额度机制:5 小时滚动窗口 + 周上限

额度不是"每月 N 条消息"这种简单配额,而是双层限制:

5 小时滚动窗口:当前时刻往前推 5 小时,这段时间内的用量决定你是否触顶。触顶后会进入只读/降速状态,直到窗口内用量滑出。
周上限:5 天左右的累计上限,即使每个 5h 窗口都没满,周累计到上限仍会受限。

实用推论:高强度 Agent 任务尽量分散在多个 5h 窗口,而不是一次性压满;遇到限额提示时,/status 可查看当前消耗状态。Max 5x 与 20x 的区别本质就是这两个上限的放大幅度。

API vs 订阅选型建议

维度	订阅(Pro/Max)	API
成本可预测性	固定月费,成本可预测	按量,高吞吐下可能更贵
适合的工作模式	交互式、探索性、多轮迭代	脚本、CI、批处理、结构化输出
额度限制	有 5h/周上限	无(只要账户余额足够)
模型与功能	全部模型,含订阅专属特性	全部模型,按 token 计费
控费粒度	粗	细(`--max-budget-usd`、`--max-turns`)

建议组合:日常交互用 Max 订阅,CI/自动化与突发需求用 API。个人开发者在 Pro 和 Max 5x 之间犹豫时,从 Pro 起步,连续两周触顶就升 Max。

2.6 首次配置

认证通过后,进入一个项目目录启动 claude,做四项基础配置。

`/init`:生成 CLAUDE.md

text

/init

Claude 会扫描当前项目,生成 CLAUDE.md 项目记忆文件,记录架构、命令、规则。生成后手动精简:只留长期稳定、每轮都可能用到的约束(测试命令、lint 命令、架构边界、红线),删掉泛泛而谈的模板话。CLAUDE.md 每轮可能进入上下文,塞太多会浪费 token。

`/permissions`:权限策略

text

/permissions

交互式查看与编辑当前权限。团队共享规则写入 .claude/settings.json,个人偏好写入 .claude/settings.local.json(不提交)。

推荐起步策略:只读操作(Read/Grep/Glob)与安全验证命令(npm test、npm run lint、git diff)设为 allow;有外部副作用的(git commit、curl)设为 ask;危险动作(git push、rm -rf、npm publish、读 .env)设为 deny。完整配置见第 1 章 1.5 节。

`/model`:选择模型

text

/model

弹出模型选择菜单。可选:sonnet(默认,均衡)、opus(最强推理)、haiku(最快最省)、fable(新型号,按需)。

日常编码默认 sonnet;复杂架构设计、难 Bug 切 opus;简单批量任务用 haiku 省额度。

`/effort`:调整推理强度

text

/effort

控制模型在回答前投入的推理深度。可选:low / medium / high / xhigh / max / ultracode。档位越高,单轮思考越深但消耗越大。

实用搭配:简单改动用 low/medium;复杂调试与重构用 high/xhigh;max 与 ultracode 留给极难问题,日常不要常驻,否则额度会快速耗尽。

Fast Mode

Fast Mode 基于 Opus 4.8,在同一模型下提供约 2.5 倍速度、约 1/3 成本,定价 $10 / $50 per M tokens(输入/输出)。适合需要 Opus 级别能力但希望更快更省的场景。具体开启方式以会话内 /status 或 /config 显示为准。Fast Mode 消耗的是 API 侧额度,与订阅额度关系以官方当前说明为准。

2.7 快速验证

在一个真实项目目录跑通三步,确认安装与认证完全可用。没有现成项目就新建一个:

bash

mkdir -p ~/cc-verify && cd ~/cc-verify
npm init -y

预期输出(示例):

text

Wrote to /Users/mba/claude/cc-verify/package.json:
{ "name": "cc-verify", "version": "1.0.0", ... }

启动 Claude Code:

bash

claude

第一步:读取 package.json

在交互会话中输入:

text

读取 package.json,告诉我项目名和入口文件。

预期(示例):

text

● Read(package.json)

项目名是 cc-verify,入口文件是 index.js(默认)。

验证:Claude 调用了 Read 工具读取真实文件,而不是凭空猜测。如果它直接回答但没显示 Read(package.json),可能在不读文件的情况下编造,要检查权限或明确要求"先读文件再回答"。

第二步:创建文件

text

创建 src/index.js,内容是一个打印 "hello from claude code" 的 Node 脚本。

预期(示例):

text

● Write(src/index.js)
   1  console.log("hello from claude code");

验证:退出会话后在终端检查:

bash

cat src/index.js

应看到文件内容与 Claude 报告的一致。

第三步:运行脚本

回到会话:

text

运行 node src/index.js,告诉我输出。

预期(示例):

text

● Bash(node src/index.js)

hello from claude code

验证:终端确实打印了 hello from claude code。三步全通,说明读取、写入、执行三类工具链路完整,安装与认证全部就绪。

失败边界速查

现象	根因	处理
`claude` 启动报 Node 版本错误	Node < 18	用 nvm 升级到 20 LTS
认证后立即报 401/403	API Key 失效或订阅不含 CC	控制台重生成 Key;Team 确认已升级 premium seat
额度触顶提示	5h 窗口或周上限用尽	`/status` 查看;等待窗口滑出或切 API Key
`Write` / `Bash` 被拦截	权限策略 deny 或 ask	`/permissions` 检查;确认 `.claude/settings.json` 配置
网络超时	无法直连 `api.anthropic.com`	配置 `https_proxy` 代理

上一章:前言与导读
下一章:核心心智模型与环境激活

02. 安装与订阅 ​

2.1 结论先行:三步上手 ​

2.2 前置要求 ​

运行时与平台 ​

验证 Node.js 版本 ​

2.3 三种安装方式 ​

方式一:原生脚本(推荐) ​

方式二:Homebrew ​

方式三:npm 全局安装 ​

三种方式对比 ​

2.4 认证 ​

路径一:Anthropic 账号登录(Pro / Max 订阅) ​

路径二:API Key(按量付费) ​

路径三:Team / Enterprise ​

2.5 订阅 tier 详解 ​

额度机制:5 小时滚动窗口 + 周上限 ​

API vs 订阅选型建议 ​

2.6 首次配置 ​

/init:生成 CLAUDE.md ​

/permissions:权限策略 ​

/model:选择模型 ​

/effort:调整推理强度 ​

Fast Mode ​

2.7 快速验证 ​

第一步:读取 package.json ​

第二步:创建文件 ​

第三步:运行脚本 ​

失败边界速查 ​

02. 安装与订阅

2.1 结论先行:三步上手

2.2 前置要求

运行时与平台

验证 Node.js 版本

2.3 三种安装方式

方式一:原生脚本(推荐)

方式二:Homebrew

方式三:npm 全局安装

三种方式对比

2.4 认证

路径一:Anthropic 账号登录(Pro / Max 订阅)

路径二:API Key(按量付费)

路径三:Team / Enterprise

2.5 订阅 tier 详解

额度机制:5 小时滚动窗口 + 周上限

API vs 订阅选型建议

2.6 首次配置

`/init`:生成 CLAUDE.md

`/permissions`:权限策略

`/model`:选择模型

`/effort`:调整推理强度

Fast Mode

2.7 快速验证

第一步:读取 package.json

第二步:创建文件

第三步:运行脚本

失败边界速查