1.4 快速上手¶
本节帮助你在 5 分钟内完成首次配置。
第一步:添加供应商¶
- 在左侧栏选中要管理的工具,点击页面右上角的 +(添加供应商)
- 在「预设供应商」中选择你的供应商
- 常用预设:智谱 GLM、MiniMax、DeepSeek、Kimi、PackyCode
- 或选择「自定义」手动配置
- 填写 API Key
- 点击「添加」
💡 提示:添加面板支持按中文名和域名搜索,同一家的不同套餐和地区合并成一行。预设会自动填充端点地址,你只需要填写 API Key。
第二步:切换供应商¶
添加完成后,供应商会出现在列表中。
方式一:应用页切换
- 点击供应商卡片的「切换」按钮,状态会显示为「使用中」
- OpenCode、OpenClaw、Hermes、MiniMax Code 是共存式应用,按钮为「添加」(Pi 为「启用」),可以同时添加多个供应商
方式二:托盘快速切换
- 右键系统托盘图标
- 每个工具一行,显示「名称 · 模式 · 供应商 · 额度」,在子菜单里直接点击供应商名称(支持 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build)
第三步:生效方式¶
切换供应商后,各 CLI 工具的生效方式不同:
| 应用 | 生效方式 |
|---|---|
| Claude Code | ✅ 即时生效(支持热重载) |
| Claude Desktop | 需要重启 Claude Desktop |
| Codex | 需要关闭并重新打开终端 |
| Gemini | 需要重启 Gemini CLI |
| Grok Build | 需要重启 Grok Build |
| OpenCode | 需要关闭并重新打开终端 |
| OpenClaw | 需要关闭并重新打开终端 |
| Hermes / Pi / MiniMax Code | 供应商添加后写入工具的配置;Pi、MiniMax Code 在工具里选择要使用的模型,Hermes 可在卡片上点击「启用」设为当前供应商 |
处于路由模式时,Claude Code、Codex、Gemini CLI、Grok Build 切换供应商会立即作用于后续请求;但如果切换改变了模型,Codex、Gemini CLI 和 Grok Build 仍可能需要重启。
直连、路由和聚合(可选)¶
Claude Code、Codex、Gemini CLI、Grok Build 的页面顶部有「直连 / 路由」标签,Claude Code 和 Codex 还有「聚合」。点标签只是切换查看的内容,不会改动配置;真正切换要点页面上写明后果的按钮:「开始路由」、「切换到聚合模式」,回到直连点「回到直连」。
- 直连(默认):客户端直接连供应商,日常使用选它
- 路由:请求经本机 CC Switch 转发(默认
127.0.0.1:15721),可以转换接口格式、做故障转移。想在 Claude Code 里用 OpenAI 或 Gemini 格式的供应商,或在 Codex 里用 Claude,选它 - 聚合:把多家供应商的模型放进同一个模型列表,选哪个模型请求就发给哪一家,不做故障转移
路由和聚合需要 CC Switch 保持运行;退出 CC Switch 会自动回到直连,下次启动再接上。官方订阅不经过路由(Codex 的 OpenAI Official 例外)。详见 开启本地路由。
Claude Code 首次安装提示¶
如果 Claude Code 首次启动时提示需要登录或显示初始化引导,请在 CC Switch 中开启「跳过 Claude Code 初次安装确认」选项:
- 打开 CC Switch「设置 → 应用配置」,找到 Claude Code 一块
- 开启「跳过 Claude Code 初次安装确认」开关
- 重新启动 Claude Code
⚠️ 注意:此选项会在
~/.claude.json中写入hasCompletedOnboarding: true,跳过官方的初次安装确认流程。
验证配置¶
重启后,启动对应的 CLI 工具并输入简单的问题进行测试:
# Claude Code - 启动后输入测试问题
claude
> 你好,请简单介绍一下自己
# Codex - 启动后输入测试问题
codex
> 你好,请简单介绍一下自己
# Gemini - 启动后输入测试问题
gemini
> 你好,请简单介绍一下自己
# OpenCode - 启动后输入测试问题
opencode
> 你好,请简单介绍一下自己
# OpenClaw - 启动后输入测试问题
openclaw
> 你好,请简单介绍一下自己
如果 AI 能正常回复,说明配置成功。
注意:首次启动时,CC Switch 会自动把 Claude Code、Codex、Gemini CLI、Grok Build 的现有配置导入为名为
default的供应商,并为这几个工具和 Claude Desktop 添加官方供应商,原有配置不会丢失。
下一步¶
恭喜!你已经完成了基础配置。接下来可以:
- 添加更多供应商 - 配置多个供应商方便切换
- 配置 MCP 服务器 - 扩展 AI 工具的能力
- 设置系统提示词 - 自定义 AI 的行为
- 开启本地路由 - 使用需要格式转换的供应商、自动故障转移
- 管理 AI 编程工具 - 在侧栏「应用」页安装、升级工具,选择侧栏显示哪些应用
- 查看用量统计 - 统计请求数、Token 和花费
常见问题¶
切换后不生效?¶
确保重启了终端或 CLI 工具。配置文件在切换时已经更新,但运行中的程序不会自动重新加载。
找不到预设?¶
如果你的供应商不在预设列表中,选择「自定义」手动配置。参考 添加供应商 了解配置格式。
如何恢复官方登录?¶
Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build 的供应商列表里都自带一个官方供应商(如 Claude Official、OpenAI Official、Google Official、Grok Official),切换过去后重启客户端,按工具自身的登录流程操作即可。如果列表里没有(例如删掉了,或从旧版本升级),可以从预设里重新添加。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cc/cc-switch