LobeChat 配置 OpenAI API：从填写 Key 到成功对话
简答：在 LobeChat 中配置 OpenAI API，进入“AI 服务商”或 OpenAI 配置页，填写 API Key、API 代理地址和模型名称，再点击“连通性检查”“获取模型列表”并发送一条最小测试消息。自托管时可使用 OPENAI_API_KEY、OPENAI_PROXY_URL、OPENAI_MODEL_LIST，但变量名应以所用版本的 .env.example 为准。
定义：LobeChat 配置 OpenAI API，是指为 LobeChat 提供可用的 API Key、OpenAI 兼容 Base URL 和模型标识，使它能够向指定模型发送聊天请求并接收回复。
配置前先准备 3 项信息
配置前准备好以下信息：API Key、API 代理地址和模型名称。API Key 用于身份验证；API 代理地址用于指定请求发送到哪个 OpenAI 或 OpenAI 兼容接口；模型名称必须与接口实际支持的模型标识完全一致。
如果使用第三方 OpenAI 兼容接口，应先查看该接口的公开文档，确认 Base URL 是否需要以 /v1 结尾，以及它是否支持聊天请求、模型列表和流式输出。不要把完整的 /chat/completions 路径直接填入 Base URL 字段，也不要仅凭模型名称判断接口一定支持该模型。
本文是第三方配置指南，不代表任何第三方接口与 LobeHub 或 OpenAI 存在官方关系。模型名称和能力会变化；截至 2026-10-17，OpenAI 当前模型列表应以其官方模型文档为准，兼容接口则以对应服务的文档为准。
网页端配置 OpenAI API 的具体步骤
- 打开 AI 服务商设置：登录 LobeChat（现称 LobeHub）后进入设置，找到“AI 服务商”或 OpenAI 配置区域。不同版本的菜单名称可能不同，本文使用“AI 服务商”作为当前版本的识别方式。
- 填写 API Key：把有效密钥填入 API Key 字段。不要把完整 Key 放进文章、截图、公开仓库或浏览器控制台；如果 Key 曾经泄露，应在对应平台撤销旧 Key 并重新生成。
- 填写 API 代理地址：在名为“API 代理地址”的字段中填写服务商提供的 OpenAI 兼容 Base URL。官方 OpenAI 地址和第三方兼容地址的路径规则可能不同，是否添加
/v1必须以接口文档和实际路由为准。 - 填写或选择模型：在模型选择框中选择接口实际支持的模型。如果没有目标模型，先点击“获取模型列表”；如果接口未实现模型列表接口，则按照服务商文档手动填写准确的模型标识。
- 点击“连通性检查”：先使用该按钮检查 Key、Base URL 和模型是否可以完成基本请求。失败时记录 HTTP 状态码和返回正文，不要只重复点击发送按钮。
- 点击“获取模型列表”：如果服务支持模型列表接口，点击该按钮刷新模型。获取不到列表不一定代表聊天接口不可用，因为部分兼容接口只支持指定模型调用。
- 发送最小测试消息：选择一个已确认存在的文本模型，发送“请回复：测试成功”。首次测试不要同时启用图片、工具调用、超长上下文或流式输出，便于定位问题。
如果网页端测试成功但聊天没有回复，打开浏览器开发者工具的 Network 面板，检查实际请求地址、状态码、响应内容和是否持续返回数据。客户端请求模式下，浏览器直接访问 API；服务端请求模式下，通常由 LobeHub 服务端代为访问 API。两种模式的网络路径、跨域条件和 Key 保存位置并不相同。
如果请求模式开关在当前版本中显示为“使用客户端请求模式”或类似名称，应按照该版本界面和官方说明判断。接口不支持浏览器跨域请求时，curl 或服务端测试成功，并不等于浏览器直连一定能正常返回。
API Key、Base URL 与模型名称怎么区分
| 配置项 | 作用 | 示例格式 | 常见错误 |
|---|---|---|---|
| API Key | 验证调用身份和权限 | sk-你的密钥 | 复制了空格、Key 已撤销、把模型名误填为 Key |
| API 代理地址 | 指定 OpenAI 兼容 API 的基础地址 | https://example.com/v1 | 填入完整聊天路径、重复添加 /v1、漏写必要路径 |
| 模型名称 | 指定实际调用的模型 | 服务商文档中的模型标识 | 模型不存在、大小写错误、接口没有该模型权限 |
| OPENAI_MODEL_LIST | 控制自托管界面显示哪些模型 | -all,+模型标识 | 变量未注入容器、修改后未重启、显示模型并不代表接口支持 |
自托管版本可以使用 OPENAI_MODEL_LIST 控制模型列表。例如：
OPENAI_MODEL_LIST=-all,+你的模型标识其中 -all 表示先隐藏已有模型，再使用 + 添加指定模型。也可以用等号设置界面显示名称，例如：
OPENAI_MODEL_LIST=-all,+provider-model=自定义显示名称该变量只影响 LobeHub 界面显示，不会授予 API Key 新权限，也不会把不存在或未开通的模型变成可调用模型。变量名、语法和支持范围可能随版本调整，应同时查看项目的官方 .env.example和当前部署文档。
Docker 自托管的最小配置示例
截至 2026-10-17，LobeHub 官方仓库的 Docker 发布工作流使用镜像名 lobehub/lobehub；较早的部署文档仍可能出现 lobehub/lobe-chat。因此，下面使用当前官方仓库发布配置对应的镜像名，并建议部署前核对版本文档和镜像标签。
docker run -d -p 3210:3210 \
-e OPENAI_API_KEY=sk-你的密钥 \
-e OPENAI_PROXY_URL=https://example.com/v1 \
-e OPENAI_MODEL_LIST=-all,+你的模型标识 \
--name lobehub \
lobehub/lobehub:latest上面的命令用于展示最小配置结构。OPENAI_API_KEY 写入服务端默认 API Key，OPENAI_PROXY_URL 指定 OpenAI 兼容接口地址，OPENAI_MODEL_LIST 控制显示的模型。环境变量名称以你所用版本的官方示例为准，不能把旧教程中的变量无条件复制到新版本。
如果镜像标签、端口或部署方式与当前版本不一致，应先查看LobeHub 官方 Docker 发布配置和官方 Docker 部署文档。修改环境变量后，需要重新创建或重启容器，并检查变量是否真正进入容器。
ACCESS_CODE 是否需要配置，以及它在客户端数据库、服务端数据库或启用鉴权的部署方式中如何生效，取决于所使用的 LobeHub 版本和部署模式。不要直接照搬旧教程，应以对应版本官方文档为准。
客户端请求模式与服务端请求模式
客户端请求模式通常由浏览器直接向 API 发起请求；服务端请求模式则由 LobeHub 服务端代为请求 API。判断问题时，先确认实际请求从哪里发出，再检查对应环境的网络和配置。
| 模式 | 主要检查位置 | Key 风险与注意事项 |
|---|---|---|
| 客户端请求 | 浏览器 Network、CORS、浏览器扩展、网页实际保存的配置 | 浏览器必须能访问 API；接口还需要允许网页来源的跨域请求 |
| 服务端请求 | 容器或服务器日志、DNS、TLS、环境变量和出站网络 | 浏览器不一定直接访问 API，但部署服务器必须能访问 API |
网页端填写的 API Key 不能简单地都归类为“保存在浏览器本地”。在客户端模式下，Key 可能保留在浏览器侧配置中，公共电脑、共享浏览器和可疑扩展会增加泄露风险；在启用服务端数据库的部署中，LobeHub 官方环境示例提供了 KEY_VAULTS_SECRET，用于加密用户 API Key 和代理地址。具体存储方式取决于版本、部署模式和是否启用数据库，因此应以所用版本文档为准。
如果是多人使用或长期运行，优先采用服务端环境变量、访问鉴权和最小权限 Key；不要把长期有效的主密钥直接放在公共设备的网页设置中。
401、403、404、429、超时与空回复排查
| 现象 | 优先检查 | 处理步骤 |
|---|---|---|
| 401 Unauthorized | Key 是否为空、失效或格式错误 | 重新复制 Key，去除首尾空格，确认 Key 未被撤销，并检查请求是否确实带上认证信息。 |
| 403 Forbidden | 权限、组织、来源限制或模型访问策略 | 查看返回正文，确认当前 Key 是否有目标模型权限，以及服务端是否限制来源或账号。 |
| 404 Not Found | Base URL、路径或模型名称 | 检查是否重复添加或漏掉 /v1，不要把完整的 /chat/completions 填入“API 代理地址”，并核对模型标识。 |
| 429 Too Many Requests | 限速、配额、并发或账户用量 | 降低并发和请求频率，检查配额与用量，按接口返回的限制信息等待后重试。 |
| 连接超时 | DNS、TLS、服务器出站网络或接口响应时间 | 从 LobeHub 所在容器或服务器测试域名解析和 HTTPS 连接，不要只在本地电脑测试。 |
| 空回复或流式中断 | 流式传输、CORS、代理缓冲和响应格式 | 先使用最小文本请求；如果界面提供流式开关，可暂时关闭流式测试；再检查接口是否返回 LobeHub 支持的 OpenAI 兼容格式，以及反向代理是否缓冲或截断响应。 |
OpenAI 官方错误码文档将认证、权限、请求限制和服务器错误分别说明，可结合OpenAI 官方错误码文档判断错误类别。兼容接口可能使用不同的错误正文，因此最终仍要以实际返回的状态码、错误字段和服务商文档为准。
建议按“API Key—API 代理地址—模型名称—请求模式—网络—响应格式”的顺序排查，每次只修改一个变量，并记录状态码、请求时间和服务端日志。公开提交日志时，只保留 Key 的少量首尾字符，不能泄露完整密钥。
常见问题
为什么 LobeChat 能获取模型列表，却发送消息失败？
获取模型列表和聊天请求可能使用不同路径、权限或参数。先确认选中的模型确实支持聊天调用，再检查 API Key、模型名称和聊天接口路径。OPENAI_MODEL_LIST 只控制界面显示，不会自动授予模型调用权限。
为什么 API 测试成功，但网页聊天没有回复？
先确认测试请求是从浏览器还是服务端发出。客户端请求模式重点检查浏览器 Network、CORS 和流式响应；服务端请求模式重点检查容器日志、服务器出站网络和环境变量。还要确认网页实际保存的 Key 与测试时使用的配置一致。
API 代理地址末尾到底要不要加 /v1？
没有统一答案，应以接口提供方文档和实际路由为准。有的服务要求 Base URL 以 /v1 结尾，有的服务会自动补充；重复或漏写都可能导致 404。
模型列表为空怎么办？
先确认 AI 服务商已启用且 API Key 有效，再点击“获取模型列表”。如果接口不提供模型列表，可按服务商文档手动填写模型名称，或在自托管环境设置 OPENAI_MODEL_LIST；修改 Docker 环境变量后需要重启或重新创建容器。
网页端填写的 API Key 安全吗？
安全性取决于部署模式。客户端请求模式下，Key 可能保存在浏览器侧配置，公共设备和共享浏览器风险更高；服务端数据库模式下，官方环境示例提供 KEY_VAULTS_SECRET 用于加密相关密钥和代理地址。具体行为以所用版本文档为准。
ACCESS_CODE 是否必须配置？
不能一概而论。它是否生效以及适用于客户端数据库、服务端数据库或启用鉴权的部署方式，取决于所使用的 LobeHub 版本和部署配置，应以对应版本官方文档为准。