2026-05-14 10:17:27 +08:00
|
|
|
|
# Claude Code 部署指南
|
|
|
|
|
|
|
|
|
|
|
|
| 资源 | 地址 |
|
|
|
|
|
|
|------|------|
|
|
|
|
|
|
| 官方文档 | [docs.claude.com](https://docs.claude.com/zh-CN/docs/claude-code/overview) |
|
|
|
|
|
|
| oneinAI 平台 | [api.oneinai.com](https://api.oneinai.com) |
|
|
|
|
|
|
|
|
|
|
|
|
## 📋 前置要求
|
|
|
|
|
|
|
|
|
|
|
|
- 已完成 [Node.js 环境安装](/node/windows)，确保 Node.js 18+ 已正确安装
|
|
|
|
|
|
- 已在 [oneinAI 平台注册账号](/guide/registration) 并 [创建 API Key](/guide/create-key)
|
|
|
|
|
|
- 确保账户余额充足（[充值指引](/guide/recharge)）
|
|
|
|
|
|
|
|
|
|
|
|
## ⚡ 首次安装必读：跳过初始化报错
|
|
|
|
|
|
|
|
|
|
|
|
使用中转渠道时，Claude Code 首次启动会出现以下报错：
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
Welcome to Claude Code
|
|
|
|
|
|
Unable to connect to Anthropic services
|
|
|
|
|
|
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
这是因为 Claude Code 首次启动会尝试连接官方 API 进行初始化确认，中转渠道无法通过此步骤。**安装完成后、首次启动前**，请先执行以下任一方法跳过：
|
|
|
|
|
|
|
|
|
|
|
|
**方法一：使用 CC-Switch 跳过（推荐）**
|
|
|
|
|
|
|
|
|
|
|
|
打开 [CC-Switch 配置工具](/tools/cc-switch)，进入 **设置 → 通用**，开启 **「跳过 Claude Code 初次安装确认」** 选项即可。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**方法二：手动修改配置文件**
|
|
|
|
|
|
|
|
|
|
|
|
在用户主目录下找到 `~/.claude.json` 文件，在末尾添加 `"hasCompletedOnboarding": true` 字段：
|
|
|
|
|
|
|
|
|
|
|
|
> ⚠️ 注意 JSON 格式：添加字段前，需要在上一个字段末尾**补一个英文逗号**，否则 JSON 格式错误会导致 Claude Code 无法启动。
|
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"installMethod": "unknown",
|
|
|
|
|
|
"autoUpdates": true,
|
|
|
|
|
|
"firstStartTime": "2025-07-14T06:11:03.877Z",
|
|
|
|
|
|
"userID": "xxxx",
|
|
|
|
|
|
"projects": {
|
|
|
|
|
|
"/home/your-user": {
|
|
|
|
|
|
"allowedTools": [],
|
|
|
|
|
|
"history": [],
|
|
|
|
|
|
"mcpContextUris": [],
|
|
|
|
|
|
"mcpServers": {},
|
|
|
|
|
|
"enabledMcpjsonServers": [],
|
|
|
|
|
|
"disabledMcpjsonServers": [],
|
|
|
|
|
|
"hasTrustDialogAccepted": false,
|
|
|
|
|
|
"projectOnboardingSeenCount": 0,
|
|
|
|
|
|
"hasClaudeMdExternalIncludesApproved": false,
|
|
|
|
|
|
"hasClaudeMdExternalIncludesWarningShown": false
|
|
|
|
|
|
}
|
|
|
|
|
|
},
|
|
|
|
|
|
"hasCompletedOnboarding": true
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
修改保存后，重新运行 `claude` 即可正常使用。
|
|
|
|
|
|
|
|
|
|
|
|
> 参考来源：[Claude Code 跳过初始化确认](https://www.cnblogs.com/gordonMlxg/articles/19103691)
|
|
|
|
|
|
|
|
|
|
|
|
## 🚀 使用 CC-Switch 快速配置（推荐）
|
|
|
|
|
|
|
|
|
|
|
|
如果您已安装 [CC-Switch 快速配置工具](/tools/cc-switch)，可以通过图形界面轻松管理 Claude Code 的配置，无需手动编辑配置文件和环境变量。
|
|
|
|
|
|
|
|
|
|
|
|
### CC-Switch 优势
|
|
|
|
|
|
|
|
|
|
|
|
- 图形化界面，操作简单直观
|
|
|
|
|
|
- 一键切换不同提供商配置
|
|
|
|
|
|
- 自动管理环境变量和配置文件
|
|
|
|
|
|
- 支持配置备份与恢复
|
|
|
|
|
|
- 无需重启终端即可切换配置
|
|
|
|
|
|
|
|
|
|
|
|
### 配置步骤
|
|
|
|
|
|
|
|
|
|
|
|
**1. 启动 CC-Switch 并添加 Claude Code 配置**
|
|
|
|
|
|
|
|
|
|
|
|
1. 打开 CC-Switch 应用程序
|
|
|
|
|
|
2. 点击顶部的「Claude」标签页
|
|
|
|
|
|
3. 点击右上角橙色「+」按钮添加新配置
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**2. 填写提供商配置信息**
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 填写内容 |
|
|
|
|
|
|
|------|----------|
|
|
|
|
|
|
| 提供商名称 | 自定义名称（如 "oneinAI"） |
|
|
|
|
|
|
| API Base URL | `https://api.oneinai.com` |
|
|
|
|
|
|
| API Key | 从 oneinAI 平台获取的 Claude 专用令牌 |
|
|
|
|
|
|
| 模型选择 | 根据需求选择可用的 Claude 模型 |
|
|
|
|
|
|
|
|
|
|
|
|
填写完成后点击「保存」按钮。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
> 💡 提示
|
|
|
|
|
|
> - 可以添加多个不同的提供商配置（如官方、oneinAI 等）
|
|
|
|
|
|
> - CC-Switch 会自动修改 `~/.claude/settings.json` 配置文件
|
|
|
|
|
|
> - 切换配置后，关闭并重启 Claude Code 即可生效
|
|
|
|
|
|
|
|
|
|
|
|
**3. 启用配置并使用**
|
|
|
|
|
|
|
|
|
|
|
|
1. 在配置列表中找到刚创建的「oneinAI」配置
|
|
|
|
|
|
2. 点击配置右侧的「当前使用」按钮（或直接点击配置卡片）
|
|
|
|
|
|
3. 配置会被标记为「当前使用」状态（绿色标签）
|
|
|
|
|
|
4. 重启 Claude Code，新配置即可生效
|
|
|
|
|
|
|
|
|
|
|
|
**4. 系统托盘快速切换**
|
|
|
|
|
|
|
|
|
|
|
|
CC-Switch 支持通过系统托盘快速切换配置：
|
|
|
|
|
|
|
|
|
|
|
|
1. 右键点击系统托盘中的 CC-Switch 图标
|
|
|
|
|
|
2. 在菜单中选择 Claude 分类
|
|
|
|
|
|
3. 直接选择要切换到的配置
|
|
|
|
|
|
4. 配置立即生效，无需打开主界面
|
|
|
|
|
|
|
|
|
|
|
|
> ⚠️ 注意事项
|
|
|
|
|
|
> - 确保从 oneinAI 平台创建的是 Claude Code 专用令牌
|
|
|
|
|
|
> - 切换配置后需要重启 Claude Code 才能生效
|
|
|
|
|
|
> - 可以在 CC-Switch 中测试 API 端点速度，选择最优配置
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## ⌨️ 手动命令行配置
|
|
|
|
|
|
|
|
|
|
|
|
如果您不使用 CC-Switch，也可以通过命令行手动配置 Claude Code。
|
|
|
|
|
|
|
|
|
|
|
|
### 🖥️ Windows 平台
|
|
|
|
|
|
|
|
|
|
|
|
#### 系统要求
|
|
|
|
|
|
|
|
|
|
|
|
- Windows 10 或 Windows 11
|
|
|
|
|
|
|
|
|
|
|
|
#### 安装步骤
|
|
|
|
|
|
|
|
|
|
|
|
**方法一：Native Install（推荐）**
|
|
|
|
|
|
|
|
|
|
|
|
PowerShell：
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
irm https://claude.ai/install.ps1 | iex
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
CMD：
|
|
|
|
|
|
|
|
|
|
|
|
```cmd
|
|
|
|
|
|
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**方法二：NPM 安装（不推荐）**
|
|
|
|
|
|
|
|
|
|
|
|
> ⚠️ npm 渠道更新滞后，安装的版本通常较旧，建议优先使用上方的 Native 方式。
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
npm install -g @anthropic-ai/claude-code
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
#### 验证安装
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
claude --version
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
#### 配置环境变量
|
|
|
|
|
|
|
|
|
|
|
|
PowerShell：
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-xxx", "User")
|
|
|
|
|
|
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.oneinai.com", "User")
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
CMD：
|
|
|
|
|
|
|
|
|
|
|
|
```cmd
|
|
|
|
|
|
setx ANTHROPIC_AUTH_TOKEN "sk-xxx"
|
|
|
|
|
|
setx ANTHROPIC_BASE_URL "https://api.oneinai.com"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
> 💡 请将 `sk-xxx` 替换为你在 oneinAI 平台获取的专属 API Key。设置完成后需**重启终端**使环境变量生效。
|
|
|
|
|
|
|
|
|
|
|
|
#### 启动 Claude Code
|
|
|
|
|
|
|
|
|
|
|
|
重启终端后，进入项目目录（或任意目录），输入以下命令即可启动：
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
claude
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
### 🍏 macOS 平台
|
|
|
|
|
|
|
|
|
|
|
|
#### 系统要求
|
|
|
|
|
|
|
|
|
|
|
|
- macOS 10.15 (Catalina) 或更高版本
|
|
|
|
|
|
|
|
|
|
|
|
#### 安装步骤
|
|
|
|
|
|
|
|
|
|
|
|
**方法一：Homebrew（推荐）**
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
brew install --cask claude-code
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**方法二：Curl Script**
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -fsSL https://claude.ai/install.sh | bash
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**方法三：NPM 安装（不推荐）**
|
|
|
|
|
|
|
|
|
|
|
|
> ⚠️ npm 渠道更新滞后，安装的版本通常较旧，建议优先使用上方的 Native 方式。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
npm install -g @anthropic-ai/claude-code
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
#### 验证安装
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
claude -v
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
正常输出类似：`1.0.108 (Claude Code)`
|
|
|
|
|
|
|
|
|
|
|
|
#### 配置环境变量
|
|
|
|
|
|
|
|
|
|
|
|
**Bash 用户（默认）：**
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.bash_profile
|
|
|
|
|
|
echo 'export ANTHROPIC_BASE_URL="https://api.oneinai.com"' >> ~/.bash_profile
|
|
|
|
|
|
source ~/.bash_profile
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**Zsh 用户（macOS Catalina+ 默认）：**
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.zshrc
|
|
|
|
|
|
echo 'export ANTHROPIC_BASE_URL="https://api.oneinai.com"' >> ~/.zshrc
|
|
|
|
|
|
source ~/.zshrc
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
> 💡 请将 `sk-xxx` 替换为你在 oneinAI 平台获取的专属 API Key。
|
|
|
|
|
|
|
|
|
|
|
|
#### 启动 Claude Code
|
|
|
|
|
|
|
|
|
|
|
|
重启终端后，进入项目目录（或任意目录），输入 `claude` 即可启动使用。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
### 🐧 Linux 平台
|
|
|
|
|
|
|
|
|
|
|
|
#### 系统要求
|
|
|
|
|
|
|
|
|
|
|
|
- Ubuntu 18.04+、CentOS 7+、Debian 9+ 等主流发行版
|
|
|
|
|
|
|
|
|
|
|
|
#### 安装步骤
|
|
|
|
|
|
|
|
|
|
|
|
**方法一：Curl Script（推荐）**
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -fsSL https://claude.ai/install.sh | bash
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**方法二：NPM 安装（不推荐）**
|
|
|
|
|
|
|
|
|
|
|
|
> ⚠️ npm 渠道更新滞后，安装的版本通常较旧，建议优先使用上方的 Native 方式。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
npm install -g @anthropic-ai/claude-code
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
#### 验证安装
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
claude -v
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
#### 配置环境变量
|
|
|
|
|
|
|
|
|
|
|
|
**Ubuntu/Debian（Bash）：**
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.bash_profile
|
|
|
|
|
|
echo 'export ANTHROPIC_BASE_URL="https://api.oneinai.com"' >> ~/.bash_profile
|
|
|
|
|
|
source ~/.bash_profile
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**Fedora/CentOS（Zsh）：**
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.zshrc
|
|
|
|
|
|
echo 'export ANTHROPIC_BASE_URL="https://api.oneinai.com"' >> ~/.zshrc
|
|
|
|
|
|
source ~/.zshrc
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
> 💡 请将 `sk-xxx` 替换为你在 oneinAI 平台获取的专属 API Key。
|
|
|
|
|
|
|
|
|
|
|
|
#### 启动 Claude Code
|
|
|
|
|
|
|
|
|
|
|
|
重启终端后，进入项目目录（或任意目录），输入 `claude` 即可启动使用。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## ❓ 常见问题
|
|
|
|
|
|
|
|
|
|
|
|
### 提示找不到 `claude` 命令？
|
|
|
|
|
|
|
|
|
|
|
|
1. 确认 Claude Code 已正确安装（重新执行安装命令）
|
|
|
|
|
|
2. 检查 PATH 环境变量是否包含安装路径
|
|
|
|
|
|
3. 重启终端窗口
|
|
|
|
|
|
4. Windows 用户可尝试重新打开一个新的终端窗口
|
|
|
|
|
|
|
|
|
|
|
|
### 连接失败或报错 401？
|
|
|
|
|
|
|
|
|
|
|
|
1. 检查网络连接是否正常
|
|
|
|
|
|
2. 确认 API Key 正确无误（注意前后不要有空格）
|
|
|
|
|
|
3. 确认 `ANTHROPIC_BASE_URL` 设置为 `https://api.oneinai.com`
|
|
|
|
|
|
4. 检查 oneinAI 平台账户余额是否充足
|
|
|
|
|
|
|
|
|
|
|
|
### 模型不可用或报错 404？
|
|
|
|
|
|
|
|
|
|
|
|
1. 确认所选模型在 oneinAI 平台上可用
|
|
|
|
|
|
2. 查看 [模型选择指南](/guide/model-selection) 了解支持的模型列表
|
|
|
|
|
|
3. 尝试切换到其他可用模型
|
|
|
|
|
|
|
|
|
|
|
|
### 更多问题
|
|
|
|
|
|
|
2026-05-15 18:07:58 +08:00
|
|
|
|
请查看 [FAQ](/support/faq)
|
