LobeChat 把多家模型、插件和知识库放在同一个界面里，配置项多，报错也容易被误判。大多数问题并不在模型本身，而是四层之一：Key 没生效、地址或模型名不对、额度或并发触顶、网络与浏览器跨域不通。先把错误归类，再逐层验证，比反复重装客户端有效。

本文按 401、404、429、连接失败展开，并补充流式输出、插件和知识库的专门问题。界面与环境变量名称会随版本变化，以你当前版本的官方文档为准；模型与价格以站内模型价格为准，价格可能调整。

说明：LobeChat、LobeHub 是其权利人的产品与商标，本文仅作技术排错说明，与相关厂商无隶属关系。

一、先记录证据，再判断类别

现象 常见状态码或提示 第一判断 先查什么
401 Unauthorized invalid_api_key、空响应 Key 未被识别 Key 完整性、所属地址、注入方式
404 / model not found not_found_error、model_not_found 路径或模型名不对 Base URL、/v1、模型 ID
429 Too Many Requests rate_limit_error、insufficient_quota 限流或额度不足 并发、用量、账单
Failed to fetch 无状态码、浏览器报错 请求没拿到响应 DNS、代理、防火墙、CORS
5xx server_error、网关错误页 上游或网关故障 重试并记录请求 ID
插件或知识库失败 工具调用错误、上传失败 能力或依赖缺失 函数调用、存储、Embedding

排错前至少记下：发生时间、LobeChat 版本、部署方式（桌面端、网页版或 Docker）、HTTP 状态码、响应体和请求 ID。缺了这些信息，只能靠猜。

二、401：Key 没有被认出来

401 表示服务端拒绝这把 Key。高频原因包括：

  • 复制时带入空格、换行或全角字符，看起来一样，实际不同；
  • 界面配置和部署环境变量混用，实际请求用的不是你以为的那把 Key；
  • Key 已删除、轮换，或所属项目被停用；
  • 用 A 服务商的 Key 请求 B 服务商的地址；
  • 请求被公司代理拦截，返回的是登录页 HTML，而不是 JSON。

先绕过客户端验证。用同一把 Key、同一个地址发一次最小请求：

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"}]}' \
  -w "\nHTTP %{http_code}\n"

返回 200 和 choices，说明 Key 与地址有效；仍然 401，问题在复制、权限或代理。Docker 部署还要确认变量真的进了容器：docker exec lobe-chat env | grep -i openai，容器名以 docker ps 为准。界面里保存的配置属于当前用户，换设备或清缓存后可能消失，团队共用应优先用环境变量。

三、404 与 model not found：地址和模型各查一遍

404 有两种：路径不存在，和模型不存在。前者看 URL，后者看模型 ID。

LobeChat 的代理地址字段，有的场景填域名即可，有的要带 /v1，取决于网关是否自己转发 /v1。判断标准不是照抄教程，而是看最终请求地址里 /v1 是否只出现一次。常见错误是主机已经以 /v1 结尾，路径又拼了一次，变成 /v1/v1/chat/completions。代理地址应指向 API 根路径，不是完整的 /chat/completions。

model not found 与路径无关。模型 ID 区分大小写、版本后缀和供应商前缀，必须从模型价格页或控制台复制。用 CUSTOM_MODELS 管理列表时，先用 -all,+一个确认可用的模型 做最小测试，跑通后再加其他模型；逗号用英文，不要带空格。模型已经出现在列表里，仍要确认它的类型和能力开关与真实情况一致，否则一调用就失败。

403 通常是认得出 Key，但不允许使用该模型或该功能，不要和 401 混在一起反复换 Key。

四、CORS、代理与 TLS：浏览器直连的坑

LobeChat 网页版在浏览器里发请求时，网关必须允许 LobeChat 所在域名的跨域请求。CORS 失败的典型表现是浏览器控制台出现 Access to fetch ... has been blocked by CORS policy，而用 curl 测试完全正常。处理方式有两种：让网关放行对应 Origin，或使用服务端转发，让请求不经过浏览器的跨域检查。

如果 LobeChat 部署在 Nginx、Caddy 或 Cloudflare 后面，代理层要能访问网关，且不要把 API 主机和 HTTP 代理混填。系统代理、VPN、容器里的 HTTP_PROXY、HTTPS_PROXY 可能叠加，只保留一层，并用 NO_PROXY 排除内网地址。

TLS 问题常表现为 UNABLE_TO_VERIFY_LEAF_SIGNATURE，多见于企业解密代理。正确做法是安装企业根证书；把 NODE_TLS_REJECT_UNAUTHORIZED 设为 0 只能临时定位，会降低安全性，不应留在生产环境。

插件服务同样要允许 LobeHub 的 Origin。自托管还要确认插件功能开关已打开，并且模型本身支持函数调用，否则插件会在执行阶段失败。

五、429：限流、并发与额度

429 有两种常见含义：请求太快，或者额度不足。前者常伴随 rate_limit_error，后者可能是 insufficient_quota，处理方向相反。

  • 请求太快：降低并发，减少同时打开的会话和客户端；长上下文会放大 token 消耗。
  • 额度不足：检查网关用量和账单，充值或更换 Key；单纯重试不会恢复。
  • 响应头有 Retry-After 时按它等待；没有时用指数退避加随机抖动，并设置重试上限。
  • 团队共用一把 Key 时，多台设备、多个窗口共享并发额度。
  • 不要在客户端连续点“检查”或连续重发，短时间内容易叠加请求。

如果只在长对话里出现 429，先压缩上下文或新建会话，再确认模型的上下文窗口。调低“最大上下文消息数”只能缓解上下文压力，不能替代用量与并发管理。

六、流式输出中断：回答到一半停了

LobeChat 默认流式返回。中途停止多半不是模型坏了，而是 SSE 被代理缓冲、连接空闲超时，或上游在生成途中断开。表现是前半段正常、后半段突然结束，或一直停在“正在输入”。

先在版本允许时关闭流式输出，用同一个问题对比。非流式能完整返回，问题就在 SSE 链路。反向代理要关闭响应缓冲并延长读超时，例如 Nginx 的 proxy_buffering off 和 proxy_read_timeout；Cloudflare 等 CDN 也可能缓冲事件流。推理模型在正文前长时间“思考”，看起来像卡住，先用非流式请求确认是否真的没有响应。

七、插件与知识库的专门报错

插件失败先分三层：模型是否支持函数调用，插件网关是否可达，插件服务是否允许跨域。自托管版本还要确认插件功能已启用。模型不支持工具调用时，界面可能仍能打开插件，但一到执行就报错。

知识库是另一套依赖。常见自托管方案需要 PostgreSQL 加 PGVector 存向量、S3 兼容存储放原文件，以及可用的 Embedding 模型。默认嵌入模型往往是 OpenAI 的某个型号，但你的网关不一定提供同款，需要单独配置一个可用的嵌入模型；自定义 Embedding 的变量名和取值格式以当前版本文档为准。

上传失败优先查存储桶地址、密钥、权限和跨域；检索失败优先查索引是否建好、Embedding 维度是否一致。换嵌入模型后，旧索引通常要重建。PDF、Word 等格式的解析还可能依赖额外的解析服务，纯文本能传、复杂格式失败，就要往这个方向查。

八、日志与取证

  1. 打开浏览器开发者工具的 Network 面板，找到失败请求，记录完整 URL、状态码、响应体和请求头；分享前删除 Key。
  2. 用 docker logs -f lobe-chat 查看容器日志，重点找启动错误、迁移失败和连接超时。
  3. 用 docker exec lobe-chat env 确认环境变量确实存在，注意变量名拼写和引号。
  4. 在容器内执行 curl 或 nslookup，判断是容器网络、DNS 还是外部网关的问题。
  5. 需要更详细日志时，用 DEBUG=lobe:* 和 LOG_LEVEL=debug 启动，再跟踪日志输出。
  6. 提交问题时附上版本、部署方式、时间、状态码和请求 ID，只写“连不上”很难定位。

九、一套固定的排查顺序

  1. 用 curl 直连网关，确认 Key、主机和模型是否有效。
  2. curl 失败：查 DNS、代理、TLS、防火墙和网关状态。
  3. curl 成功但 LobeChat 失败：查 API 类型、/v1 是否重复、模型 ID、CORS 和客户端代理。
  4. 按状态码分流：401 查 Key，404 查路径与模型，429 查用量与并发，连接失败查网络与证书。
  5. 每次只改一个变量，改完立即复测并记录结果。

这套顺序的价值在于把客户端问题和服务端问题分开。多数所谓 LobeChat 报错，最后都能归到某一条配置或某一层网络。需要统一管理 Key、用量和模型入口，可以注册中商起航 AI 网关；可用模型与计费方式以模型价格页为准。

常见问题

LobeChat 报 Failed to fetch，是 Key 错了吗？

不一定。这个提示只说明浏览器没有拿到有效响应。先用 curl 测同一地址；curl 也失败，优先查 DNS、代理、防火墙和证书；curl 成功，再查 CORS、路径拼接和客户端代理。

为什么 curl 能通，LobeChat 里却报 401 或返回空白？

常见原因是界面里保存的 Key 与环境变量不一致、复制时带入了空格、代理地址少了或多了 /v1，以及浏览器跨域被拦截。逐项对比最终请求地址和请求头，不要只看界面显示。

CUSTOM_MODELS 加了模型，列表里还是不显示？

先确认变量名与当前版本一致，逗号是英文逗号且没有空格，容器是重建而不是只重启。可以先用 -all,+一个确认可用的模型 做最小测试，跑通后再加其他模型。

429 一直重试会恢复吗？

限流类 429 在退避并降低并发后可能恢复；额度不足类不会因为重试恢复，需要检查账单、用量或更换 Key。先看响应体里的错误类型，再决定是否重试。

知识库上传失败，和对话 API 是同一个问题吗？

通常不是。对话走的是聊天接口，知识库还依赖数据库、向量扩展、对象存储和 Embedding 模型。先确认这几项配置，再检查文件格式与解析服务。

相关阅读：