1. 免踩配置文件的坑
Claude Code 读 JSON、Codex 读 TOML，字段名与鉴权方式都不一样。 Codex 甚至存在「配置里残留一个旧字段就导致所有命令启动失败」的情况 （见 Codex 篇）。CC-Switch 用图形界面生成这些文件，绕开全部手写错误。
CC-Switch 简介
CC-Switch 是一个免费开源的跨平台桌面应用（Tauri 2 + React，MIT 许可）， 用来统一管理各类 AI 编程工具的供应商配置。
一句话：它替你手改 settings.json、config.toml 这些格式各异、写错就静默失效的配置文件，
并提供「一键切换供应商」的能力。
图片来源：CC-Switch 官方仓库（MIT 许可）
为什么接入 ZiAI 时推荐用它
Section titled “为什么接入 ZiAI 时推荐用它”2. 多站一键切换
ZiAI、官方账号、其他中转站可以同时保存为多张供应商卡片， 在托盘菜单点一下就切换 —— 不用记环境变量、不用反复改文件。
3. 协议不匹配时本地转换
Codex 只认 OpenAI Responses 协议。若某个模型在 ZiAI 上只有 Chat Completions 通道， CC-Switch 的本地代理能把 Responses 请求转换成 Chat 再把流式响应转换回来， 并附带自动故障转移与熔断。这是它相对手改配置文件最大的优势。
4. 配置安全可回滚
数据存在本地 SQLite，写入采用原子操作（临时文件 + 重命名），并自动备份最近 10 份。 设计原则是「最小侵入」：卸载 CC-Switch 不会影响你的 CLI 继续使用。
覆盖范围：能管什么、不能管什么
Section titled “覆盖范围：能管什么、不能管什么”什么时候不需要它
Section titled “什么时候不需要它”- 你只用 ChatBox / CherryStudio / ZCode / WorkBuddy 这类图形客户端 —— 它们自带供应商管理界面，填一次即可；
- 你只用 Claude Code，且长期固定用 ZiAI 一个站 —— 直接按 Claude Code 篇 改一次
settings.json更轻； - 你的环境不允许安装第三方桌面应用 —— 用手动配置路径即可，两篇 CLI 教程都给了完整的手写方案。
反之，同时使用 Claude Code 和 Codex、或需要在多个供应商之间来回切换，CC-Switch 能省下大量时间。
唯一官方渠道（务必阅读）
Section titled “唯一官方渠道（务必阅读）”实测 v3.20.3 建议安装 v3.20.1 及以上，理由：
| 版本 | 与本站相关的关键变更 |
|---|---|
| v3.20.1 | 修复 Codex CLI ≥ 0.149 切换第三方供应商后 401「Missing API key」：切换改为 config-only，密钥随供应商表走，不再写入 auth.json |
| v3.20.3 | 修复上游回传空 reasoning_content 时 Claude Code 被空思考块刷屏；Codex 长任务不再在一句进度汇报后中断；Claude 供应商编辑器新增「禁用 Artifact 工具」开关 |
版本更新较快，以 Releases 页面 的最新版为准。 安装步骤见下一页。
- 安装 CC-Switch —— Windows / macOS / Linux 三平台
- 添加 ZiAI 并切换 —— 核心操作页
- 进阶：本地代理、统一供应商与用量统计