Claude Code 安装与配置完整教程：Windows、macOS、服务器
从零装好 Claude Code：环境要求、npm 安装、三种认证方式、把请求指向兼容端点、常用命令与省钱设置，附 6 个高频报错的对应解法。
Claude Code 是 Anthropic 官方出的终端 Agent：不像补全插件那样等你打几个字，它自己读文件、改代码、跑测试、看报错再改。装好之后，很多「读代码 + 改一处 + 验证」的活可以直接一句话交代。
安装本身只有一条命令，麻烦的是认证和网络。这篇从环境检查写到排错，按顺序照做就行。
一、先确认环境
| 项目 | 要求 | 检查命令 |
|---|---|---|
| Node.js | 18 或更高 | node -v |
| npm | 随 Node 一起装 | npm -v |
| 操作系统 | macOS / Linux 原生支持；Windows 走 WSL | wsl -l -v |
| 终端 | 支持 ANSI（Windows 用 Windows Terminal，别用 cmd 老窗口） | — |
Node 版本不够就先升：
# macOS（用 nvm 最省事）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20 && nvm use 20
# Windows：在 WSL 里装，命令相同
wsl --install -d Ubuntu二、安装
npm install -g @anthropic-ai/claude-code
claude --version如果 npm install 卡在 idealTree 阶段，先换源：
npm config set registry https://registry.npmmirror.com装完在项目根目录执行 claude，第一次会引导你选择认证方式。
三、三种认证方式
1. 官方账号登录
claude 启动后选登录，浏览器走 OAuth 授权。需要 Claude 订阅（Pro / Max）或 API 余额。国内网络环境下这一步最容易超时。
2. API Key（官方）
export ANTHROPIC_API_KEY="sk-ant-xxxx"
claude3. API Key + 兼容端点（国内常用）
把请求指向支持 Anthropic 原生协议的服务，只改 base_url 和环境变量名：
export ANTHROPIC_BASE_URL="https://api.zaimod.com"
export ANTHROPIC_AUTH_TOKEN="sk-你的zaimod密钥"
claude注意两个细节：ANTHROPIC_BASE_URL 不要带 /v1（Claude Code 会自己拼 /v1/messages）；部分版本读 ANTHROPIC_AUTH_TOKEN 而不是 ANTHROPIC_API_KEY，两个都设上最稳。
想长期生效，写进 ~/.claude/settings.json：
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.zaimod.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
"ANTHROPIC_MODEL": "claude-sonnet-5",
"ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4"
}
}ANTHROPIC_SMALL_FAST_MODEL 是后台任务（生成标题、判断意图）用的小模型，把它设成便宜的型号，一个月能省掉三成成本。
四、常用命令
| 命令 | 作用 |
|---|---|
claude | 进入交互模式 |
claude -p "总结这个仓库的入口" | 单次执行，输出到 stdout，适合脚本调用 |
claude -c | 继续上一次会话 |
/init | 扫描仓库生成 CLAUDE.md（项目说明书） |
/clear | 清空上下文，长任务之间必用 |
/compact | 压缩上下文，保留结论丢弃细节 |
/review | 审查当前 diff |
claude --output-format json -p "..." | 输出结构化 JSON，便于管道处理 |
真正的效率差别在 CLAUDE.md。执行 /init 之后，把这几件事补进去：
- 项目结构和关键目录的一句话说明
- 构建、测试、lint 的准确命令（它不会猜，写清楚就不用反复试）
- 代码风格约定：命名、目录分层、禁止事项
- 不要碰的目录（生成的产物、迁移脚本）
写好之后，它每次动手前都会读这个文件，比你在对话里解释十遍都省事。
五、省钱设置
Claude Code 的成本主要来自上下文：它每轮都要读文件、看 diff。四个开关最有效：
/clear用得勤：一个任务结束就清，别让无关历史占着 token- 小模型干杂活：
ANTHROPIC_SMALL_FAST_MODEL指向 haiku 系列 - 指定文件而不是目录：说「改 src/api/client.ts」，别说「看看 src」
- 用
/compact而不是硬撑：长任务到后半段，压缩比继续堆历史便宜得多
按 claude-sonnet-5（$4 / $20 每百万 tokens）估算，一次中等规模的重构大约消耗 15 万输入 + 2 万输出 tokens，成本约 1 美元。同一件事如果用官方订阅额度，通常更划算——前提是你付得起订阅。
六、高频报错对照
| 现象 | 原因 | 解决 |
|---|---|---|
401 Invalid API key | Key 错、未启用，或用了 ANTHROPIC_API_KEY 但服务端只认 AUTH_TOKEN | 两个变量都设，重新 claude |
404 not found | ANTHROPIC_BASE_URL 多了 /v1 | 去掉 /v1 后重试 |
429 rate limit | 触发限流 | 降低并发，等 60 秒；长期方案见下文 |
Connection error / 超时 | 网络或代理拦截 | 检查代理环境变量，HTTPS_PROXY 是否影响 API 域名 |
装了但 claude: command not found | npm 全局 bin 不在 PATH | npm bin -g 查路径，加进 PATH |
| WSL 里中文乱码 | 终端编码 | export LANG=zh_CN.UTF-8 |
429 的根因和系统性解法（退避重试、并发池、降级链）单独写了一篇：大模型 API 429 报错：原因、重试与并发调优。
七、什么时候不该用 Claude Code
它不是万能的。三类任务不适合：
- 一行改动：直接编辑比描述需求更快
- 强规范的老项目：风格约束写不进 CLAUDE.md 的，它会持续产出需要返工的代码
- 需要跑很久的重构：上下文会被压缩，中途丢细节，不如拆成小任务
判断标准：如果这件事你要跟同事解释五分钟以上，它大概也做不好；如果一句话能说清、但手工要改十个文件，它最擅长。
八、三个高频工作流
工作流一：接手陌生仓库。 进目录先 /init，然后问「这个项目的入口在哪，请求从进来到返回经过哪些层」。让它边读边画调用链，比自己翻目录快得多。读完的结论建议让它写进 CLAUDE.md，下次直接复用。
工作流二：改一个跨文件的 bug。 把复现步骤、报错堆栈、期望行为一次说完，不要挤牙膏。它定位后会自己改多个文件并跑测试；改完让它输出 diff 摘要，人只审关键改动。
claude -p "修复 src/api/retry.ts 里 429 重试没有退避的问题，
复现：并发 8 个请求必然触发限流。要求：指数退避+抖动，跑通 npm test" \
--output-format json工作流三：批量代码审查。 这条已经写成完整流水线（pre-commit 拦本地问题、CI 审 PR、夜间扫全仓），配置和成本账见 Claude API 代码审查流水线：从 hook 到 CI，这里不重复。
三个工作流的共同点：任务边界清晰、验收标准明确。满足这两条，它基本不会跑偏。
延伸阅读
- Claude API 代码审查流水线：从 hook 到 CI
- Cursor / Cline / Cherry Studio 接入自定义 API 中转的完整配置
- Cursor、Copilot 与自接 API 的成本账：Tab 补全怎么算