CC-Switch 是一款跨平台桌面应用，通过统一的 GUI 管理 Claude Code、Codex、OpenCode 和 Gemini CLI 的提供商配置。不再需要手动编辑 JSON 和 TOML 文件——添加一个提供商，点击切换，所有编程工具立即完成重新配置。

问题是什么？每个 AI 编程工具都需要独立的提供商配置，如果你使用多个 LLM 提供商，跨四个工具管理 Key 会变得非常混乱。

将 Omniside 作为统一 API 网关，你只需在 CC-Switch 中添加一次提供商，Claude Code、Codex、OpenCode、Gemini CLI 四个工具就会全部通过同一个端点、同一个 API Key 路由请求。

本指南覆盖 macOS、Windows 和 Linux（Ubuntu、Debian、CentOS） 的安装与配置。

CC-Switch 界面

CC-Switch 做什么

CC-Switch 常驻系统托盘，管理各 AI 编程工具的配置文件：

  • Claude Code → 写入 ~/.claude.json（API Key + Base URL）
  • Codex → 写入 ~/.codex/config.toml（模型提供商 + API Key）
  • OpenCode → 写入 ~/.config/opencode/opencode.json（提供商配置）
  • Gemini CLI → 写入 ~/.gemini/.env（API Key + Base URL）

在 CC-Switch 中切换提供商时，它会立即自动重写对应工具的配置文件，无需手动操作。

前置条件

  1. 至少安装一个 AI 编程工具 — Claude Code、Codex、OpenCode 或 Gemini CLI
  2. Omniside API Key — 在这里注册

第一步：安装 CC-Switch

macOS

  1. 从 GitHub Releases 下载最新 .dmg 或 .zip
  2. 将 CC-Switch.app 拖入应用程序文件夹
  3. 首次启动可能触发 Gatekeeper 拦截——前往系统设置 → 隐私与安全性 → 仍要打开

或通过 Homebrew（如已支持）：

Terminal window
brew install --cask cc-switch

Windows

方案 A：MSI 安装包（推荐）

  1. 从 GitHub Releases 下载 .msi 文件
  2. 双击安装
  3. 从开始菜单启动

方案 B：便携版

  1. 下载 .zip 便携版
  2. 解压后直接运行 CC-Switch.exe，无需安装

Ubuntu / Debian

从 GitHub Releases 下载 .deb 包：

Terminal window
# 下载最新 .deb（具体 URL 见 releases 页面）
wget https://github.com/farion1231/cc-switch/releases/latest/download/cc-switch_amd64.deb


# 安装
sudo dpkg -i cc-switch_amd64.deb


# 如需修复依赖
sudo apt-get install -f

CentOS / RHEL / Fedora

下载 .rpm 包：

Terminal window
wget https://github.com/farion1231/cc-switch/releases/latest/download/cc-switch_x86_64.rpm


sudo rpm -i cc-switch_x86_64.rpm
# 或 Fedora：
sudo dnf install cc-switch_x86_64.rpm

Arch Linux

Releases 页面也提供 AppImage，下载后直接运行：

Terminal window
chmod +x CC-Switch-*.AppImage
./CC-Switch-*.AppImage

Linux ARM64

v3.10.3 起支持 ARM64，从 releases 页面下载 arm64.deb 或 arm64.AppImage。

第二步：获取 Omniside API Key

  1. 前往 platform.omniside.ai
  2. 注册或登录
  3. 进入 API Keys 页面
  4. 点击 Create API Key
  5. 复制 Key（以 sk- 开头）

第三步：添加 Omniside 提供商

启动 CC-Switch 后，顶部导航栏有各编程工具的标签页（Claude Code、Codex、OpenCode、Gemini）。

Claude Code

  1. 选择 Claude Code 标签页
  2. 点击 Add Provider
  3. 填写以下信息：
字段值
Provider NameOmniside
API Keysk-your-omniside-key
Base URLhttps://api.omniside.ai
API FormatOpenAI Chat Completions
  1. 点击 Save

重要：由于 Omniside 兼容 OpenAI API，API Format 选择 “OpenAI Chat Completions”。CC-Switch v3.10.3+ 为 Claude 提供商支持此格式选择器。切换到 OpenAI Chat 格式提供商时，CC-Switch 会提示你启用内置代理。

Codex

  1. 选择 Codex 标签页
  2. 点击 Add Provider
  3. 填写：
字段值
Provider NameOmniside
API Keysk-your-omniside-key
Base URLhttps://api.omniside.ai/v1
  1. 点击 Save

CC-Switch 会将此配置以 model_providers 条目的形式写入 ~/.codex/config.toml。

OpenCode

  1. 选择 OpenCode 标签页
  2. 点击 Add Provider
  3. 填写：
字段值
Provider NameOmniside
API Keysk-your-omniside-key
Base URLhttps://api.omniside.ai/v1
  1. 点击 Save

CC-Switch 会自动生成带 @ai-sdk/openai-compatible npm 适配器的 opencode.json 配置。

Gemini CLI

  1. 选择 Gemini 标签页
  2. 点击 Add Provider
  3. 填写：
字段值
Provider NameOmniside
API Keysk-your-omniside-key
Base URLhttps://api.omniside.ai/v1
  1. 点击 Save

CC-Switch 会将 Key 和 Base URL 写入 ~/.gemini/.env。

Universal Provider（推荐）

CC-Switch 支持 Universal Provider 模式——配置一次 Omniside，自动同步至全部四个工具：

  1. 添加提供商时勾选 “Cross-app sharing (Universal Provider)”
  2. 同一套 Omniside 配置会同时应用到 Claude Code、Codex、OpenCode 和 Gemini CLI

这是最快的全工具配置方式。

第四步：切换至 Omniside

在提供商列表中，点击 “Omniside” 旁边的切换按钮激活它。CC-Switch 会立即重写所选工具的配置文件。

你可以通过内置速度测试验证连接——点击提供商旁边的测速图标，确认 API 延迟正常。

第五步：配置模型映射（Claude Code）

针对 Claude Code，CC-Switch 支持将其三档速度层级映射至 Omniside 具体模型：

层级推荐映射
Opus（高性能）claude-sonnet-4-5-20250514
Sonnet（均衡）gpt-4o
Haiku（快速）deepseek-chat

这样当 Claude Code 根据任务复杂度自动选择层级时，会路由到最具性价比的 Omniside 模型。

使用 CC-Switch 内置代理

CC-Switch 包含本地代理服务器，提供以下高级功能：

  • 自动故障转移 — Omniside 临时不可用时，CC-Switch 可自动切换至备用提供商
  • 请求日志 — 实时查看所有 API 调用、Token 用量和费用
  • Claude Rectifier（思维签名修复） — 修复使用 Claude 模型时第三方 API 的兼容性问题

启用方式：进入 Settings → Proxy 并打开开关。使用 OpenAI Chat 格式提供商（如 Omniside）时，CC-Switch 会提示你启用此功能。

各平台注意事项

macOS

CC-Switch 以菜单栏应用形式运行。如果找不到图标，检查系统设置 → 登录项，确认其被允许运行。

Windows

CC-Switch 支持三种终端：cmd、PowerShell 和 Windows Terminal，在 Settings → Preferred Terminal 中设置偏好。

Windows 配置路径：

  • CC-Switch 数据：%USERPROFILE%\.cc-switch\
  • Claude Code 配置：%USERPROFILE%\.claude.json
  • Codex 配置：%USERPROFILE%\.codex\config.toml
  • OpenCode 配置：%USERPROFILE%\.config\opencode\opencode.json

Linux

在 Wayland（GNOME/Sway）下，CC-Switch 会禁用模态背景虚化以避免卡死。如遇 UI 问题，尝试加 --disable-gpu 参数启动。

CC-Switch 数据存储在 ~/.cc-switch/：

  • cc-switch.db — SQLite 数据库（提供商、MCP 服务器、提示词、技能）
  • settings.json — 设备级设置
  • backups/ — 自动轮换备份（保留最近 10 份）

CentOS / RHEL

如果 .rpm 包有依赖问题，改用 AppImage——它打包了所有依赖项。

导入 / 导出与云同步

CC-Switch 支持完整配置的备份与恢复：

  • 导出：Settings → Export → 保存 .sql 备份文件
  • 导入：Settings → Import → 从备份恢复

跨设备云同步：

  1. 进入 Settings → Custom Configuration Directory
  2. 指向云盘目录（Dropbox、OneDrive、iCloud Drive）
  3. 重启应用

你的所有 Omniside 提供商配置将自动在多台设备间同步。

问题排查

切换提供商后未生效

确认你点击了切换按钮激活提供商（而不只是保存）。切换后尝试重启编程工具的会话。

Codex 出现 404 错误

Codex 的 base URL 应为 https://api.omniside.ai/v1。CC-Switch v3.10.3 修复了 /v1 被重复拼接的 bug，请确保使用最新版本。

健康检查失败

运行 CC-Switch 内的速度测试。如果失败：

  1. 检查 API Key 是否正确
  2. 验证网络连接：curl https://api.omniside.ai/v1/models -H "Authorization: Bearer sk-your-key"
  3. 如在代理后面，在 Settings → Global Proxy 中配置

Claude Code 出现认证错误

如果使用 OpenAI Chat Completions 格式，确认 CC-Switch 内置代理已启用。Claude Code 原生使用 Anthropic 协议，代理负责格式转换。

为什么选择 CC-Switch + Omniside？

没有 CC-Switch，切换提供商意味着跨四个工具编辑 JSON 和 TOML 文件，每次都要保证语法正确。没有 Omniside，你需要为每个 LLM 提供商维护独立的 API Key。

两者结合，你得到一个统一 GUI：配置一次 Omniside，一键切换，Claude Code、Codex、OpenCode 和 Gemini CLI 四个工具瞬间接入所有主流 AI 模型。

前往 platform.omniside.ai 获取 API Key，开始编程。