配置用户模型白名单
什么时候用
需要限制用户可直接调用的模型时——模型白名单控制用户在不使用智能体的情况下，可以调用哪些模型。调用智能体时不受此限制，按智能体绑定的模型执行。
你需要准备
- 管理员权限
- 已创建的用户（见前面章节）
- 已配置好的模型（见「添加与配置模型」）
重要：白名单为空 = 全部拒绝（不是「全部允许」）。如果用户需要直接调用模型，请至少添加一个模型到白名单。
操作步骤
第 1 步：进入用户管理
左侧菜单 -> 用户管理。
在用户列表中找到要配置模型白名单的用户，点击右侧「更多」下拉菜单，选择「模型」。
第 2 步：配置模型白名单
在弹出的「模型管理」对话框中：
- 选择「自定义可用模型」单选按钮
- 在「选择可用模型」列表中，勾选要允许用户使用的模型
- 点击「确定」保存
模型列表显示格式：供应商名 - 模型显示名称。
提示：API 调用时使用界面显示的模型名（即创建模型时填写的显示名称）。请确保用户知道正确的模型名称。
第 3 步：清空模型白名单（可选）
如果想禁止用户直接调用任何模型（只允许通过智能体调用）：
- 在「模型管理」对话框中选择「不分配可用模型」单选按钮
- 点击「确定」保存
此时用户发起的任何非智能体模型调用都会返回 403 错误。
第 4 步：配置模型组白名单（可选）
除了单个模型，也可以配置模型组白名单：
- 在用户列表中点击用户的「更多」下拉菜单，选择「模型组」
- 在「模型组管理」对话框中选择「自定义可用模型组」
- 勾选要允许的模型组
- 点击「确定」保存
模型组在 API 调用时使用 group- 前缀加模型组名（如 group-客服组）作为模型名调用。
怎么验证成功了
- 使用该用户的 API Key 调用
/openai/v1/models，返回的模型列表应与白名单一致 - 使用白名单内的模型调用（不走智能体调用路径，直接调模型），能正常返回
- 使用白名单外的模型调用，应返回 403 错误
常见问题
配置了白名单但调用还是返回 403
请检查：
- 白名单不为空（空 = 全部拒绝）
- 调用时使用的模型名称与界面显示的模型名完全一致（区分大小写）
- 模型状态为「启用」
- 调用时没有指定智能体（指定了走智能体路径，不走白名单）
白名单为空时用户完全不能用模型吗？
用户仍然可以通过智能体调用模型。白名单仅限制未指定智能体的调用。
管理员可以豁免白名单限制吗？
不可以。所有人（包括平台管理员、管理员）都受模型白名单约束。
配置了模型组白名单，怎么调用？
在调用时使用 group- 前缀加模型组名（如 group-客服组）作为模型名即可走模型组路由。
模型白名单和模型组白名单可以同时配置吗？
可以。用户可以调用白名单内的单个模型，也可以调用白名单内的模型组。
深入
核心概念
模型白名单机制
模型白名单只决定用户在非智能体路径下可使用哪些模型：白名单为空列表 = 全部拒绝（不是「允许全部」），此时会返回权限错误。
智能体路径只看智能体绑定（未绑定才回退租户默认）；非智能体路径只看用户白名单；平台管理员、租户管理员都不豁免。
模型访问鉴权（重点）
模型访问权限由调用上下文决定，分为两种路径：
智能体路径（请求中带了智能体）
权限判断顺序：
- 智能体绑定模型组：仅允许该模型组候选（按路由策略选择）
- 智能体绑定模型：仅允许该模型
- 智能体未绑定：回退租户默认模型组；再回退默认模型
- 都没有：返回服务不可用
- 用户模型白名单不参与智能体路径的判断
- 智能体绑定的模型可以是当前用户白名单里没有的
非智能体路径（请求中没有智能体）
权限判断：
- 检查请求的模型是否在用户的模型白名单中
- 白名单包含 → 通过
- 白名单为空 → 直接返回权限错误
- 不会回退到租户默认模型
- 必须显式传模型，且该模型必须在用户白名单内
- 空白名单 = 全部拒绝
谁可以豁免
没有人可以豁免。 平台管理员、租户管理员都不例外。模型鉴权是对所有用户的硬约束。
公开模型列表
返回当前用户可用的模型列表，其内容为当前用户白名单中的模型和已绑定到智能体的模型的并集。如果任一智能体未绑定模型，还会包含租户默认模型/默认模型组。
权限边界
| 操作 | 谁可以 |
|---|---|
| 分配模型白名单 | 租户管理员 |
| 调用某模型（智能体路径） | 智能体绑定模型/模型组，或租户默认模型/默认模型组 |
| 调用某模型（非智能体路径） | 必须在用户模型白名单中 |
| 查看公开模型列表 | 有有效 API Key 的任何用户（仅看到自己有权限的模型） |
| 访问其它租户的模型 | 无法访问（隔离） |
常见坑
白名单为空 → 权限错误，不是「全部允许」
这是最常见的误解。空数组 = 全部拒绝，不是「不做限制」。如果用户一个模型都没有分配，所有非智能体路径的调用都会失败。
智能体路径不走白名单
智能体绑定模型后，即使该模型不在用户白名单中，智能体路径也能正常使用。但非智能体路径仍然检查白名单。
管理员没有豁免权
即使你是租户管理员，调用聊天 API 时依然受模型鉴权约束。管理员在界面上操作没问题，但通过 SDK 调用同样需要 API Key 和模型权限。
排错速查
| 症状 | 可能原因 | 排查路径 |
|---|---|---|
| 调用 API 返回权限错误 | 模型不在白名单 / 白名单为空 | 检查用户模型白名单配置 |
| 调用 API 返回服务不可用 | 智能体未绑模型/模型组 + 无租户默认模型/默认模型组 | 给智能体绑定模型/模型组，或设置租户默认模型/默认模型组 |
- 想了解如何创建用户？见 创建用户并分配智能体
- 想了解如何添加和配置模型？见 添加与配置模型
- 想了解如何创建模型组？见 模型组：多模型路由