# 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 配置格式

```json
{
  "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 密钥：

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

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

```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 配置格式

```json
{
  "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. 点击「确认导入」

**获取深度链接**：
- 从他人分享获取
- 使用 [在线生成工具](https://farion1231.github.io/cc-switch/deplink.html) 创建

### 方式二：数据库备份导入

从 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](../../../release-notes/v3.13.0-zh.md#️-风险提示)。

## 高级选项

### 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 代理服务](../4-proxy/4.1-service.md)。

当配置了非默认 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 | 设置 `effortLevel = "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（较慢）

![image-20260108005327817](../../assets/image-20260108005327817.png)