ccs CLI：用命令行管理 CC Switch 配置

开始前先确认

ccs CLI 适合服务器和脚本场景，但它仍然会修改本机目标 CLI 的配置。第一次使用前，先确认命令、权限和令牌边界，避免脚本把错误 Provider 扩散到长期环境。

日常命令流程：每次切换都留回证

ccs 最适合放在服务器、部署脚本和应急切换流程里。安全的用法不是只跑 ccs use，而是切换前后都确认应用范围、当前 Provider 和真实请求。

谁适合用 ccs

一、安装

按 ccs CLI GitHub 仓库 或 Releases 选择对应系统版本。官方可执行文件通常叫 cc-switch；本文为了命令更短，统一用 ccs 表示你本机设置好的命令名。

macOS / Linux 一键安装

curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash

一键脚本默认把命令安装到用户目录。安装完成后，新开一个终端，把用户 bin 目录加入 PATH，再检查版本：

export PATH="$HOME/.local/bin:$PATH"
cc-switch --version

如果你想使用 ccs 这个短命令

如果安装后只有 cc-switch 命令，可以任选一种方式设置短别名。团队文档、脚本和教程里建议统一一个命令名，避免复制命令时混乱。

# 临时别名：只对当前 shell 生效
alias ccs="cc-switch"

# 持久别名：追加到你的 shell 配置
echo 'alias ccs="cc-switch"' >> ~/.zshrc

# 或者创建软链接，路径按你的实际安装位置调整
ln -s "$HOME/.local/bin/cc-switch" "$HOME/.local/bin/ccs"

Homebrew 安装

brew install cc-switch-cli
cc-switch --version

手动下载安装

手动安装适合不能跑安装脚本、需要固定二进制路径或需要离线分发的服务器。下面是常见平台示例；如果 Releases 页面文件名有变化，以官方页面为准。

# macOS Universal
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/ccs

# 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/ccs

# 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/ccs

Windows 安装要点

1. 从 Releases 下载 Windows x64 zip。
2. 解压得到 cc-switch.exe。
3. 可以保留原名，也可以重命名为 ccs.exe。
4. 放入 PATH 目录，或把所在目录加入 PATH。
5. 重新打开 PowerShell，执行 cc-switch.exe --version 或 ccs.exe --version。

二、首次配置

第一次使用 ccs，先准备 6星中转 的 API URL 和令牌。地址规则和图形版一致：

进入交互式向导：

ccs

1. 选择添加 Provider。
2. 选择目标应用：Claude、Codex 或 Gemini。
3. 填写 API URL、API Key 和可选模型。
4. 保存并启用。
5. 查看当前状态。

ccs status

三、最常用的 4 个命令

ccs list
ccs use 6星中转-Codex-prod
ccs status
ccs edit

四、按应用单独操作

一台机器同时配置 Claude、Codex、Gemini 时，建议加应用参数锁定操作范围，避免“以为在切 Codex，实际切了 Claude”。

ccs --app claude list
ccs --app codex list
ccs --app gemini list

ccs --app codex use 6星中转-Codex-prod
ccs --app codex status

脚本里尤其建议显式写应用名，不要依赖默认上下文。

五、备份、迁移和回滚

换机器、重装系统、大改配置之前，先导出或备份。导出的文件通常包含明文令牌，必须像密码一样保管。

# 老机器导出
ccs config export ./ccs-backup.json

# 新机器导入
ccs config import ./ccs-backup.json
ccs status

# 大改前先备份
ccs config backup

# 如果改坏了，恢复到备份
ccs config restore

六、其他能力先知道边界

ccs 除了切 Provider，还可能提供配置、MCP、Prompt 模板等管理命令。新手先把 Provider、备份和状态检查用稳；其他能力只在明确需要时使用，不要把无关模块一起写进切换脚本。

切错或改坏时怎么回滚

如果切换后目标 CLI 报错、模型不可用或用量日志没有记录，先回到最近可用配置，再慢慢排查。不要一边改多处配置一边重试。

密钥和备份安全

ccs 省去了手写配置文件的麻烦，但 Provider 和备份里可能保存完整 API Key。服务器场景尤其要把文件权限、日志和 Git 边界说清楚。

七、典型运维场景

部署后切回生产 Provider

ccs --app codex use 6星中转-Codex-prod
ccs --app codex status

预期状态里当前启用项就是 6星中转-Codex-prod。之后重开目标 CLI 或重启依赖该配置的进程，再跑健康检查。

新服务器初始化

# 老机器
ccs config export ./ccs-backup.json

# 新机器
ccs config import ./ccs-backup.json
ccs status

令牌轮换

ccs --app claude list
ccs --app claude edit
ccs --app claude status

替换 Key 后，用目标 CLI 做一次短请求，并到 6星中转 用量日志核对时间点。

八、脚本模板

把 ccs 写进脚本时，重点不是“切换命令能跑”，而是切换前后都有状态记录，失败时能立刻停住。

#!/usr/bin/env bash
set -euo pipefail

APP="codex"
PROVIDER="6星中转-Codex-prod"

echo "[before]"
ccs --app "$APP" status

echo "[switch]"
ccs --app "$APP" use "$PROVIDER"

echo "[after]"
ccs --app "$APP" status

echo "请重启目标 CLI 或相关进程后，再发起一次短请求验证。"

九、完成标准

十、常见误区

十一、写进脚本时的建议

• 切换前后各跑一次 ccs status，日志里留下证据。
• 大改前先 ccs config backup。
• 切换完成后，用目标 CLI 跑一个最小请求，不要只看状态。
• 多应用机器一律带 --app。
• 生产机器及时清理不用的旧 Provider，避免误切。

脚本或服务器切换失败时，提交这些定位信息

ccs 常用于服务器、脚本和多应用机器。排障时要证明命令执行过、切换的是哪个应用、备份在哪里，以及目标 CLI 是否真的走到 6星中转。

如果切错应用，先按 回滚流程 恢复；如果仍无法定位，再使用 FAQ 工单模板 提交脱敏信息。