> ## Content Index
> Fetch the complete content index at: https://orbiorbi.com/news/llms.txt
> Use this file to discover other available public pages before exploring further.

# CC Switch 新手入门：安装、配置与第一次切换
- URL: https://orbiorbi.com/news/cc-switch-xinshou-rumen/
- Published: 2026-10-21T20:54:29.000Z
- Updated: 2026-10-21T20:54:29.000Z
- Description: CC Switch 把 AI 工具的供应商配置放进一个桌面界面。本文从下载安装到第一次请求验证，带你分清客户端、模型和供应商，再学会切换、查看用量与恢复配置。
- Author: Orbis News
- Tags: API 接入与排障, #model:claude-haiku-5-5, #model:gpt-6.1-sol

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

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

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

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

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

## 二、下载安装

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

打开[官方下载页](https://ccswitch.io/download?ref=orbiorbi.com)，按系统选择：

| 电脑          | 选什么                     | 怎么安装                                                                                                                                      |
| ----------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Windows 10+ | x64 或 ARM64 的 MSI       | 双击，按向导完成                                                                                                                                  |
| macOS 12+   | Universal DMG           | 打开后拖入“应用程序”                                                                                                                               |
| Linux       | 对应发行版的 deb/rpm/AppImage | 按[官方安装说明](https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/zh/1-getting-started/1.2-installation.md?ref=orbiorbi.com)操作 |

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

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

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

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

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

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

```bash
brew install --cask cc-switch

```

### 3\. 检查要管理的 AI 工具

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

![应用页显示工具版本和安装升级入口](https://orbiorbi.com/news/content/images/2026/10/apps-zh.png)

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

**成功标志：** 对应工具能单独启动；装好 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，顶部选“直连”。
- 点击右上角“添加供应商”。

![主界面显示左侧客户端入口、添加按钮及供应商状态](https://orbiorbi.com/news/content/images/2026/10/main-zh.png)

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

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

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

本次用 Orbis API 完成练习。先在 [Orbis](https://orbiorbi.com/?ref=orbiorbi.com) 注册或登录，再打开对应模型页，选线路、获取该线路的 API Key。**Key 绑定线路，改模型名称不会自动换线路。**

| 你使用的工具      | 本次模型与线路                                                                                                                    | 请求地址与协议                                      |
| ----------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| Claude Code | [Claude Haiku 5.5](https://orbiorbi.com/pricing/claude-haiku-5-5?catalogKey=model%2F112&ref=orbiorbi.com)，Claude Code · AH | https://api.orbiorbi.com；Anthropic Messages  |
| Codex       | [GPT 6.1 Sol](https://orbiorbi.com/pricing/gpt-6.1-sol?catalogKey=model%2F91&ref=orbiorbi.com)，GPT · HA                    | https://api.orbiorbi.com/v1；OpenAI Responses |

**推荐导入：** 在 Orbis 线路详情打开“快速接入”→选择 Key→“工具接入”→选择 Claude Code 或 Codex CLI→“填入 CC Switch”。在 CC Switch 核对后确认导入。导入链接含 Key，不要发给别人。步骤见 [Orbis 快速开始](https://orbiorbi.com/docs/quickstart/?ref=orbiorbi.com)。

模型

[Claude Haiku 5.5](https://orbiorbi.com/pricing/claude-haiku-5-5?catalogKey=model%2F112&ref=news-cc-switch-xinshou-rumen)`claude-haiku-5-5`

查看本教程使用的模型及对应线路接入信息。

体验

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

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

```json
{
  "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` 与供应商表名称要对应，例如：

```toml
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`。两种接法协议匹配，不必为转换开启路由。保存时只改连接相关字段，别覆盖原有全局设置。

模型

[GPT 6.1 Sol](https://orbiorbi.com/pricing/gpt-6.1-sol?catalogKey=model%2F91&ref=news-cc-switch-xinshou-rumen)`gpt-6.1-sol`

查看本教程使用的模型及对应线路接入信息。

体验

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

### 7\. 启用后发一次短请求

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

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

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

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

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

### 8\. 查看一次请求的用量

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

![用量页显示时间筛选、请求趋势和日志](https://orbiorbi.com/news/content/images/2026/10/usage-zh.png)

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

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

### 9\. 找回旧会话

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

![会话阅读页展示项目路径、对话与操作记录](https://orbiorbi.com/news/content/images/2026/10/session-zh.png)

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

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

## 五、进阶与故障恢复

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

| 需求            | 功能                             |
| ------------- | ------------------------------ |
| 接口转换、失败后自动换备用 | 路由与故障转移                        |
| 在客户端直接选多家模型   | 聚合，仅 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 是否运行、旧环境变量是否覆盖配置 |

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

## 参考与图片

步骤依据[官方手册](https://github.com/farion1231/cc-switch/tree/main/docs/user-manual/zh?ref=orbiorbi.com)，组织参考[Gunzo 分步教程](https://gunzo.cc/content/how-to-use-cc-switch?ref=orbiorbi.com)、[XieCoding 图文教程](https://xiecoding.cn/view/855.html?ref=orbiorbi.com)及[Q Docs](https://docs.qcode.cc/docs/ide/cc-switch?ref=orbiorbi.com)。

图片为 CC Switch 官方文档原图，MIT 许可，Copyright (c) 2025 Jason Young；品牌归各权利人。