【AI Coding】Claude Code 入门（一）：安装配置 & CC Switch 多模型切换

本系列教程面向对 AI 辅助编程感兴趣的开发者，从零开始讲解 Claude Code 的安装、配置和使用。本篇聚焦环境搭建和 API 配置。

一、Claude Code 是什么？

Claude Code 是 Anthropic 官方推出的 AI 编程工具，它不是简单的代码补全，而是一个能读写文件、执行命令、理解整个项目的 AI 编程搭档。

核心能力：

读写代码：直接在项目中创建、修改、删除文件
执行命令：运行 shell 命令（bash/PowerShell）、Git 操作等
理解上下文：自动扫描项目结构、阅读代码、理解架构
多模型支持：可接入 Claude、DeepSeek、Qwen 等多种大模型
双模式运行：CLI 命令行模式 + VSCode 插件模式

二、安装 Claude Code

2.1 环境要求

项目	要求
Node.js	18+
操作系统	Windows / macOS / Linux
终端	PowerShell / Bash / zsh 均可

2.2 安装命令

复制代码

# 全局安装（推荐）
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

安装完成后，输入 claude 即可启动交互式会话。

2.3 首次启动

复制代码

# 进入你的项目目录
cd your-project

# 启动 Claude Code
claude

首次启动会引导你完成：

信任确认 --- 确认当前目录是你的工作空间
认证方式 --- 选择 Anthropic API Key 或 OAuth 登录
基本偏好 --- 主题、权限等

三、API 配置详解

Claude Code 支持多种 API 接入方式。对于国内用户，直接访问 Anthropic API 可能存在网络问题，因此推荐使用中转代理 或第三方模型兼容方案。

3.1 配置文件位置

Claude Code 的配置文件分布在多个层级：

复制代码

~/.claude/                    # 全局配置目录
├── settings.json             # 用户级设置（模型、环境变量）
├── settings.local.json       # 本地设置（权限白名单）
├── .claude.json              # 运行时状态（会话、实验特性）
└── projects/                 # 项目级配置
    └── <project-path>/
        └── settings.json     # 项目专属设置

3.2 核心配置：settings.json

这是最重要的配置文件，路径 ~/.claude/settings.json：

复制代码

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
    "ANTHROPIC_BASE_URL": "https://your-proxy.com/v1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3.7-max",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_NAME": "qwen3.7-max",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "deepseek-v4-pro"
  },
  "model": "opus"
}

各字段说明：

环境变量	作用
`ANTHROPIC_AUTH_TOKEN`	API 密钥（支持 sk- 开头的标准 Key）
`ANTHROPIC_BASE_URL`	API 端点地址（中转代理/兼容接口）
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	轻量模型映射（用于简单任务）
`ANTHROPIC_DEFAULT_SONNET_MODEL`	标准模型映射（日常编程）
`ANTHROPIC_DEFAULT_OPUS_MODEL`	强力模型映射（复杂推理）
`model`	默认使用的模型级别

3.3 国内常用 API 中转方案

方案	说明	示例 Base URL
阿里云 MaaS	阿里云百炼平台，支持多模型	`https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic`
硅基流动	支持 DeepSeek/Qwen 等国产模型	自行查阅文档
自建中转	使用 one-api 等开源方案搭建	自己的域名
Anthropic 官方	需海外网络	`https://api.anthropic.com`

提示：选择中转时注意确认其兼容 Anthropic Messages API 格式，否则 Claude Code 无法正常工作。

3.4 权限配置：settings.local.json

复制代码

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Edit",
      "Write"
    ]
  }
}

这里配置的是 Claude Code 执行操作时的权限白名单 。在 allow 列表中的操作会自动通过，不需要每次确认。

四、CC Switch：多模型一键切换

4.1 CC Switch 是什么？

CC Switch 是一个 Claude Code 的多模型管理工具，提供图形化界面来管理多个 API Provider，实现一键切换。

核心功能：

多 Provider 管理 --- 同时配置 Anthropic 官方、阿里云、硅基流动等多个 API 源
一键切换 --- 系统托盘快速切换，无需手动改配置文件
模型映射 --- 为每个 Provider 自定义 Haiku/Sonnet/Opus 对应的实际模型
自动故障转移 --- 某个 Provider 不可用时自动切换备用
用量统计 --- 可视化查看各 Provider 的 token 消耗

4.2 安装 CC Switch

复制代码

# 从 GitHub Release 下载对应平台安装包
# https://github.com/cft0808/CCSwitch/releases

# Windows: 下载 .exe 安装包
# macOS: 下载 .dmg
# Linux: 下载 .AppImage

4.3 CC Switch 配置步骤

第一步：添加 Provider（API 源）

打开 CC Switch，点击「添加 Provider」，填写：

字段	示例值	说明
名称	阿里云 MaaS	自定义名称
Base URL	`https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic`	API 端点
API Key	`sk-sp-xxx`	密钥
模型映射	Haiku → deepseek-v4-flash	选择实际模型

第二步：配置模型映射

CC Switch 的核心价值在于模型映射。Claude Code 内部使用三个模型等级：

复制代码

Haiku（轻量快速）→ 映射到实际模型，如 deepseek-v4-flash
Sonnet（均衡）    → 映射到实际模型，如 deepseek-v4-pro
Opus（强力推理）  → 映射到实际模型，如 qwen3.7-max

第三步：一键切换

CC Switch 常驻系统托盘，右键菜单即可切换当前使用的 Provider：

复制代码

托盘图标 → 选择 Provider → 自动写入 ~/.claude/settings.json → 下次对话生效

4.4 CC Switch 的 settings.json

CC Switch 自身的配置文件在 ~/.cc-switch/settings.json：

复制代码

{
  "showInTray": true,
  "minimizeToTrayOnClose": true,
  "language": "zh",
  "currentProviderClaude": "provider-uuid-here",
  "visibleApps": {
    "claude": true,
    "claude-desktop": true,
    "codex": true
  }
}

五、验证配置是否生效

5.1 快速测试

复制代码

# 启动 Claude Code
claude

# 在交互界面中输入：
> 你是什么模型？

如果返回正确的模型名称（如 "我是 Claude" 或对应映射模型），说明配置成功。

5.2 检查当前模型

复制代码

# 在 Claude Code 交互界面中输入 /model
/model

会显示当前使用的模型信息。

5.3 常见问题排查

问题	原因	解决方案
401 Unauthorized	API Key 无效	检查 `ANTHROPIC_AUTH_TOKEN`
Connection refused	Base URL 错误	检查 URL 是否正确，是否可访问
Model not found	模型名不匹配	确认 Provider 支持的模型名
超时	网络问题	检查代理/中转是否可用

六、总结

复制代码

安装 Node.js 18+
    ↓
npm install -g @anthropic-ai/claude-code
    ↓
配置 ~/.claude/settings.json（API Key + Base URL + 模型映射）
    ↓
（可选）安装 CC Switch 实现多模型图形化切换
    ↓
运行 claude 验证配置

下一篇我们将深入 Claude Code 的 CLI 命令行模式，讲解所有实用命令和高效操作技巧。

系列目录

【AI Coding】Claude Code 入门（一）：安装配置 & CC Switch 多模型切换 ← 本篇

【AI Coding】Claude Code 入门（二）：CLI 命令行模式

【AI Coding】Claude Code 入门（三）：VSCode 插件模式