CC Switch 新手入门指南

一、先认识工具：这篇学会什么？

目标：装好 CC Switch，添加一家供应商，成功收到回答，再切回原配置。

CC Switch 是管理 AI 工具配置的桌面软件。你在 Claude Code 或 Codex 里提任务，在 CC Switch 里管理“连接哪家服务”。它不提供模型额度。

表单里的词	意思
供应商	提供模型调用服务的一方
API Key	使用该服务的密钥，不是登录密码
API 地址	软件请求的入口，不一定是官网首页
模型 ID	供应商接口认识的模型名称

本文核查于 2026 年 10 月 22 日，正式版为 v4.0.18。

二、下载安装

1. 下载对应电脑的安装包

打开官方下载页，按系统选择：

电脑	选什么	怎么安装
Windows 10+	x64 或 ARM64 的 MSI	双击，按向导完成
macOS 12+	Universal DMG	打开后拖入“应用程序”
Linux	对应发行版的 deb/rpm/AppImage	按官方安装说明操作

Windows 在“设置→系统→系统信息”查看架构。Linux 要求 glibc 2.35+和 WebKitGTK 4.1。不要下载名为 Source code 的源码包。

成功标志： 从开始菜单或“应用程序”打开后，能看到 CC Switch 窗口。

2. 可选：让 agent 一句话代装

已有能操作电脑的 agent 时，复制：

请识别我的系统和架构，按 https://github.com/farion1231/cc-switch 官方说明安装最新稳定版桌面应用，保留已有配置，不安装社区 CLI；管理员授权交给我，完成后报告版本和打开方式。

普通网页聊天不一定有本地安装能力。Mac 已装 Homebrew 时，也可在“终端”运行：

brew install --cask cc-switch

3. 检查要管理的 AI 工具

点左下角“应用”。
找到 Claude Code 或 Codex：未安装就点安装，已安装则确认版本。
本次只选一个工具练习。

看每行右侧的版本与按钮。

成功标志： 对应工具能单独启动；装好 CC Switch 不等于客户端也已装好。

本教程使用电脑本机的工具。如果你在 Windows 里的 Linux 环境（WSL）运行客户端，两边的配置目录和网络不同，需要另按官方 WSL 说明设置。

三、第一次使用：添加、启用、验证

4. 先确认客户端的官方使用方式

CC Switch 管理连接配置，模型账号的登录在对应客户端完成：

Claude Code：在终端运行 claude，按提示完成官方账号登录，用 /status 核对状态。
Codex：运行 codex，选择 Sign in with ChatGPT，完成浏览器授权后返回终端。
已有可用配置时，先发一条短消息确认正常，再进行下面的备份。官方账号的使用权限以账号显示为准。

成功标志： 客户端本身能正常使用。接下来以 Orbis 为例，学习怎样添加 API 服务并切换回来。

5. 先备份，再打开添加入口

已有配置：进入“设置→数据”，导出 SQL 备份，并保存客户端原配置。
左侧选 Claude Code，顶部选“直连”。
点击右上角“添加供应商”。

先看左侧选中了谁，再找右上角添加按钮。图中“使用中”才是当前供应商。

成功标志： 添加页标题与要配置的客户端一致。Codex 用户应从 Codex 入口添加。

6. 从 Orbis 导入，也可以手动填写

本次用 Orbis API 完成练习。先在 Orbis 注册或登录，再打开对应模型页，选线路、获取该线路的 API Key。Key 绑定线路，改模型名称不会自动换线路。

你使用的工具	本次模型与线路	请求地址与协议
Claude Code	Claude Haiku 5.5，Claude Code · AH	`https://api.orbiorbi.com`；Anthropic Messages
Codex	GPT 6.1 Sol，GPT · HA	`https://api.orbiorbi.com/v1`；OpenAI Responses

推荐导入： 在 Orbis 线路详情打开“快速接入”→选择 Key→“工具接入”→选择 Claude Code 或 Codex CLI→“填入 CC Switch”。在 CC Switch 核对后确认导入。导入链接含 Key，不要发给别人。步骤见 Orbis 快速开始。

导入没有唤起桌面软件时，回到“添加供应商→自定义配置”，命名为 Orbis-Claude 或 Orbis-Codex。这是自定义名称，不是内置预设。

Claude Code 手填： 上游格式选 Anthropic Messages，地址填上表根地址。若显示 JSON 编辑框，在已有 env 中设置以下字段，Key 只在本机填写：

{
  "ANTHROPIC_BASE_URL": "https://api.orbiorbi.com",
  "ANTHROPIC_AUTH_TOKEN": "你的 Orbis 线路 Key",
  "ANTHROPIC_MODEL": "claude-haiku-5-5",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5"
}

Codex 手填： 上游格式选 OpenAI Responses，Key 填供应商编辑器的 OPENAI_API_KEY 字段，模型填 gpt-6.1-sol，地址填上表 /v1。若显示 TOML，model_provider 与供应商表名称要对应，例如：

model_provider = "orbis"
model = "gpt-6.1-sol"
[model_providers.orbis]
name = "Orbis"
base_url = "https://api.orbiorbi.com/v1"
wire_api = "responses"

保留“完整 URL”关闭；这些地址是前缀，不要再拼 /messages 或 /responses。两种接法协议匹配，不必为转换开启路由。保存时只改连接相关字段，别覆盖原有全局设置。

成功标志： 出现对应 Orbis 卡片，模型 ID 与线路一致。此时只是保存，还没切过去。

7. 启用后发一次短请求

点目标卡片的切换按钮，确认显示“使用中”。
Claude Code 通常即时生效；Codex 按提示重启，桌面版要彻底退出再开。
在客户端新建对话，发送：

请用三句话解释什么是文件夹。只回答，不读取或修改文件。

成功标志： 收到完整回答；结合供应商调用记录核对线路。不要靠“你是什么模型”的回答判断。

卡片“检测连通”只检查地址可达，不等于模型生成成功。

四、基本使用：看记录，找回任务

8. 查看一次请求的用量

点“用量统计”，选择刚才的时间范围。
查看请求、模型和费用信息。
最终费用以供应商账单为准；客户端日志导入的记录未必能分清供应商。

先选时间，再看请求日志。

成功标志： 知道记录来自哪里，不把估算费用当成结算账单。

9. 找回旧会话

点“会话”，选择应用和项目。
搜索任务，打开阅读页。
需要继续时，使用该工具支持的恢复入口。

先核对顶部项目路径，再继续任务。

成功标志： 找到的是目标项目的对话，实际文件也能对应上。

五、进阶与故障恢复

先跑通上面的练习，再按需要增加功能：

需求	功能
接口转换、失败后自动换备用	路由与故障转移
在客户端直接选多家模型	聚合，仅 Claude Code/Codex，不自动故障转移
连接外部工具	MCP
复用一套办事步骤	Skills，安装前先读内容

10. 增加第二个模型，不重建供应商

编辑现有供应商，先核对地址与 Key，再点“获取模型列表”。
搜索需要的模型，只勾选要用的条目，点“添加所选模型”。
列表接口返回 404/405 时，按服务文档手动添加模型 ID；不要把显示名当 ID。

Codex 的“模型映射”里，菜单显示名是给人看的，实际请求模型才是发给接口的名称。上下文窗口、思考等级没把握就留空；填大数字不会扩展模型能力。修改后彻底重启 Codex。

成功标志： 客户端列表出现新模型，选中后能完成一次短请求。若要跨供应商选择，继续阅读聚合教程。

11. 用日志定位一次失败

记下失败时间、所选模型和错误码。
打开“设置→数据→应用诊断日志→打开日志”。
找该时段的错误，核对请求是否发向预期地址，再检查 Key 和模型 ID。

若顶部提示“检测到系统环境变量冲突”，点“查看详情”，核对变量的来源。只删除确认不用的旧配置；清理前软件会备份到 .cc-switch/backups/env-backup-<timestamp>.json。然后重启终端和客户端。

成功标志： 能区分“地址连不上”“认证失败”“模型不存在”，而不是反复重装。向别人求助前，遮住密钥、请求内容和个人路径。

12. 配错时恢复原供应商

回到“直连”，选择原供应商。
按要求重启客户端，再发一次短请求。
必须恢复备份时，先在“设置→数据”导出当前 SQL，再导入需要的旧备份。导入会覆盖供应商、MCP、提示词、用量等数据库内容，不是只撤销一张卡片。

错误	优先检查
401/403	Key、权限、是否选错供应商
模型不存在	模型 ID 是否属于当前接口
切换没生效	“使用中”状态、客户端入口、重启
路由连接失败	CC Switch 是否运行、旧环境变量是否覆盖配置

最终验收： 新供应商能回答，原供应商能恢复。两项都做到，再增加第二家。

参考与图片

步骤依据官方手册，组织参考Gunzo 分步教程、XieCoding 图文教程及Q Docs。