📖 关于

本项目是 CC-Switch 的 CLI 分支。

🔄 WebDAV 同步功能与上游项目完全兼容。

致谢： 原始架构和核心功能来自 farion1231/cc-switch

🆕 5.3.0 新增内容

• 可以在不同的窗口中针对不同提供商运行 Claude/Codex，而不会影响当前的全局设置。
• 为 MCP 环境编辑增加了更丰富的 TUI 支持，包括基于覆盖的编辑、重复键保护以及更清晰的字段摘要。
• 改进了临时启动路由、提供商安全流程以及平台感知功能之间的运行时和 TUI 对齐。
• 继续优化 OpenClaw 流程、赞助者预设、配置路由以及当前 CLI 版本的发布文档。

❤️ 赞助商

	感谢 PackyCode 对本项目的赞助！PackyCode 是一家可靠高效的 API 中继服务提供商，为 Claude Code、Codex、Gemini 等提供中继服务。 PackyCode 为我们的软件用户提供特别折扣：通过 此链接 注册，并在充值时使用优惠码 cc-switch-cli，即可享受 10% 折扣。
	感谢 AICodeMirror 对本项目的赞助！AICodeMirror 为 Claude Code / Codex / Gemini CLI 提供官方高稳定性中继服务，具备企业级并发处理能力、快速开票以及全天候专属技术支持。Claude Code / Codex / Gemini 官方渠道价格分别仅为原价的 38% / 2% / 9%,且充值还可享受额外折扣！AICodeMirror 为 cc-switch-cli 用户提供特别福利：通过 此链接 注册，首次充值可享受 20% 折扣,企业客户最高可享 25% 折扣！
	感谢 RightCode 对本项目的赞助！RightCode 可靠地为 Claude Code、Codex 和 Gemini 等模型提供路由服务。它拥有极具性价比的 Codex 月度订阅计划，并且支持配额结转——当天未使用的配额可结转至次日继续使用。 RightCode 为 CC-Switch CLI 用户提供特别优惠：通过 此链接 注册，每次充值即可获得 25% 的按量付费积分奖励！

📸 截图

首页

切换	设置

🚀 快速入门

交互模式（推荐）

cc-switch

🤩 按照屏幕上的菜单探索各项功能。

命令行模式

cc-switch provider list              # 列出提供商
cc-switch provider switch <id>       # 切换提供商
cc-switch provider stream-check <id> # 检查提供商流媒体健康状况
cc-switch config webdav show         # 查看 WebDAV 同步设置
cc-switch env tools                  # 检查本地 CLI 工具
cc-switch mcp sync                   # 同步 MCP 服务器
cc-switch proxy show                 # 查看代理路由及状态

# 使用全局 `--app` 标志来指定特定应用：
cc-switch --app claude provider list    # 管理 Claude 提供商
cc-switch --app codex mcp sync          # 同步 Codex MCP 服务器
cc-switch --app gemini prompts list     # 列出 Gemini 提示词
cc-switch --app openclaw provider list  # 管理 OpenClaw 提供商

# 支持的应用：`claude`（默认）、`codex`、`gemini`、`opencode`、`openclaw`

完整命令列表请参阅“功能”部分。

📥 安装

方法 1：快速安装（macOS / Linux）

Windows 用户：请参阅下方的手动安装步骤。

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

这会将 cc-switch 安装到 ~/.local/bin。可通过设置 CC_SWITCH_INSTALL_DIR 来更改目标目录。

• 如果目标目录已存在，安装程序会在 TTY 中提示，并且在非交互式 shell 中拒绝覆盖，除非设置了 CC_SWITCH_FORCE=1。
• 在 Linux 上，如果需要 glibc 版本，请设置 CC_SWITCH_LINUX_LIBC=glibc。

# 下载通用二进制文件（推荐，支持 Apple Silicon + Intel）
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

# 移动到 PATH
sudo mv cc-switch /usr/local/bin/

# 如果遇到“无法验证”的警告
xattr -cr /usr/local/bin/cc-switch

# 下载
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

# 移动到 PATH
sudo mv cc-switch /usr/local/bin/

# 适用于树莓派或 ARM 服务器
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/

# 下载压缩包
# https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-windows-x64.zip

# 解压后，将 cc-switch.exe 移动到 PATH 目录，例如：
move cc-switch.exe C:\Windows\System32\

# 或直接运行
.\cc-switch.exe

方法 2：从源码构建

前提条件：

• Rust 1.85+（可通过 rustup 安装）

构建：

git clone https://github.com/saladday/cc-switch-cli.git
cd cc-switch-cli/src-tauri
cargo build --release

# 二进制文件位置：./target/release/cc-switch

安装到系统：

# macOS/Linux
sudo cp target/release/cc-switch /usr/local/bin/

# Windows
copy target\release\cc-switch.exe C:\Windows\System32\

✨ 功能特性

🔌 提供者管理

管理 Claude Code、Codex、Gemini、OpenCode 和 OpenClaw 的 API 配置。

功能： 一键切换、多端点支持、API 密钥管理、远程模型发现，以及在支持的情况下提供速度测试或流健康检查等应用级诊断功能。

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 duplicate <id>    # 复制提供者
cc-switch provider delete <id>       # 删除提供者
cc-switch provider speedtest <id>    # 测试 API 延迟
cc-switch provider stream-check <id> # 运行流健康检查
cc-switch provider fetch-models <id> # 获取远程模型列表

🛠️ MCP 服务器管理

管理 Claude、Codex、Gemini 和 OpenCode 中的模型上下文协议服务器。

功能： 统一管理、多应用支持、三种传输方式（stdio/http/sse）、自动同步，以及针对 TOML 和 JSON 目标的实时配置适配器。

cc-switch mcp list                   # 列出所有 MCP 服务器
cc-switch mcp add                    # 添加新 MCP 服务器（交互式）
cc-switch mcp edit <id>              # 编辑 MCP 服务器
cc-switch mcp delete <id>            # 删除 MCP 服务器
cc-switch mcp enable <id> --app claude   # 为特定应用启用
cc-switch mcp disable <id> --app claude  # 为特定应用禁用
cc-switch mcp validate <command>     # 验证 PATH 中的命令
cc-switch mcp sync                   # 同步到实时配置文件
cc-switch mcp import --app claude    # 从实时配置导入

💬 提示词管理

管理 AI 编程助手的系统提示词预设。

跨应用支持： Claude (CLAUDE.md)、Codex (AGENTS.md)、Gemini (GEMINI.md)、OpenCode (AGENTS.md)、OpenClaw (AGENTS.md)。

cc-switch prompts list               # 列出提示词预设
cc-switch prompts current            # 显示当前激活的提示词
cc-switch prompts activate <id>      # 激活提示词
cc-switch prompts deactivate         # 取消激活当前提示词
cc-switch prompts create             # 创建新的提示词预设
cc-switch prompts edit <id>          # 编辑提示词预设
cc-switch prompts show <id>          # 显示完整内容
cc-switch prompts delete <id>        # 删除提示词

🎯 技能管理

管理和扩展 Claude Code/Codex/Gemini/OpenCode 的能力，使用社区提供的技能。

功能： 基于 SSOT 的技能库、多应用启用/禁用、同步到应用目录、未管理扫描/导入、仓库发现。

cc-switch skills list                # 列出已安装的技能
cc-switch skills discover <query>      # 发现可用技能（别名：search）
cc-switch skills install <name>      # 安装技能
cc-switch skills uninstall <name>    # 卸载技能
cc-switch skills enable <name>       # 为当前应用启用（--app）
cc-switch skills disable <name>      # 为当前应用禁用（--app）
cc-switch skills info <name>         # 显示技能信息
cc-switch skills sync                # 将启用的技能同步到应用目录
cc-switch skills sync-method [m]     # 显示/设置同步方法（auto|symlink|copy）
cc-switch skills scan-unmanaged      # 扫描应用目录中的未管理技能
cc-switch skills import-from-apps    # 将未管理技能导入 SSOT
cc-switch skills repos list          # 列出技能仓库
cc-switch skills repos add <repo>    # 添加仓库（owner/name[@branch] 或 GitHub URL）
cc-switch skills repos remove <repo> # 移除仓库（owner/name 或 GitHub URL）
cc-switch skills repos enable <repo> # 启用仓库而不更改分支
cc-switch skills repos disable <repo> # 禁用仓库而不更改分支

⚙️ 配置管理

管理配置的备份、导入和导出。

功能： 自定义备份命名、交互式备份选择、自动轮转（保留 10 个）、导入/导出、常用片段、WebDAV 同步。

cc-switch config show                # 显示配置
cc-switch config path                # 显示配置文件路径
cc-switch config validate            # 验证配置文件

# 常用片段（跨提供者的共享设置）
# 在适用时尝试刷新实时配置（--apply 仅作为兼容性标志保留）
cc-switch --app claude config common show
cc-switch --app claude config common set --snippet '{"env":{"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":1},"includeCoAuthoredBy":false}'
cc-switch --app claude config common clear

# 备份
cc-switch config backup              # 创建备份（自动命名）
cc-switch config backup --name my-backup  # 创建自定义名称的备份

# 恢复
cc-switch config restore             # 交互式：从备份列表中选择
cc-switch config restore --backup <id>    # 根据 ID 恢复特定备份
cc-switch config restore --file <path>    # 从外部文件恢复

# 导入/导出
cc-switch config export <path>       # 导出到外部文件
cc-switch config import <path>       # 从外部文件导入

# WebDAV 同步
cc-switch config webdav show
cc-switch config webdav set --base-url <url> --username <user> --password <password> --enable
cc-switch config webdav jianguoyun --username <user> --password <password>
cc-switch config webdav check-connection
cc-switch config webdav upload
cc-switch config webdav download
cc-switch config webdav migrate-v1-to-v2

cc-switch config reset               # 重置为默认配置

🌉 代理管理

检查并控制受支持的应用程序使用的本地多应用代理。

功能： 持久化的启用/禁用开关、当前路由检查、仪表板遥测，以及用于调试的前台服务模式。

cc-switch proxy show                 # 显示代理配置和路由
cc-switch proxy enable               # 启用持久化的代理开关
cc-switch proxy disable              # 禁用持久化的代理开关
cc-switch proxy serve                # 在前台运行代理

🧪 环境与本地工具

检查环境冲突以及是否已安装所需的本地 CLI 工具。

cc-switch env check                  # 检查环境冲突
cc-switch env list                   # 列出相关环境变量
cc-switch env tools                  # 检查 Claude/Codex/Gemini/OpenCode 的 CLI 工具

🌐 多语言支持

交互模式支持英语和中文，语言设置会自动保存。

• 默认语言：英语
• 前往 ⚙️ 设置 菜单切换语言

🔧 实用工具

Shell 补全、环境管理及其他实用工具。

# Shell 补全
cc-switch completions <shell>        # 生成 shell 补全（bash/zsh/fish/powershell）

# 环境管理
cc-switch env check                  # 检查环境冲突
cc-switch env list                   # 列出环境变量

# 自我更新
cc-switch update                     # 更新到最新版本
cc-switch update --version vX.Y.Z    # 更新到指定版本

🏗️ 架构

核心设计

• SQLite 支持的状态存储：核心数据存储在 ~/.cc-switch/cc-switch.db 中；旧版的 ~/.cc-switch/config.json 仅保留用于旧版本的导入和迁移路径。
• 技能的唯一事实来源 (SSOT)：技能源文件存储在 ~/.cc-switch/skills/ 目录中，而安装状态和应用启用信息则保存在数据库中。
• 安全的实时同步（默认）：对于尚未初始化的应用，跳过写入实时配置文件的操作，以防止意外创建 ~/.claude、~/.codex、~/.gemini、~/.config/opencode 或 ~/.openclaw 目录。
• 原子写入：通过临时文件加重命名的方式避免数据损坏。
• 服务层复用：100% 复用自原始 GUI 版本。
• 并发安全：使用带有作用域保护的读写锁。

配置文件

CC-Switch 存储：

• ~/.cc-switch/cc-switch.db - 主数据库，用于存储提供商、MCP、提示词和应用状态。
• ~/.cc-switch/settings.json - 设置文件。
• ~/.cc-switch/skills/ - 已安装技能的源文件（SSOT）。
• ~/.cc-switch/backups/ - 自动轮转备份（保留 10 个）。
• ~/.cc-switch/config.json - 旧版 JSON 文件，为兼容性和导入流程保留。

实时配置：

• Claude：~/.claude/settings.json（提供商/通用配置）、~/.claude.json（MCP）、~/.claude/CLAUDE.md（提示词）。
• Codex：~/.codex/auth.json（认证状态）、~/.codex/config.toml（提供商/通用配置 + MCP）、~/.codex/AGENTS.md（提示词）。
• Gemini：~/.gemini/.env（提供商环境变量）、~/.gemini/settings.json（设置 + MCP）、~/.gemini/GEMINI.md（提示词）。
• OpenCode：~/.config/opencode/opencode.json（提供商 + MCP + 运行时配置）、~/.config/opencode/AGENTS.md（提示词）。
• OpenClaw：~/.openclaw/openclaw.json（提供商 + 环境/工具/代理人默认值）、~/.openclaw/AGENTS.md（提示词）。

❓ 常见问题解答 (FAQ)

cc-switch --app codex provider list

🛠️ 开发

要求

• Rust：1.85+（rustup）
• Cargo：随 Rust 一起提供

命令

cd src-tauri

cargo run                            # 开发模式
cargo run -- provider list           # 运行特定命令
cargo build --release                # 构建发布版本

cargo fmt                            # 格式化代码
cargo clippy                         # 代码 lint 检查
cargo test                           # 运行测试

代码结构

src-tauri/src/
├── cli/
│   ├── commands/          # CLI 子命令（provider、mcp、prompts、skills、proxy、env 等）
│   ├── tui/               # 交互式 TUI 模式（ratatui）
│   ├── interactive/       # 交互式入口 / TTY 门控
│   └── ui/                # UI 工具（表格、颜色）
├── services/              # 业务逻辑（provider、mcp、prompt、webdav 等）
├── database/              # SQLite 存储、迁移、备份
├── main.rs                # CLI 入口点
└── ...                    # 应用特定配置、代理、错误处理等

🤝 贡献

欢迎贡献！此分支专注于 CLI 功能。

提交 PR 之前：

• ✅ 通过格式检查：cargo fmt --check
• ✅ 通过 linter 检查：cargo clippy
• ✅ 通过测试：cargo test
• 💡 请先开一个议题进行讨论

📜 许可证

• MIT © 原作者：Jason Young
• CLI 分支维护者：saladday

cc-switch-cli 快速上手指南

cc-switch-cli 是一款基于 Rust 开发的命令行工具，用于统一管理 Claude Code、Codex、Gemini、OpenCode 和 OpenClaw 的配置。它支持一键切换 API 提供商、管理 MCP 服务器、同步技能（Skills）、管理系统提示词（Prompts）以及配置本地代理。

🛠️ 环境准备

系统要求

• 操作系统：Windows、macOS (Intel/Apple Silicon)、Linux (x64/ARM64)
• 架构支持：通用二进制或特定架构包（见安装步骤）

前置依赖

• 运行模式：直接下载预编译二进制文件无需额外依赖。
• 源码编译模式：需安装 Rust 1.85+ (rustup)。
• 网络环境：访问 GitHub Releases 下载资源；若连接不畅，建议配置终端代理或使用国内镜像加速。

📥 安装步骤

方法一：一键安装脚本（推荐 macOS / Linux）

在终端执行以下命令，自动下载并安装到 ~/.local/bin：

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

注意：

• 安装完成后，请确保 ~/.local/bin 已加入环境变量 PATH。
• 若需自定义安装目录，可设置环境变量 CC_SWITCH_INSTALL_DIR。
• Linux 用户如需 glibc 版本，请设置 CC_SWITCH_LINUX_LIBC=glibc。

方法二：手动安装

macOS (Universal Binary)

支持 Apple Silicon 和 Intel 芯片。

# 下载
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/

# 若遇到“无法验证开发者”警告，执行：
xattr -cr /usr/local/bin/cc-switch

Linux (x64 / ARM64)

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/

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 包：cc-switch-cli-windows-x64.zip
2. 解压后，将 cc-switch.exe 移动到系统路径（如 C:\Windows\System32\）或任意已加入 PATH 的目录。
3. 或在当前目录直接运行：

   .\cc-switch.exe
   

方法三：源码编译

需安装 Rust 1.85+。

git clone https://github.com/saladday/cc-switch-cli.git
cd cc-switch-cli/src-tauri
cargo build --release

# 二进制文件位于 ./target/release/cc-switch
# 将其复制到系统 PATH 即可使用

🚀 基本使用

1. 交互式模式（推荐新手）

直接运行命令进入图形化终端界面（TUI），通过菜单操作所有功能：

cc-switch

2. 命令行模式

管理 API 提供商 (Provider)

列出、切换或测试不同模型的 API 配置：

cc-switch provider list              # 列出所有提供商
cc-switch provider switch <id>       # 切换到指定 ID 的提供商
cc-switch provider speedtest <id>    # 测试 API 延迟
cc-switch provider stream-check <id> # 检查流式响应健康度

针对特定应用操作

使用 --app 标志指定目标应用（支持 claude, codex, gemini, opencode, openclaw）：

# 管理 Claude 的提供商
cc-switch --app claude provider list

# 同步 Codex 的 MCP 服务器
cc-switch --app codex mcp sync

# 列出 Gemini 的提示词预设
cc-switch --app gemini prompts list

管理 MCP 服务器与技能

cc-switch mcp list                   # 列出 MCP 服务器
cc-switch mcp sync                   # 同步 MCP 配置到应用
cc-switch skills list                # 列出已安装的技能
cc-switch skills install <name>      # 安装新技能
cc-switch skills sync                # 将启用的技能同步到应用目录

其他常用命令

cc-switch prompts list               # 查看提示词预设
cc-switch proxy show                 # 查看代理路由状态
cc-switch env tools                  # 检查本地 CLI 工具环境

💡 提示：首次使用时，建议先运行 cc-switch 进入交互模式熟悉配置流程，后续可通过命令行脚本实现自动化切换。