---
title: 供应商配置
pageTitle: 供应商配置
eyebrow: 详细配置
lead: 配置 CCR 的上游模型服务，包括协议、基础 URL、模型列表和凭据。
---

## 导入本机 Agent 登录态

添加供应商时，CCR 会扫描本机已有的 Agent 登录状态。检测到可复用凭据后，添加弹窗会显示对应导入入口。导入会创建一个普通供应商和配套 provider plugin，让 CCR 复用本机 Agent 授权访问上游服务，不需要再手动粘贴常规 API Key。

### Claude Code

Claude Code 导入会读取本机 Claude Code OAuth 凭据。检测到可用 access token 时，可以导入为 `Claude Code API` 供应商。

导入后：

1. 协议使用 `anthropic_messages`。
2. 默认模型包含 `claude-sonnet-4-20250514`，后续可以在供应商模型列表中增减模型。
3. CCR 会创建 OAuth provider plugin，把请求认证转换为 Claude Code 登录态。
4. 账号用量会使用 Anthropic OAuth 用量接口，适合在供应商列表、托盘或账号面板里查看额度状态。

如果只检测到登录痕迹但没有可用 access token，导入入口会显示不可导入原因。此时先在 Claude Code 中重新登录，再回到 CCR 添加供应商。

### Codex

Codex 导入会读取本机 Codex 登录文件和模型缓存。检测到 Codex access token 或 refresh token 时，可以导入为 `Codex API` 供应商。

导入后：

1. 协议使用 `openai_responses`。
2. API 地址指向 Codex 后端，默认模型至少包含 `gpt-5-codex`，也会合并本机模型缓存中的模型和显示名。
3. CCR 会创建 Codex OAuth provider plugin，并在需要时刷新访问凭据。
4. 账号用量会读取 Codex 额度、余额和 token 统计接口。

导入后可以直接在路由或 Agent配置中选择 `Codex API/模型名`。如果模型缓存较旧，可以先打开 Codex 让它刷新模型列表，再回到 CCR 重新导入或编辑模型。

### ZCode

ZCode 导入会读取本机 ZCode 配置中的供应商 API Key、API 地址和模型列表。只有检测到可用供应商 Key 和 Base URL 时，才能导入为 `ZCode API` 供应商。

导入后：

1. 协议使用 `anthropic_messages`。
2. 模型优先来自 ZCode 本机配置；没有配置时会使用 ZCode 运行缓存或默认模型。
3. CCR 会创建 API Key provider plugin，把 ZCode 本机配置中的 Key 用于请求认证。
4. 如果 API 地址命中 CCR 内置预设，账号用量配置会复用对应预设。

如果只检测到 ZCode 登录态，但没有检测到可用供应商 API Key，导入入口会显示不可导入。此时需要先在 ZCode 中配置可用模型供应商，再回到 CCR 添加供应商。

## 主字段

| 字段 | 代表的能力 |
| --- | --- |
| 选择 预设供应商 | 套用 CCR 内置供应商模板，包括默认 API 地址、可用协议、默认模型、图标、官网链接和部分供应商的用量读取配置。选择 `其他 / 自定义 API 地址` 时，可以接入任意兼容 OpenAI、Anthropic 或 Gemini 协议的上游服务。 |
| 名称 | CCR 内部显示名，也是路由、模型选择、日志和配置中识别供应商的名字。名称必须唯一，建议短且稳定。 |
| API 地址 | 上游 API Base URL。它决定请求实际发往哪里，也用于协议探测、模型列表探测、图标探测和安全校验。预设供应商添加时默认隐藏该字段，可在高级设置里覆盖。自定义供应商必须填写。 |
| API 密钥 | 默认供应商凭据。没有配置凭据池时，模型请求会使用这条 Key；协议探测、模型探测、连通性检测和默认用量读取也会使用它。只填写由当前 API 地址对应供应商签发的 Key。 |
| 模型 | 暴露给 CCR 的模型 ID 列表。路由规则、Profile 模型选择、模型目录和客户端 `/models` 响应都会基于这里的模型。 |
| 搜索模型 / 全部 / 清除 | 当 CCR 能从上游或模型目录拿到模型列表时，可以搜索、全选、清除并勾选模型。勾选结果会保存到供应商的模型列表。 |
| 自定义模型 | 手动添加没有被探测出来的模型 ID。适合供应商没有 `/models` 接口，或新模型还未进入模型目录的情况。 |
| 检测连通性 | 用当前 API 地址、API 密钥、协议和所选模型发送真实测试请求。它可以验证 Key、模型名和协议是否真的可调用。 |
| 要检测的模型 | 连接检查确认弹窗中的模型选择。用于控制只测试部分模型，避免一次性检查全部模型造成额外消耗。 |
| 检测结果 | 展示每个模型是否可用、命中的协议和上游返回的诊断信息。可用结果不会自动增加模型，仍以弹窗主表单中的模型选择为准。 |

## 连通性检测

`检测连通性` 会对你选择的模型发送真实的模型请求，用来确认 API 地址、API 密钥、协议和模型 ID 是否可用。检测请求会限制输出长度，但仍然可能产生额外 token 消耗或计入供应商侧请求次数。

如果供应商按请求、输入 token 或输出 token 计费，建议只勾选需要确认的模型，不要一次性检查全部模型。检测结果只用于诊断连通性，不会自动修改模型列表或用量读取配置。

## 凭据

`API 密钥` 是最简单的单 Key 配置。需要管理多条上游 Key 时，展开“高级设置”中的“凭据池”。

| 字段 | 代表的能力 |
| --- | --- |
| 显示凭据配置 | 展开或收起凭据池配置。未展开不影响已保存的凭据，只是隐藏编辑区域。 |
| 导入 JSON | 从 JSON 文件批量导入凭据。支持顶层数组，或对象中的 `credentials`、`keys`、`apiKeys` 数组。 |
| 添加 Key | 新增一条上游 API Key。 |
| 启用 | 控制单条凭据是否参与请求转发和用量读取。关闭后保留配置，但不会被选中。 |
| 名称 | 单条凭据的显示名。会出现在账号用量、日志和内部诊断里，建议写成可识别的用途或额度来源。 |
| API 密钥 | 该凭据实际发送给上游的 Key。配置了凭据池后，CCR 会把启用的凭据展开成多个内部上游目标，并优先使用凭据池中的 Key。主表单的默认 `API 密钥` 只作为单 Key 配置使用。 |
| 移除 | 删除当前凭据行。 |
| Key 高级选项 | 展开单条凭据的调度和限额字段。 |
| 优先级 | 凭据优先级，数字越小越优先。未填写时按凭据行顺序作为优先级。 |
| 权重 | 同优先级、相近使用率下的排序权重，数字越大越优先。未填写时为 `1`。 |
| 限制 JSON | 该 Key 的本地限额规则。CCR 会按请求、tokens 或图片数量统计窗口使用量，达到上限后自动跳过该 Key，尝试同供应商的其他可用 Key。 |

`限制 JSON` 支持的常用字段：

| 字段 | 含义 |
| --- | --- |
| `rpm` / `rph` / `rpd` | 每分钟 / 每小时 / 每天最多请求数 |
| `tpm` / `tph` / `tpd` | 每分钟 / 每小时 / 每天最多 tokens |
| `ipm` / `iph` / `ipd` | 每分钟 / 每小时 / 每天最多图片数 |
| `maxRequests` + `windowMs` | 自定义时间窗口内最多请求数 |
| `maxTokens` + `quotaWindowMs` | 自定义时间窗口内最多 tokens |

示例：

```json
{
  "rpm": 60,
  "tpm": 100000
}
```

凭据池的作用是“上游 Key 池”，不同于“API 密钥”页面里的 CCR 客户端访问 Key。前者控制 CCR 调用供应商时使用哪个 Key，后者控制客户端访问 CCR 时使用哪个 Key。

## 用量读取

“获取用量”用于让 CCR 在供应商列表、托盘或账号面板中展示余额、套餐额度、状态和错误信息。它不会影响模型是否能请求，只影响账号用量展示。

| 字段 | 代表的能力 |
| --- | --- |
| 获取用量 | 启用或关闭该供应商的账号用量读取。关闭后不请求用量接口。 |
| 用量模式 | 用量读取方式。`标准用量端点` 使用 CCR 标准账号端点；`HTTP JSON 请求` 手动配置一个 JSON 接口；`原始连接器 JSON` 直接编辑 connector 数组。 |
| 刷新间隔（毫秒） | 用量刷新间隔，单位毫秒。未填写时使用默认刷新间隔，最小有效间隔为 30000ms。 |

### 标准用量端点

该模式会尝试供应商侧的 CCR 标准账号端点，例如 `/.well-known/ccr/account` 和 `/v1/account/limits`。适合已经适配 CCR 标准格式的供应商或内置预设。

### HTTP JSON 请求

该模式适合供应商已有自己的余额或额度接口，且返回自定义 JSON 格式的情况。

| 字段 | 代表的能力 |
| --- | --- |
| 方法 | 用量请求方法，支持 `GET` 或 `POST`。 |
| 用量请求 URL | 用量接口地址。可以是完整 URL。请求会附带供应商 API Key，除非在 raw connector 中改成其他认证方式。 |
| 请求头 | 用量接口需要的额外请求头。不要在这里写固定的敏感认证头，优先使用供应商 API Key 认证。 |
| 请求体 | `POST` 请求体，必须是合法 JSON。 |
| 余额剩余字段 | 余额剩余值在响应 JSON 中的路径。 |
| 余额总额字段 | 余额总量或充值总额在响应 JSON 中的路径。 |
| 余额已用字段 | 已用余额在响应 JSON 中的路径。 |
| 余额单位 | 余额单位，例如 `USD`、`CNY` 或 `%`。 |
| 订阅剩余字段 | 套餐、订阅、tokens 或配额剩余量路径。 |
| 订阅上限字段 | 套餐、订阅、tokens 或配额总量路径。 |
| 订阅重置字段 | 套餐重置时间路径。可以返回 ISO 时间，也可以返回秒级或毫秒级时间戳。 |
| 订阅单位 | 套餐单位，例如 `tokens`、`requests`、`hours`。 |
| 状态字段 | 账号状态路径。支持 `ok`、`warning`、`critical`、`error`、`unsupported`。 |
| 消息字段 | 账号提示信息路径。适合展示供应商返回的错误、套餐说明或风控提示。 |
| 测试用量请求 | 立即请求用量接口并解析映射结果，方便在保存前验证字段路径。 |
| 响应字段 | 测试后列出响应 JSON 中可选字段。点击 `余额剩余`、`余额总额`、`余额已用`、`订阅剩余`、`订阅上限`、`重置时间` 可以把该路径快速填入对应字段。 |

字段路径支持 CCR 的轻量 JSONPath 语法：

| 写法 | 说明 |
| --- | --- |
| `$` | 整个响应对象 |
| `$.balance.remaining` | 读取对象字段 |
| `$.items[0].value` | 读取数组下标 |
| `$["weird-key"]` | 读取包含特殊字符的字段名 |
| `$.limits[?(@.type=="TOKENS")].remaining` | 在数组中查找第一个满足简单等值条件的对象 |
| `100 - $.data.percentage` | 数值字段支持简单减法表达式，常用于把“已用百分比”转换成“剩余百分比” |

### 原始连接器 JSON

`连接器 JSON` 允许直接编辑 `account.connectors` 数组，适合需要更复杂能力的供应商。

| 连接器类型 | 能力 |
| --- | --- |
| `standard` | 使用 CCR 标准账号端点。 |
| `http-json` | 请求一个 JSON 接口，并用 mapping 字段映射余额、套餐、状态和消息。 |
| `plugin` | 调用已安装插件注册的账号用量 connector。 |
| `local-estimate` | 不请求远程接口，基于本地窗口配置展示估算额度。 |

点击 `插入示例` 会填入一个包含 `standard`、`http-json`、`plugin` 和 `local-estimate` 的示例 connector 数组。
