供应商管理

供应商管理是 Claude Code Hub 最核心的功能之一，用于添加、配置和管理上游 AI 服务供应商。通过合理配置供应商的权重、优先级和分组，您可以实现智能负载均衡、故障转移和成本优化。

本文主要介绍供应商管理页面的操作指南。如需了解各字段的详细含义和配置建议，请参阅供应商字段详解。

页面概览

供应商管理页面位于 设置 > 供应商管理 (/settings/providers)，提供以下功能：

供应商列表：展示所有已配置的供应商及其状态
搜索与筛选：按类型、名称、URL 或分组快速查找供应商
排序功能：按优先级、权重、名称或创建时间排序
新增供应商：添加新的 AI 服务供应商
调度规则说明：了解系统如何选择供应商

供应商列表

列表展示

每个供应商卡片包含以下信息：

元素	说明
状态图标	绿色勾表示启用，灰色叉表示禁用
类型图标	显示供应商类型（Claude、Codex、Gemini 等）
名称	供应商的显示名称
分组标签	供应商所属的分组（如有）
熔断状态	红色警告标签表示供应商已被熔断
URL	供应商 API 端点地址
官网链接	快速访问供应商官网（如有配置）
API Key	脱敏显示的密钥，点击可查看完整值
超时配置	显示流式首字节/空闲/非流式超时时间
优先级	数值越小优先级越高
权重	同优先级内的流量分配比例
成本系数	用于调整该供应商的成本计算
今日用量	今日调用次数和消费金额

搜索与筛选

页面顶部提供三个筛选工具：

类型筛选：按供应商类型筛选（全部、Claude、Codex、Gemini 等）
排序方式：按优先级、权重、名称或创建时间排序
搜索框：根据名称、URL 或分组标签进行模糊搜索

搜索框支持 500ms 防抖，输入后稍等片刻即可看到搜索结果。

创建供应商

点击页面右上角的「新增服务商」按钮，打开供应商创建表单。

创建流程

点击「新增服务商」按钮
填写基础信息（名称、类型、URL、API Key）
配置调度参数（权重、优先级、分组）
根据需要配置高级选项（限流、代理、模型重定向等）
点击「保存」完成创建

创建成功后，新供应商会自动出现在列表中。

默认启用

新创建的供应商默认处于启用状态，可立即参与请求调度。如需先配置后启用，可在创建后手动禁用。

创建供应商时，API Key 只需输入一次。系统会安全存储密钥，后续仅显示脱敏值。

编辑供应商

点击供应商卡片右侧的编辑图标（铅笔图标）可修改供应商配置。编辑表单与创建表单字段相同，所有配置项均可修改。

可编辑内容

基础信息（名称、URL、API Key）
调度参数（权重、优先级、分组标签）
启用状态
限流配置（RPM、并发数、成本限制）
超时配置
代理设置
模型重定向规则
熔断器配置

克隆供应商

点击供应商卡片右侧的复制图标可快速克隆一个供应商。克隆功能会复制原供应商的所有配置，您只需修改名称和 API Key 即可创建新供应商。

当您需要添加多个配置相似的供应商时，使用克隆功能可以节省大量时间。

启用与禁用

每个供应商卡片右侧有一个开关，用于快速启用或禁用供应商。

启用：供应商参与请求调度
禁用：供应商被排除在调度之外，但配置保留

禁用供应商不会影响已建立的会话。当前活跃的会话会继续使用该供应商，直到会话结束或超时。

删除供应商

点击供应商卡片右侧的删除图标（垃圾桶图标）可删除供应商。

删除供应商是软删除操作。历史日志数据会保留以供审计，但供应商将不再参与请求调度，且无法恢复。

删除确认对话框会显示即将删除的供应商名称，请仔细确认后再执行。

连接测试

供应商编辑表单中提供「测试连接」功能，用于验证供应商配置是否正确。该功能不仅验证连接是否可用，还提供详细的诊断信息。

基础验证项

API 端点是否可访问
API Key 是否有效
代理配置是否正确（如有配置）
响应延迟是否在可接受范围内
响应内容是否符合预期

预置检测模板

系统为不同类型的供应商预置了多套检测模板，这些模板模拟真实 CLI 客户端的请求特征：

Claude 类型供应商

模板	说明	默认模型	成功检测关键字
`cc_base`	Claude CLI 基础检测，速度快	claude-haiku-4-5-20251001	`isNewTopic`
`cc_sonnet`	Claude CLI Sonnet，使用消息级缓存	claude-sonnet-4-5-20250929	`pong`
`public_cc_base`	社区/公开 Claude，启用扩展思考	claude-sonnet-4-5-20250929	`pong`

Codex / OpenAI 兼容类型供应商

模板	说明	默认模型	成功检测关键字
`cx_base`	Codex CLI Response API 格式	gpt-5-codex	`pong`

cx_base 模板同时适用于 Codex 和 OpenAI 兼容类型的供应商。Gemini 类型供应商使用独立的请求格式，不使用预置模板。

客户端限制兼容性

重要说明

即使上游 API 配置了严格的客户端限制（仅允许官方 CLI 请求），检测功能依然可以正常工作。

这是因为检测请求完全模拟真实客户端的特征：

供应商类型	模拟的 User-Agent
Claude	`claude-cli/2.0.50 (external, cli)`
Codex	`codex_cli_rs/0.63.0`
Gemini	`GeminiCLI/v0.17.1 (darwin; arm64)`

除了 User-Agent，检测请求还包含：

完整的请求头特征（Accept、Accept-Language、Accept-Encoding 等）
真实 CLI 格式的请求体结构
标准的 metadata 字段（如 Claude 的 user_id）

因此，即使您使用的是仅对官方客户端开放的转发服务，检测功能也能正常验证连接状态。

三层验证机制

检测功能采用三层验证机制，确保供应商不仅能连接，而且性能达标：

第一层：HTTP 状态码验证

通过：2xx/3xx 状态码
失败：
- 401/403：认证错误（API Key 无效或权限不足）
- 429：请求频率限制
- 400：请求格式错误
- 5xx：服务端错误

第二层：延迟阈值验证

绿色：延迟低于阈值（默认 5000ms）
黄色：延迟超过阈值，供应商可用但性能降级

第三层：内容验证

检查响应体是否包含预期的关键字（如 pong 或 isNewTopic）
可通过模板默认值或自定义配置指定检测关键字

检测结果状态

状态	含义	建议操作
🟢 GREEN	所有验证通过，供应商健康	可正常使用
🟡 YELLOW	HTTP 正常但延迟过高	检查网络或降低该供应商优先级
🔴 RED	验证失败	检查配置或联系供应商

错误类型分类

当检测失败时，系统会对错误进行分类以帮助诊断：

错误类型	说明	常见原因
Timeout	请求超时	网络慢、供应商响应慢
DNS Error	DNS 解析失败	URL 配置错误、DNS 故障
Connection Refused	连接被拒绝	端口错误、服务未启动
Connection Reset	连接被重置	网络不稳定、防火墙
SSL/TLS Error	证书问题	证书过期、域名不匹配
Auth Error	认证失败	API Key 错误或过期
Rate Limit	频率限制	请求过于频繁

使用建议

建议在保存供应商配置前先进行连接测试，确保配置正确无误。

新增供应商时：先使用 cc_base（Claude）或 cx_base（Codex）进行快速验证
验证高级功能时：使用 cc_sonnet 测试提示缓存功能是否正常
自定义检测：如需特殊验证，可切换到自定义模式编写 JSON payload

熔断器管理

当供应商因连续错误触发熔断器后，列表中会显示红色的「已熔断」标签。

熔断状态

已熔断：供应商暂时被排除在调度之外，等待自动恢复
恢复中：熔断器处于半开状态，尝试有限的请求以验证恢复

手动重置

如果确认供应商已恢复正常，可以点击旋转图标手动重置熔断器，让供应商立即参与调度。

手动重置熔断器需谨慎操作。如果供应商仍存在问题，可能会导致请求失败并再次触发熔断。

调度规则说明

点击页面右上角的「调度规则」按钮，可查看系统选择供应商的详细逻辑。

核心调度逻辑

优先级优先：系统首先选择优先级最高（数值最小）的供应商组
权重分配：在同优先级组内，按权重比例随机分配请求
健康过滤：自动排除已禁用、已熔断的供应商
会话复用：5 分钟内的连续请求优先路由到同一供应商

使用场景

调度规则弹窗提供了多个实际场景示例，帮助您理解如何配置：

成本优先：如何配置主力供应商和备用供应商
用户分组：如何为不同用户组配置不同的供应商
高可用：如何配置多供应商实现故障转移
负载均衡：如何使用权重实现流量分配

供应商排行榜

点击页面右上角的「排行榜」按钮，可跳转到供应商维度的排行榜页面，查看各供应商的使用统计：

请求数量
Token 消耗
成本消费
使用趋势

操作权限

操作	管理员	普通用户
查看供应商列表	可以	不可以
创建供应商	可以	不可以
编辑供应商	可以	不可以
删除供应商	可以	不可以
测试连接	可以	不可以
重置熔断器	可以	不可以
查看 API Key	可以	不可以

供应商管理属于系统配置功能，仅管理员可访问。普通用户无法看到供应商管理页面。

最佳实践

配置建议

至少配置两个供应商：确保主供应商故障时有备用方案
合理设置优先级：将最稳定、性价比最高的供应商设为最高优先级
使用权重实现负载均衡：对于同等质量的供应商，通过权重分配流量
配置分组标签：便于管理和用户分组绑定
定期检查熔断状态：关注供应商健康状况，及时处理问题

故障排查

如果供应商不可用，请检查：

供应商是否已启用
API Key 是否正确且有效
URL 是否可访问（使用连接测试验证）
是否触发了熔断器
代理配置是否正确（如有使用代理）