令牌、模型配置、IP 白名单：403 的三个来源
令牌决定可用范围的三处设置：绑定的模型配置（能用哪些模型）、IP 白名单（从哪些地址能调用）、以及有效期与状态；任何一项不满足都会返回 401 或 403。
更新于 2026-11-14 · SageLib 团队 · 标签：token、permission、403
结论要点
- 密钥只在创建时显示一次，丢了只能删除重建
- 模型不在令牌的模型配置里 → 403
- IP 白名单留空表示不限制，不要填 []
令牌不只是「一串密钥」，它还带着三处范围限制。
一、密钥本身
- 创建后只显示一次，关闭弹窗就看不到完整密钥；
- 状态分「启用 / 禁用」，可设置有效期；
- 401 的四种错误体：
missing api key、invalid key format、invalid or disabled api key、api key expired。
二、模型配置（决定能用哪些模型）
新建令牌时必须选用一个模型配置：里面勾选的模型才是这把 Key 的可用范围。
请求不在范围内的模型 → 403 model … is not allowed for this api key。
所以「模型广场里有这个模型，但我的 Key 调不了」几乎都是这一条。
三、IP 白名单（决定从哪能调用）
- 留空 = 不限制；
- 填了 IP/网段才生效；同一把 Key 从白名单外调用 → 403；
- 企业用户还要留意令牌组、模型配置上的 IP 访问控制，规则取交集。
快速自检清单
- 认证头对不对（Bearer / x-api-key / x-goog-api-key）；
- 密钥有没有被禁用、过期、删掉；
- 令牌的模型配置里有没有这个模型；
- IP 白名单是否包含当前出口 IP；
- 模型是否已下架（
model_offline）。
参考来源
常见问题
为什么新建的令牌调用报 403？
最常见是没有绑定模型配置，或绑定的配置里没有你请求的那个模型。
IP 白名单填错了怎么救？
把白名单留空即表示不限制；填了格式不对的值（如 []）会直接命中「规则配置错误」。