CC Switch v3.16.1 多 CLI 切换器：Claude Code / Codex / Gemini CLI / OpenCode / OpenClaw / Hermes 一个面板管完（2026）

安装完能干嘛，30 秒看完

如果你已经在用 CC Switch、只想查特定问题——config 文件没生效、OAuth 反复登录、Codex wire_api 不对——直接跳到下面 常见报错与修法。否则下面四节按「装好 → 加 provider → 验证 → 多 CLI」顺序走完。

ZH 那边几篇 cc-switch 文章只专攻 Claude Code 单 CLI，这篇专走 7 个目标 CLI 的横切。Claude Code 深度向下挖，看 cc-switch 配置 Claude Code 完全指南 和 CC Switch 中转配置避坑指南。

系统要求

CC Switch 是 Tauri 2 桌面 app——本体小（~10 MB 安装包），但需要图形会话 + 对应 CLI 运行时。开始前对照下表，多数「CC Switch 不工作」的报告其实是底下 CLI 没装。

不需要每个 CLI 都装——CC Switch 只管理硬盘上实际存在的面板。先从你最常用的一两个开始。

第 1 步 —— 装 CC Switch

按平台选原生路径。macOS 不要 Homebrew 和手动下载混用，auto-update 只跟一条通道。

macOS（Homebrew）

brew install --cask cc-switch
# 后续升级：
brew upgrade --cask cc-switch

cask 已经过 Apple 签名 + 公证——首次打开不会弹 Gatekeeper 警告。

macOS（手动 .dmg）

# 从 Releases 页下最新 DMG，然后：
open CC-Switch-v3.16.1-macOS.dmg
# 把 CC Switch.app 拖到 /Applications

Windows

去 github.com/farion1231/cc-switch/releases 下 CC-Switch-v3.16.1-Windows.msi 双击装。机器禁止跑 MSI 就下 CC-Switch-v3.16.1-Windows-Portable.zip 免安装版。

Linux（Debian / Ubuntu）

# x86_64 示例
sudo dpkg -i CC-Switch-v3.16.1-Linux-x86_64.deb
# apt 抱怨依赖时：
sudo apt-get install -f

Linux（Arch）

paru -S cc-switch-bin   # 或：yay -S cc-switch-bin

Linux（通用 AppImage）

chmod +x CC-Switch-v3.16.1-Linux-x86_64.AppImage
./CC-Switch-v3.16.1-Linux-x86_64.AppImage

无头服务器 / CI

Tauri 2 桌面版必须有 Wayland 或 X11。无头机器——构建 runner、远程沙箱——用 Rust CLI fork SaladDay/cc-switch-cli 替代。它读跟桌面 app 同款 WebDAV 同步的 config bundle，所以可以笔记本上写 provider、agent 上拉下来。

装完验一下

首次启动后：

1. CC Switch 窗口默认打开到 Claude Code 面板。
2. CC Switch 图标出现在系统托盘里（macOS 菜单栏 / Windows 任务栏 / Linux 系统托盘）。
3. 左上角 app 切换器列出 7 个被管的目标——Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes Agent。灰掉的条目是硬盘上没检测到的 CLI，正常——还没装的话就是这样。

Linux 上托盘图标不见，多半是 DE 不支持 StatusNotifierItem；GNOME 装 gnome-shell-extension-appindicator（或 KDE 同类扩展），重启会话。

第 2 步 —— 把要管的 CLI 装上

CC Switch 不替你装 CLI——它管的是 config 文件。需要哪个就装哪个：

# 7 个都列上做参考。按需挑。
npm install -g @anthropic-ai/claude-code   # Claude Code（Node 18+）
npm install -g @openai/codex               # Codex（Node 16+）
npm install -g @google/gemini-cli          # Gemini CLI（Node 20+）
npm install -g opencode-ai                 # OpenCode（无 engine floor）
npm install -g openclaw                    # OpenClaw（Node 22.19+）
npm install -g hermes-agent                # Hermes Agent（Node 20+）

Claude Desktop 是 Anthropic 独立桌面 app，去 claude.ai/download 下，不走 npm。

npm install -g 报 EACCES 或者新 shim 不在 PATH 上时，看 Codex CLI 装完报 command not found 的 7 个修法——同一批修法适用于所有 CLI。

第 3 步 —— 加你的第一个 provider

打开 CC Switch，点右上角 +。Add Provider 面板有两个 tab：

• App-specific Provider —— 只给当前面板用
• Universal Provider —— Claude Code、Codex、Gemini CLI 共用

首次跑用 App-specific：

1. 从 Preset 下拉选发 key 给你的 provider。CC Switch 跨所有面板内置 ~50 个第三方 preset：DeepSeek、智谱 GLM、MiniMax、Kimi、百炼（阿里 Qwen）、AWS Bedrock、NVIDIA NIM、OpenRouter，加上一长串中转服务。多数只要填 API Key，endpoint URL 和协议字段会自动填好。
2. 粘 API Key。
3. （只针对 Codex）选的 preset 如果标了「Needs Local Routing」——所有 chat-completions 后端比如 DeepSeek、智谱 GLM 都是——CC Switch 自动开 Local Routing 开关，把 Codex 的 Responses API 协议代理转到 provider 的 /v1/chat/completions。别关——Codex 0.137.0 已经在 config 加载时砍掉了 wire_api = "chat"，只接 responses。
4. 点 Add。

每个 preset 实际写了什么

preset 是便利层。底下 CC Switch 写的是 CLI 原生 config 文件：

原则是「最小侵入」——明天卸掉 CC Switch，每个 CLI 照样工作，因为它们的原生 config 文件还在。CC Switch 自己在 ~/.cc-switch/cc-switch.db 里的状态是纯加法。

第 4 步 —— 切换 + 验证

每个 CLI 至少加完一个 provider 之后：

• app 里：点 provider 卡片 → Enable。
• 托盘里（更好用的部分）：右键 CC Switch 图标 → 选 CLI 面板 → 点 provider 名。菜单关掉之前新 config 已经写完。

然后在 CLI 那边激活：

进各自 CLI 会话里随手测一下：

> 你好——告诉我现在在跟哪个模型说话？

模型给出合理的自我介绍，就证明 key 有效 + routing 路径对。

常见报错与修法

如果是 CLI 自己的运行时错——model_not_found、EACCES、429、503——属于 CLI 的问题不是 CC Switch 的。Codex 那一类的认证 / 限流 / 沙箱报错看 Codex CLI 常见错误排查手册；装机时的 command not found 单独看 Codex 装完 command not found 7 个修法。

团队 / 多人配置

CC Switch 真正解决的痛是团队跨多个 agent 共用第三方 key——不是单人单 CLI。三种姿势能扩。

姿势 1 —— Universal Provider 共享中转 key

团队跨 Claude Code、Codex、Gemini CLI 用同一个 OpenAI 兼容中转（一个 base URL、一把共享 key），Universal Provider tab 就是干这个的。加一次填中转的 endpoint + key，勾选要同步到的三个 app，CC Switch 把同一把 key 写到每个 CLI 的原生 config 文件里。中转旋转 key 时改一行点 Save and Sync——每个 CLI 在每台笔记本上下一次切换都拿到新值。

姿势 2 —— WebDAV 同步 config bundle 给笔记本 + CI

搭一个 WebDAV server（Nextcloud、自托管、或者团队已经有的），Settings → Storage → 自定义 config 目录指过去。作者们在笔记本上加 provider；CI runner 跑 SaladDay/cc-switch-cli 拉同一份 SQLite 快照。不要用普通 Dropbox / iCloud 文件夹同步 ~/.cc-switch/cc-switch.db——两台设备同时 push 会高高兴兴互相覆盖。带正经 locking 的 WebDAV 才是这个数据库文件的安全传输方式。

姿势 3 —— 给值班工程师做单机覆盖

某个工程师要测不影响其他人的 provider 时，设备级 ~/.cc-switch/settings.json 里的 claudeConfigDir、codexConfigDir 等覆盖把那台机器的 CC Switch 指到一个非共享 config 目录。团队的 WebDAV bundle 不受影响；改回设置覆盖就消失。

三种姿势都一样，把 ~/.cc-switch/cc-switch.db 当 ~/.ssh/ 看——它没加密，文件保护靠文件系统权限加你选的传输通道。

进阶 —— MCP、Skills、Prompts 和 OAuth 复用

切换 provider 这件事解决之后，统一面板才是 CC Switch 真正出力的地方。

5 个 CLI 的统一 MCP

任何面板上点 MCP 按钮。CC Switch 从每个 CLI 的原生位置读 MCP server 列表——Claude Code 的 ~/.claude.json、Codex 的 ~/.codex/config.toml 里 [mcp_servers.*] 块、Gemini CLI 的 ~/.gemini/settings.json 里 mcpServers，OpenCode 和 Hermes 同款逻辑——然后让你按 CLI 切每个 server 的开关。mcp-fetch 加一次，同步到 Claude Code + Codex + Gemini，每个 agent 拿到同一份工具集。

Prompts（CLAUDE.md / AGENTS.md / GEMINI.md）

Prompts 面板是带跨 app 同步的 Markdown 编辑器。CC Switch 里改一份 prompt，一键同步到 ~/.claude/CLAUDE.md、~/.codex/AGENTS.md、~/.gemini/GEMINI.md。backfill 保护意思是：在 live 文件里直接改的内容，下次同步覆盖前会被拉回 CC Switch——比如同事直接改了 CLAUDE.md。

Skills

Skills 面板从 GitHub 仓库或 ZIP 装 skill 到每个 CLI 的 skills 目录（~/.claude/skills/、~/.config/opencode/skills/ 等）。symlink 模式是默认——canonical 一份在 ~/.cc-switch/skills/，CLI 通过 symlink 看；CLI 是沙箱不跟 symlink 的话切到文件拷贝模式。

Codex OAuth 反向代理（v3.13 起）

CC Switch 加了一条路径，把已登录 ChatGPT 账号的 Codex 额度复用到 Claude Code 里。它出现在 Claude provider 列表里作为一种新卡片类型——不是 Codex 那边的 preset——通过本地代理把 Claude Code 请求转到 chatgpt.com 和 auth.openai.com。适合你已经付 ChatGPT Plus 或 Pro 的场景。生产用之前先看 app 里的风险提示；这是非官方复用路径，OpenAI 一收紧鉴权就可能断。

替代方案 —— 不想要桌面 app 的时候

桌面 Tauri app 不适合的场景，下面两条路覆盖。

• 单一 OpenAI 兼容网关 —— 如果只想要一个 base URL，让 Claude Code、Codex、Cursor、Cline、OpenClaw 都指过去，OfoxAI 暴露 https://api.ofox.ai/v1 作为统一 OpenAI 兼容端点。多数团队完全不想改每个 CLI 的 config 时就选这个；看 Claude Code 集成指南 的一行设置。可以保留 CC Switch 做托盘级切换、底下用 ofox 做 provider；也可以一个端点够用就完全跳过 CC Switch。
• 无头 / 脚本化场景 —— SaladDay/cc-switch-cli 是 Rust CLI fork，在终端里做 provider 切换、MCP 管理、skills 安装、本地代理。跟桌面 app 同款 WebDAV 兼容存储格式。最适合构建 agent、远程 dev 容器、纯 tmux 的服务器。
• 浏览器 UI —— Laliet/cc-switch-web 是社区基于 web 的替代品，覆盖 Claude Code、Codex、Gemini CLI。今天功能没桌面 app 全，但适合团队共用一个 URL 打开看的场景。

怎么持续跟上版本

• Auto-updater —— Settings → About → Check for updates。桌面 app 启动时也会自动查。
• Release feed —— 订阅 github.com/farion1231/cc-switch/releases。近期值得跟的：Claude Desktop 升一等公民、Codex OAuth 反向代理（v3.13）、统一 Skills 从 GitHub 装（v3.16 前加的）、按 app 的用量 dashboard。
• 备份卫生 —— ~/.cc-switch/backups/ 自动留最近 10 个 SQLite 快照。大版本升级前手动 cp ~/.cc-switch/cc-switch.db ~/.cc-switch/cc-switch.db.bak.$(date +%F)——手动快照能抗住滚动窗口。

FAQ

frontmatter 上面的 faq 块是规范答案；问题对齐了「cc switch 安装」「ccswitch claude code」相关 query 的 PAA。扫一眼即可——覆盖支持的 CLI 范围、终端重启行为、fork 选型、官方账号共存、Codex OAuth 反向代理、key 存储、无头支持、跟手动改对比这几个点。

本次刷新核对的来源

• farion1231/cc-switch README —— 核实 7 CLI 范围 + v3.16.1 发布日期（2026-06-05 核对）
• cc-switch 用户手册 —— 安装指南 和 provider config 格式 —— 核实每个 CLI 的 config 文件路径 + Codex「Needs Local Routing」行为
• cc-switch FAQ —— 5.1 Configuration Files —— 核实 SQLite 路径 + 每个 CLI 的原生 config 位置
• npm registry —— npm view <pkg> version engines 跑过 @anthropic-ai/[email protected]、@openai/[email protected]、@google/[email protected]、[email protected]、[email protected]、[email protected] —— 确认发布版本和 Node engine floor（2026-06-05 核对）
• SaladDay/cc-switch-cli 和 Laliet/cc-switch-web —— 确认 WebDAV 兼容存储和两个 fork 的支持 CLI 范围
• openai/codex model-provider-info 源码 —— 确认 wire_api = "responses" 是 0.137.0 唯一接受的变体；"chat" 反序列化到 CHAT_WIRE_API_REMOVED_ERROR