供应商字段详解

本文档详细说明 Claude Code Hub 供应商（Provider）的所有配置字段，包括字段类型、默认值、取值范围和使用场景。这是管理员配置供应商时的核心参考文档。

字段分类概览

供应商配置字段按功能分为以下几类：

基础字段

基础字段定义供应商的核心标识和连接信息。

字段说明

供应商类型（providerType）

配置示例

{
  "name": "官方 Claude API",
  "url": "https://api.anthropic.com",
  "key": "sk-ant-api03-xxx...",
  "providerType": "claude",
  "isEnabled": true,
  "websiteUrl": "https://console.anthropic.com"
}

调度相关字段

调度字段控制系统如何选择供应商处理请求，是实现智能负载均衡的核心。

字段说明

调度算法说明

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

权重（weight）

权重决定了同优先级供应商之间的流量分配比例：

供应商A (weight=70) + 供应商B (weight=30)
-> A 获得 70% 流量，B 获得 30% 流量

数值越大，被选中的概率越高。

优先级（priority）

数值越小，优先级越高。系统优先选择优先级最高的供应商组。

优先级用于实现主备切换和故障转移：

排序算法（v0.3.33 可视化）：

1. 首先按 priority 升序排列（数值越小越优先）
2. 然后在同 priority 内按 weight 降序排列（数值越大越优先）

成本系数（costMultiplier）

成本系数用于调整供应商的计费计算，常见场景：

• 中转站优惠：设为 0.8 表示 8 折计费
• 溢价供应商：设为 1.2 表示 120% 成本
• 内部渠道：设为 0 表示免费（不计入成本统计）

分组标签（groupTag）

供应商所属的分组标签，支持多标签格式（逗号分隔）。

格式示例：

• 单标签：cli
• 多标签：cli,chat,premium

匹配规则：

与用户或 Key 的 providerGroup 进行交集匹配。只要存在一个共同标签，即视为匹配成功。

使用场景：

• 用户隔离：不同用户组使用不同供应商池
• 资源分配：VIP 用户使用高优供应商
• 成本控制：按部门分配不同供应商

严格隔离策略：

当用户或 Key 配置了 providerGroup 后，系统启用严格隔离策略：

• 只有标签匹配的供应商可以被选中
• 未设置 groupTag 的供应商会被拒绝

配置示例

{
  "name": "主力供应商",
  "weight": 80,
  "priority": 0,
  "costMultiplier": 1.0,
  "groupTag": "production"
}

限制字段

限制字段用于控制供应商的并发使用和成本消耗。

字段说明

并发限制（limitConcurrentSessions）

控制同时活跃的会话数量，防止单供应商过载：

• 0：不限制并发
• 正整数：最大允许的同时活跃会话数

成本限制时间窗口

每日重置模式（dailyResetMode）

配置示例

{
  "limitConcurrentSessions": 50,
  "limit5hUsd": 100,
  "limitDailyUsd": 500,
  "dailyResetMode": "fixed",
  "dailyResetTime": "00:00",
  "limitWeeklyUsd": 2000,
  "limitMonthlyUsd": 8000
}

超时配置

超时配置用于控制与上游供应商的请求超时行为。

字段说明

流式首字节超时（firstByteTimeoutStreamingMs）

控制从发起请求到收到首个响应字节的最大等待时间：

• 作用：解决流式请求启动缓慢问题
• 场景：供应商响应延迟过高时快速切换
• 推荐值：30000（30 秒）

流式空闲超时（streamingIdleTimeoutMs）

控制流式响应中两次数据块之间的最大间隔：

• 作用：解决流式中途卡住问题
• 场景：检测供应商中途无响应
• 推荐值：60000（60 秒）
• 最小值：如果配置，最少为 60 秒

非流式总超时（requestTimeoutNonStreamingMs）

控制非流式请求的总处理时间：

• 作用：防止长请求无限挂起
• 场景：count_tokens 等非流式 API
• 推荐值：120000（2 分钟）

配置示例

{
  "firstByteTimeoutStreamingMs": 30000,
  "streamingIdleTimeoutMs": 60000,
  "requestTimeoutNonStreamingMs": 120000
}

代理配置

代理配置用于通过 HTTP/HTTPS/SOCKS 代理访问上游供应商。

字段说明

代理 URL 格式

支持以下代理协议：

降级直连（proxyFallbackToDirect）

当代理连接失败时的处理策略：

• false（默认）：代理失败直接返回错误
• true：代理失败后尝试直接连接

配置示例

{
  "proxyUrl": "http://192.168.1.100:7890",
  "proxyFallbackToDirect": true
}

IP 透传配置

IP 透传功能用于将客户端真实 IP 地址传递给上游供应商。

字段说明

工作原理

启用 IP 透传后，系统会在转发请求时添加以下 HTTP 头：

• x-forwarded-for：包含客户端 IP 的转发链
• x-real-ip：客户端的真实 IP 地址

默认情况下，系统会移除所有客户端 IP 相关的请求头以保护用户隐私。启用此选项后，这些头部会被保留并传递给上游供应商。

IP 解析优先级

系统按以下优先级从请求头中解析客户端 IP：

配置示例

{
  "preserveClientIp": true
}

模型配置

模型配置用于控制模型名称映射和访问限制。

字段说明

模型重定向（modelRedirects）

将请求中的模型名称映射到实际模型：

{
  "modelRedirects": {
    "claude-3-5-sonnet-20241022": "claude-3-5-sonnet-latest",
    "gpt-4": "claude-3-opus-20240229"
  }
}

使用场景：

• 模型名称规范化
• 模型版本升级过渡
• 跨平台模型映射

允许模型列表（allowedModels）

根据供应商类型有不同语义：

{
  "allowedModels": [
    "claude-3-5-sonnet-20241022",
    "claude-3-opus-20240229",
    "claude-3-haiku-20240307"
  ]
}

• null 或空数组：不限制（允许所有模型）

加入 Claude 调度池（joinClaudePool）

joinClaudePool 用于让非 Claude 类型供应商在“用户请求 claude-* 模型”时也能参与候选选择。

它的生效条件与约束：

• 仅对 providerType != claude/claude-auth 的供应商有意义
• 仅当 modelRedirects 中存在“重定向目标以 claude- 开头”的映射时，管理后台才会显示该开关
• 启用后，调度器会在用户请求 claude-* 模型时，将该供应商纳入候选集（并依赖 modelRedirects 进行模型名适配）

{
  "providerType": "openai-compatible",
  "joinClaudePool": true,
  "modelRedirects": {
    "claude-sonnet-4-20250514": "claude-3-5-sonnet-20241022"
  }
}

Codex 特殊配置

针对 Codex 类型供应商的专属配置。

字段说明

配置示例

{
  "providerType": "codex",
  "codexReasoningEffortPreference": "inherit",
  "codexReasoningSummaryPreference": "inherit",
  "codexTextVerbosityPreference": "inherit",
  "codexParallelToolCallsPreference": "inherit"
}

MCP 透传配置

MCP（Model Context Protocol）透传功能用于增强模型能力。

字段说明

MCP 透传类型

配置示例

{
  "mcpPassthroughType": "minimax",
  "mcpPassthroughUrl": "https://api.minimaxi.com"
}

1M 上下文窗口配置

1M 上下文窗口是 Anthropic 提供的大容量上下文功能，允许模型处理最多 100 万 token 的上下文内容。此功能通过供应商级别的配置进行控制。

字段说明

配置选项（context1mPreference）

支持的模型

1M 上下文窗口功能仅支持以下模型前缀：

分层定价

使用 1M 上下文窗口时，超过 200k token 的部分会按溢价计费：

工作原理

1. 客户端请求：客户端通过 anthropic-beta: context-1m-2025-08-07 请求头申请启用 1M 上下文
2. 供应商过滤：路由选择器会自动过滤掉设置为 disabled 的供应商
3. 请求转发：对于 inherit 或 force_enable 的供应商，系统会在转发请求时添加相应的 beta 头部

配置示例

{
  "context1mPreference": "inherit"
}

强制启用示例（适用于需要保证长上下文支持的供应商）：

{
  "context1mPreference": "force_enable"
}

禁用示例（适用于成本敏感或不支持 1M 上下文的中转站）：

{
  "context1mPreference": "disabled"
}

熔断器配置

熔断器用于隔离故障供应商，防止级联失败。

字段说明

熔断器状态

CLOSED（正常）
    ↓ 连续失败达到阈值
  OPEN（熔断）
    ↓ 等待 openDuration 后
HALF-OPEN（试探）
    ↓ 连续成功达到阈值 → CLOSED
    ↓ 发生失败 → OPEN

参数说明

• 失败阈值（failureThreshold）：越小越敏感，越容易触发熔断
• 熔断时长（openDuration）：建议 30 分钟（1800000ms），避免频繁探测
• 恢复阈值（halfOpenSuccessThreshold）：建议 2-3 次，确保真正恢复

配置示例

{
  "circuitBreakerFailureThreshold": 5,
  "circuitBreakerOpenDuration": 1800000,
  "circuitBreakerHalfOpenSuccessThreshold": 2
}

元数据字段

系统自动管理的时间戳和软删除字段。

字段说明

软删除说明

• 删除供应商时设置 deletedAt 为当前时间
• 已删除的供应商不参与调度
• 历史日志仍可关联到已删除供应商
• 软删除数据不可恢复

废弃字段

以下字段已废弃，保留仅为向后兼容，不再生效：

完整配置示例

以下是一个典型供应商的完整配置示例：

{
  "name": "主力 Claude API",
  "url": "https://api.anthropic.com",
  "key": "sk-ant-api03-xxx...",
  "providerType": "claude",
  "isEnabled": true,
  "websiteUrl": "https://console.anthropic.com",

  "weight": 70,
  "priority": 0,
  "costMultiplier": 1.0,
  "groupTag": "production",

  "limitConcurrentSessions": 50,
  "limit5hUsd": 100,
  "limitDailyUsd": 500,
  "dailyResetMode": "fixed",
  "dailyResetTime": "00:00",
  "limitWeeklyUsd": 2000,
  "limitMonthlyUsd": 8000,

  "firstByteTimeoutStreamingMs": 30000,
  "streamingIdleTimeoutMs": 60000,
  "requestTimeoutNonStreamingMs": 120000,

  "proxyUrl": null,
  "proxyFallbackToDirect": false,

  "preserveClientIp": false,

  "modelRedirects": {
    "claude-3-5-sonnet-20241022": "claude-3-5-sonnet-latest"
  },
  "allowedModels": null,

  "circuitBreakerFailureThreshold": 5,
  "circuitBreakerOpenDuration": 1800000,
  "circuitBreakerHalfOpenSuccessThreshold": 2
}

相关文档

• 供应商管理 - 供应商管理页面操作指南
• 高可用机制 - 熔断器和故障转移详解
• 限流配置 - 多维度限流机制说明
• 用户管理 - 用户分组与供应商绑定