---
title: "Claude Code 完整安装与配置教程（支持国内模型）"
author: deletexiumu
pubDatetime: 2026-01-20T10:00:00+08:00
featured: false
draft: false
tags:
  - Claude Code
  - 教程
description: "Claude Code 从安装到配置的完整教程，包括如何接入国内模型服务作为替代方案。"
---

本文将详细介绍 Claude Code 的安装步骤，以及如何接入国内模型服务作为替代方案。

---

## 💡 本文内容概览

本教程将帮你解决以下问题：

- Claude Code 的完整安装步骤（macOS + Windows）
- 国内网络环境下的配置优化
- 如何接入国内模型服务（可选）
- 常见问题排查

**适合人群**：想尝试 Claude Code 的开发者，无论是否有终端使用经验。

---

## 📖 目录

1. 什么是 Claude Code？
2. 安装前准备
3. macOS 安装教程
4. Windows 安装教程
5. 接入国内模型（可选）
6. CC-Switch 多模型管理工具
7. 常见问题排查

---

## 一、什么是 Claude Code？

简单说：**Claude Code = 能动手干活的 AI**

你平时用的豆包、DeepSeek、Kimi 这些网页聊天，都只能「说」不能「做」。而 Claude Code 是一个运行在你电脑终端里的 AI 编程助手，它能直接操作你的代码文件。

**网页聊天（豆包/DeepSeek/Kimi）：**
- 只能聊天讨论
- 需要复制粘贴代码
- 一问一答
- 需要手动上传文件

**Claude Code：**
- 直接操作你的文件
- 自动修改代码
- 自动执行多步骤任务
- 直接读取项目文件夹

**一句话总结**：网页聊天是顾问给建议，Claude Code 是打工人直接干活。

![Claude Code 与普通 Claude 对比](https://substackcdn.com/image/fetch/w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F0c8816fd-c583-43f3-b1a5-811cb97e83f5_960x596.png)

---

## 二、安装前准备

### 系统要求

- **macOS**：10.15 (Catalina) 及以上
- **Windows**：Windows 10 及以上
- **Linux**：Ubuntu 22.04+ / Debian 11+

### 必装软件

**Node.js 18+**（必须）

下载地址：https://nodejs.org/

安装时一路 Next 即可，安装完成后打开终端验证：

```
node --version
```

应该显示 v18.x.x 或更高版本

**Windows 用户额外需要**：Git for Windows

下载地址：https://git-scm.com/download/win

![Git for Windows 安装](https://substackcdn.com/image/fetch/w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F58f8586d-7c06-4955-bba8-6b8588725241_600x469.png)

安装时保持默认选项，一路 Next 即可。

### 🚀 设置国内 npm 镜像（推荐）

国内直接用 npm 下载较慢，建议先配置国内镜像：

```
npm config set registry https://registry.npmmirror.com
```

验证配置是否成功：

```
npm config get registry
```

应该显示 https://registry.npmmirror.com

---

## 三、macOS 安装教程

### 步骤 1：打开终端

按 **Command + 空格**，搜索 "终端" 或 "Terminal"，打开它。

### 步骤 2：安装 Claude Code

在终端中输入：

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

如果提示权限问题，改用：

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

### 步骤 3：验证安装

```
claude --version
```

看到版本号就说明安装成功了！🎉

### 步骤 4：首次运行

**重要**：先 cd 到你想让 Claude Code 操作的项目文件夹，例如：

```
cd ~/Projects/my-project
claude
```

![Claude Code 欢迎界面](https://substackcdn.com/image/fetch/w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F446489ad-2781-4cfd-ab46-26ecff5d63c5_1027x444.png)

⚠️ **安全提示**：Claude Code 可以读写工作目录下的所有文件，所以不要在根目录或重要系统文件夹运行它！

---

## 四、Windows 安装教程

### 步骤 1：安装 Git for Windows

如果还没装，去 https://git-scm.com/download/win 下载安装。

安装时保持默认选项即可。

### 步骤 2：打开 PowerShell

按 **Win + X**，选择 "Windows PowerShell (管理员)"。

或者在开始菜单搜索 "PowerShell"，右键选择 "以管理员身份运行"。

![以管理员身份运行终端](https://substackcdn.com/image/fetch/w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F7c4dcde6-9668-42cf-b2c4-ba0d763c1e7d_398x256.png)

### 步骤 3：设置国内 npm 镜像

```
npm config set registry https://registry.npmmirror.com
```

### 步骤 4：安装 Claude Code

在 PowerShell 中输入：

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

![安装成功](https://substackcdn.com/image/fetch/w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F873d4697-bfd9-4ced-9074-3e6af24d57d5_541x265.png)

### 步骤 5：验证安装

```
claude --version
```

### 步骤 6：首次运行

**方法一（推荐）**：在文件资源管理器中，进入你的项目文件夹，右键空白处，选择 "在终端中打开"，然后输入 claude。

![在终端中打开](https://substackcdn.com/image/fetch/w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fedce0e7c-36c2-4fef-ba81-6a2b4069ba1a_675x492.png)

**方法二**：在 PowerShell 中用 cd 命令切换目录：

```
cd C:\Users\你的用户名\Projects\my-project
claude
```

---

## 五、接入国内模型（可选）

如果你不想订阅官方 Claude Pro/Max，可以考虑接入国内的兼容模型服务。以智谱 GLM 为例，介绍配置方法。

⚠️ **声明**：以下内容仅供技术交流，建议根据自身需求选择官方或第三方服务。

### 为什么选择专业版？

**基础版（¥20/月）：**
- ❌ 不支持多模态（图片）
- 5 路并发
- 仅适合纯文字编程

**专业版（¥100/月）：**
- ✅ 支持多模态（图片识别）
- 10 路并发
- **实际开发必备**

**官方 Claude Pro（$20/月，约¥145）：**
- ✅ 支持多模态
- 有用量限制
- 官方原版

💡 **提示**：基础版不支持多模态（图片识别），如果你的开发工作需要处理截图、UI 设计稿等，建议选择专业版。

### 配置步骤

**步骤 1：注册智谱账号**

在浏览器搜索「智谱AI开放平台」或者点击[我的邀请链接](https://www.bigmodel.cn/glm-coding?ic=F1OOWDWJYZ)，进入官网注册/登录。

**步骤 2：订阅 GLM Coding Plan**

登录后在官网找到[「GLM Coding Plan」](https://www.bigmodel.cn/glm-coding?ic=F1OOWDWJYZ))页面，选择**专业版**并完成订阅。

**步骤 3：获取 API Key**

在用户中心的[「API Keys 管理」](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys)页面，创建一个新的 API Key。

⚠️ **重要**：API Key 只显示一次，务必保存好！

**步骤 4：配置环境**

**方式一：一键配置（推荐）**

智谱官方提供了配置助手，打开终端运行：

```
npx @z_ai/coding-helper
```

按照界面提示操作即可自动完成配置。

![配置助手界面](https://cdn.bigmodel.cn/markdown/1764664136830image.png)

**方式二：手动配置**

**macOS / Linux：**

编辑配置文件 ~/.claude/settings.json：

```
mkdir -p ~/.claude
nano ~/.claude/settings.json
```

输入以下内容（替换 your_api_key 为你的 API Key）：

```
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_api_key",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  }
}
```

按 Ctrl + O 保存，Ctrl + X 退出。

再创建 ~/.claude.json：

```
echo '{"hasCompletedOnboarding": true}' > ~/.claude.json
```

**Windows：**

1. 打开文件资源管理器，在地址栏输入 %USERPROFILE% 回车
2. 创建 .claude 文件夹
3. 在 .claude 文件夹中创建 settings.json 文件，内容同上
4. 在用户目录（%USERPROFILE%）创建 .claude.json 文件，内容：{"hasCompletedOnboarding": true}

**步骤 5：验证配置**

**重新打开一个新终端窗口**（这一步很重要！），然后：

```
cd 你的项目目录
claude
```

运行后会提示 "Do you want to use this API key?"，选择 **Yes**。

在 Claude Code 中输入 /status 可以查看当前使用的模型。

![模型状态确认](https://cdn.bigmodel.cn/markdown/1759228558734cline-2.png)

---

## 六、CC-Switch 多模型管理工具

如果你想灵活切换不同的模型服务商，可以使用开源工具 **CC-Switch**。

它支持多种国内外模型：
- 智谱 GLM
- 月之暗面 Kimi
- 阿里通义千问 Qwen
- 以及更多第三方服务...

你可以根据不同任务选择合适的模型，或者在某个服务不稳定时快速切换。

### CC-Switch 功能介绍

一个开源的跨平台桌面应用，用于管理 Claude Code、Codex、Gemini CLI 的配置：

- 🔄 一键切换不同模型服务商
- 🧪 API 延迟测试
- 📦 MCP 服务器管理
- 💾 配置自动备份
- 🌐 支持中英日界面

### 界面预览

**主界面：**

![主界面](https://github.com/farion1231/cc-switch/raw/main/assets/screenshots/main-zh.png)

**添加供应商：**

![添加供应商](https://github.com/farion1231/cc-switch/raw/main/assets/screenshots/add-zh.png)

### 安装 CC-Switch

**macOS 用户（推荐 Homebrew）**

```
brew tap farion1231/ccswitch
brew install --cask cc-switch
```

更新版本：

```
brew upgrade --cask cc-switch
```

⚠️ **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告，请先关闭，然后前往 **"系统设置" → "隐私与安全性" → 点击"仍要打开"**，之后便可以正常打开。

**Windows 用户**

在 GitHub 搜索「cc-switch」，进入 farion1231/cc-switch 项目的 Releases 页面：
1. 下载最新的 CC-Switch-v{版本号}-Windows.msi 安装包
2. 或下载 CC-Switch-v{版本号}-Windows-Portable.zip 绿色版
3. 双击安装或解压使用

**Linux 用户**

Ubuntu/Debian - 下载 .deb 包安装：

```
sudo dpkg -i CC-Switch-v{版本号}-Linux.deb
```

或使用 AppImage：

```
chmod +x CC-Switch-v{版本号}-Linux.AppImage
./CC-Switch-v{版本号}-Linux.AppImage
```

ArchLinux：

```
paru -S cc-switch-bin
```

### 使用 CC-Switch 配置智谱

**1. 添加供应商**

点击 **"添加供应商"** 按钮，可以：

- **选择预设**：CC-Switch 已内置智谱 GLM Coding Plan 预设，只需填写 API Key
- **自定义配置**：手动填写 API 地址和密钥

**2. 切换供应商**

**方法一：主界面切换**
- 选中配置好的供应商
- 点击 **"启用"** 按钮

**方法二：系统托盘快速切换**
- 右键点击托盘图标
- 直接点击供应商名称即可切换（无需重启）

**3. 重启生效**

切换后重新打开终端，运行 claude 即可使用新配置。

### CC-Switch 高级功能

**速度测试**

点击闪电图标 ⚡，测试当前 API 的响应延迟，根据结果选择最快的供应商。

**MCP 服务器管理**

点击右上角 **"MCP"** 按钮：
- 添加和管理 MCP 服务器
- 支持 stdio/http/sse 三种传输方式
- 自动同步到 Claude/Codex/Gemini 配置文件

**云同步配置**

1. 进入 **设置** → **"自定义配置目录"**
2. 选择云同步文件夹（Dropbox、OneDrive、iCloud 等）
3. 重启应用生效
4. 在其他设备上选择相同目录即可同步

**配置文件位置**

- **数据库**：~/.cc-switch/cc-switch.db（SQLite 存储供应商、MCP 等数据）
- **设置**：~/.cc-switch/settings.json（本地设备设置）
- **备份**：~/.cc-switch/backups/（自动轮换，保留 10 个）

💡 **提示**：首次启动时，CC-Switch 会自动导入现有的 Claude/Codex 配置作为默认供应商。

---

## 七、常见问题排查

**Q1: 安装时提示权限错误**

macOS/Linux：在命令前加 sudo

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

Windows：以管理员身份运行 PowerShell

**Q2: npm 下载太慢或超时**

确保已设置国内镜像：

```
npm config set registry https://registry.npmmirror.com
```

**Q3: Windows 提示找不到 git-bash**

确保已安装 Git for Windows：https://git-scm.com/download/win

安装后**重启 PowerShell** 再试。

**Q4: 配置修改后不生效**

- 关闭**所有**终端窗口
- 重新打开一个新终端
- 再次运行 claude
- 检查 settings.json 格式是否正确（可用在线 JSON 校验工具）

**Q5: 提示 "Unauthorized" 或 API Key 无效**

- 检查 API Key 是否正确（无多余空格）
- 确认 settings.json 格式正确
- 确认套餐是否已激活
- 确认 API Key 在智谱后台没有被删除

**Q6: 响应太慢或超时**

智谱专业版模型默认映射：
- Opus/Sonnet → GLM-4.7
- Haiku → GLM-4.5-Air

如果感觉慢，可以：
1. 检查网络连接
2. 在 CC-Switch 中测试 API 延迟
3. 调整超时时间（API_TIMEOUT_MS）

**Q7: macOS 打开 CC-Switch 提示"无法验证开发者"**

1. 先关闭应用
2. 打开 **"系统设置" → "隐私与安全性"**
3. 向下滚动，找到 CC-Switch 相关提示
4. 点击 **"仍要打开"**

**Q8: 想恢复使用官方 Claude**

在 CC-Switch 中选择 **"官方登录"** 预设，重启 Claude Code 后按照登录流程操作即可。

---

## 🎯 快速回顾

**macOS 安装步骤：**
1. 安装 Node.js
2. 设置国内镜像：npm config set registry https://registry.npmmirror.com
3. 安装 Claude Code：npm install -g @anthropic-ai/claude-code
4. 可选：配置国内模型（编辑 ~/.claude/settings.json）
5. 可选：安装 CC-Switch 管理多模型

**Windows 安装步骤：**
1. 安装 Node.js
2. 安装 Git for Windows
3. 设置国内镜像：npm config set registry https://registry.npmmirror.com
4. 安装 Claude Code：npm install -g @anthropic-ai/claude-code
5. 可选：配置国内模型（编辑 %USERPROFILE%\.claude\settings.json）
6. 可选：安装 CC-Switch 管理多模型

---

## 📣 结语

希望这篇教程对你有帮助。如有问题，欢迎评论区交流。

---

**相关资源：**

- Node.js 官网：https://nodejs.org/
- Git 下载：https://git-scm.com/download/win
- Claude Code 官方文档：https://docs.anthropic.com/en/docs/claude-code
- CC-Switch 项目：GitHub 搜索「farion1231/cc-switch」
- 智谱 GLM：搜索「智谱AI开放平台」

---

*作者：Knowing | 欢迎关注我的技术分享*

---

## 相关阅读

- [普通人用 Claude Code 能做什么？远不止写代码](/posts/claude-code-for-everyone/) — 装之前先看看它能帮你做哪些事
- [让 AI 帮我收拾那个乱成一锅粥的「下载」文件夹](/posts/claude-code-organize-downloads/) — 装好后的第一个上手实战
- [多模型共识：让 Claude Code 调用 DeepSeek、通义千问、KIMI 的完整配置教程](/posts/multi-model-consensus/) — 不想用官方模型？这里是国内模型的接入方案