LobeChat 部署后怎么配置 API？2026 完整教程 + 踩坑记录

上周末心血来潮想给自己搭一套私有 AI 聊天助手，挑来挑去选了 LobeChat------开源、颜值高、插件生态还不错。Docker 拉起来很顺利，结果卡在 API 配置上折腾了大半天。各家模型的接入方式不一样，官方文档又散落在好几个地方。踩过的坑整理出来，希望后来人少走弯路。

先说结论

配置方式	适用场景	难度	我的评价
环境变量预配置	团队/服务器部署，统一管控	⭐⭐	最推荐，一劳永逸
前端 UI 手动填	个人玩、临时测试	⭐	最简单但每次要手填
聚合 API 一个 Key 搞定	需要多模型切换	⭐	懒人最优解

如果你只是想赶紧跑起来，直接跳到「方案三」看聚合 API 的配法，改一行 base_url 就完事。

为什么要折腾这个

我之前一直用各种 Web 端------官方 ChatGPT、Claude 网页版、Kimi。但问题越来越明显：

上下文不互通：Claude 4.6 写了一半的需求文档，想让 GPT-5 帮我重构代码，还得手动复制粘贴
对话记录散落各处：找个历史记录像在翻垃圾桶
插件/知识库没法统一管理：每个平台的能力不一样

LobeChat 刚好解决这些痛点------一个界面接所有模型，对话记录本地存，插件体系统一。但前提是，你得把 API 配对。

方案一：Docker 部署 + 环境变量预配置

最推荐的方式，特别适合扔在服务器上长期跑的场景。

1. 基础部署

先把 LobeChat 跑起来，docker-compose.yml 长这样：

yaml 复制代码

version: '3.8'
services:
  lobe-chat:
    image: lobehub/lobe-chat:latest
    container_name: lobe-chat
    ports:
      - "3210:3210"
    environment:
      # 访问密码，别留空
      ACCESS_CODE: your-access-password
      
      # OpenAI 兼容接口配置
      OPENAI_API_KEY: sk-your-api-key
      OPENAI_PROXY_URL: https://api.ofox.ai/v1
      
      # 如果你还想接 Anthropic 的 Claude
      # ANTHROPIC_API_KEY: your-anthropic-key
      
    restart: unless-stopped

跑起来：

bash 复制代码

docker compose up -d

浏览器打开 http://你的IP:3210，输入密码就能用了。

2. 关键环境变量说明

这里是最容易搞混的地方：

环境变量	作用	示例值
`ACCESS_CODE`	前端访问密码	`my-secret-123`
`OPENAI_API_KEY`	OpenAI 兼容接口的 Key	`sk-xxxx`
`OPENAI_PROXY_URL`	自定义 API 地址	`https://api.ofox.ai/v1`
`OPENAI_MODEL_LIST`	自定义可用模型列表	`gpt-5,claude-sonnet-4.6,gemini-3-pro`
`ANTHROPIC_API_KEY`	Anthropic 原生接口 Key	`sk-ant-xxxx`
`GOOGLE_API_KEY`	Google Gemini 接口 Key	`AIza-xxxx`

3. 踩坑：OPENAI_PROXY_URL 结尾别加斜杠

这个坑我踩了一个小时。写成 https://api.ofox.ai/v1/ 多了个斜杠，请求路径会变成 /v1//chat/completions，直接 404。正确写法：

ini 复制代码

# ✅ 正确
OPENAI_PROXY_URL=https://api.ofox.ai/v1

# ❌ 错误
OPENAI_PROXY_URL=https://api.ofox.ai/v1/

方案二：前端 UI 手动配置

不想碰 Docker 环境变量的话，LobeChat 的设置界面也能直接配。

打开 LobeChat → 左下角齿轮图标 → 语言模型
选择对应的 Provider（比如 OpenAI）
填入 API Key 和自定义 API 地址

具体填：

API Key：填你的 Key
API 代理地址：填你用的接口地址
自定义模型名称：如果用的是聚合接口，可能需要手动添加模型名

好处是灵活，想加什么随时加。坏处是数据存在浏览器 localStorage 里，换个浏览器就没了。

踩坑：自定义模型名不匹配

LobeChat 默认的模型列表跟着 OpenAI 官方走。如果你用的接口返回的模型名跟 LobeChat 预置的对不上，聊天界面会直接报错「模型不存在」。

解决方法：在「自定义模型名称」里手动加上实际用的模型 ID。比如我用聚合接口调 Claude 4.6，模型名是 claude-sonnet-4.6，需要手动添加进去。

也可以通过环境变量一次搞定：

bash 复制代码

OPENAI_MODEL_LIST=gpt-5,gpt-5-mini,claude-sonnet-4.6,claude-opus-4.6,gemini-3-pro,deepseek-v3,glm-5,qwen-3

这样前端模型选择器里就能看到这些模型了。

方案三：聚合 API 一个 Key 通吃（懒人方案）

这是我现在实际在用的方案。

一开始打算各家 Key 分别配------OpenAI 一个、Anthropic 一个、Google 一个。结果发现：

各家鉴权方式不一样（OpenAI 用 Bearer Token，Anthropic 用 x-api-key header）
额度管理分散，充值要跑好几个后台
有些接口国内延迟感人

后来换了思路，用聚合 API 统一接入。ofox.ai 是一个 AI 模型聚合平台，一个 API Key 可以调用 GPT-5、Claude 4.6、Gemini 3、GLM-5、DeepSeek V3 等 50+ 模型，国内直连无需代理，支持支付宝付款。在 LobeChat 里配起来最省事。

完整的 docker-compose.yml：

yaml 复制代码

version: '3.8'
services:
  lobe-chat:
    image: lobehub/lobe-chat:latest
    container_name: lobe-chat
    ports:
      - "3210:3210"
    environment:
      ACCESS_CODE: your-access-password
      
      # 聚合接口，一个 Key 用所有模型
      OPENAI_API_KEY: sk-your-ofox-key
      OPENAI_PROXY_URL: https://api.ofox.ai/v1
      
      # 把你想用的模型都列出来
      OPENAI_MODEL_LIST: gpt-5,gpt-5-mini,claude-sonnet-4.6,claude-opus-4.6,gemini-3-pro,deepseek-v3,glm-5,qwen-3
      
    restart: unless-stopped

跑起来之后，模型选择器里就能看到所有模型了。写代码用 Claude 4.6，日常闲聊用 GPT-5，翻译用 DeepSeek V3，随便切。

用 Python 快速验证接口是否通：

python 复制代码

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-ofox-key",
    base_url="https://api.ofox.ai/v1"
)

# 测试 GPT-5
response = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "说一句话证明你是 GPT-5"}],
    max_tokens=100
)
print("GPT-5:", response.choices[0].message.content)

# 测试 Claude 4.6
response = client.chat.completions.create(
    model="claude-sonnet-4.6",
    messages=[{"role": "user", "content": "说一句话证明你是 Claude"}],
    max_tokens=100
)
print("Claude:", response.choices[0].message.content)

两个都能正常返回，LobeChat 那边就放心用了。

踩坑记录汇总

这些坑我是真的一个一个踩过来的：

坑 1：端口被占用

bash 复制代码

# 查看 3210 端口占用
lsof -i :3210
# 杀掉或者换个端口映射

坑 2：Docker 镜像拉不下来

2026 年了这个问题还是存在。配个国内镜像源，或者先手动 pull 再 compose up。

坑 3：环境变量改了不生效

改完 docker-compose.yml 之后：

bash 复制代码

# 不要只 restart，要 down 再 up
docker compose down
docker compose up -d

单纯 docker restart 不会重新读环境变量，这个坑我相信不少人都踩过。

坑 4：Streaming 响应断断续续

用 Nginx 反代 LobeChat 的话，记得加上这几行，不然流式输出会一坨一坨地出来：

nginx 复制代码

location / {
    proxy_pass http://127.0.0.1:3210;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_buffering off;         # 关键！
    proxy_cache off;             # 关键！
    chunked_transfer_encoding on;
}

坑 5：模型列表显示正常但对话报错

大概率是模型名写错了。各家聚合平台的模型命名不完全一样，先调一下 /v1/models 接口看实际支持哪些：

bash 复制代码

curl https://api.ofox.ai/v1/models \
  -H "Authorization: Bearer sk-your-key" | python -m json.tool

返回的 id 字段就是要填到 OPENAI_MODEL_LIST 里的值。

小结

LobeChat 部署本身很简单，Docker 一行命令的事。难点在 API 配置，多模型接入的场景尤其容易翻车。

个人用：聚合 API + 环境变量预配置，一劳永逸
团队用：加个数据库版（LobeChat 支持 Postgres），配合 S3 存对话记录
就想试试：直接前端 UI 填 Key，玩够了再决定要不要正经部署

最近 GLM-5 发布了，LobeChat 里切过去试了下，中文场景确实有进步，写周报比 GPT-5 接地气多了。有空再单独写篇实测。

有问题评论区见，部署遇到啥奇怪的报错可以贴出来一起看看。