Open WebUI 怎么接小鱼API：管理员面板加连接、环境变量、报错排查一次讲完

一、Open WebUI 是自托管的 ChatGPT 替代界面

Open WebUI 是能装在自己电脑或服务器上的网页对话界面，打开浏览器就能聊，账号、聊天记录、模型配置全留在自己机器上，不受网页版改版影响。装好后左边是对话列表，中间是聊天区，顶部切模型，右下角能传文件，手感和 ChatGPT 网页版接近。它自己不产生回答，必须接一个 OpenAI 兼容接口才有模型可用。要填的四个值照抄即可：

API 类型：OpenAI 兼容
接口地址：https://xyuapi.top/v1
API Key：你自己的令牌，sk- 开头，平台后台生成
模型名：填具体 ID，如 gemini-2.5-pro、deepseek-v4-flash-thinking、claude-sonnet-4-5-thinking

它只认一个 OpenAI 兼容后端

启动后它问后端两个地址：/v1/models 拿模型清单，/v1/chat/completions 发对话。界面没有填完整 endpoint 的输入框，地址写到 /v1 这一层就行，后面那段路径它自己拼；本地 Ollama 是另一条路，同时开着不冲突。

自托管的好处：数据在自己手里

聊天记录存在挂载的数据目录里。一台机器跑一个，几个人开浏览器访问同一地址，各聊各的，管理员能看到谁在用哪个模型，比每人一个标签页靠谱。

长上下文为什么容易把账单拉高

按 token 计费的接口，价格跟着输入长度走：贴一份几万字的合同让它读完，单次花费可能是问一句「你好」的几十倍。小鱼API 按次计费，一次请求一个固定价，输入多长都不改价——同一份合同和一句「你好」，gemini-2.5-pro 都是 0.031 元，长文档直接丢进去读就行，不用先估 token。反过来说，如果你习惯把整本书、整份财报、整个代码目录丢进去问，按次计费的账是可预期的：问几次就是几个单价，不随输入膨胀。

二、接上小鱼API：管理员设置里的那条连接

先拿到令牌和模型 ID

平台上生成一个 sk- 开头的令牌，复制下来，多个客户端能共用一个。模型 ID 从模型列表复制，别手打，大小写和版本后缀都要一致。

用管理员账号登录，进管理员面板

装好后头一个注册的账号就是管理员。点头像，菜单里有「管理员面板」（英文 Admin Panel）。不同版本叫法略有差异，按关键词找 Admin 那一项。

「设置」里的「连接 / Connections」

进去找「设置」里的「连接」（英文 Connections），这一页管所有外部后端。不同版本叫法略有差异，按关键词找 Connections 或中文「连接」那一项。

在 OpenAI API 这一组点新增连接

页面往下拉，OpenAI API 这一组右边有加号或「新增连接」。点开会出现地址、密钥两个框，有的版本多一个前缀框和一个模型白名单框，留空即可。

地址和密钥分别填什么

地址填 https://xyuapi.top/v1，结尾带 /v1，不带斜杠。密钥粘 sk- 令牌，检查有没有带进空格或换行。填完点刷新或验证，能列出模型就通了。

保存后到「模型 / Models」把模型加进来

连接保存只是让界面认识后端，模型还要再启用一层：到「模型」（英文 Models）页把要用的 ID 点进去启用，有的版本在「管理模型」里手工登记。模型不在这个清单里，聊天页顶部的下拉框就选不到它。

菜单叫法不一样时按关键词找

记三个关键词：Connections／「连接」、OpenAI、Models／「模型」。位置会变，名字一定带这几个词。

三、两种配置方式：界面里点，或者环境变量

两种办法都能接上小鱼API，区别是配置存在哪、什么时候生效。日常调整用界面，批量部署用环境变量。

对比项	界面里点	环境变量
生效方式	保存即生效	重启容器才生效
存在哪	数据库（在数据卷里）	容器的环境变量
重启后	还在	按变量值重新生成
适合	日常调整、多连接共存	批量部署、一键拉起

方式一：界面里点，写进数据库

管理员设置里加的连接会写进 Open WebUI 自己的数据库，重启容器、升级镜像都不丢（前提是数据卷挂了）。多设备开着页面时，改完刷新另一台就能看到。

方式二：环境变量，容器启动时注入

常用变量如下，写进 docker run 的 -e 或 compose 的 environment：

变量名	作用
`OPENAI_API_BASE_URL`	OpenAI 兼容地址，填 `https://xyuapi.top/v1`
`OPENAI_API_KEY`	令牌，`sk-` 开头那一串
`ENABLE_OPENAI_API`	打开 OpenAI 兼容连接这一路，默认就开
`OPENAI_API_CONFIGS`	给连接起名字、配前缀、设模型白名单
`WEBUI_SECRET_KEY`	会话加密，换机器时带上，否则登录状态失效
`NO_PROXY`	需要直连的域名，坑六会用到
`WEBUI_URL`	对外访问地址，影响部分链接生成

变量名各版本有出入，以项目文档里 OPENAI_API_BASE_URL 这组为准。OPENAI_API_CONFIGS 的值是 JSON 字符串，引号转义写错容器会直接起不来。

优先级：界面里配过的连接覆盖环境变量

一句话：数据库里有连接就用数据库里的，没有才用环境变量。 界面上加过一条连接，之后把 OPENAI_API_BASE_URL 改成别的地址再重启，界面看到的还是原来那条。所以「改了变量没反应」时，先回「连接」页看看是不是有旧连接顶着。验证办法很直接：把界面上那条连接删掉再重启容器，环境变量里的地址才会接管。

界面那一路改完立刻生效，环境变量那一路必须重启容器。两条能并存：环境变量配默认的，界面上补一条备用地址兜底。

四、用 Docker 跑起来：命令、数据卷、重启

项目提供的镜像不带模型，起容器时把连接的三项一起注进去。

一条 docker run 命令

docker run -d \
  --name open-webui \
  -p 8080:8080 \
  -e ENABLE_OPENAI_API=true \
  -e OPENAI_API_BASE_URL=https://xyuapi.top/v1 \
  -e OPENAI_API_KEY=sk-你复制的令牌 \
  -e NO_PROXY=xyuapi.top,xyuai.cc \
  -v open-webui:/app/backend/data \
  --restart always \
  ghcr.io/open-webui/open-webui:main

起完打开 http://localhost:8080，头一个注册的账号自动成为管理员。

docker-compose.yml 片段

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "8080:8080"
    environment:
      - ENABLE_OPENAI_API=true
      - OPENAI_API_BASE_URL=https://xyuapi.top/v1
      - OPENAI_API_KEY=sk-你复制的令牌
      - NO_PROXY=xyuapi.top,xyuai.cc
    volumes:
      - open-webui:/app/backend/data
    restart: always

volumes:
  open-webui:

数据卷为什么必须挂上

-v open-webui:/app/backend/data 这行不能省：账号、聊天记录、界面上配的连接都存在这一层。少了它，删掉容器再起一个就是从零开始，重新注册管理员、重新填地址密钥。升级镜像也一样，卷在，配置就在。

改了环境变量要重启容器才生效

环境变量在容器启动那一刻注入，改完 compose 必须重新拉起容器，按 F5 没用。想确认注进去没有：

docker exec -it open-webui env | grep -i openai

返回 OPENAI_API_BASE_URL=https://xyuapi.top/v1 就说明生效了。这条输出里令牌是明文，别截图发出去。

五、七个必踩的坑，每条都有报错原文

遇到报错先对下面这张表，再往下看细节。

报错原文 / 现象	真实原因	动作
连接测试报 `Connection failed`	地址少写 `/v1`	补成 `https://xyuapi.top/v1`
聊天报 `404 page not found`	地址多写一层，路径变 `/v1/v1/chat/completions`	删掉重复的那层
`{"error":{"message":"model not found"}}`	模型名不在上游清单，或没启用	复制准确 ID 并启用
`invalid_request_error`	模型 ID 拼错、大小写不对	逐字符对照模型列表
`401 invalid api key`	令牌复制不全，或首尾带空格	重新复制并去空白
日志里 `Connection timed out`	容器出网被代理或 DNS 卡住	看坑五、坑六
找不到刚加的模型	模型清单缓存没刷新	点刷新，或重开页面

坑一：地址少写 `/v1`

只写 https://xyuapi.top，界面会拼成 https://xyuapi.top/chat/completions，这层路径不存在，返回 404 page not found，连接测试报 Connection failed。动作：补成 https://xyuapi.top/v1 再测一次。

坑二：地址多写一层 `/v1/v1`

末尾又补一个 /v1，实测路径就成了 /v1/v1/chat/completions，一样 404。动作：按 F12 看请求的真实 URL，多出来的那层删掉。

坑三：模型名写错，或者模型没被启用

名字不对，上游回 {"error":{"message":"model not found"}}，有时是 invalid_request_error。清单是从 /v1/models 拉的，模型没进「已启用模型」那一列，下拉框里就没有它。勾上它才进下拉框，这一步和填对地址一样重要。动作：先刷新模型列表并启用，清单里没有的用第六节 curl 确认，再按返回的 data[].id 一字不差填。

坑四：容器里的 `127.0.0.1` 指的是容器自己

容器有自己的网络命名空间，localhost 指的是容器自己，不是你电脑。要连宿主机的服务得用 host.docker.internal。地址填公网域名 https://xyuapi.top/v1 就没这层麻烦：容器和宿主机解析到同一个地方。本地转发、本地模型那些写 localhost 的配置，搬进容器就得换写法。

坑五：容器出网和 DNS 验证

容器发不出请求，先验它能不能出网：

docker exec -it open-webui curl -I https://xyuapi.top/v1/models

HTTP/2 401 或 HTTP/2 200 都算通（401 只是没带令牌）。报 Could not resolve host 就是容器 DNS 的事，给容器指定可用 DNS，或检查宿主机的解析配置。

坑六：系统级 HTTP 代理导致的超时

宿主或容器里配了系统级 HTTP 代理，请求会被按代理转发，结果是 Connection timed out，有时是 SSL handshake failed；Docker Desktop 的 ~/.docker/config.json 里的代理也会被注入容器。动作：把域名排除，加两个变量：

-e NO_PROXY=xyuapi.top,xyuai.cc -e no_proxy=xyuapi.top,xyuai.cc

不用容器的话，在客户端或系统网络设置里把这两个域名选成直连。

坑七：模型列表缓存没刷新

清单拉一次就缓存了，后台新加的模型不会自动出现。动作：到模型页点刷新模型列表，或重开页面；还不出现就回坑三确认有没有启用。清单明显是旧的，先刷新再看，别急着改配置。

六、用 curl 先证明接口通，再去查界面

先证明上游通，再看界面。curl 能复现同一报错，问题就在配置或上游；curl 通了界面不通，问题在 Open WebUI 这一侧。把令牌换成自己的，在宿主机上直接跑。

先验 `/v1/models`，看 `data[].id`

curl https://xyuapi.top/v1/models \
  -H "Authorization: Bearer sk-你复制的令牌"

返回长这样：

{
  "object": "list",
  "data": [
    { "id": "gemini-2.5-pro", "object": "model" },
    { "id": "deepseek-v4-flash-thinking", "object": "model" },
    { "id": "claude-sonnet-4-5-thinking", "object": "model" }
  ]
}

data 数组里每个 id 就是能填进 Open WebUI 的模型名，照抄，一个字符别改。

再验 `/v1/chat/completions`，看 `choices`

curl https://xyuapi.top/v1/chat/completions \
  -H "Authorization: Bearer sk-你复制的令牌" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-pro","messages":[{"role":"user","content":"用一句话介绍你自己"}]}'

重点看两处：model 是不是你请求的模型，choices[0].message.content 有没有正常文字。

返回 JSON 里该看哪几个字段

字段	含义	用途
`data[].id`	可用模型 ID	复制去填模型名
`model`	本次实际调用的模型	和请求不一致说明上游做了映射
`choices[0].message.content`	回答正文	有文字说明链路通
`error.message`	错误说明	配合坑三定位
`usage`	用量信息	核对这次请求的消耗

报错 JSON 怎么读

401 配 invalid api key 是令牌的事；404 page not found 查坑一坑二；400 配 invalid_request_error 多半是模型名或请求体；429 是发得太密，等一会儿再试。同一个报错能在 curl 里复现，就不用再折腾界面。curl 通了的排查就三层：地址写法、密钥里的空白、模型有没有启用，按这个顺序过一遍基本都能定位。

七、模型怎么选：按用途对号入座

用途和模型的对应关系

用途	建议模型	单价
日常问答、写文案	`gemini-2.5-pro`	0.031 元/次
长文档总结、合同审读	`deepseek-v3.2-thinking`	0.049 元/次
代码补全、读报错	`deepseek-v4-flash-thinking`	0.05 元/次
强推理、数学题	`deepseek-r1-thinking`	0.049 元/次
复杂重构、架构设计	`claude-sonnet-4-5-thinking`	0.09 元/次
高难度长链路任务	`claude-opus-4-5-thinking`	0.12 元/次
作图需求	`gpt-image-2-pro`	0.25 元/次

成本账怎么算

按次计费下，一天 100 次请求，gemini-2.5-pro 是 3.1 元，claude-sonnet-4-5-thinking 是 9 元。影响账单的是请求次数，不是字数，所以长文档不必切成小段——切段反而增加次数。最低充值 7 元，支付宝微信都能付款，不用海外信用卡。同一份令牌在 Open WebUI、Chatbox、Cherry Studio 都能用。