模型白名单

模型白名单是 Claude Code Hub 的核心访问控制功能，允许管理员限制特定用户或供应商可以访问的 AI 模型。该功能支持两个独立的控制层级：用户级白名单和供应商级白名单。

用户级模型白名单

用户级白名单由 ProxyModelGuard 在请求管道中执行，控制单个用户可以请求哪些模型。

基本行为

匹配规则

• 大小写不敏感：claude-3-opus 可匹配 Claude-3-Opus
• 精确匹配：不支持通配符或模式匹配
• 完整名称：claude-3-opus-20240229 必须完整列出

错误响应

当用户配置了白名单但请求不符合要求时：

供应商级模型白名单

供应商级 allowedModels 字段具有双重语义，根据供应商类型有不同含义。

Anthropic 供应商（claude, claude-auth）

作为白名单使用，限制供应商可以提供哪些 Claude 模型：

非 Anthropic 供应商（codex, gemini, gemini-cli, openai-compatible）

作为声明列表使用，声明供应商支持哪些模型：

请求管道位置

模型白名单检查在请求处理管道的特定位置执行：

认证 -> 敏感词检测 -> 客户端限制 -> [模型白名单] -> 版本检查 -> ... -> 供应商选择

这确保：

1. 用户已通过认证后才检查模型权限
2. 无效模型在供应商选择前被拒绝
3. 速率限制在模型验证后执行

配置方法

用户白名单配置

在用户管理界面的「访问限制」部分配置：

• 支持标签式输入模型名称
• 最多配置 50 个模型
• 每个模型名称最长 64 字符
• 支持从供应商配置获取模型建议

供应商白名单配置

在供应商设置的「路由配置」部分配置：

• 使用模型多选组件选择允许的模型
• 支持手动输入模型名称
• 根据供应商类型显示不同的帮助文本

配置示例

限制用户使用特定模型

{
  "userId": 123,
  "allowedModels": ["claude-3-opus-20240229", "claude-3-sonnet-20240229"]
}

用户只能请求这两个特定版本的 Claude 模型。

限制 Anthropic 供应商的模型

{
  "providerId": 456,
  "providerType": "claude",
  "allowedModels": ["claude-3-opus-20240229", "claude-3-sonnet-20240229"]
}

该供应商只能提供这两个模型，即使上游支持更多。

声明 OpenAI 兼容供应商支持的模型

{
  "providerId": 789,
  "providerType": "openai-compatible",
  "allowedModels": ["gpt-4", "gpt-4-turbo", "gpt-3.5-turbo"]
}

声明该供应商支持这些模型，用于路由选择。

交互行为

与模型重定向的交互

模型重定向在白名单检查之后执行：

1. 用户请求 claude-3-opus
2. 模型守卫验证 user.allowedModels
3. 供应商选择找到合适的供应商
4. 模型重定向可能将请求改为其他模型
5. 上游收到重定向后的模型名称

与供应商分组的交互

模型白名单与供应商分组独立工作：

• 用户的 allowedModels 限制可请求的模型
• 供应商的 allowedModels 限制可提供的模型
• 两者的交集决定实际可用性

示例：

• 用户白名单：["claude-3-opus", "claude-3-sonnet"]
• 供应商 A 白名单：["claude-3-opus"]
• 供应商 B 白名单：["claude-3-sonnet", "claude-3-haiku"]
• 结果：用户可通过供应商 A 访问 opus，通过供应商 B 访问 sonnet

count_tokens 端点

模型白名单同样适用于 /v1/messages/count_tokens 端点，确保所有 API 端点的访问控制一致。

注意事项

跨类型代理支持

供应商级 allowedModels 支持跨类型代理场景：

• Claude 类型供应商可通过 allowedModels 或 modelRedirects 声明支持非 Claude 模型
• 这允许将 gemini-* 请求通过配置了模型重定向的 Claude 供应商路由

相关文档

• 智能路由算法 - 了解供应商选择的完整流程
• 供应商管理 - 了解供应商配置界面
• 用户管理 - 了解用户配置界面