LobeChat 接入自定义 API：OpenAI 兼容配置与部署（2026）

LobeChat 是开源的 AI 对话应用，支持多模型、多助手、插件和知识库。它既可以一键部署到云端，也可以用自己的服务器运行。接入自定义 API 有两条路：在界面里填服务商信息，或者用环境变量在部署时写死。前者适合个人电脑，后者适合团队和长期运行。

本文以 2026 年 10 月的常见版本为例，讲清参数准备、Docker 部署、环境变量、界面配置和排错。

说明：LobeChat、LobeHub 是其权利人的产品，OpenAI 是其权利人的商标，本文仅作技术接入说明。环境变量名称和界面入口可能随版本调整，以当前版本官方文档为准；模型与价格以站内模型价格为准。

一、三种接入方式怎么选

方式	适合场景	配置位置	优点
界面配置	个人使用、快速试用	设置里的 AI 服务商	改完即生效，不用重启
Docker 环境变量	自建服务器、团队共用	`docker run` 或 compose	可版本化、可复制
云平台环境变量	Vercel 等托管部署	项目环境变量设置	免运维，适合小团队

个人电脑建议先用界面配置跑通，再迁移到 Docker；团队部署建议直接用环境变量，把 Key 和地址放进密钥管理，不要写进代码仓库。

二、准备三项参数

API Key：在中商起航 AI 网关创建，按项目或环境命名。
Base URL：https://ai.zhongshangqihang.com/v1，这是 OpenAI 兼容入口。
模型 ID：从模型价格页复制，注意是 API 标识而不是展示名。

先用 curl 验证，避免把网关问题误判成 LobeChat 配置问题：

export ZSQH_API_KEY="sk-你的密钥"

curl "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，说明三件事都有效，可以进入部署环节。

三、Docker 部署

最简方式是用官方镜像起一个容器，把 Key、代理地址和模型列表通过环境变量传入：

docker run -d --name lobechat \
  -p 3210:3210 \
  -e OPENAI_API_KEY="sk-你的密钥" \
  -e OPENAI_PROXY_URL="https://ai.zhongshangqihang.com/v1" \
  -e CUSTOM_MODELS="-all,+your-model-id" \
  lobehub/lobe-chat

启动后访问 http://服务器地址:3210。几个参数的含义：

OPENAI_API_KEY：网关 Key，建议通过环境变量或密钥管理注入，不要写在公开的 compose 文件里。
OPENAI_PROXY_URL：覆盖默认的 OpenAI 地址，指向你的兼容网关。
CUSTOM_MODELS：控制模型列表，-all 表示先清空默认列表，+模型ID 表示加入一个模型。

如果使用 Docker Compose，把同样的变量写进 environment 段即可。改完变量后要重建容器，单纯重启不一定加载新环境。

四、环境变量与模型列表

变量	是否必需	示例	说明
`OPENAI_API_KEY`	是	`sk-...`	网关创建的 Key
`OPENAI_PROXY_URL`	是	`https://ai.zhongshangqihang.com/v1`	覆盖默认 Base URL
`CUSTOM_MODELS`	建议	`-all,+model-a,+model-b`	控制可见模型
`OPENAI_MODEL_LIST`	视版本	`+model-a`	旧版本可能使用该名称

CUSTOM_MODELS 的语法要点：

+模型ID 添加模型，-模型ID 隐藏模型。
-all 先清空默认列表，避免出现一堆无法调用的模型。
用英文逗号分隔，不要加空格。
改名可以用 模型ID=显示名，但不要改模型 ID 本身。

不同版本对变量名和语法的支持不完全一样，旧版本可能用 OPENAI_MODEL_LIST。升级后如果模型列表消失，先查当前版本的文档，不要照旧教程硬套。

五、在界面里配置

如果不想改环境变量，可以在界面里配置。以当前常见版本为例：

打开 LobeChat，进入设置。
找到“AI 服务商”或“语言模型”。
选择 OpenAI，填入 API Key 和代理地址。
在模型列表里添加自定义模型 ID。
保存后新建对话，选择该模型测试。

界面配置适合本机使用。部署到服务器后，浏览器里保存的配置属于当前用户，换设备或清缓存后可能要重配；团队共用应优先用环境变量。

六、验证与反向代理

容器启动后，先看日志确认没有环境变量错误：

docker logs -f lobechat

然后在界面发一条消息测试。如果部署在公网，建议在前面加 Nginx 或 Caddy，至少做三件事：

配置 HTTPS，不要用明文 HTTP 传 Key。
设置访问控制，避免应用直接暴露给所有人。
配置超时和缓冲，流式响应需要关闭代理缓冲。

Nginx 处理流式响应时，常见配置是关闭 proxy_buffering，并适当延长读超时。否则表现为“回答一次性蹦出来”或“中途卡住”。

七、生产部署清单

用密钥管理或环境变量注入 Key，不写进镜像。
给 LobeChat 单独发一把 Key，方便限额和吊销。
配置数据库，否则会话和配置可能只存在本地。
开启 HTTPS 和访问控制，公网部署不要裸奔。
设置网关预算和并发上限，防止异常循环消耗额度。
定期备份数据库和上传文件。
升级前看 changelog，镜像固定版本标签，不要长期用 latest。

八、常见报错与处理

现象	常见原因	处理
启动后没有模型	`CUSTOM_MODELS` 未生效	检查变量名、逗号和容器是否重建
`401 Unauthorized`	Key 未注入或失效	进容器确认环境变量，重新创建 Key
`404 Not Found`	代理地址路径不对	核对 `/v1`，必要时增减结尾
`model not found`	模型 ID 与价格页不一致	复制准确标识
回答中途卡住	反向代理缓冲或超时	关闭缓冲，延长读超时
上传文件失败	存储或模型能力未配置	检查存储配置与模型能力
知识库不可用	嵌入模型未配置	单独配置可用的嵌入模型

排错时先分清楚是“应用没读到配置”还是“网关拒绝了请求”。前者看容器环境变量和日志，后者看 HTTP 状态码。两者的处理方式完全不同。

常见问题

LobeChat 是免费的吗？

LobeChat 是开源项目，可以自行部署；模型调用费用由你接入的 API 服务商收取。托管服务和增值功能的价格以官方为准。

一定要用 Docker 吗？

不一定。也可以用 Node.js 运行，或部署到支持 Next.js 的云平台。Docker 的好处是环境一致、迁移方便，团队部署更常见。

`OPENAI_PROXY_URL` 和界面里的代理地址有什么区别？

环境变量在部署层生效，适合团队统一配置；界面配置属于当前用户，换设备后可能要重配。两者同时存在时，以当前版本的优先级为准。

为什么模型列表里出现了用不了的模型？

多半是没有用 -all 清空默认列表，或者 CUSTOM_MODELS 语法写错。先只保留一个确认可用的模型，跑通后再加。

能接 Claude 或 Gemini 吗？

可以，前提是网关以 OpenAI 兼容格式提供对应模型，并且模型 ID 正确。原生协议不同的能力，例如某些工具调用或图片参数，需要实际测试，以站内文档为准。

下一步

LobeChat 的接入可以拆成两步：先用 curl 确认网关可用，再用环境变量或界面把 Base URL、Key、模型三处对齐。团队部署优先用环境变量，个人试用优先用界面。需要统一模型入口和用量管理，可以注册中商起航 AI 网关，模型与价格以模型价格页为准。