# CC Switch 配置

> **最后核实**：2026-09-18 · 📄 依据官方文档（CC Switch v3.20.3，2026-09-11 发布）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | 取决于它代管的 CLI 本身：Claude Code（Claude ✅）、Codex（GPT ✅）、OpenCode / [OpenClaw](/docs/ide/openclaw) / [Hermes Agent](/docs/ide/hermes-agent) 等——CC Switch 自己不是推理端点，只写各 CLI 的配置文件 |
| 协议与 Base URL | 写入目标各按自身协议：Claude 腿 `https://api.qcode.cc/api` · Codex 腿 `https://api.qcode.cc/openai` |
| 配置位置 | 应用内管理，落盘到 `~/.claude/settings.json`、`~/.codex/config.toml` 等 |
| 官方文档 | [GitHub 仓库](https://github.com/farion1231/cc-switch) · [用户手册](https://github.com/farion1231/cc-switch/tree/main/docs/user-manual) |

[CC Switch](https://github.com/farion1231/cc-switch) 是一款跨平台桌面应用（Windows / macOS / Linux），统一管理 **9 个工具**的 API 服务商配置：Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、MiniMax Code（清单出自官方 README；手册界面图更新略滞后）。本文介绍如何在 CC Switch 中新增 QCode.cc 作为自定义供应商，如何在多个供应商/账号之间一键切换，以及常见使用场景与排错。

## 为什么用 CC Switch

- **零配置文件手写**：可视化表单替代 `settings.json` / `config.toml`
- **一键切换供应商**：在 qcode.cc、官方 Anthropic、本地反代之间秒切
- **Claude + Codex 双生态**：同一个应用管理 Claude Code 和 Codex CLI 配置
- **多账号/多套餐管理**：为同一供应商保存多份配置（如工作 Key 与个人 Key），随时切换
- **系统托盘快捷切换**：托盘菜单无需打开主界面

> CC Switch 的本质是一个"配置档案（profile）切换器"——它把每份供应商配置写入对应 CLI 的标准配置文件，激活时覆盖、切换时换回。理解这一点能帮你避免误以为多个供应商会同时生效。

## 前置条件

- 已安装 [Claude Code CLI](/docs/getting-started/installation) 或 Codex CLI
- 拥有 QCode.cc API Key（`cr_` 开头），在 [控制台](https://qcode.cc/dashboard) 获取
- 同一把 Key 同时适用于 Anthropic、OpenAI、Gemini 等多种协议端点，详见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)

## 安装 CC Switch

从 [GitHub Releases](https://github.com/farion1231/cc-switch/releases) 下载对应平台安装包：

| 平台 | 下载包 |
|------|--------|
| Windows 10+ | `CC-Switch-v{ver}-Windows.msi` 或便携版 `.zip` |
| macOS 12+ | `.dmg` 包；或 `brew install --cask cc-switch`（官方 README 的写法） |
| Linux | `.deb` / `.rpm` / `.AppImage`；Arch 用 `paru -S cc-switch-bin` |

各版本的具体安装步骤与签名提示以 [项目 README](https://github.com/farion1231/cc-switch) 为准。

## 配置 Claude 供应商（用于 Claude Code）

启动 CC Switch → 用**顶部应用切换器**选到 **Claude** → 点右上角 **「+」（添加供应商）** → 在「应用专属供应商」Tab 的预设下拉里选 **自定义（Custom）** → 直接编辑面板里的配置 JSON（界面文案随版本变化，以应用内实际显示为准）：

| 字段 | 值 |
|------|-----|
| 供应商名称 | `QCode.cc` |
| ANTHROPIC_BASE_URL | `https://api.qcode.cc/api` |
| ANTHROPIC_AUTH_TOKEN | 你的 QCode.cc API Key（`cr_` 开头） |

> **为什么推荐 `asia.qcode.cc`？** 这是 QCode.cc 的亚洲节点（韩国 / 台湾 / 香港就近），对中国大陆用户延迟最低；不稳定时切回 `api.qcode.cc`（全球 Route 53）。同一把 Key 在 `api` / `asia` / `us` 三个域名下通用。

保存后点该卡片的 **「启用」**（英文界面 Enable；卡片操作按钮需悬停才显示）将其设为当前 Claude 供应商，CC Switch 会自动把 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN` 写入 `~/.claude/settings.json`。在终端运行 `claude` 验证连接。

### 选择默认模型

QCode.cc 提供完整的旗舰到轻量模型阵容，可在 Claude Code 中用 `/model` 切换，或直接在配置中指定：

| 模型 | 适用 |
|------|------|
| `claude-sonnet-5` | **日常默认**，当前平衡档 |
| `claude-opus-5` | 当前旗舰，复杂推理与大型重构 |
| `claude-sonnet-4-6` | 仍在售的上一代，可作对照 |
| `claude-opus-4-8` | 仍在售的上一代旗舰 |
| `claude-haiku-4-5` | 快速问答、批量小任务 |

单价与上下文长度以 [qcode.cc/models](https://qcode.cc/models) 实时显示为准（本页不复制数字，避免过时）。完整阵容（含 GPT、Gemini 与国产家族）见同一页。另外 v3.20.3 起 Claude 供应商编辑器提供**按角色**（Sonnet / Opus / Fable / Haiku / 子代理）的模型映射面板，可一键应用到所有角色。

## 配置 Codex 供应商（用于 Codex CLI）

在顶部应用切换器选 **Codex** → 右上角 **「+」添加供应商** → 预设选 **自定义** → 按下表填写：

> ⚠️ Codex 供应商编辑面板里有「需要本地路由映射」开关，它是给只支持 Chat Completions 的上游做本地代理转换用的。**接 QCode 不要开**——QCode 原生提供 Responses 协议，开了反而要求本地代理常驻。

| 字段 | 值 |
|------|-----|
| 供应商名称 | `qcode`（推荐小写，便于作为 TOML 键名） |
| Base URL | `https://api.qcode.cc/openai` |
| API Key | 你的 QCode.cc API Key |
| 默认模型 | `gpt-6-sol`（推荐）或 `gpt-5.6-terra`（编程场景） |

CC Switch 会生成等效的 `~/.codex/config.toml` 和 `~/.codex/auth.json`：

```toml
model_provider = "qcode"
model = "gpt-6-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
```

保存并点「启用」，运行 `codex` 验证连接。GPT 模型可选 `gpt-6-sol` / `gpt-5.6-terra` / `gpt-5.6-sol`（单价与上下文见 [qcode.cc/models](https://qcode.cc/models)）。Codex CLI 的版本号以你本机 `codex --version` 为准，不要依赖文档里的历史数字。

## 在多个供应商/账号之间切换

CC Switch 的核心价值在于"切换"。常见做法：

1. 在 **Claude** 标签下保存多份供应商，例如 `QCode.cc`（主力）、`QCode.cc (asia)`（大陆节点）、`Anthropic Official`（备用）。
2. 需要切换时，点击目标供应商卡片的 **「启用」**，CC Switch 会把对应的 `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` 重新写入 `~/.claude/settings.json`。
3. 让新配置生效：官方 [README](https://github.com/farion1231/cc-switch) 写 Claude Code **目前支持供应商数据热切换**；官方 [FAQ](https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/en/5-faq/5.2-questions.md) 和 [issue #3057](https://github.com/farion1231/cc-switch/issues/3057) 则记录了「磁盘上的 `settings.json` 已改、**正在跑的会话仍走旧供应商**」。若当前会话还在打旧节点，**关掉该会话、开新终端**再跑 `claude`。Codex / 其它 CLI 按 FAQ 一律重开终端。
4. Codex 同理：在 **Codex** 标签切换激活项会重写 `~/.codex/config.toml`。

> **托盘快捷切换**：CC Switch 常驻系统托盘；v3.13.0 起托盘右键菜单**按应用分组子菜单**（Claude / Codex / Gemini 各一个），子菜单标题显示当前启用的供应商与用量摘要，点供应商名即切换。托盘切换和主界面「启用」写的是同一份 live 配置，坑见下文「接入之后」。

### 多账号 / 多套餐示例

为同一个 QCode.cc 保存两份配置，分别填不同的 API Key：

| 供应商名称 | Base URL | API Key | 用途 |
|-----------|----------|---------|------|
| `QCode.cc (work)` | `https://api.qcode.cc/api` | 工作 Key | 团队/报销账号 |
| `QCode.cc (personal)` | `https://api.qcode.cc/api` | 个人 Key | 个人项目 |

切换启用即在两套配额之间无缝切换，互不串账。

## 使用场景

- **国内网络波动**：主力用 `asia.qcode.cc`，抖动时一键切到 `api.qcode.cc` 全球节点。
- **多供应商对比**：同一任务分别用 QCode.cc 与官方 Anthropic 跑一遍，对比响应与成本。
- **团队 / 个人分账**：用不同 Key 区分工作与私人用量，便于核账。
- **Claude + Codex 协同**：一个应用里同时管理 Claude Code 与 Codex CLI，分别接 Anthropic 协议端点与 OpenAI 协议端点。

## Claude Code 高级能力（接 QCode 后同样可用）

CC Switch 只负责切换供应商，Claude Code 自身的能力不受影响。接入 QCode 后，以下功能照常工作（运行在 Claude Code 当前配置指向的模型上）：

### 视觉输入：从截图 / 图表理解需求

Claude Code 支持把图片喂给具备视觉能力的模型：在提示中粘贴（Ctrl+V）、拖拽图片，或直接引用图片文件路径。常见用途：

- 从设计稿 / 截图还原 UI
- 从报错截图定位 Bug
- 阅读架构图、图表

经 QCode 可用的视觉模型包括 `claude-opus-5` / `claude-sonnet-5`，以及仍在售的 `claude-opus-4-8` / `claude-sonnet-4-6` 和 GPT-5.x。实时能力标记以 [qcode.cc/models](https://qcode.cc/models) 为准。

> **注意：这里说的是图像"输入"（理解），不是图像"生成"。** 需要让模型生成图片，请用 `gpt-image-2` 模型，详见 [gpt-image-2 图像生成](/docs/usage/image-2)。

### 动态工作流（后台子代理编排）

在提示中包含关键词 **ultracode**（或直接说"运行一个工作流"）即可触发 Claude Code 的动态工作流：它会编排数十到上百个后台子代理并行处理，适合全代码库级别的审查、迁移、调研。子代理在后台运行的同时你可以继续工作，用 `/workflows` 命令查看运行情况。该能力运行在 Claude Code 当前配置的模型上——所以当 Claude Code 指向 QCode 时同样可用。延伸阅读 [子代理](/docs/advanced/subagents)。

### 无头模式 / 自动化输出

在脚本与 CI 中用 `-p` 一次性运行并指定输出格式：

```bash
# 结构化 JSON（含 result / total_cost_usd / usage / session_id），用 jq 解析
claude -p "总结本仓库的测试覆盖" --output-format json | jq '.result'

# 行分隔的流式 JSON 事件，适合实时管道
claude -p "审查 src/ 的安全风险" --output-format stream-json
```

更多管道与 CI 用法见 [自动化与 CI/CD](/docs/advanced/headless)。

## 关于 Gemini / Antigravity

CC Switch 的可视化列表里包含 Gemini CLI，但请注意：**Google 已让 Gemini CLI 退役**（Pro/免费层 EOL 为 2026-06-18，企业付费 Key 不受影响），后继为 **Google Antigravity CLI**（2026-05-19 起可用）。如需通过 QCode 使用 Gemini 系模型，推荐改用 Antigravity：

- CC Switch 目前仍把 Gemini CLI 作为一等应用维护，配置入口与 Claude / Codex 相同
- 通过 QCode 使用 Gemini 系模型的逐步配置见 [Google Antigravity CLI 接入](/docs/ide/antigravity)，确切配置键以 [官方文档](https://antigravity.google/docs) 为准

QCode 上仍在售、文档里常用的 Gemini 型号包括 `gemini-2.5-pro`、`gemini-3.5-flash`。是否有倍率、具体单价以 [qcode.cc/models](https://qcode.cc/models) 为准，不要沿用口头「2 倍」除非该页当时就是这个数。

## 备用节点

若主节点访问异常，可切换到其他节点（同一把 Key 通用）：

| 节点 | Claude Base URL | Codex Base URL |
|------|-----------------|----------------|
| 国际 | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai` |
| 亚洲（大陆推荐） | `https://asia.qcode.cc/api` | `https://asia.qcode.cc/openai` |
| 北美 / 欧洲 | `https://us.qcode.cc/api` | `https://us.qcode.cc/openai` |

> 自检：直接访问 Base URL 对应路径返回 `401` 是正常的——说明路径正确，只是缺少鉴权。

## 共享配额

CC Switch 中的 Claude 和 Codex 供应商使用同一个 QCode.cc API Key，共享你的套餐配额（详见 [计费说明](/docs/reference/billing)），不会因为多开两个供应商而重复扣费。若你为不同 Key 建了多份供应商，则各 Key 各自计费、互不影响。

## 接入之后：切换、并存、恢复

这一节对应搜「CC Switch」进来之后最常见的用后问题。配置怎么填见上文；这里只讲跑起来以后。

### 多套餐 / 多 Key 怎么管

一份供应商 = 一组 `BASE_URL` + Key +（Codex 的）模型。同一家 QCode 可以存多份，例如：

| 供应商名称 | 用途 |
|-----------|------|
| `QCode.cc` | 国际域，主力 |
| `QCode.cc (asia)` | 亚洲节点（韩国 / 台湾 / 香港就近），大陆网络抖动时切 |
| `QCode.cc (work)` / `QCode.cc (personal)` | 两把不同的 `cr_` Key，分账 |

同一时刻只有**一份**供应商处于启用态——CC Switch 不会让两套配置同时写进 `~/.claude/settings.json`。要对照官方 Anthropic 和 QCode，就来回点「启用」，不要指望两个一起生效。

### 切换后 CLI 没走新供应商

按下面顺序查，不要先怀疑 Key：

1. 打开 `~/.claude/settings.json`（Codex 则看 `~/.codex/config.toml`），确认 `ANTHROPIC_BASE_URL` / `base_url` 已经变成你刚激活的那一套。
2. 文件已变但会话没变：这是 [issue #3057](https://github.com/farion1231/cc-switch/issues/3057) 写过的行为——Claude Code 在**进程启动时**把 `settings.json` 的 `env` 打进环境变量，跑着的会话不会重读。关掉当前 `claude` / `codex`，新开终端再进。
3. 官方 README 说 Claude Code 现在支持热切换。若你的版本热切换有效，可以不重启；**一旦还在打旧节点，仍以重开会话为准**。
4. FAQ 对 Gemini CLI 的口径是托盘切换立即生效。Gemini CLI 本身已 EOL（见上文），不要把这条套到 Claude / Codex 上。

### 和官方 Anthropic / ChatGPT 账号并存

官方 README / FAQ 的做法：

1. 在预设列表里加一份 **Official Login**（Claude / Codex）或 **Google Official**（Gemini）
2. 点「启用 / Enable」
3. 重开对应 CLI，按它自己的 Log out / Log in（或 OAuth）走一遍
4. 之后就可以在「官方登录」和 `QCode.cc` 自定义供应商之间来回切

不要手改 `settings.json` 去「合并」官方 OAuth 和 QCode 的 `ANTHROPIC_AUTH_TOKEN`——激活时 CC Switch 会按当前供应商重写它管理的字段。Codex 的多个官方账号之间切换，以 README「Codex 可以在不同官方供应商之间切换」为准。

### 托盘切换的坑

- **图标不见了**：macOS 看菜单栏设置；Windows 看任务栏溢出区；Linux 可能要装 `libappindicator`（官方 FAQ）
- **轻量模式**（托盘菜单 Lightweight Mode）：主窗口关闭（销毁而非隐藏）只留托盘；该状态不持久，下次正常启动回到普通模式；第一次被 `ccswitch://` 深链拉起时会重建窗口，会慢一点（官方 FAQ，v3.13.0 起）
- **托盘点了但 CLI 没变**：托盘切换写的仍是 live 配置文件，和主界面「激活」相同，**不会**替你杀掉正在跑的 `claude`。仍然要按上一小节重开会话
- 供应商名加 `(asia)` / `(work)` 后缀，托盘菜单里才分得清

### 配置被覆盖了怎么恢复

激活 / 接管时，CC Switch 会把供应商字段写进 CLI 的 live 文件。多个 issue（[#2992](https://github.com/farion1231/cc-switch/issues/2992)、[#4274](https://github.com/farion1231/cc-switch/issues/4274)；另 [#1656](https://github.com/farion1231/cc-switch/issues/1656) 是要求改为合并写入的功能请求）记录过：`~/.claude/settings.json` 里它不管理的键（`enabledPlugins`、`hooks`、`statusLine`、`permissions` 等）可能被整文件覆盖丢掉。插件文件往往还在磁盘上，只是 `enabledPlugins` 没了所以不加载。

可核对的恢复路径（均来自官方 README / 用户手册，不是第三方口诀）：

1. **应用自己的备份**：`~/.cc-switch/backups/`（自动轮换，官方写保留最近 10 个）
2. **你导出过的包**：设置里的导出文件名形如 `cc-switch-export-{timestamp}.sql`；导入会覆盖当前库，先再导出一份再导回去
3. **通用配置片段**（README FAQ「切换后插件不见了」）：编辑供应商 → 通用配置面板 →「从当前供应商提取」，以后新建供应商勾选「写入通用配置」（README 亦作「应用通用配置」/ "Write Shared Config"，默认勾选）。首次导入的默认供应商里应还留着当时的完整项
4. **Claude 的手改**：若你只改过 `~/.claude/settings.json` 且从未进过 CC Switch 的通用配置，先从自己的备份 / Time Machine / 编辑器本地历史找回，再贴进通用配置，不要指望下一次激活自动合并

CC Switch 自己的库在 `~/.cc-switch/cc-switch.db`，设备级 UI 在 `~/.cc-switch/settings.json`。删后者只重置界面，不会还原 Claude 的 hooks。

## 实用技巧

- **命名带后缀**：供应商名加上 `(asia)` / `(work)` 等后缀，托盘切换时一眼可辨。
- **切换后先看文件再开新会话**：以 `~/.claude/settings.json` / `~/.codex/config.toml` 是否已变为准；跑着的进程按 FAQ / #3057 不会热加载。
- **末尾不要带斜杠**：QCode 要求 Base URL 末尾不带 `/`（否则 SDK 会拼出 `//v1/...` 类错误路径）。
- **Key 单独保管**：CC Switch 对每个供应商独立存储 Key，更换 Key 时记得逐个更新。
- **备份配置**：切换前若手改过 `~/.claude/settings.json`，激活会覆盖你的手改内容，建议先备份或抽进通用配置片段。

## 常见问题

### 保存后「启用」按钮不可点

按顺序确认：① 端点字段非空；② 面板里的 JSON / TOML 语法合法（手改最容易破坏）；③ 再试去掉 Base URL 末尾的 `/`（QCode 端点要求不带尾斜杠。CC Switch 本身对尾斜杠的行为官方文档未记载，此排查顺序为我方经验）。

### Claude Code 2.1.265–2.1.267 每轮请求都 400（Artifact schema）

Claude Code 2.1.265–2.1.267 发出的 Artifact 工具 schema 会被严格校验的网关整请求拒绝（400，提示 `Invalid schema for function 'Artifact'`）。**CC Switch 3.20.3（2026-09-11）起**在 Claude 供应商编辑器提供「**Disable Artifact Tool**（禁用 Artifact 工具）」快捷开关，勾选后写入 `env.CLAUDE_CODE_DISABLE_ARTIFACT="1"`。Claude Code 的官方修复是升级到 ≥2.1.268，详见 [故障排查](/docs/reference/troubleshooting)。该问题是否与 QCode 通道相关未经我们逐一复现，遇到请带 request id 提工单。

### 报错 401 Unauthorized

1. 确认 API Key 以 `cr_` 开头且无前后空格
2. 到 [qcode.cc/dashboard](https://qcode.cc/dashboard) 检查密钥是否有效
3. 若 Claude 端报 401 但 Codex 正常（或反之），说明某一份供应商的 Key 没填对——CC Switch 对每个供应商独立存储 Key

### 切换供应商后没生效

先看 live 文件是否已经换成新供应商。文件已变则关掉当前 `claude` / `codex` 会话再开（官方 FAQ；[#3057](https://github.com/farion1231/cc-switch/issues/3057)）。不要只点托盘然后在旧窗口里继续打。

### Codex 启动后一直转圈

确认 `config.toml` 中按 **QCode 端点约定**把 `base_url` 填到 `/openai` 为止（**不是** `/openai/v1`）；`wire_api = "responses"` 必须保留。最常见漏因：顶层 `model_provider` 没写或与 `[model_providers.xxx]` 表名不一致——此时 Codex 会回落内置 openai 官方端点（官方 issue #7263 记录过该症状）。

### 能同时用 Claude 和 Codex 吗

可以。CC Switch 把 Claude 写到 `~/.claude/`，Codex 写到 `~/.codex/`，两份配置互不干扰。终端分别运行 `claude` 和 `codex` 即可。

### 我手改过 settings.json，激活会丢吗

会。激活时 CC Switch 会用该供应商的字段覆盖 `~/.claude/settings.json` 中对应项；若干版本里还出现过整文件覆盖、丢掉 `enabledPlugins` / `hooks` 的报告（[#2992](https://github.com/farion1231/cc-switch/issues/2992)、[#4274](https://github.com/farion1231/cc-switch/issues/4274)）。自定义项放到「通用配置片段」，激活前备份，丢掉后从 `~/.cc-switch/backups/` 或导出的 `.sql` 恢复。

### 怎么切回官方 Anthropic 登录

预设里加 **Official Login** → 启用 → 重开 CLI → 走官方 Log out / Log in。不要手搓一份「空 env 又留着 cr_ 密钥」的混合配置。

## 下一步

- [WorkBuddy 集成](/docs/ide/workbuddy) — 同一把 Key 接到腾讯 WorkBuddy 自定义模型
- [Claude Code 完整教程](/docs/getting-started/claude-code-tutorial) — 掌握 Claude Code 的核心用法
- [Codex 完整教程](/docs/ide/codex) — 深入使用 Codex CLI
- [VS Code 集成](/docs/ide/vscode) — 在编辑器中直接使用 Claude Code
- [子代理](/docs/advanced/subagents) — 用动态工作流编排后台代理
- [自动化与 CI/CD](/docs/advanced/headless) — 无头模式与脚本集成
- [计费说明](/docs/reference/billing) — 了解套餐和配额规则

> 还没有 QCode.cc API Key？前往 [qcode.cc/pricing](https://qcode.cc/pricing) 选套餐，一把 Key 在 CC Switch 里同时驱动 Claude Code 与 Codex CLI。