背景

Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手，可以直接在终端里帮你写代码、查 bug、读项目。但因为它走的是 Anthropic 官方 API，国内用户直接使用有门槛。我在自己的 Windows 电脑和云服务器（Linux）上都跑通了，也帮几个朋友配置过，发现整个过程对于不熟悉命令行的同学来说，坑还挺多的。本文从一台新电脑的视角出发，手把手带你装好 Claude Code，并接入第三方 API 中转服务，让国内用户也能流畅使用。

本文将覆盖：Windows、Mac、Linux 三个平台。

1 前置准备：安装 Node.js

Claude Code 是通过 npm 分发的，npm 是 Node.js 自带的包管理器。所以第一步：装 Node.js。

Claude Code 目前要求 Node.js ≥ 22.0.0，建议直接装最新的 LTS 版本。

1.1 Windows 安装

1）打开 Node.js 官网：https://nodejs.org

2）下载左边的 LTS 版本（长期支持版），右边是最新版也可以用，但 LTS 更稳。你会得到一个 .msi 安装包，比如 node-v22.x.x-x64.msi。

3）双击运行安装包，一路点 "Next" 就行。注意这一步：在安装选项页面，确保 "Add to PATH" 是勾选状态（默认就是勾的），这样才能在任意位置使用 node 和 npm 命令。

4）安装完成后，验证一下。按 Win + R，输入 cmd 回车，打开命令提示符，输入：

node --version
npm --version

如果分别输出 v22.x.x 和 10.x.x，说明安装成功。

1.2 Mac 安装

Mac 推荐用 Homebrew，一行搞定。如果你还没有 Homebrew，先去 https://brew.sh 复制那行安装命令跑一遍。

# 安装 Node.js
brew install node

# 验证
node --version
npm --version

如果你习惯用 nvm 管理 Node 版本，也可以 nvm install 22，效果一样。对小白来说 Homebrew 就够。

1.3 Linux 安装

以 Ubuntu/Debian 为例：

# 添加 NodeSource 源（Node.js 22.x）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装
sudo apt-get install -y nodejs

# 验证
node --version
npm --version

CentOS/RHEL 用对应的 yum 源；其他发行版请参考 NodeSource 官方文档。装完验证版本号，确保 ≥ 22。

2 安装 Claude Code

Node.js 就位后，打开终端（Windows 是 cmd 或 PowerShell，Mac/Linux 是 Terminal），执行一行命令：

2.1 通过 npm 全局安装

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

-g 表示全局安装，装完后在任意目录都能使用 claude 命令。

安装过程大概 1-2 分钟，取决于网络速度。如果下载很慢，可以先设置 npm 镜像：

# 可选：设置淘宝镜像加速下载
npm config set registry https://registry.npmmirror.com

# 然后再安装
npm install -g @anthropic-ai/claude-code

2.2 验证安装

claude --version

如果输出版本号（如 2.1.217），说明安装成功。

3 接入第三方 API

这是本文最核心的部分。Claude Code 默认连的是 Anthropic 官方 API（https://api.anthropic.com），需要海外信用卡和网络。国内用户可以通过 API 中转服务（也叫 API Proxy / API 网关）来使用，原理很简单：

你的 Claude Code → 中转服务器 → Anthropic 官方 API → 中转服务器 → 你的 Claude Code

你只需要一个中转服务的 API Key 和一个 Base URL，就能跟官方一样使用。

3.1 获取中转 API 地址和 Key

市面上有多个中转服务商，比如 APIHub、AIHubMix、LobeChat 网关、CloudFlare Worker 自建等，选一个注册获取：

• Base URL：类似 https://your-api-proxy.com 的地址
• API Key：类似 sk-xxxxxxxxxxxxxxxxxxxxxxxx 的密钥
• 模型名称：中转服务会告诉你可以用哪些模型，比如 claude-sonnet-4-20250514

[!warning] 注意
不要把 API Key 发给任何人，不要贴到公开的 GitHub 仓库里。Key 泄露会被盗刷。

3.2 配置 settings.json

Claude Code 的配置统一放在 settings.json 里。这个文件有两级：

推荐先配置用户级，这样不管在哪个目录用 Claude Code，都能用同一个中转 API。

步骤 1：找到或创建配置文件

.claude 文件夹在用户主目录下，不同系统的路径：

• Windows：C:\Users\你的用户名\.claude\
• Mac / Linux：~/.claude/

如果该目录不存在，自己创建：

# Windows (PowerShell)
mkdir $env:USERPROFILE\.claude

# Mac / Linux
mkdir -p ~/.claude

步骤 2：编写 settings.json

在 .claude/ 目录下新建 settings.json，写入以下内容：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-api-proxy.com",
    "ANTHROPIC_API_KEY": "sk-your-api-key-here",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "model": "claude-sonnet-4-20250514"
}

逐项解释：

步骤 3：创建文件的方式

Windows 用户如果不熟悉命令行，用记事本就行：

1. 打开记事本，把上面的 JSON 复制进去，替换 BASE_URL 和 API_KEY 为你的真实值
2. 另存为 → 路径填 C:\Users\你的用户名\.claude\settings.json
3. 保存类型选"所有文件"，编码选 UTF-8

Mac / Linux 用户直接用命令：

# 创建并编辑
vim ~/.claude/settings.json

3.3 环境变量方式（备选）

除了 settings.json，也可以直接用环境变量，效果一样：

# Windows PowerShell
$env:ANTHROPIC_BASE_URL="https://your-api-proxy.com"
$env:ANTHROPIC_API_KEY="sk-your-api-key-here"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"

# Mac / Linux
export ANTHROPIC_BASE_URL="https://your-api-proxy.com"
export ANTHROPIC_API_KEY="sk-your-api-key-here"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"

不过这种方式只在当前终端窗口有效，关掉就没了。想持久化的话，把 export 写到 ~/.bashrc 或 ~/.zshrc 里，或者在 settings.json 里配置（推荐后者，集中管理）。

4 配置 CLAUDE.md

CLAUDE.md 是给 Claude Code 看的"说明书"。你在这个文件里告诉 Claude：你做什么工作、这个项目是什么、有什么特殊规则——Claude 每次启动都会自动读它，并按照里面的约定来帮你干活。

分两级（跟 settings.json 一样）：

4.1 项目级 CLAUDE.md

放在你正在做的项目的根目录下。比如你有一个项目叫 my-project/，就在里面放一个 CLAUDE.md。Claude Code 在那个目录启动时会自动加载。

典型场景：

my-project/
├── CLAUDE.md          ← 这个项目的专属指令
├── src/
├── package.json
└── ...

CLAUDE.md 内容示例：

# 项目说明

这是一个个人博客项目，基于 Next.js 构建。

## 技术栈
- Next.js 14 + TypeScript
- Tailwind CSS
- Contentlayer 管理文章

## 规则
- 所有新组件放 `src/components/`
- 提交前先跑 `npm run lint`
- 不要直接改 `content/` 下的 .mdx，走 Contentlayer 生成

4.2 用户级 CLAUDE.md

放在 ~/.claude/CLAUDE.md（即 C:\Users\你的用户名\.claude\CLAUDE.md），对所有项目生效。适合放通用的个人偏好和工作习惯：

# 个人偏好

- 用中文回复
- 写代码先解释思路再动手
- 每次改完代码自动跑测试
- 不要主动新建文件，先问我

4.3 一个简单的入门模板

如果你是第一次用，跟我一样只是拿 Claude Code 处理零散任务，用户级 CLAUDE.md 够用了：

# 通用指令

- 默认用中文交流
- 修改文件前先和我确认
- 代码注释用中文
- 遇到不确定的，列出选项让我选，不要直接做决定

创建后用 claude 命令启动，它会自动读取 CLAUDE.md。你可以问它："你读到了什么规则？"来验证是否加载成功。

5 开始使用

配置完成后，打开终端，进入你的项目目录，输入：

claude

首次启动可能提示权限确认，一路 Yes 就行。启动后你会看到类似这样的界面：

  Claude Code v2.1.217
  Model: claude-sonnet-4-20250514
  API: https://your-api-proxy.com

> 

到这里就成功了。试着输入第一个指令：

帮我看看这个项目的结构

按 Ctrl + C 或输入 /exit 退出。

6 常见问题

Q: 启动后报 "401 Unauthorized"？
A: API Key 写错了，或者 Base URL 格式不对。检查 settings.json 里的 key 有没有多余空格，Base URL 末尾不要带斜杠。

Q: 报 "Model not found"？
A: model 名称写错了，或者中转服务不支持这个模型。先确认中转给的支持列表，然后把 "model" 字段改成正确的。也可以删掉 model 字段，加上 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 让程序自动发现。

Q: 速度很慢？
A: 中转服务走的海外线路，有天然延迟，正常现象。换一个延迟更低的中转商，或者自建 Worker 能改善。

Q: npm install 报错 / 权限不够？
A: Mac/Linux 如果不用 sudo 就报权限错，可以这样修：

# 方法1：修复 npm 全局目录权限（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 方法2：直接 sudo（不推荐，但快）
sudo npm install -g @anthropic-ai/claude-code

Q: Windows 上 PowerShell 提示"无法加载文件"？
A: PowerShell 执行策略限制了脚本运行。管理员身份打开 PowerShell，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

然后重新打开终端即可。

Q: 怎么更新 Claude Code？

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

Q: 怎么卸载？

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