LobeChat 接入自定义 API 教程：Base URL、Key 与模型（2026）

LobeChat 是开源的 AI 对话应用，现在项目与镜像逐步改用 LobeHub 这个名字。它本身不提供模型，回答质量取决于你接入的 API 服务商。对使用统一网关的团队来说，接入自定义 API 的价值很直接：一个 Base URL、一把 Key，就能在多模型之间切换，用量也集中在一个地方看。

本文按 2026 年常见版本，从部署方式讲到服务商配置、连通性验证，再到助手、插件、知识库和团队部署。界面与变量名会随版本变化，动手前先对照当前版本文档。

说明：LobeChat、LobeHub 是其权利人的产品与商标，OpenAI 是 OpenAI, Inc. 的商标。本文仅作技术接入说明，与上述公司无隶属或合作关系。模型范围与价格以站内模型价格页为准。

一、先选部署方式

LobeChat 可以只在本机跑，也可以部署到服务器给团队用。两种场景的依赖不同：

方式	适合场景	主要依赖	注意事项
单容器试跑	个人试用、功能验证	Docker、PostgreSQL	最快跑通，长期使用要补存储与备份
Docker Compose	团队长期使用	PostgreSQL、S3 兼容存储，可选 Redis	官方推荐，功能完整
Vercel 等托管	轻量试用、少运维	外部 PostgreSQL、S3	Serverless 有函数超时限制，不支持 WebSocket

2026 年的服务端版本把 PostgreSQL 作为必需组件，知识库还需要 pgvector 与全文检索插件，文件上传需要 S3 兼容存储。旧版本曾有纯浏览器模式，新版本以服务端部署为主，动手前先确认当前版本的依赖。准备给团队用，直接按 Compose 方案准备，后面少返工。

二、准备三项参数

无论哪种部署方式，接入自定义 API 都只需要三样东西：

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

三项里最容易错的是后两项：Key 粘贴时带空格，模型 ID 多了版本后缀或少了大写。建议先在密码管理器里存好 Key，再开始配置。

三、启动服务并写入环境变量

团队部署建议把配置放进环境变量文件，不要写进镜像或代码仓库。下面是一份最小示例，数据库、存储和密钥需要换成你自己的值：

# lobehub.env 示例，密钥请自行生成并妥善保管
APP_URL=https://chat.example.com
DATABASE_URL=postgres://postgres:change-me@postgres:5432/postgres
AUTH_SECRET=用 openssl rand -base64 32 生成
KEY_VAULTS_SECRET=同样方式单独生成一个
OPENAI_API_KEY=sk-你的网关密钥
OPENAI_PROXY_URL=https://ai.zhongshangqihang.com/v1
OPENAI_MODEL_LIST=-all,+你的模型ID

启动容器时挂载这个文件：

docker run -d --name lobehub -p 3210:3210 \
  --env-file lobehub.env lobehub/lobehub

启动日志出现数据库迁移完成和 Ready，再访问 http://服务器地址:3210。如果日志停在数据库连接失败，先查 DATABASE_URL 的主机名、端口和密码；容器里的 localhost 不等于宿主机。升级镜像前固定版本标签，不要长期用 latest。

四、在界面添加 OpenAI 兼容服务商

环境变量适合统一配置，界面配置适合个人试用或临时调整。以当前常见版本为例：

登录后打开设置，进入“AI 服务商”。
选择 OpenAI，或添加一个自定义服务商，名称写清用途，例如“团队网关”。
在 API 地址填入 https://ai.zhongshangqihang.com/v1，只填到 /v1。
填入网关 Key，确认没有多余空格。
在模型列表里添加模型 ID，并按实际能力勾选视觉、工具调用、文件等选项。
保存后把该服务商设为默认，或回到对话里手动选择模型。

自定义服务商支持配置模型能力标签，这一点常被忽略。标签勾错不会报错，但会让插件、图片理解或文件上传在运行中途失败。不确定时先少勾，用一条真实任务验证后再补。

五、验证：先 curl，再对话

配置完成后不要直接开始工作，先用一条最小请求确认链路：

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，说明地址、Key 和模型至少是通的。然后回到 LobeChat 新建对话，选同一个模型，发一句“只回复 OK”。两步都通过，再去配置助手和知识库。

常见状态码的指向很明确：401 查 Key 和空格，404 查 /v1 路径，model not found 查模型 ID 是否与价格页一致，429 查网关用量和并发。一次只改一个变量，否则无法判断是哪一项生效。

六、助手：把模型分配到具体任务

助手（新版本也叫 Agent）用于保存系统提示词、模型和参数。实用的做法是按任务分工，而不是把所有模型都堆在默认列表里：

日常问答用响应快、成本可控的通用模型。
长文总结和合同审阅单独建助手，配长上下文模型，并把输出结构写进提示词。
代码任务用代码能力稳定的模型，要求先说明改动再执行。
翻译、润色各建一个助手，把术语表和语气要求固定下来。

每个助手只解决一类问题，提示词越短越容易维护。团队可以把常用助手的提示词整理成模板分发，但不要在里面写 Key。

七、插件与知识库：先确认依赖

插件依赖模型的函数调用能力。模型不支持工具调用时，插件按钮可能仍能点，但调用会失败。自建插件市场时还要配置插件索引地址和插件所需的密钥；只安装来源可信的插件，并检查它会读取哪些内容。

知识库的依赖更多，常见组合是 PostgreSQL、pgvector、S3 兼容存储和一个嵌入模型。当前版本默认使用 OpenAI 的嵌入模型，也可以通过环境变量指定其他兼容嵌入模型。接入网关时，要先确认网关提供嵌入接口和对应模型；没有的话，知识库的语义检索无法工作。

建议先导入一两份答案明确的文件，用具体问题测试检索效果，再批量上传。分块大小、文件格式和扫描件质量都会影响结果，不要一次改多项设置。

八、团队部署：配置集中，密钥分散

团队使用时，建议遵循几条边界：

服务端环境变量只放共享配置和默认模型，Key 放密钥管理，不进 Git。
成员各自使用自己的网关 Key，按人命名，离职或泄露时单独吊销。
数据库和 S3 都纳入备份计划，备份文件按敏感数据处理。
公网部署必须上 HTTPS，并在反向代理层做访问控制。
流式响应要关闭代理缓冲，否则会出现回答一次性出现或中途卡住。
在网关侧设置预算和并发上限，定期看用量报表。

如果只是内部小团队，可以在网关侧按项目分 Key，再配合 LobeChat 的账号体系区分使用者。两层都保留记录，排查和结算会轻松很多。

常见问题

LobeChat 和 LobeHub 是什么关系？

LobeChat 是项目早期名称，2026 年的新版本文档与镜像使用 LobeHub 品牌。功能延续，但环境变量和界面入口有调整，部署时以当前官方文档为准。

Base URL 要不要带 `/v1`？

要。填到 https://ai.zhongshangqihang.com/v1 即可，不要填完整的 /chat/completions 路径，客户端会自己拼接。个别代理会代为转发 /v1，以实际测试结果为准。

配好环境变量后模型列表还是空的？

先确认 OPENAI_MODEL_LIST 的变量名和语法，-all,+模型ID 用英文逗号分隔且不加空格。改完环境变量要重建容器，单纯重启不一定加载新值。

知识库上传成功但检索不到内容？

按依赖顺序查：数据库是否装好向量插件、S3 是否可写、嵌入模型是否可调用。三项任一不满足，文件可能显示上传成功，但无法建立索引。

团队可以共用一把 Key 吗？

不建议。共用 Key 无法区分用量，一人泄露全组受影响。按人、按项目或按环境分别发 Key，再配合网关的额度与日志管理。

下一步

LobeChat 的接入可以拆成三步：选对部署方式，把 Base URL、Key、模型 ID 三处对齐，再用 curl 和一条真实对话验证。跑通之后，再逐步加助手、插件和知识库，问题会少很多。需要统一模型入口和用量管理，可以注册中商起航 AI 网关，可用模型与价格以模型价格页为准。