CC Switch 统一配置
用 CC Switch 统一管理 Claude Code、Codex、OpenCode、OpenClaw 等客户端的 QiyuanHub 接入，避免为每个工具单独维护配置文件。
01
适用说明
CC Switch 是跨平台桌面端配置助手，支持 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等。把供应商指到 QiyuanHub 后，各客户端会从 CC Switch 读取 Base URL 与 API Key，统一计费与模型路由。
若你只用某一个工具，也可直接看对应文档（Claude Code / Codex / OpenCode）；多工具场景更建议走 CC Switch。
- 适合：同时使用多种 CLI / IDE Agent 的开发者
- 协议：OpenAI Compatible（Chat Completions）
- 推荐：优先用控制台「一键导入 CC Switch」，再按需微调模型
02
开始前请确认
- 已注册并登录 QiyuanHub，账号状态为 active
- 已在「控制台 → API 密钥」创建密钥（格式 `sk-opc-...`，完整 Key 仅创建时显示一次）
- 钱包有可用余额，目标模型在定价页为「已上线」
- 本机已安装 CC Switch 桌面端（安装后会注册 `ccswitch://` 协议）
03
安装 CC Switch
项目地址：https://github.com/farion1231/cc-switch ；官网下载：https://ccswitch.io 。请从 Releases 下载对应系统的最新版本并安装。
# 1. 打开官网或 GitHub Releases
# https://ccswitch.io
# https://github.com/farion1231/cc-switch/releases
# 2. 下载 macOS 安装包（.dmg / .pkg）并安装
# 3. 首次打开若提示协议未注册，可执行：
/usr/bin/open -a "CC Switch" --args --register-protocol
# 4. 确认能打开应用后即可进行导入04
方式一：控制台一键导入（推荐）
QiyuanHub 控制台已对接 CC Switch 深度链接（`ccswitch://`）。创建密钥后可直接唤起本机应用并带入配置。
完整 API Key 不会长期保存在服务器。一键导入依赖创建时的本机会话缓存；换浏览器 / 清缓存后需重新粘贴完整 Key。
1. 打开控制台 → API 密钥
确认列表中有可用密钥；若刚创建，请先复制保存完整 `sk-opc-...`。
2. 点击「导入 CC Switch」
在操作列、禁用按钮前。若本会话刚创建过该密钥，会直接唤起 CC Switch；否则需粘贴完整 Key。
3. 选择应用类型
- Codex — Codex CLI / OpenAI 兼容客户端（默认）
- Claude Code — Claude Code CLI
- OpenCode / Gemini CLI / OpenClaw — 按你实际使用的工具选择
4. 在 CC Switch 确认导入
浏览器会提示打开 CC Switch。确认弹窗中应看到类似信息后点击「导入」：
- 供应商名称：QiyuanHub · <你的密钥名>
- 官网：当前站点地址
- API 端点：https://api.qiyuanapi.cc/v1
- API 密钥：sk-opc-…（已脱敏展示）
- 模型：deepseek-v4.1（可按需修改）
- 用量查询：已启用（默认每 15 分钟）
5. 在目标客户端验证
重启终端或对应 CLI，发送一句测试对话；再到 QiyuanHub「使用日志」确认有请求记录。
05
方式二：在 CC Switch 内手动添加
# 对接参数速查
Base URL : https://api.qiyuanapi.cc/v1
API Key : sk-opc-your-api-key
Model : deepseek-v4.11. 打开 CC Switch → 添加配置 / 添加供应商
顶部切换到目标应用（Claude / Codex / OpenCode 等），再点击右上角「+」或「添加供应商」。
2. 选择「自定义配置」
不要选其他平台的预设供应商；用自定义 / OpenAI Compatible 才能指向 QiyuanHub。
3. 填写自定义 / OpenAI Compatible 供应商
- 供应商名称：QiyuanHub（或任意便于识别的名称，如图中 `qiyuan`）
- 官网链接：可填 https://qiyuanapi.cc/
- API 端点 / Base URL：https://api.qiyuanapi.cc/v1（Codex / OpenAI 兼容务必带 /v1）
- API Key：控制台创建的 sk-opc-...
- 默认模型：填写定价页 slug（deepseek-v4.1）
- 填写默认模型后，点击右侧「下载」按钮拉取可用模型列表，再从下拉中选择或核对 slug
4. 保存并启用该供应商
启用后，对应客户端会读取此配置，无需再手改各工具本地文件（高级定制除外）。
06
密钥分组与模型建议
创建 API 密钥时可选择分组。分组影响可用模型集合与计费倍率（以控制台 / 定价页为准）：
分组不是「渠道品牌名」。参考站里的 max / codex-pro 等名称属于对方平台；在 QiyuanHub 请使用 default / studio，并以本站定价页为准。
- default — 自营 DeepSeek V4.1 · 默认渠道（倍率 1x）
- studio — 自营 DeepSeek V4.1 · Studio 渠道（倍率 1.25x）
- custom — 手动勾选模型白名单；目前公开可用模型仍是 deepseek-v4.1，后续上新模型时再扩白名单
- 模型填写：`deepseek-v4.1`；思考深浅用 reasoning_effort 调，见「思考强度设置」
- 模型名必须与定价页 slug 完全一致，不要填写插件内置的官方模型名（除非碰巧相同）
07
各客户端使用注意
- Claude Code：在 CC Switch 中选择 app=Claude；导入后一般无需再设 ANTHROPIC_* 环境变量
- Codex / OpenAI 兼容 CLI：选择 app=Codex；Base URL 必须带 `/v1`
- OpenCode：选择 app=OpenCode，或继续使用文档中的 opencode.json 自定义 Provider
- OpenClaw：选择 app=OpenClaw；部署侧环境变量也可指向同一套 Base URL 与 Key
- Gemini CLI：若工具支持 OpenAI 兼容模式，可导入 Gemini 应用类型并填写同上参数
08
验收清单
- CC Switch 供应商列表中出现 QiyuanHub，且状态为已启用
- 目标 CLI 能正常返回模型回复
- 控制台「使用日志」出现对应 model 与 Token / 费用
export OPC_API_KEY="sk-opc-your-api-key"
curl https://api.qiyuanapi.cc/v1/chat/completions \
-H "Authorization: Bearer $OPC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4.1",
"messages": [{"role": "user", "content": "你好，请用一句话介绍自己"}]
}'09
排错
- 点击导入无反应：确认已安装 CC Switch，且 `ccswitch://` 协议已注册
- 导入弹窗里端点不对：应以 `https://api.qiyuanapi.cc/v1` 为准，不要漏掉 /v1，也不要多写 /chat/completions
- 401：Key 错误、被禁用，或未使用完整 sk-opc-... 密钥
- 402 / 余额不足：充值或使用兑换码
- 403 application_pending：账号尚未审核通过
- 403 ip_not_allowed：当前 IP 不在该 Key 白名单内
- 模型不存在 / model_not_allowed：slug 写错或模型未上线
- Claude 可用但 Codex 不可用：给 Codex 补上 /v1 端点
- 只填 Host（https://api.qiyuanapi.cc）导致 404：改为完整 Base URL https://api.qiyuanapi.cc/v1