cc-switch/docs/user-manual/zh/2-providers/2.1-add.md

2.1 添加供应商

打开添加面板

点击主界面右上角的 + 按钮，打开添加供应商面板。

面板分为两个 Tab：

• 应用专属供应商：仅用于当前选中的应用（Claude/Codex/Gemini/OpenCode/OpenClaw）
• 统一供应商：跨应用共享的配置

使用预设添加

预设是预先配置好的供应商模板，只需填写 API Key 即可使用。

操作步骤

1. 在「预设」下拉框中选择供应商
2. 名称和端点会自动填充
3. 填写你的 API Key
4. （可选）填写备注
5. 点击「添加」

常用预设

Claude 预设

预设名称	说明
Claude 官方	使用 Anthropic 官方账号登录
DeepSeek	DeepSeek 模型
智谱 GLM	智谱 AI 的 GLM 模型
智谱 GLM en	智谱 AI（英文版）
百炼	阿里云百炼（通义千问）
Kimi	Moonshot Kimi 模型
Kimi For Coding	Kimi 编程专用模型
StepFun	阶跃星辰 Step模型
ModelScope	魔搭社区
KAT-Coder	KAT-Coder 模型
Longcat	Longcat AI
MiniMax	MiniMax 模型
MiniMax en	MiniMax（英文版）
DouBaoSeed	豆包 Seed 模型
BaiLing	百灵 AI
AiHubMix	AiHubMix 聚合服务
SiliconFlow	硅基流动
SiliconFlow en	硅基流动（英文版）
DMXAPI	DMXAPI 中转服务
PackyCode	PackyCode 中转服务 ⭐
Cubence	Cubence 服务
AIGoCode	AIGoCode 服务
RightCode	RightCode 服务
AICodeMirror	AICodeMirror 服务
OpenRouter	聚合路由服务
Nvidia	Nvidia AI 服务
Xiaomi MiMo	小米 MiMo 模型

⭐ 标注为官方合作伙伴。预设列表可能随版本更新，以应用内实际显示为准。

Codex 预设

预设名称	说明
OpenAI 官方	使用 OpenAI 官方账号登录
Azure OpenAI	Azure OpenAI 服务
AiHubMix	AiHubMix 聚合服务
DMXAPI	DMXAPI 中转服务
PackyCode	PackyCode 中转服务
Cubence	Cubence 服务
AIGoCode	AIGoCode 服务
RightCode	RightCode 服务
AICodeMirror	AICodeMirror 服务
OpenRouter	聚合路由服务

Gemini 预设

预设名称	说明
Google 官方	使用 Google OAuth 登录
PackyCode	PackyCode 中转服务
Cubence	Cubence 服务
AIGoCode	AIGoCode 服务
AICodeMirror	AICodeMirror 服务
OpenRouter	聚合路由服务
自定义	手动配置所有参数

OpenCode 预设

预设名称	说明
DeepSeek	DeepSeek 模型
智谱 GLM	智谱 AI 的 GLM 模型
智谱 GLM en	智谱 AI（英文版）
百炼	阿里云百炼
Kimi k2.5	Moonshot Kimi-k2.5 模型
Kimi For Coding	Kimi 编程专用模型
StepFun	阶跃星辰 Step模型
ModelScope	魔搭社区
KAT-Coder	KAT-Coder 模型
Longcat	Longcat AI
MiniMax	MiniMax 模型
MiniMax en	MiniMax（英文版）
DouBaoSeed	豆包 Seed 模型
BaiLing	百灵 AI
Xiaomi MiMo	小米 MiMo 模型
AiHubMix	AiHubMix 聚合服务
DMXAPI	DMXAPI 中转服务
OpenRouter	聚合路由服务
Nvidia	Nvidia AI 服务
PackyCode	PackyCode 中转服务
Cubence	Cubence 服务
AIGoCode	AIGoCode 服务
RightCode	RightCode 服务
AICodeMirror	AICodeMirror 服务
OpenAI Compatible	OpenAI 兼容接口
Oh My OpenCode	Oh My OpenCode 服务

💡 预设列表持续更新中，以应用内实际显示为准。

OpenClaw 预设

预设名称	说明
DeepSeek	DeepSeek 模型
智谱 GLM	智谱 AI 的 GLM 模型
智谱 GLM en	智谱 AI（英文版）
Qwen Coder	通义千问编码模型
Kimi k2.5	Moonshot Kimi-k2.5 模型
Kimi For Coding	Kimi 编程专用模型
StepFun	阶跃星辰 Step模型
MiniMax	MiniMax 模型
MiniMax en	MiniMax（英文版）
KAT-Coder	KAT-Coder 模型
Longcat	Longcat AI
DouBaoSeed	豆包 Seed 模型
BaiLing	百灵 AI
Xiaomi MiMo	小米 MiMo 模型
AiHubMix	AiHubMix 聚合服务
DMXAPI	DMXAPI 中转服务
OpenRouter	聚合路由服务
ModelScope	魔搭社区
SiliconFlow	硅基流动
SiliconFlow en	硅基流动（英文版）
Nvidia	Nvidia AI 服务
PackyCode	PackyCode 中转服务
Cubence	Cubence 服务
AIGoCode	AIGoCode 服务
RightCode	RightCode 服务
AICodeMirror	AICodeMirror 服务
AICoding	AICoding 服务
CrazyRouter	CrazyRouter 服务
SSSAiCode	SSSAiCode 服务
AWS Bedrock	AWS Bedrock 服务
OpenAI Compatible	OpenAI 兼容接口

自动获取模型

添加或编辑供应商时，可以自动从供应商端点发现可用模型列表，免去手动复制粘贴模型 ID 的繁琐流程。

1. 确保已填写 API Key 和 端点地址
2. 点击模型输入框旁的 获取模型 按钮（下载图标）
3. CC Switch 使用配置的 API Key 调用 OpenAI 兼容的 /v1/models 端点
4. 从按类别分组的下拉菜单中选择模型

此功能覆盖全部五个应用 —— Claude / Codex / Gemini / OpenCode / OpenClaw，适用于所有支持 /v1/models 端点的供应商。

常见错误：

• 认证失败（401/403）：检查你的 API Key 是否正确
• 端点不支持（404/405）：该供应商未提供 /v1/models 端点，需手动填写模型 ID
• 解析失败：返回内容不符合 OpenAI 兼容格式
• 超时：端点响应缓慢，请稍后重试或检查网络

自定义配置

选择「自定义」预设后，需要手动编辑 JSON 配置。

Claude 配置格式

{
  "env": {
    "ANTHROPIC_API_KEY": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://api.example.com"
  }
}

字段	必填	说明
ANTHROPIC_API_KEY	是	API 密钥
ANTHROPIC_BASE_URL	否	自定义端点地址
ANTHROPIC_AUTH_TOKEN	否	替代 API_KEY 的认证方式

Codex 配置格式

Codex 使用两个配置文件：

1. auth.json（~/.codex/auth.json）- 存储 API 密钥：

{
  "OPENAI_API_KEY": "your-api-key"
}

2. config.toml（~/.codex/config.toml）- 存储模型和端点配置：

# 基础配置
model_provider = "custom"
model = "gpt-5.2"
model_reasoning_effort = "high"
disable_response_storage = true

# 自定义供应商配置
[model_providers.custom]
name = "custom"
base_url = "https://api.example.com/v1"
wire_api = "responses"
requires_openai_auth = true

auth.json 字段说明：

字段	必填	说明
OPENAI_API_KEY	是	API 密钥

config.toml 字段说明：

字段	必填	说明
model_provider	是	模型提供商名称（需与 [model_providers.xxx] 匹配）
model	是	使用的模型（如 gpt-5.2、gpt-4o）
model_reasoning_effort	否	推理强度：low / medium / high
disable_response_storage	否	是否禁用响应存储
base_url	是	API 端点地址
wire_api	否	API 协议类型（通常为 responses）
requires_openai_auth	否	是否使用 OpenAI 认证方式

Gemini 配置格式

{
  "env": {
    "GEMINI_API_KEY": "your-api-key",
    "GOOGLE_GEMINI_BASE_URL": "https://api.example.com"
  }
}

字段	必填	说明
GEMINI_API_KEY	是	API 密钥
GOOGLE_GEMINI_BASE_URL	否	自定义端点地址
GEMINI_MODEL	否	指定模型

💡 认证类型由 CC Switch 自动检测（PackyCode API 代理 / Google OAuth / 通用 API Key），无需手动配置。

统一供应商

统一供应商可以跨 Claude/Codex/Gemini/OpenCode/OpenClaw 共享配置，适用于支持多种 API 格式的中转服务。

创建统一供应商

1. 切换到「统一供应商」Tab
2. 点击「添加统一供应商」
3. 填写通用配置：
   • 名称
   • API Key
   • 端点地址
4. 勾选要同步的应用（Claude/Codex/Gemini/OpenCode/OpenClaw）
5. 保存

同步机制

统一供应商会自动同步到勾选的应用：

• 修改统一供应商后，所有关联应用的配置同步更新
• 删除统一供应商后，关联的应用配置也会删除

保存并同步

编辑统一供应商时，可以选择：

操作	说明
保存	仅保存配置，不立即同步
保存并同步	保存配置并立即同步到所有启用的应用

手动同步

如果需要手动触发同步：

1. 在统一供应商卡片上点击「同步」按钮
2. 确认同步操作
3. 配置会覆盖各应用中关联的供应商

导入供应商

CC Switch 支持两种方式导入供应商配置：

方式一：深度链接导入

通过 ccswitch:// 协议链接一键导入：

1. 点击或访问深度链接
2. CC Switch 自动打开并显示导入确认
3. 预览配置信息
4. 点击「确认导入」

获取深度链接：

• 从他人分享获取
• 使用 在线生成工具 创建

方式二：数据库备份导入

从 SQL 备份文件批量导入：

1. 打开「设置 → 高级 → 数据管理」
2. 点击「选择文件」
3. 选择之前导出的 .sql 备份文件
4. 点击「导入」
5. 确认覆盖现有配置

导入内容：

• 所有供应商配置
• MCP 服务器配置
• Prompts 预设
• 用量日志

⚠️ 注意：导入会覆盖现有数据库，建议先导出当前配置作为备份。导出的文件名格式为 cc-switch-export-{时间戳}.sql。

Codex OAuth 反向代理（Claude 供应商）

v3.13.0 起，CC Switch 新增了 Codex OAuth 反向代理路径，让你可以用 ChatGPT 账号在 Claude Code 中复用 Codex 服务。

💡 位置提示：这项功能作为一个新的 Claude 供应商卡片类型出现，而不是 Codex 侧的预设。添加后会和普通 API-Key 型供应商并列在 Claude 的供应商列表中。

前提条件

• 拥有可登录的 ChatGPT 账号
• 能够访问 auth.openai.com 和 chatgpt.com
• 在使用前请先阅读本节末尾的 ⚠️ 风险提示

两个入口

你可以从下面任意一个入口开始：

入口 A：从添加供应商面板开始（推荐新用户）

1. 切换到 Claude 应用
2. 点击右上角的 + 按钮打开添加供应商面板
3. 在预设列表的第三方分类下选择 Codex (ChatGPT Plus/Pro) 预设（以 UI 中显示的名称为准）
4. 如果尚未登录 ChatGPT 账号，面板会自动引导你进入登录流程（见下文"登录流程"）
5. 登录成功后，供应商表单会显示已登录的账号，点击「保存」完成添加

入口 B：从 OAuth 认证中心开始（适合多账号管理）

1. 打开 设置 → OAuth 认证中心（标签页顶部带 Beta 标记）
2. 在 ChatGPT (Codex OAuth) 区块点击 使用 ChatGPT 登录 按钮
3. 完成登录流程（见下文）
4. 登录完成后，回到 Claude 应用 → 添加供应商 → 选择同一个 Codex (ChatGPT Plus/Pro) 预设
5. 在表单中的「选择账号」下拉框选择刚登录的账号，保存即可

登录流程（Device Code）

不管从哪个入口进入，登录流程都一致：

1. 获取验证码：CC Switch 调用 OpenAI Device Code 流程，并在界面上显示：
   • 一个 验证码（约 8 位字符，例如 ABCD-1234）
   • 验证码右侧的 复制 按钮
   • 下方的授权链接 https://auth.openai.com/codex/device
   • "等待授权中..." 的动画提示
2. 浏览器授权：点击链接（或手动访问该 URL），在浏览器中：
   • 登录你的 ChatGPT 账号
   • 输入上一步复制的验证码
   • 确认授权
3. 自动轮询完成：CC Switch 会在后台持续轮询 OpenAI 服务器，检测到授权成功后自动关闭等待界面
4. 显示已登录账号：登录的 ChatGPT 账号会出现在 OAuth 认证中心 → 已登录账号列表中，显示登录邮箱

⏱️ 验证码有效期约 15 分钟。如果超时，界面会显示"Device Code 已过期"，点击「重试」即可重新获取验证码。

启用与使用

添加并保存 Codex OAuth 供应商后：

1. 在 Claude 供应商列表中找到它
2. 点击卡片的 启用 按钮 — 和普通供应商完全一致
3. Claude Code CLI 即可通过反向代理使用 ChatGPT 订阅
4. 托盘菜单的 Claude 子菜单中也会出现这个供应商，支持快速切换

💡 底层细节：CC Switch 会将请求路由到 https://chatgpt.com/backend-api/codex，Base URL 被强制重写 — 你无需在表单中手动填写端点地址。API 格式固定为 openai_responses。

默认模型

Codex OAuth 预设的默认模型映射：

角色	默认模型
主模型	gpt-5.4
Sonnet 角色	gpt-5.4
Opus 角色	gpt-5.4
Haiku 角色	gpt-5.4-mini

你可以在供应商的 JSON 编辑器中覆盖 ANTHROPIC_MODEL 等环境变量来自定义。

多账号管理（OAuth 认证中心）

OAuth 认证中心支持同时管理多个 ChatGPT 账号：

操作	说明
添加其他账号	点击「添加其他账号」重复登录流程
设为默认	在账号行点击「设为默认」—— 新建供应商默认使用该账号
为供应商选账号	供应商表单中通过「选择账号」下拉框指定特定账号
移除账号	点击账号右侧的红色 × 移除（Token 被清除）
注销所有账号	底部「注销所有账号」按钮一键清除

💡 使用场景：如果你和团队共享一台开发机，可以为每个成员的 ChatGPT 账号各建一个供应商，通过托盘菜单快速切换。

Token 自动刷新

• Token 会在过期前 60 秒自动刷新，全程后台进行，无需手动干预
• Refresh Token 存储在本地数据目录，不会上传到任何地方
• 不支持导出 Token（防止泄露）

配额展示

登录并启用供应商后，供应商卡片底部会自动显示账号配额：

显示元素	示例	颜色规则
使用百分比	45%	< 70% 绿色，70–89% 橙色，≥ 90% 红色
重置倒计时	7d12h 后重置	ChatGPT 账号的滑动窗口或每日限额
刷新按钮	圆形箭头	手动重新查询配额

⚠️ 会话已过期：如果 Token 完全失效（无法自动刷新），卡片底部会显示黄色警告框「会话已过期」。此时请到 OAuth 认证中心移除该账号并重新登录。

常见失败

场景	表现	解决方法
验证码超时	显示"Device Code 已过期"	点击「重试」重新获取验证码
浏览器拒绝授权	显示"用户拒绝授权"	重新登录，在浏览器中点击"授权"
网络错误	显示具体错误信息	检查网络连接，确认能访问 OpenAI 域名
创建供应商前未登录	"请先登录 ChatGPT 账号"提示	先到 OAuth 认证中心完成登录
Token 失效无法刷新	配额框显示"会话已过期"	移除账号后重新登录
配额查询失败	配额框显示"查询失败"	点击「刷新」按钮重试

⚠️ 风险提示（重要）

Codex OAuth 反向代理通过逆向工程的 OAuth 流程访问 ChatGPT 账号的 Codex 服务。启用前请务必理解以下风险：

1. 违反服务条款：可能违反 OpenAI 的服务条款，该条款禁止未经授权的自动化访问、服务复制和绕过既定访问路径
2. 账号风险：OpenAI 可能将异常使用模式标记为可疑自动化，对 ChatGPT 账号施加临时或永久限制
3. 无法保证长期可用：OpenAI 随时可能更新其认证和检测机制，当前可用的方式未来可能被封堵

启用此功能即表示你自行承担所有风险。CC Switch 不对因使用本功能产生的账号限制、警告或服务暂停承担责任。

📖 完整免责声明及更多背景参见 v3.13.0 Release Notes。

高级选项

API 格式（仅 Claude）

添加使用第三方 API 的 Claude 供应商时，可能需要在高级选项中选择正确的 API 格式：

格式	说明	适用场景
Anthropic Messages	原生 Anthropic API 格式（默认）	直接 Anthropic API 或兼容代理
OpenAI Chat Completions	OpenAI Chat API 格式，由代理自动转换	供应商仅支持 OpenAI Chat 格式
OpenAI Responses API	OpenAI Responses API 格式，由代理自动转换	供应商仅支持 OpenAI Responses 格式

注意：API 格式转换由代理服务处理。使用非 Anthropic 格式时，需要开启代理并启用应用接管才能正确转换请求/响应。详见 4.1 代理服务。

当配置了非默认 API 格式时，高级选项区域会自动展开。

完整 URL 端点模式

v3.13.0 起新增的高级选项。默认情况下，CC Switch 会把配置的 base_url 视作前缀，再在其后拼接 /v1/chat/completions 等固定路径。对于部分厂商（如需要非标准 URL 布局的第三方服务），这种拼接方式会导致请求失败。

启用方式：

1. 编辑供应商，展开「高级选项」
2. 勾选 完整 URL 模式 复选框
3. 将完整的上游端点（而非前缀）填入 base_url

示例对比：

模式	base_url 填写	实际请求目标
默认（前缀拼接）	https://api.example.com	https://api.example.com/v1/chat/completions
完整 URL 模式	https://api.example.com/custom/path/messages	https://api.example.com/custom/path/messages

适用场景：

• 供应商要求使用非标准路径（不是 /v1/chat/completions）
• 供应商有多层级路径结构
• 厂商专属的 API 网关路径

💡 提示：代理转发和 Stream Check 都会遵循「完整 URL 模式」配置，因此启用后无需额外调整。如果关闭此选项，路径拼接恢复为默认行为。

Claude 通用配置快捷开关

编辑 Claude 供应商时，JSON 编辑器上方提供一组 快捷开关：

开关	效果	配置变更
隐藏署名	清除提交/PR 的署名元数据	设置 attribution: {commit: "", pr: ""}
启用 Teammates	启用 Agent 团队功能	设置 env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"
启用工具搜索	启用工具搜索功能	设置 env.ENABLE_TOOL_SEARCH = "true"
最大强度思考	将 effort 级别设为 max	设置 env.CLAUDE_CODE_EFFORT_LEVEL = "max"
禁用自动更新	阻止 Claude Code 自动更新	设置 env.DISABLE_AUTOUPDATER = "1"

取消勾选开关时，对应的配置项会被完全移除。更改会实时反映在 JSON 编辑器中。

此外，写入通用配置 复选框可将全局配置片段合并到供应商中。点击 编辑通用配置 可自定义共享的配置片段。

Codex 1M 上下文窗口

添加 Codex 供应商时，提供 启用 1M 上下文窗口 开关：

• 启用时：在 config.toml 中设置 model_context_window = 1000000 并自动填充 model_auto_compact_token_limit = 900000
• 禁用时：移除这两个字段

开关开启后显示的文本框可自定义自动压缩限制值。

自定义图标

点击名称左侧的图标区域，可以：

• 选择预设图标
• 自定义图标颜色

网站链接

填写供应商的官网或控制台地址，方便快速访问：

• 点击供应商卡片的链接图标可直接打开
• 用于查看余额、获取 API Key 等

备注

添加备注信息，如：

• 账号用途（个人/工作）
• 套餐信息
• 到期时间

备注会显示在供应商卡片上，也支持搜索。

端点测速

添加供应商后，可以对 API 端点进行速度测试：

1. 点击供应商卡片的「测速」按钮
2. 在测速面板中添加多个端点 URL
3. 点击「测速」执行测试
4. 选择延迟最低的端点

测速结果：

• 🟢 绿色：延迟 < 500ms（优秀）
• 🟡 黄色：延迟 500-1000ms（一般）
• 🔴 红色：延迟 > 1000ms（较慢）