CC-Switch CLI 使用指南

CC-Switch CLI 是 CC-Switch 的命令行版本，适合没有图形界面的服务器、批量运维、远程桌面较少使用的主机，以及需要把配置切换写进脚本的场景。

如果你平时主要在桌面环境里点界面，CC-Switch 图形版更直观；如果你要做自动化、巡检、迁移和应急切换，这一页的 CLI 方式更稳。

它最常见的 4 个用途是：

• 在 Claude、Codex、Gemini 之间切换 Provider
• 快速确认当前机器到底启用了哪套配置
• 批量同步 MCP / Prompt / 配置备份
• 在发版、迁移、故障切换时减少人工操作

一、安装

macOS

curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-darwin-universal.tar.gz
tar -xzf cc-switch-cli-darwin-universal.tar.gz
chmod +x cc-switch
sudo mv cc-switch /usr/local/bin/

Linux x64

curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-linux-x64-musl.tar.gz
tar -xzf cc-switch-cli-linux-x64-musl.tar.gz
chmod +x cc-switch
sudo mv cc-switch /usr/local/bin/

Linux ARM64

curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-linux-arm64-musl.tar.gz
tar -xzf cc-switch-cli-linux-arm64-musl.tar.gz
chmod +x cc-switch
sudo mv cc-switch /usr/local/bin/

Windows

1. 下载对应 zip
2. 解压得到 cc-switch.exe
3. 放入 PATH 目录（如 C:\Windows\System32 或自定义工具目录）

安装验证：

cc-switch --version

如果命令能输出版本号，说明可执行文件已经进入 PATH。

二、初始化与首次配置

首次使用建议先准备好下面两项信息：

• Base URL：https://www.yuzhixiaolongxia.com/v1
• 对应工具分组的 API Key

建议一开始不要把所有 Provider 一次性全加满，先用你当前最需要的那个工具建立第一条配置，验证通过后再继续扩展。

cc-switch

进入交互界面后按流程完成：

1. 添加 Provider
2. 选择目标应用（claude/codex/gemini）
3. 填写 Base URL 与 API Key
4. 保存并启用

推荐地址：

• https://www.yuzhixiaolongxia.com/v1

首次配置完成后，建议立刻再做 2 个动作：

1. 执行 cc-switch provider current，确认当前启用的是你刚创建的 Provider。
2. 重开终端，再启动目标 CLI 做最小请求测试。

三、子命令总览

下面这张表可以先建立一个全局认识，避免把 CLI 当成“只能切换 Provider”的单一工具。

模块	作用	典型场景
provider	管理模型线路、端点、Key 和当前启用项	切换测试/正式环境，切换 Claude/Codex/Gemini 线路
mcp	管理 MCP 相关配置并同步	给不同机器同步 MCP 能力，统一工具接入
prompts	管理和启用 Prompt 模板	团队统一系统提示词或预设
config	备份、导出、恢复整体配置	迁移新机器、做故障回滚、定期备份
--app	指定操作作用于哪个应用	一台机器同时维护多套应用配置

四、常用子命令与用途说明

Provider 管理

cc-switch provider list
cc-switch provider current
cc-switch provider switch <id>
cc-switch provider add
cc-switch provider edit <id>
cc-switch provider delete <id>

命令	用途	什么时候用
cc-switch provider list	查看当前机器保存了哪些 Provider	排查“这台机器到底配了几套线路”
cc-switch provider current	查看当前生效项	发版前确认没有误用测试线路
cc-switch provider switch <id>	切换到指定 Provider	测试/生产切换、故障切换
cc-switch provider add	新增一条 Provider	新增工具、新增环境或新增账户
cc-switch provider edit <id>	修改已有 Provider	Key 轮换、Base URL 调整、模型名修正
cc-switch provider delete <id>	删除废弃 Provider	下线旧线路、清理失效配置

多应用切换

cc-switch --app claude provider list
cc-switch --app codex provider list
cc-switch --app gemini provider list

这组写法的重点不是“列出更多内容”，而是把操作范围限定到某个应用，避免你在多工具共存的机器上切错目标。

常见用途：

• 查看 Claude 当前有哪些可切换配置
• 只修改 Codex 的 Provider，不影响 Claude
• 给 Gemini 单独维护一套测试线路

MCP 管理

cc-switch mcp list
cc-switch mcp add
cc-switch mcp edit <id>
cc-switch mcp delete <id>
cc-switch mcp sync

命令	用途	运维价值
cc-switch mcp list	查看当前 MCP 配置	巡检某台机器有没有同步到位
cc-switch mcp add	新增 MCP 条目	接入新的工具或服务端能力
cc-switch mcp edit <id>	修改 MCP 配置	地址变更、参数调整
cc-switch mcp delete <id>	删除废弃条目	清理无效依赖
cc-switch mcp sync	执行同步	多机器统一配置时很常用

Prompt 管理

cc-switch prompts list
cc-switch prompts activate <id>
cc-switch prompts deactivate
cc-switch prompts create
cc-switch prompts edit <id>

命令	用途	适合场景
cc-switch prompts list	查看可用 Prompt 模板	确认机器上有哪些预设
cc-switch prompts activate <id>	启用某个 Prompt	切换团队预设、任务预设
cc-switch prompts deactivate	取消当前 Prompt	排查 Prompt 是否影响输出
cc-switch prompts create	创建新模板	新建团队规范 Prompt
cc-switch prompts edit <id>	修改模板	更新提示词策略

配置备份与恢复

cc-switch config backup
cc-switch config restore
cc-switch config export <path>
cc-switch config import <path>

命令	用途	典型场景
cc-switch config backup	创建本地备份	大改配置前先留回退点
cc-switch config restore	恢复最近备份	改错配置后快速回滚
cc-switch config export <path>	导出配置文件	迁移新机器或归档
cc-switch config import <path>	导入配置文件	初始化新环境、批量复制

五、典型运维操作

场景 1：切换到生产配置

cc-switch --app codex provider switch prod

适用场景：

• 代码发版后，把 Codex 从测试线路切回正式线路
• 排查结束后恢复默认生产配置

场景 2：部署后快速验活

cc-switch --app claude provider current
claude

建议做法：

1. 先用 provider current 确认当前启用项确实是目标线路。
2. 再启动对应 CLI 发一条最小请求。
3. 如果结果异常，先不要急着改所有配置，先切回上一个已知可用 Provider。

场景 3：迁移到新机器

cc-switch config export ./cc-switch-backup.json
cc-switch config import ./cc-switch-backup.json

适用场景：

• 新服务器初始化
• 员工换电脑
• 本地环境重装后快速恢复

场景 4：Key 轮换后批量修正

cc-switch provider list
cc-switch provider edit <id>
cc-switch provider current

适用场景：

• 某条线路的 API Key 已过期
• 怀疑令牌泄露，需要替换但不想重建整套配置

场景 5：大改前先做回退点

cc-switch config backup
cc-switch --app codex provider switch staging
cc-switch --app codex provider current

适用场景：

• 计划临时切到测试环境排查问题
• 想确保排查结束后可以快速恢复原线路

六、服务器和脚本场景的使用建议

在运维环境里，建议遵守下面几条：

• 不要在生产机上保存一堆没人维护的旧 Provider。
• 每次切换前后都执行一次 provider current 留痕确认。
• 大改前先 config backup，避免改乱后只能手工重配。
• 迁移机器时优先用 export/import，不要靠人工逐项重填。
• CLI 切换完成后，务必再用目标应用做一次最小业务验证。

七、常见错误

现象	原因	处理方式
cc-switch: command not found	可执行文件不在 PATH	重新放入 PATH 并重开终端
切换成功但 CLI 仍报旧错误	CLI 进程未重启	关闭并重开终端后再测
401 或 403	Key 无效或分组不匹配	更换正确令牌
导入配置失败	导出文件格式不兼容	升级到最新版本后重试

补充判断方法：

• provider current 看着没问题，但 CLI 还走旧配置，优先怀疑终端会话未重启。
• 多应用共存时，优先加上 --app claude / --app codex / --app gemini，不要在默认上下文里盲切。
• 导入旧备份后如果表现异常，先检查 CLI 版本是否与导出时差异过大。

上一步：Gemini 配置