CC Switch 配置

使用 CC Switch 把 QCode.cc 接入 Claude Code 和 Codex CLI：填表、多套餐切换、和官方账号并存、切换未生效与配置被覆盖后的恢复

需要 API Key？ 前往注册 →·端点与 Base URL →

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

接入速览¶

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 或 Codex CLI
• 拥有 QCode.cc API Key（cr_ 开头），在 控制台 获取
• 同一把 Key 同时适用于 Anthropic、OpenAI、Gemini 等多种协议端点，详见 接入点与 API 格式

安装 CC Switch¶

从 GitHub Releases 下载对应平台安装包：

各版本的具体安装步骤与签名提示以 项目 README 为准。

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

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

为什么推荐 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 切换，或直接在配置中指定：

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

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

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

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

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

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）。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 写 Claude Code 目前支持供应商数据热切换；官方 FAQ 和 issue #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：

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

使用场景¶

• 国内网络波动：主力用 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 为准。

注意：这里说的是图像"输入"（理解），不是图像"生成"。 需要让模型生成图片，请用 gpt-image-2 模型，详见 gpt-image-2 图像生成。

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

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

无头模式 / 自动化输出¶

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

# 结构化 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。

关于 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 接入，确切配置键以 官方文档 为准

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

备用节点¶

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

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

共享配额¶

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

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

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

多套餐 / 多 Key 怎么管¶

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

同一时刻只有一份供应商处于启用态——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 写过的行为——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、#4274；另 #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，详见 故障排查。该问题是否与 QCode 通道相关未经我们逐一复现，遇到请带 request id 提工单。

报错 401 Unauthorized¶

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

切换供应商后没生效¶

先看 live 文件是否已经换成新供应商。文件已变则关掉当前 claude / codex 会话再开（官方 FAQ；#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、#4274）。自定义项放到「通用配置片段」，激活前备份，丢掉后从 ~/.cc-switch/backups/ 或导出的 .sql 恢复。

怎么切回官方 Anthropic 登录¶

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

下一步¶

• WorkBuddy 集成 — 同一把 Key 接到腾讯 WorkBuddy 自定义模型
• Claude Code 完整教程 — 掌握 Claude Code 的核心用法
• Codex 完整教程 — 深入使用 Codex CLI
• VS Code 集成 — 在编辑器中直接使用 Claude Code
• 子代理 — 用动态工作流编排后台代理
• 自动化与 CI/CD — 无头模式与脚本集成
• 计费说明 — 了解套餐和配额规则

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

企业团队版 →