通用步骤

大约 2 分钟

CC-Switch 通用步骤

本页是三端共用的安装与检查流程。先完成这里，再进入 Claude、Codex、Gemini 的专页。

一、前置检查

1. Node.js 与 npm

node -v
npm -v

通过标准：

Node.js 建议 >= 20
npm 可正常输出版本号

2. CLI 是否已安装

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

说明：

你不一定要三个都装，但至少要安装当前要使用的那个 CLI
如果提示 command not found，先到 /docs/cli/1-env.html 完成安装

3. 网络连通性

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

通过标准：

返回 200 / 301 / 302 均可
连接超时或 TLS 失败需先处理网络问题

二、下载与安装

Windows（图形安装）

在下载区选择 Windows 安装包
双击安装包并完成安装
在开始菜单启动 CC-Switch

macOS（推荐 Homebrew）

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

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
进入 Provider 或供应商页面
新增供应商，类型选择 OpenAI 兼容或平台模板
填写 API 地址与 API Key
保存并启用

配置时常用参数：

API 地址：https://www.yuzhixiaolongxia.com/v1
API Key：你在平台控制台创建的令牌

四、验证是否生效

完成启用后，任选一个 CLI 验证：

claude

codex

gemini

通过标准：

CLI 可以正常进入会话
能成功返回一条简单问答结果

五、常见错误

问题	原因	处理方式
保存后仍走旧配置	未点启用或启用了错误配置	回到配置列表，确认目标配置状态为“使用中”
CLI 报 401/403	API Key 无效或分组不匹配	重新创建对应分组令牌并替换
CLI 报模型不存在	模型名称不在当前分组可用列表	改用分组支持的模型名
配置后无变化	终端进程没重启	关闭并重开终端，再次执行 CLI

下一步