cc-switch 完全使用指南

一键切换 Claude Code / Codex 的多套配置 —— 供应商、模型、API Key 点一下就换，不用手改配置文件

这个工具解决什么问题

如果你同时用 Claude Code 和 Codex CLI，又同时有官方账号和几个第三方网关，你大概率经历过这些：

# 想换个供应商试试
vim ~/.zshrc                    # 改 ANTHROPIC_BASE_URL
source ~/.zshrc                 # 重载
vim ~/.codex/config.toml        # 再改 Codex 的
# 结果忘了改回来，第二天发现在烧错账号的额度

cc-switch 把这套手工活变成点一下。 它是一个跨平台桌面应用，帮你管理 Claude Code、Codex 等 AI 编程工具的多套配置，切换供应商就像切 Wi-Fi。

📦 项目地址：https://github.com/farion1231/cc-switch 💻 CLI 版本：https://github.com/SaladDay/cc-switch-cli

安装

桌面版

从 Releases 下载对应平台的安装包：

平台	文件
Windows	`.exe` 安装包
macOS (Apple Silicon)	`.dmg` (aarch64)
macOS (Intel)	`.dmg` (x64)
Linux	`.AppImage` / `.deb`

macOS 首次打开被拦：

xattr -cr /Applications/cc-switch.app

CLI 版

npm install -g cc-switch-cli

核心概念

cc-switch 管理的是配置片段，不是应用本身。

┌─────────────────────────────────────────┐
│  cc-switch                              │
│                                         │
│  Claude Code                            │
│   ├── ○ 官方订阅                        │
│   ├── ● Leonis AI          ← 当前生效   │
│   └── ○ 自建 new-api                    │
│                                         │
│  Codex                                  │
│   ├── ○ 官方 API                        │
│   └── ● Leonis AI          ← 当前生效   │
└─────────────────────────────────────────┘
              │
              ▼  切换时自动改写
   ~/.claude/settings.json
   ~/.codex/config.toml + auth.json

切换动作做了什么：

把选中的配置写入对应工具的真实配置文件
备份被覆盖的原配置
你重开终端（或重启客户端）就生效了

配置 Claude Code

添加一个第三方网关

打开 cc-switch → Claude Code 标签 → 添加供应商

字段	填什么	示例
名称	自己认得出就行	`Leonis AI`
Base URL	网关地址	`https://ai.svtun.cn`
API Key	网关签发的 Key	`sk-xxxxxxxx`
模型（可选）	默认模型	`claude-sonnet-5`

保存后点一下即可切换。

它实际写了什么

cc-switch 会写入 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.svtun.cn",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxx"
  }
}

等价于你手动执行：

export ANTHROPIC_BASE_URL="https://ai.svtun.cn"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxx"

⚠️ 关键坑：如果你的 ~/.zshrc 里还留着旧的 ANTHROPIC_API_KEY，它的优先级更高，会覆盖 cc-switch 的设置。用 cc-switch 之前先清干净：
# 检查
env | grep -i anthropic
# 清掉冲突的
unset ANTHROPIC_API_KEY
# 并从 ~/.zshrc 里删掉相关行

切换后怎么生效

场景	操作
终端里跑 `claude`	重开终端窗口
VS Code 集成终端	重启 VS Code
已经在跑的会话	退出重进

配置 Codex

Codex 标签 → 添加供应商

字段	填什么	示例
名称	随意	`Leonis AI`
Base URL	注意结尾的 `/v1`	`https://ai.svtun.cn/v1`
API Key	网关 Key	`sk-xxxxxxxx`
wire_api	协议类型	`responses`

它实际写了什么

写入 ~/.codex/config.toml：

model_provider = "leonis"

[model_providers.leonis]
name = "Leonis AI"
base_url = "https://ai.svtun.cn/v1"
wire_api = "responses"
env_key = "LEONIS_API_KEY"

以及 ~/.codex/auth.json 存放 Key。

`wire_api` 填错的表现

现象	解决
`404 Not Found`	从 `responses` 改成 `chat`，或反之
`Unsupported endpoint`	同上

不确定就先试 responses（功能最全），报 404 再改 chat。

📖 Codex 配置的完整字段说明见 codex-cli-guide。

多供应商实战

真实场景下值得配这么几组：

1. 官方订阅（有 Max 就配）

名称：      Claude 官方
Base URL：  （留空，走官方）
说明：      订阅额度，不额外花钱，但有 5h 窗口限制

2. 第三方网关 · 主力

名称：      Leonis AI
Base URL：  https://ai.svtun.cn
API Key：   sk-xxxxxxxx
说明：      按量付费，无窗口限制，同一个 Key 还能用 GPT / Gemini / Grok

3. 第三方网关 · 备用

名称：      备用网关
Base URL：  https://backup-gateway.com/api
说明：      主力挂了顶上，别把鸡蛋放一个篮子

4. 自建 new-api / one-api

名称：      自建
Base URL：  http://192.168.1.100:3000/api
说明：      内网自建，走自己的上游

🎯 强烈建议至少配两个能用的通道。 第三方网关的上游随时可能挂或限流，有备用配置的话切一下就能继续干活，不用中断。

按任务切换的实用策略

配置多了之后，真正的价值在于按任务选通道。

策略一：按成本分层

任务	切到	理由
日常写代码	便宜的 Sonnet 通道	90% 任务够用
卡住的疑难问题	Opus 通道	值得为质量付费
批量改格式 / 重命名	Haiku 或 flash-lite 通道	最省

策略二：按能力分层

任务	切到
跨文件重构	Claude Code + Opus
精确单点修改	Codex + 沙箱模式
读超长文档 / 大代码库	Gemini（上下文窗口最大）
需要实时信息	Gemini `-search` 变体
出图	Nano Banana / Imagen 通道

策略三：按稳定性分层

主力通道挂了 → 切备用通道 → 还挂 → 切官方订阅

把这三档都配好，实际停工时间接近零。

CLI 版本

不想装桌面应用的话，用 cc-switch-cli：

npm install -g cc-switch-cli

常用命令

cs list                    # 列出所有配置
cs use leonis              # 切换到名为 leonis 的配置
cs current                 # 查看当前生效的配置
cs add                     # 交互式添加新配置
cs remove leonis           # 删除配置

配合 shell 别名

# ~/.zshrc
alias cs-work='cs use leonis && echo "→ Leonis AI"'
alias cs-official='cs use official && echo "→ 官方订阅"'
alias cs-backup='cs use backup && echo "→ 备用通道"'

手动方案对照

不想装任何工具，纯 shell 也能做到类似效果。

方案一：函数切换

# ~/.zshrc

use-leonis() {
  export ANTHROPIC_BASE_URL="https://ai.svtun.cn"
  export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxx"
  unset ANTHROPIC_API_KEY
  echo "→ Leonis AI"
}

use-official() {
  unset ANTHROPIC_BASE_URL
  unset ANTHROPIC_AUTH_TOKEN
  echo "→ 官方订阅"
}

use-backup() {
  export ANTHROPIC_BASE_URL="https://backup.com/api"
  export ANTHROPIC_AUTH_TOKEN="sk-yyyyyyyy"
  unset ANTHROPIC_API_KEY
  echo "→ 备用通道"
}

use-leonis && claude

方案二：多份 env 文件

# ~/.ai/leonis.env
export ANTHROPIC_BASE_URL="https://ai.svtun.cn"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxx"

# ~/.ai/backup.env
export ANTHROPIC_BASE_URL="https://backup.com/api"
export ANTHROPIC_AUTH_TOKEN="sk-yyyyyyyy"

source ~/.ai/leonis.env && claude

方案三：Codex 用 Profile

Codex 原生支持 profile，不需要外部工具：

# ~/.codex/config.toml
[profiles.leonis]
model = "gpt-5.6-sol"
model_provider = "leonis"

[profiles.official]
model = "gpt-5.6"
model_provider = "openai"

codex --profile leonis
codex --profile official

三种方案怎么选

	cc-switch	shell 函数	Codex profile
上手成本	低（图形界面）	中	低
跨工具	✅ Claude + Codex	✅	❌ 仅 Codex
需要重开终端	✅ 需要	❌ 当前会话即时生效	❌
Key 管理	集中管理	明文在 rc 文件里	环境变量
适合	配置多、经常切	熟悉 shell、配置少	只用 Codex

报错排查

切换后没生效

排查顺序：

# 1. 看当前环境变量
env | grep -iE 'anthropic|openai|leonis'

# 2. 有没有优先级更高的变量在捣乱
unset ANTHROPIC_API_KEY

# 3. 有没有本地登录凭据覆盖
claude logout

# 4. 重开终端

最常见的原因：~/.zshrc 或 ~/.bashrc 里残留了旧的 export ANTHROPIC_*，每次开终端都会覆盖掉 cc-switch 写的配置。去 rc 文件里删干净。

Claude Code 里 `/status` 显示的还是旧地址

配置文件写了但进程没重启。退出 claude 重进；VS Code 集成终端要重启 VS Code。

Codex 报 404

wire_api 或 base_url 的 /v1 有问题：

base_url = "https://ai.svtun.cn/v1"   # ✅ Codex 要带 /v1
wire_api = "responses"                     # 404 就换成 "chat"

对照验证：

curl -s https://ai.svtun.cn/v1/chat/completions \
  -H "Authorization: Bearer $YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"hi"}],"max_tokens":16}'

能返回 JSON 说明网关没问题，是本地配置的事。

macOS 打不开应用

xattr -cr /Applications/cc-switch.app

配置丢失

cc-switch 切换时会备份原配置。检查：

~/.claude/settings.json.bak
~/.codex/config.toml.bak

养成习惯：重要配置自己也留一份。

mkdir -p ~/.ai-backup
cp ~/.claude/settings.json ~/.ai-backup/
cp ~/.codex/config.toml ~/.ai-backup/

Windows 上环境变量不生效

setx 设置后必须重开终端（甚至重新登录）：

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://ai.svtun.cn", "User")
# 重开 PowerShell

贡献

工具更新较快，发现文档过时欢迎提 Issue 和 PR。

License

MIT

本文档是第三方使用指南，与 cc-switch 上游项目无隶属关系。

_{关键词 · cc-switch · Claude Code 切换 · Codex 切换 · 供应商切换 · AI 配置管理 ·
claude code 多账号 · codex 多配置 · ANTHROPIC_BASE_URL · config.toml · AI 中转 · API 中转 · 一键切换}

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
LICENSE		LICENSE
README.md		README.md

仓库	说明
claude-code-guide	Claude Code 中文完全指南
codex-cli-guide	Codex CLI 完全配置手册
gemini-api-guide	Gemini API 配置手册
ai-client-configs	20+ 客户端配置模板
awesome-ai-api-gateway	AI 网关生态精选

Folders and files

Latest commit

History

Repository files navigation

cc-switch 完全使用指南

这个工具解决什么问题

目录

安装

桌面版

CLI 版

核心概念

配置 Claude Code

添加一个第三方网关

它实际写了什么

切换后怎么生效

配置 Codex

它实际写了什么

wire_api 填错的表现

多供应商实战

1. 官方订阅（有 Max 就配）

2. 第三方网关 · 主力

3. 第三方网关 · 备用

4. 自建 new-api / one-api

按任务切换的实用策略

策略一：按成本分层

策略二：按能力分层

策略三：按稳定性分层

CLI 版本

常用命令

配合 shell 别名

手动方案对照

方案一：函数切换

方案二：多份 env 文件

方案三：Codex 用 Profile

三种方案怎么选

报错排查

切换后没生效

Claude Code 里 /status 显示的还是旧地址

Codex 报 404

macOS 打不开应用

配置丢失

Windows 上环境变量不生效

相关项目

上游项目

贡献

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

`wire_api` 填错的表现

Claude Code 里 `/status` 显示的还是旧地址