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

与虾牵手
14 阅读1分钟

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

先说结论

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

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

为什么要折腾这个

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

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

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

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

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

1. 基础部署

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

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

跑起来：

docker compose up -d

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

2. 关键环境变量说明

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

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

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

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

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

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

方案二：前端 UI 手动配置

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

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

具体填：

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

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

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

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

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

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

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：

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 快速验证接口是否通：

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：端口被占用

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

坑 2：Docker 镜像拉不下来

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

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

改完 docker-compose.yml 之后：

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

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

坑 4：Streaming 响应断断续续

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

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 接口看实际支持哪些：

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 接地气多了。有空再单独写篇实测。

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

avatar
文章
阅读
粉丝