CC Switch

CC Switch 是一款免费开源的桌面应用（MIT 许可），用于统一管理各类 AI 编程工具的供应商配置。它会将配置写入各工具自己的配置文件，工具仍然直接连接供应商；默认不代理请求，也不记录请求内容。

支持的工具：Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes Agent、Pi。

适用场景#

• 需要在订阅额度与 API 调用之间切换：可以切换到 Amux 的按量计费，减少工具侧重复配置
• 需要管理多套供应商配置：各配置可独立保存，并通过界面快速切换
• 需要为 Claude Code 的三档模型指定不同映射：可直接使用内置的模型映射界面
• 已经手动配置过工具，想统一回收管理：CC Switch 可以整体切换配置，减少环境变量残留带来的干扰

一、安装#

macOS#

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

也可以从 GitHub Releases 下载 DMG 或 ZIP，把 CC-Switch.app 拖进「应用程序」。

Windows#

从 Releases 下载 .msi 安装包运行即可。或者下载免安装的 .zip，解压到任意目录后运行 CC-Switch.exe。

Linux#

# Debian / Ubuntu
sudo dpkg -i cc-switch_*.deb

# AppImage
chmod +x CC-Switch_*.AppImage
./CC-Switch_*.AppImage

二、创建 Amux 密钥#

在控制台的密钥页创建密钥。创建后仍可在该页面再次查看，无需重新生成。

想按工具分开统计用量的话，给每个工具建一把单独的密钥：所有走同一把密钥的请求都记在那把密钥上，事后分不开。

三、添加 Amux 作为供应商#

打开 CC Switch，在顶部导航选中要配置的工具，点「添加供应商」。三个字段：

下面会按工具列出需要填写的值，以及 CC Switch 最终写入的配置示例。排查时可直接对照对应配置文件，确认是写入失败，还是工具尚未重新读取配置。

Claude Code、Claude Desktop（Anthropic 协议）#

地址不带 /v1：Anthropic 客户端会自己拼 /v1/messages，多一段会打到 /v1/v1/messages 上，返回 404。

模型映射填 Amux 的规范 ID：

三档不必都填 Claude。 协议和模型是两件事——把 Opus 那一档映射到 openai/gpt-5.6 或 deepseek/deepseek-v3.2 同样可以，Claude Code 照常工作。

写进 Claude Code 的配置大致是：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.amux.ai",
    "ANTHROPIC_AUTH_TOKEN": "<你的 Amux 密钥>",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Codex（OpenAI 协议）#

写进 ~/.codex/config.toml 的大致是：

model_provider = "amux"
model = "openai/gpt-5.6"

[model_providers.amux]
name = "Amux"
base_url = "https://gateway.amux.ai/v1"
wire_api = "responses"

wire_api 可选 responses 或 chat。两个端点都已原生实现；默认建议使用 responses，这也是 Codex 的默认路径。

Gemini CLI（Gemini 协议）#

写进 ~/.gemini/.env 的大致是：

GOOGLE_GEMINI_BASE_URL=https://gateway.amux.ai
GEMINI_API_KEY=<你的 Amux 密钥>
GEMINI_MODEL=google/gemini-3-pro

OpenCode、OpenClaw、Hermes Agent、Pi（OpenAI 协议）#

OpenCode 那份写出来是这样：

{
  "npm": "@ai-sdk/openai-compatible",
  "options": {
    "baseURL": "https://gateway.amux.ai/v1",
    "apiKey": "<你的 Amux 密钥>"
  },
  "models": {
    "anthropic/claude-opus-5": { "name": "Claude Opus 5 (via Amux)" }
  }
}

四、切过来#

在供应商列表里点 Amux 那一条旁边的切换按钮。

Claude Code 支持热切换——切完当前会话就生效。其余工具需要重开终端或重启应用，它们是在启动时读的配置。

通用供应商#

CC Switch 有个「通用供应商」开关：打开之后同一份 Amux 配置可以在 Claude Code、Codex、Gemini CLI、OpenCode 之间共享，每个工具仍然各自保留模型映射。同时用好几个工具时，省掉逐个添加。

注意 Base URL 在不同协议下形状不同（Anthropic 不带 /v1，OpenAI 带），共享时以工具自己那一档为准。

验证#

切换完成后，可发送一条测试消息进行验证。

Claude Code 里可以用 /status 看当前生效的地址与鉴权方式，确认是不是 Amux。

常见问题#

鉴权失败 / 密钥无效#

先确认 Base URL 那一栏选对了协议——填错协议报的也是鉴权类错误，而人会去查密钥。再看密钥是否复制完整（首尾空格和换行是最常见的原因），以及控制台里这把密钥是不是还启用着、工作区余额是否充足。

macOS 提示应用已损坏 / 无法打开#

只从官方 GitHub Releases 下载。系统设置 → 隐私与安全性，在被拦截的列表里找到 CC Switch，点「仍要打开」。

切换之后工具没反应#

建议按顺序检查三项：CC Switch 是否仍在运行；供应商列表中的 Amux 配置是否显示为当前生效；目标工具是否已经重启（除 Claude Code 外通常都需要）。如果都正常，再核对对应配置文件内容是否已写入。

模型不可用 / 协议不匹配#

模型 ID 要带厂商前缀（anthropic/claude-opus-5，不是 claude-opus-5）。另外不是每个模型都支持每种协议——模型详情页会列出它实际可用的协议，用 Anthropic 协议的工具就得挑支持 Anthropic 的那些。调一个不支持的组合会明确报错，不会静默降级。

订阅和 Amux 能同时留着吗#

能。两份配置都可以保存在 CC Switch 里随时切，但同一时刻只有一个生效。

它会代理或记录我的请求吗#

默认不会。CC Switch 仅负责写入配置，请求仍由工具直接发送。只有在启用其可选的本地代理与故障转移模式后，请求才会经过 CC Switch，并可能产生本地日志。

用量怎么看#

在 Amux 控制台的用量页。按密钥统计，分不出是哪个工具发的——要分开就给每个工具建一把单独的密钥。