文档

文档

LobeChat

自托管的 LobeChat 需要设置三个环境变量才能连接 Kunavo:密钥、代理 URL,以及希望在选择器中显示的模型 ID 列表。

将 OPENAI_API_KEY 设置为你的 sk-kn-… 密钥,将 OPENAI_PROXY_URL 设置为 https://api.kunavo.com/v1,并在 OPENAI_MODEL_LIST 中列出所需 ID。这样,Claude 和 GPT 就会共用一个选择器和一个余额。

.env
OPENAI_API_KEY=sk-kn-...
OPENAI_PROXY_URL=https://api.kunavo.com/v1

# LobeChat only shows models it knows about, so name the ones you want.
OPENAI_MODEL_LIST=claude-sonnet-5,claude-haiku-4-5,claude-opus-5,gpt-5-6-terra
/v1 后缀应包含在 OPENAI_PROXY_URL 中。LobeChat 会将请求转发到你提供的 URL,而不是重新拼接 OpenAI 路径;因此,它自己的 .env.example 将默认值写为 https://api.openai.com/v1,其中已包含后缀。

分步操作

  1. 在 /app/keys 创建密钥并复制——它只会显示一次。
  2. 将这三个变量添加到部署环境中——裸机安装时添加到 .env 文件,Docker 部署时添加到 environment 配置块。
  3. 重启容器以读取新的环境变量。
  4. 打开 LobeChat,开始一个会话,并选择你在 OPENAI_MODEL_LIST 中列出的某个 ID。
docker-compose.yml
services:
  lobe-chat:
    image: lobehub/lobe-chat
    ports:
      - "3210:3210"
    environment:
      OPENAI_API_KEY: sk-kn-...
      OPENAI_PROXY_URL: https://api.kunavo.com/v1
      OPENAI_MODEL_LIST: claude-sonnet-5,claude-haiku-4-5,gpt-5-6-terra

LobeChat 对这些变量的参考说明见模型提供方环境变量页面。

调试容器前先验证

一个请求即可判断故障出在端点、密钥还是 LobeChat 的模型列表。如果返回 JSON 模型 ID 列表,说明同一个 URL 和密钥可正常使用——此后选择器仍为空,问题就在 OPENAI_MODEL_LIST,而不在端点。

# Settles whether a failure is the endpoint, the key, or LobeChat.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

要列出哪些 ID

Kunavo 上的所有文本模型都可以放进 OPENAI_MODEL_LIST——完整列表见模型页面,并且会通过 GET /v1/models 实时返回。费率以美元/1M tokens 计,依次为输入 / 输出。

模型 IDKunavo 输入 / 输出适用场景
claude-haiku-4-5$0.70 / $3.50最便宜的 Claude——适合每轮成本很重要的长聊天会话
claude-sonnet-5$1.40 / $7.00质量与价格的默认平衡选择
claude-opus-5$3.50 / $17.50质量最高的 Claude 档位
gpt-5-6-terra$0.70 / $4.20同一密钥,不同模型系列——无需再配置第二个服务商
聊天客户端每轮都会重新发送完整对话,因此 LobeChat 中的 token 消耗会随会话长度增长,而不会保持每条消息的固定水平——对于这种模式,最重要的调节手段是 提示缓存。费用按 token 从预付余额中扣除,没有月费,因此闲置一个月也不会产生费用;详情见计费。

常见问题

如何让 LobeChat 使用自定义的兼容 OpenAI 端点?

在部署环境中将 OPENAI_PROXY_URL 设置为端点的基础 URL,并将 OPENAI_API_KEY 设置为你的密钥——Kunavo 的基础 URL 是 https://api.kunavo.com/v1。LobeChat 自己的 .env.example 将 https://api.openai.com/v1 作为该变量的示例值,这提醒你 /v1 后缀应包含在变量值中,而不是由系统自动追加。

为什么自定义模型没有出现在 LobeChat 的模型列表中?

LobeChat 会显示已告知它的模型,而不会列出端点能够提供的所有模型;因此,即使端点能响应某个模型 ID,只要该 ID 不在列表中,它就不会显示。请在 OPENAI_MODEL_LIST 中以逗号分隔的列表形式填写模型 ID。LobeChat 的文档还为该变量定义了前缀语法:前缀 + 表示添加模型,前缀 - 表示隐藏模型,model_name=display_name 表示在选择器中重命名模型。

LobeChat 能否通过 OpenAI 提供方使用 Claude 模型?

可以,前提是模型通过兼容 OpenAI 的端点提供。LobeChat 的 OpenAI 提供方会将模型 ID 发送到 OPENAI_PROXY_URL 指定的地址,因此 Claude ID 会由网关解析,而不是在 LobeChat 内部解析,也无需 Anthropic 凭据。在 Kunavo 上,Claude 和 GPT ID 共用一个密钥,因此要添加一个模型系列,只需将对应 ID 加入 OPENAI_MODEL_LIST。

LobeChat 的图像生成功能能否通过自定义端点使用?

这取决于端点实现了哪些路由,而非 LobeChat。聊天提供方需要 /v1/chat/completions;图像生成则使用单独的路由。Kunavo 在自己的端点上实现了图像和视频生成功能,相关文档分别位于 images 和 video 章节。因此,可靠的做法是使用 LobeChat 进行聊天,并直接调用媒体端点,而不要假定一个提供方设置能同时处理两者。