CC Switch 如何安装并验证首条模型链路

CC Switch 的首次配置应先证明一条最小模型请求能成功，再扩展到多个应用。本文从安装渠道、供应商字段和最小验证请求开始，说明如何区分桌面配置问题、协议问题和模型本身不可用。文中只讨论可在本地复现的步骤，不把单次结果扩展成产品承诺；每个结论都标注前提、证据和无法覆盖的边界。读者可以先完成最小验证，再根据自己的版本、权限和数据补充实验，避免把配置示例误当成普遍结论。

很多人同时使用 Claude Code、Codex、Gemini CLI 或 OpenClaw，真正麻烦的并不是模型不够多，而是每个工具都有自己的配置入口：API Key 在一个文件里，Base URL 在另一个文件里，模型名又要写在第三处。

你只想换一个模型，最后却要反复修改配置、重启终端、确认工具到底有没有读到新设置。

CC Switch：管理应用和配置
上游 API：提供模型 API 入口
Claude Code / Codex：真正发起任务

一、先回答三个问题

1. CC Switch 是什么

CC Switch 是面向多种 AI 编程工具的桌面配置管理工具。官方仓库当前将它定位为 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw 和 Hermes 等应用的统一管理器。

它可以帮助你集中管理：

供应商名称和启用状态
API Key、Base URL 和模型配置
某些应用的角色模型映射
直连或本地代理路由
请求日志、用量统计和诊断信息
供应商切换、备份和恢复

完整能力会随版本变化，安装前建议从官方渠道查看当前说明：

官方网站：ccswitch.io
源码仓库：farion1231/cc-switch
官方下载：GitHub Releases

截至 2026-07-24，官方 Releases 页面显示最新版本为 v3.18.0，发布日期为 2026-07-21。这个版本号会继续变化，文章里的版本只用于说明写作时的核验结果，不建议把它当成永久安装要求。

常见的配置关系是：

供应商名称：上游 API
Base URL：以 上游 API 控制台显示为准
API Key：你的 上游 API Key
模型 ID：以当前模型列表显示为准
协议：以目标应用和 上游 API 文档匹配结果为准

3. 最后要得到什么

第一天不要把所有应用和所有模型全部配完。最小目标只有一个：

安装 CC Switch
添加一个 上游 API 供应商
绑定一个应用
启用一个模型
发出“只回复 OK”

看到 OK，才说明至少这一条链路是通的。后面再添加第二个模型，否则一旦报错，你不知道问题来自 Key、URL、协议、模型 ID 还是应用本身。

二、先看懂四层结构

层	负责什么	常见误区
AI 应用	Claude Code、Codex、Gemini CLI 等，发起请求	以为切了 CC Switch 就换了模型
CC Switch	保存配置、启用供应商、切换应用和可选路由	以为它本身提供模型
上游模型	真正生成回答、调用工具或执行推理	以为模型名可以随便写

直连时，调用链路大致是：

Claude Code / Codex
        -> 上游 API Base URL
        -> 上游 API
        -> 上游模型

启用本地路由后，链路会变成：

Claude Code / Codex
        -> CC Switch 本机地址
        -> 协议转换 / 模型映射 / 日志
        -> 上游 API
        -> 上游模型

本地路由能力更强，但变量更多。直连能跑通时，不要为了“看起来高级”强行打开代理。

三、安装前做三个决定

决定一：第一天先管哪个应用

建议只选一个：

目标	第一选择
想先完成复杂代码任务	Claude Code
已经使用 Codex，想接第三方模型	Codex
想统一管理多个工具但暂时不实操	先安装 CC Switch，再逐个绑定

不要第一天同时打开 Claude Code、Codex、Gemini CLI、OpenClaw、Hermes。应用越多，配置层越多，排错越慢。

决定二：先直连还是走本地路由

场景	建议
只想临时验证 Key 和模型	先直连
需要 Chat Completions 与 Responses 转换	使用本地路由
需要统一日志、用量或故障转移	使用本地路由
不知道本地代理在做什么	先直连，理解后再开

本地代理默认应只监听 127.0.0.1。不要把它改成公网地址，也不要把本机 API 入口当作公开服务。

决定三：模型是按任务选，还是按品牌选

不要只写“我要接入某某模型”。先把任务分成：

复杂代码理解和多文件修改
日常代码补全和小修复
长文档阅读和资料整理
结构化输出和批量处理
高并发、低成本的简单任务

四、从官方渠道安装 CC Switch

Windows

打开官方 Releases 页面，选择 Windows 安装包或便携版。不要从搜索结果里随便下载所谓“CC Switch 破解、增强、网页版客户端”。如果下载页面要求你先输入 API Key 或账号密码，直接停止。

安装完成后打开 CC Switch，确认应用能正常显示。Windows 选择便携版时，也要记住它的配置、备份和日志目录，后续迁移时不要只复制桌面快捷方式。

macOS

可以使用官方 Release 提供的安装包，也可以根据官方说明使用 Homebrew。不同版本的安装方式会变化，以当前仓库和 Releases 页面为准。

Linux

安装后先做一件事

第一次启动不要急着添加十个供应商。先在设置或关于页面确认版本，再打开应用列表，找到你准备先接入的工具。

五、第一次打开要看什么

不同版本界面可能不同，但你通常会看到四类入口：

应用入口：Claude Code、Codex、Gemini CLI 等。
供应商列表：添加、编辑、启用和删除配置。
路由/代理入口：启动本地路由、配置端口、查看接管状态。
用量/诊断入口：观察请求、Token、错误和模型映射。

先点进目标应用，再添加供应商。不要在 Claude Code 页面添加配置后，跑到 Codex 里期待它自动出现；很多应用的配置是分开管理的。

具体字段名称可能随 CC Switch 版本和应用变化，但通常需要确认下面这些内容：

字段	应该填什么	常见错误
模型 ID	控制台当前可用的模型名	凭记忆填写旧模型名
上游格式	OpenAI-compatible、Anthropic 或其他	和目标应用协议不匹配
角色映射	主模型、快速模型、子代理模型	所有角色填同一个不兼容模型

API Key 只填进 CC Switch 的密码字段。不要把真实 Key 粘贴到文章、截图、公开仓库、群聊或 AI 对话里。

七、保存后如何验证

按下面顺序验证，不要直接开始一个大项目：

确认供应商在目标应用页面显示为已启用。
完全退出并重新打开目标应用。
先发送：只回复 OK。
确认返回内容、模型名称和用量记录。
再发送一个不涉及敏感资料的小任务。

如果第一步就报错，先不要添加第二个供应商。用下面的检查 Prompt 可以让 AI 帮你整理排错范围，但不要把 Key、OAuth、完整日志或私密配置发给它：

请帮我检查 CC Switch 接入 上游 API 的排错思路。
我使用的应用是：[Claude Code / Codex / Gemini CLI / 其他]
当前目标是：验证一个最小模型请求。

不要让我提供或粘贴 API Key、OAuth、账户信息、完整私密日志或本地私密配置。
只根据以下非敏感信息告诉我应该依次检查什么：
1. 应用是否选择正确
2. Base URL 是否填写到文档要求的层级
3. API 格式是否匹配
4. 模型 ID 是否在当前供应商列表中
5. 供应商是否已启用
6. 是否需要重启应用
7. 是否需要本地路由
请按“现象 -> 可能层级 -> 安全检查动作”输出。

八、什么时候打开本地路由

Codex 需要 Responses 入口，而当前上游只提供 Chat Completions。
你需要看到完整调用日志和用量。
你需要按应用做模型映射或故障转移。
你需要在多个应用之间统一出口。

打开本地路由后要重新验证三件事：监听地址、端口、目标应用是否真的被接管。CC Switch 页面显示“已开启”不等于请求一定经过本地代理，最终还要看用量或诊断日志。

九、第一天不要做的事

不要同时接入所有应用。
不要一次加入十个模型。
不要把 Base URL 写成猜出来的路径。
不要把一个应用的配置原样复制到另一个应用。
不要为了看日志就把本地代理暴露到公网。
不要把 API Key 写进脚本、截图或公开 Markdown。
不要一遇到 401、404 就删除整个配置目录。

总结

一个应用
一个供应商
一个模型
一个最小请求

结论

本文给出了问题定位、配置或验证的可执行路径。实际结果仍取决于当前版本、权限和运行环境，提交前应按官方文档复核可变字段，并保留失败证据和回滚边界。