# 安装教程

> ⚡ **推荐：一键配置脚本** —— 一条命令自动完成本页全部步骤（测速选域、写配置、装 Node.js / Claude Code、连通验证，无需 sudo）。手动安装请继续往下阅读。

```bash
# macOS / Linux
curl -fsSL https://qcode.cc/install/claude-code.sh | bash
```

```powershell
# Windows PowerShell
irm https://qcode.cc/install/claude-code.ps1 | iex
```

> 详见 [一键配置脚本](/docs/getting-started/one-click-install)（非交互参数 / 排错 / 回滚说明）。

> 📖 关于 `ANTHROPIC_BASE_URL` 要填 `/api` 还是 `/claude/v1/messages`？四个接入点如何选？见 [接入点与 API 格式](./endpoints-and-api-paths)。

跟着这个教程，你可以轻松在自己的电脑上安装并使用 Claude Code。整个过程只需要 5 分钟。

## 前置要求

Claude Code 需要 Node.js 环境才能运行。请确保你的电脑已安装 Node.js 18.0 或更高版本（推荐 **Node.js 22 LTS**）。

<div data-os="windows" markdown="1">

## Windows 系统

### 步骤 1：安装 Node.js

#### 方法一：官网下载（推荐）

1. 打开浏览器，访问 [https://nodejs.org/](https://nodejs.org/)

2. 点击 "LTS" 版本下载（推荐的长期支持版本）

3. 下载完成后双击 `.msi` 文件

4. 按照安装向导，使用默认设置完成安装

#### 方法二：使用包管理器

如果你已经安装了 Chocolatey 或 Scoop：

```powershell
# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs
```

#### 验证安装

安装完成后，打开 PowerShell 或 CMD，输入以下命令：

```powershell
node --version
npm --version
```

如果显示版本号，说明安装成功了！

### 步骤 2：安装 Claude Code

打开 PowerShell 或 CMD，运行：

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

验证安装：

```powershell
claude --version
```

### 步骤 3：设置环境变量

#### 临时设置（当前会话）

在 PowerShell 中运行：

```powershell
$env:ANTHROPIC_BASE_URL = "https://api.qcode.cc/api"
$env:ANTHROPIC_AUTH_TOKEN = "your-api-key"
```

#### 永久设置（推荐）

设置用户级环境变量：

```powershell
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.qcode.cc/api", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "your-api-key", [System.EnvironmentVariableTarget]::User)
```

> 记得将 `your-api-key` 替换为在 [QCode.cc 控制台](https://qcode.cc/dashboard) 中创建的实际密钥。

#### 验证设置

```powershell
echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_AUTH_TOKEN
```

### 步骤 4：开始使用

```powershell
# 进入你的项目目录
cd C:\path\to\your\project

# 启动 Claude Code
claude
```

### Windows 常见问题

**权限错误？**

- 以管理员身份运行 PowerShell

- 或配置 npm 使用用户目录：`npm config set prefix %APPDATA%\npm`

**PowerShell 执行策略错误？**

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

**环境变量不生效？**

- 设置永久环境变量后重启 PowerShell 或 CMD

- 或注销并重新登录 Windows

</div>

<div data-os="macos" markdown="1">

## macOS 系统

### 步骤 1：安装 Node.js

#### 方法一：使用 Homebrew（推荐）

如果你已经安装了 Homebrew：

```bash
# 更新 Homebrew
brew update

# 安装 Node.js
brew install node
```

#### 方法二：官网下载

1. 访问 [https://nodejs.org/](https://nodejs.org/)

2. 下载 macOS 的 LTS 版本

3. 打开下载的 `.pkg` 文件

4. 按照安装说明完成安装

#### 验证安装

```bash
node --version
npm --version
```

### 步骤 2：安装 Claude Code

#### 方法一：Homebrew（推荐）

```bash
brew install --cask claude-code
```

#### 方法二：npm 安装

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

如果遇到权限问题，使用 sudo：

```bash
sudo npm install -g @anthropic-ai/claude-code
```

验证安装：

```bash
claude --version
```

### 步骤 3：设置环境变量

#### 临时设置（当前会话）

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="your-api-key"
```

#### 永久设置（推荐）

编辑你的 shell 配置文件：

```bash
# 对于 zsh（macOS 默认）
echo 'export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="your-api-key"' >> ~/.zshrc
source ~/.zshrc

# 对于 bash
echo 'export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"' >> ~/.bash_profile
echo 'export ANTHROPIC_AUTH_TOKEN="your-api-key"' >> ~/.bash_profile
source ~/.bash_profile
```

> 记得将 `your-api-key` 替换为在 [QCode.cc 控制台](https://qcode.cc/dashboard) 中创建的实际密钥。

### 步骤 4：开始使用

```bash
# 进入你的项目目录
cd /path/to/your/project

# 启动 Claude Code
claude
```

### macOS 常见问题

**权限错误？**

- 使用 sudo 安装：`sudo npm install -g @anthropic-ai/claude-code`

- 或配置 npm 使用用户目录：`npm config set prefix ~/.npm-global`

**系统阻止执行？**

- 打开 "系统偏好设置" → "安全性与隐私"

- 点击 "仍要打开" 或 "允许"

</div>

<div data-os="linux" markdown="1">

## Linux / WSL2 系统

### 步骤 1：安装 Node.js

#### 方法一：使用 NodeSource 官方仓库（推荐）

```bash
# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

# 安装 Node.js
sudo apt-get install -y nodejs
```

#### 方法二：使用系统包管理器

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# CentOS/RHEL/Fedora
sudo dnf install nodejs npm
```

#### 验证安装

```bash
node --version
npm --version
```

### 步骤 2：安装 Claude Code

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

如果遇到权限问题：

```bash
sudo npm install -g @anthropic-ai/claude-code
```

验证安装：

```bash
claude --version
```

### 步骤 3：设置环境变量

#### 临时设置

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="your-api-key"
```

#### 永久设置

```bash
# 对于 bash（默认）
echo 'export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="your-api-key"' >> ~/.bashrc
source ~/.bashrc

# 对于 zsh
echo 'export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="your-api-key"' >> ~/.zshrc
source ~/.zshrc
```

### 步骤 4：开始使用

```bash
cd /path/to/your/project
claude
```

### Linux 常见问题

**缺少依赖库？**

```bash
# Ubuntu/Debian
sudo apt install build-essential

# CentOS/RHEL
sudo dnf groupinstall "Development Tools"
```

</div>

## 高级配置（可选环境变量）

除了必需的两个环境变量外，还可以通过以下变量进行更多自定义：

### ANTHROPIC_MODEL

指定默认使用的模型。日常推荐显式设为 Sonnet 5；未设置时以 Claude Code 当前版本的内置默认为准（会随 CLI 版本变化，不要依赖本文的历史默认名）。4.x（如 `claude-sonnet-4-6`、`claude-opus-4-8`）仍在售。

```bash
# 日常推荐（Sonnet 5）
export ANTHROPIC_MODEL=claude-sonnet-5

# 重活（Opus 5，费用更高）
export ANTHROPIC_MODEL=claude-opus-5
```

### MAX_THINKING_TOKENS

控制模型思考过程的最大 token 数（设为 0 禁用思考）：

```bash
export MAX_THINKING_TOKENS=16000
```

### CLAUDE_CODE_EFFORT_LEVEL

调整 Claude 的工作努力程度：

```bash
# 可选值：low / medium / high
export CLAUDE_CODE_EFFORT_LEVEL=high
```

### CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

禁用非必要的网络请求（如遥测）：

```bash
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
```

## 下一步

恭喜！你已经成功安装了 Claude Code。接下来：

1. 查看 [快速上手](/docs/getting-started/quick-start) 学习基本用法

2. 探索 [命令行技巧](/docs/usage/cli-tips) 提高效率