LobeChat API Key 配置教程：多模型、环境变量与安全（2026）

LobeChat 把多个模型服务商放进同一个界面，用起来方便，但 Key 的管理常被忽略：谁建的、能调用哪些模型、存在浏览器还是数据库、备份会不会带走、成员离职后是否还有效。本文按创建、配置、存储、轮换、团队策略和排查的顺序，给出一套可执行的做法。

说明：LobeChat、LobeHub 是其权利人的产品与商标，OpenAI 是 OpenAI, Inc. 的商标。本文仅作技术说明，与上述公司无隶属或合作关系。界面、变量名与存储方式随版本调整，以当前官方文档为准；模型与价格以站内模型价格页为准。

一、先分清三种 Key

“LobeChat API Key”经常指三样不同的东西：

账号或平台凭证：用于登录 LobeHub Cloud 或企业平台，权限由平台决定。
模型厂商 Key：由 OpenAI、Anthropic、Google 等签发，填进对应服务商。
网关 Key：由 OpenAI 兼容网关签发，一把 Key 可调用多家模型。

本文讲第三类，也适用于你填入 LobeChat 的其他厂商 Key。网关 Key 不用于登录，也不能调用客户端厂商的私有接口；配置时要选 OpenAI 兼容入口或自定义服务商，而不是把 Key 填进某个厂商的专用字段。

二、创建 Key：先定用途和上限

不要先建 Key 再想给谁用。顺序反过来，后面省很多事：

打开中商起航 AI 网关注册页，完成注册并登录控制台。
进入 API 密钥页面，新建密钥。
名称写清使用者、环境和用途，例如 lobe-team-prod，不要用 test。
设置额度上限和到期时间；支持模型范围时，按项目限制可用模型。
确认账户余额，避免配置完成后才发现无法调用。
复制 Key 存入密码管理器，不要先发到群聊、文档或工单。

建好后先用命令行确认 Key、地址和模型三者是通的：

export ZSQH_API_KEY="sk-你的密钥"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"你的模型ID","messages":[{"role":"user","content":"只回复 OK"}]}'

返回中有 choices 字段，说明请求链路正常。若报 401，先查 Key；报 404，先查 /v1 路径；报模型不存在，先核对模型 ID。

三、服务端环境变量与用户级配置

LobeChat 的 Key 可以放在两个层级，作用完全不同：

层级	配置位置	作用范围	适合
服务端环境变量	部署环境、`lobehub.env`、密钥管理	全实例共享	团队统一入口、默认模型
用户级服务商配置	登录后的设置界面	单个账号	个人自带 Key、临时试用
网关侧 Key	网关控制台	按 Key 计量	限额、审计、吊销

服务端的 OPENAI_API_KEY 是共享 Key，能使用该实例的人都可以调用。用户也可以在设置里填自己的 Key；服务端数据库模式下，用户 Key 加密后写入数据库，加密依赖 KEY_VAULTS_SECRET。这个变量丢失后，已存的用户 Key 可能无法解密，部署时就要备份好。

常见的服务端变量包括：

OPENAI_API_KEY：共享的网关 Key。
OPENAI_PROXY_URL：覆盖默认的 OpenAI 地址，指向兼容网关。
OPENAI_MODEL_LIST：控制模型列表，不授予额外权限。
KEY_VAULTS_SECRET：加密数据库中的用户 Key 与代理地址。
AUTH_SECRET：会话与认证相关，需单独生成。
DATABASE_URL：PostgreSQL 连接串，服务端模式必需。

不要把同一把 Key 同时写进环境变量和用户配置，除非你清楚哪一层会生效。排错时先确认请求用的是哪把 Key，再看网关日志。

四、多模型与多服务商怎么配

OPENAI_MODEL_LIST 的语法是：+ 添加、- 隐藏、模型ID=展示名<能力> 自定义展示与能力，英文逗号分隔。例如：

-all,+model-a=日常问答<128000:fc:vision>,+model-b=长文分析<200000:reasoning>

尖括号里第一项是最大上下文，后面是能力标签，常见有 fc（函数调用）、vision（视觉）、file（文件）、reasoning（推理）、search（联网搜索）。标签要按模型真实能力填，填错不会立刻报错，但会在插件或图片任务里失败。

多服务商配置的原则是“一个上游端点一套配置”：

同一个网关只建一个服务商条目，用模型列表区分用途。
不同网关或不同环境各建条目，名称带环境后缀。
每个条目使用独立的 Key，便于分别限额和吊销。
不要为显得模型多而复制同一把 Key，账目会乱。

模型列表只决定界面显示，真正的权限在网关侧。要限制 Key 可调用的模型，应在控制台设置，而不是依赖前端隐藏。

五、Key 存在哪里，哪些地方会泄露

按部署方式分：

本机或浏览器模式：配置保存在浏览器本地存储，换设备或清缓存后可能消失。公用电脑不要保存长期 Key。
服务端数据库模式：用户 Key 加密后写入 PostgreSQL，加密依赖 KEY_VAULTS_SECRET。数据库备份里是密文，但密钥文件本身必须单独保管。
环境变量文件：lobehub.env 是明文，权限设为仅服务账号可读，不进 Git，不随镜像分发。
S3 与备份：S3 存的是文件和知识库资料，通常不含 Key；数据库备份和部署配置则可能间接包含敏感信息。

还要注意截图、工单和聊天记录。很多泄露不是数据库被攻破，而是 Key 被贴错了地方。

六、轮换与吊销

建议每 90 天轮换一次，或在成员离职、设备丢失、疑似泄露时立即执行。顺序是“先建新、再切换、后禁用”：

新建权限相同的新 Key，名称加日期后缀。
更新 lobehub.env 或用户级服务商配置，逐个检查条目。
重启或重建服务，发一条测试请求。
在网关日志确认新 Key 有调用记录，旧 Key 没有新增流量。
观察一段时间的错误率和用量，确认没有遗漏的脚本或设备。
禁用旧 Key，保留记录一段时间后再删除。

不要先删旧 Key 再配新 Key，中间会出现无法调用的窗口。若怀疑泄露，先禁用止损，再查异常用量和调用来源。

七、团队策略：一人一 Key，环境分开

一人一 Key，一用途一 Key；自动化任务单独建 Key。
开发、测试、生产各用独立 Key，避免测试流量污染生产账目。
能设额度、到期时间和模型范围就都设上，至少设前两项。
共享的服务端 Key 只用于默认入口，额度要保守，异常时容易发现。
维护台账：只记 Key 名称、持有人、用途、创建与到期时间，不记完整 Key。
每月检查长期未用的 Key、超额 Key 和鉴权失败异常。
把 Key 的创建、交接、禁用写进入职和离职流程。
规定哪些数据允许进入云端模型，敏感项目先评估再使用。
定期复核模型价格，价格和可用模型会调整。

团队再小，也建议保留“谁申请、谁使用、何时失效”的记录。出事时能快速定位。

八、故障排查

现象	常见原因	处理
`401 Unauthorized`	Key 错误、被禁用或带空格	重新复制，确认 Key 属于当前网关
`403 Forbidden`	额度用完、权限不足或模型范围受限	到控制台查额度与模型权限
`404 Not Found`	API 地址路径不对	只保留到 `/v1`
`429 Too Many Requests`	触发限流或达到额度上限	查用量与并发设置
`model not found`	模型 ID 错误或未开通	从价格页复制准确标识
用户 Key 突然失效	`KEY_VAULTS_SECRET` 变更或缺失	恢复原密钥，重新填写用户 Key
curl 正常、界面失败	配置未保存、浏览器缓存或网络代理	重新保存并检查代理

排查时先分清是“应用没读到配置”还是“网关拒绝了请求”：前者看环境变量、数据库和日志，后者看 HTTP 状态码。

常见问题

LobeChat 的 API Key 存在浏览器还是服务器？

取决于部署方式。浏览器或本机模式保存在本地存储；服务端数据库模式下，用户 Key 加密后写入 PostgreSQL，服务端环境变量里的共享 Key 则以明文存在于部署环境。

服务端配置了 `OPENAI_API_KEY`，用户还要填吗？

不需要。服务端 Key 是共享的，实例内用户可直接调用。用户也可以填自己的 Key，用于独立额度或不同服务商，优先级以当前版本为准。

一把 Key 能调用多个模型吗？

通常可以，只要网关允许该 Key 调用这些模型。模型列表只控制显示，真正的权限和额度在网关控制台设置。

修改 `KEY_VAULTS_SECRET` 会有什么影响？

已加密的用户 Key 和代理地址可能无法解密，表现为用户 Key 突然失效。变更前先备份并查阅当前版本的迁移说明，不要随意更换。

Key 泄露后最先做什么？

先禁用或删除 Key 止损，再查异常用量、调用来源和时间段。之后检查环境变量文件、数据库备份、仓库、聊天记录和截图，必要时轮换同一环境的其他凭证。

小结

LobeChat 的 Key 配置不复杂，难的是长期管理：名称可追溯、额度有上限、存储有保护、备份有边界、泄露能止损。可以先注册中商起航 AI 网关建一把客户端专用 Key，跑通后再按团队策略收紧，并结合模型价格定期复核成本。