跳至主要內容

通用概念与配置

大约 5 分钟

CC-Switch 通用概念与配置

这一篇是所有人都要先看的入门篇。装好 CC-Switch、理解界面、把第一个"后端"加进去、知道切换的工作原理。看完再去 Claude / Codex / Gemini 的专页就很顺。

一、下载安装

打开 CC-Switch 官网 https://ccswitch.app，或者去 GitHub 仓库下载最新版安装包。

Windows

  1. 在下载区选 Windows 安装包（一般是 CC-Switch-Setup-x.x.x.exe）
  2. 双击安装，一路下一步
  3. 安装完成后从开始菜单启动 CC-Switch

macOS（推荐 Homebrew）

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

也可以直接下 .dmg 拖进 Applications。

Linux（Debian / Ubuntu）

wget https://github.com/farion1231/cc-switch/releases/latest/download/cc-switch_x.x.x_amd64.deb
sudo dpkg -i cc-switch_x.x.x_amd64.deb

启动后界面找不到？

CC-Switch 启动后通常会缩到系统托盘（Windows 右下角 / macOS 右上角菜单栏）。点托盘小图标可以呼出主面板，关闭窗口默认是隐藏，不是退出。

二、界面结构

CC-Switch 主面板大致分三块：

区域作用
顶部应用切换在 Claude / Codex / Gemini 三个应用之间切换当前管理对象
左侧 / 中部配置列表当前应用下保存的所有"后端配置"
右侧编辑区选中某个配置后，能看到详情、能编辑、能"启用"

理解一句话：CC-Switch 是一个"本机 CLI 配置文件的可视化管理器"。你在面板里点"启用"，它就把对应配置写进 Claude / Codex / Gemini 的本机配置文件。

三、最关键的动作：添加一个后端配置

不管你最终是要切 Claude、Codex 还是 Gemini，第一次都要走"添加配置"这一步。

  1. 顶部先把应用切到你要配的工具（Claude / Codex / Gemini）
  2. 点击 Add Provider（添加供应商 / 新建配置）
  3. 按下面的"配置项含义"逐项填写
  4. 保存
  5. 在列表里找到刚加的项，点 Enable（启用 / 使用中）

只有看到该配置的状态变成"使用中 / In Use"，才算切换成功。

配置项含义

字段填什么说明
名称 / Name自己看得懂就行推荐写成用途-工具，比如预制小龙虾-Claude、预制小龙虾-Codex-测试
Provider / 应用Claude / Codex / Gemini这条配置写给哪个 CLI
API URL / Base URL见下面的接口地址表容易踩坑，往下看
API Key / 令牌你在平台创建的令牌必须用对应家族分组的令牌
Model（可选）模型 ID不填会用 CLI 默认值；要锁定模型时再填

四、平台接口地址（重点）

三个工具的接口地址写法不一样

工具API URL（一字不能错）
Claude Codehttps://www.yuzhixiaolongxia.com（不带 /v1）
Codex CLIhttps://www.yuzhixiaolongxia.com/v1（带 /v1）
Gemini CLIhttps://www.yuzhixiaolongxia.com/（末尾必须有斜杠）

最常踩的坑：

  • 给 Claude 多填了 /v1 —— 401 / 路由错误
  • 给 Codex 漏了 /v1 —— 找不到接口
  • 给 Gemini 漏了末尾斜杠 —— 部分版本会报路径异常

五、平台令牌怎么拿

CC-Switch 里填的 API Key，就是你在平台创建的"令牌"。

  1. 登录平台后台
  2. 进 /console/token（令牌管理）
  3. 点"新增令牌"
  4. 关键：令牌分组要选对
    • 配 Claude Code → 选 Claude 家族令牌分组
    • 配 Codex CLI → 选 Codex 家族令牌分组
    • 配 Gemini CLI → 选 Gemini 家族令牌分组
  5. 命名 + 保存，令牌只显示一次，立刻复制保存

分组选错会怎样

分组选错最常见的现象就是接入时报 model not found 或 permission denied。重建令牌时记得勾对家族。

详细分组介绍：令牌分组介绍。

六、切换的工作原理

理解这一点能少走很多弯路：

  1. 你在 CC-Switch 里点"启用某个配置"
  2. CC-Switch 会把这条配置写进对应 CLI 的本机配置文件（环境变量 / 配置 JSON / 用户目录下的设置文件）
  3. 已经打开的 CLI 进程不会自动更新，需要重开终端窗口
  4. 重开后再启动 CLI，就走的是新后端

切换后一定要重开终端

不重开终端的话，旧进程还在用内存里旧的环境变量，看起来"切了没生效"。99% 的"切换没反应"其实就是这个原因。

七、验证有没有切成功

打开新终端窗口，跑下面任一命令（取决于你切的工具）：

claude --version
codex --version
gemini --version

再进入会话发一句话（比如"回复：连接成功"），能正常返回就算切换到位。

更稳妥的验证流程：

curl -I https://www.yuzhixiaolongxia.com

返回 200 / 301 / 302 之一说明本机网络能到平台，问题不在网络。

八、常见坑速查

现象原因怎么处理
点了"启用"还是走旧后端终端进程没重开关掉所有 CLI 终端窗口，再重新打开
返回 401 / 403令牌错、分组不对、令牌已过期重建对应家族分组的令牌再替换
Claude 报路径或鉴权异常API URL 多填了 /v1改回 https://www.yuzhixiaolongxia.com
Codex 找不到接口API URL 漏了 /v1改成 https://www.yuzhixiaolongxia.com/v1
Gemini 部分版本报路径异常API URL 末尾漏了斜杠改成 https://www.yuzhixiaolongxia.com/
model not found模型 ID 不在你这条令牌的分组里去 模型广场 复制可用 ID，或换分组
多个配置同时显示"使用中"老版本 UI Bug重启 CC-Switch，再确认只有一个启用

下一步

通用篇看完了，按你的工具去对应专页：

上一步：CC-Switch 使用

预制小龙虾 | 文档系统
Copyright © 2026 预制小龙虾