OpenWebUI API：用你自己的模型和任意网页聊天

如果你在用 OpenWebUI，那最费功夫的配置工作已经完成了。模型都配好了，key 也集中在一处管理——可能是家里服务器上跑着的 Ollama，再加一两个云服务商，外加几个你亲手调过的自定义工作区模型。

OpenWebUI 做不到的，是在你正在浏览的网页里直接干活。想就眼前这篇文章、这份 PDF 或这页文档问问模型，你还是得把内容复制、粘贴到另一个标签页里。

这正是 SurfMind 的用武之地。OpenWebUI 不只是一个聊天界面。通过 OpenWebUI API，它还能充当 API 服务器，所以 SurfMind 可以把它当作后端来用。模型照旧在 OpenWebUI 里管理，SurfMind 则成了它们在浏览器里的前端。

这篇指南会讲清楚 OpenWebUI API 是什么、它和 SurfMind 是什么关系、该粘贴哪些确切的 URL，以及大家实际遇到的报错该怎么解决。

OpenWebUI 和 SurfMind：表面相似，分工不同

乍一看，两者像是竞争对手。都是 AI 界面，都能连接多家 LLM 服务商，也都能和模型聊天。但它们面向的场景并不一样：

OpenWebUI 是一个自托管的 AI 工作台，SurfMind 则是装进你常用浏览器里的 AI。 最关键的是加粗的那一行。正因为 OpenWebUI 能通过 API 对外提供模型，两者正好可以配合使用。

为什么要把 OpenWebUI 接入 SurfMind？

设想一个典型的配置：你在家里的服务器或一台小 VPS 上跑着 OpenWebUI，背后接着：

• 通过 Ollama 在本地运行的 Llama、Qwen 或 Gemma
• 通过云端 API key 调用的 GPT 或 Claude 模型
• 在你自己 GPU 上由 vLLM 提供服务的模型
• 几个你在 OpenWebUI 里搭建的工作区模型（workspace models），各有各的系统提示词和参数设置

这些在 OpenWebUI 的聊天页面里都能用。现在你还想要浏览器助手最擅长的那些事：就当前页面提问、总结一条长长的讨论串、跨标签页对比信息，或者不离开网站就起草一条回复。

你当然可以把每个服务商在 SurfMind 里重新添加一遍：先加 Ollama，再加 OpenAI key，再加 vLLM 端点。但这样既繁琐，又让 key 散落两处，而且你搭好的工作区模型也带不过来。

或者，你只加一条连接：SurfMind → OpenWebUI。OpenWebUI 能看到的每个模型，都会出现在 SurfMind 的模型选择器里。模型、用户和权限依旧在你熟悉的 OpenWebUI 里管理，SurfMind 只是在上面加了一层浏览器能力。

团队共用一套配置时，这种方式也很方便。如果团队共用一个 OpenWebUI 实例，每个人都可以创建自己的 API key，在自己的浏览器里使用团队的模型。他们拥有的权限和在 OpenWebUI 里完全一样，而且谁都不需要接触服务商的 key。

第 1 步：创建 OpenWebUI API key

API key 功能默认是关闭的，所以第一次配置要多花一分钟。

如果你是管理员，先开启 API key：

1. 以管理员身份登录 OpenWebUI。
2. 进入 Settings → Admin → Authentication。
3. 打开 API Keys 开关，然后点击 Save。

如果你不是管理员，请让管理员给你开通 API Keys 功能权限。管理员可以在 Admin Panel → Users → Groups 中设置：要么在 Default Permissions 里对所有人开放，要么只对某个特定分组开放。

然后生成你的 key：

1. 点击左下角的头像。
2. 打开 Settings → Account。
3. 在 API keys 区域，点击 Secrets 旁边的 Show。这个区域默认是折叠的，所以看起来空空如也是正常的。
4. 点击 Create new secret key 并复制。它以 sk- 开头。

根据 OpenWebUI 的 API key 文档，有几点值得留意：

• 每个账号只有一个 key。 新建 key 会替换旧 key，旧 key 立即失效。如果别的工具已经在用你的 key，那么为 SurfMind 新建一个就会让那个工具罢工。给 SurfMind 单独建一个非管理员账号，就能避开这个问题。
• key 代表的就是你本人。 它能看到的模型、拥有的权限，都和创建它的账号一模一样。
• 不要用 JWT token，也就是同一面板里展示给管理员的那个。那是你浏览器会话的 token，会过期。

第 2 步：在 SurfMind 中添加 OpenWebUI

在 SurfMind 中，点击面板底部的模型名称，然后依次点 Show all → Custom → Add Custom Models。选择通用的 OpenAI-compatible 预设，并填写：

如果 OpenWebUI 和你的浏览器在同一台电脑上，host 通常是 http://localhost:3000（Docker 常用的端口映射）或 http://localhost:8080（pip 安装或裸机安装）：

• API URL：http://localhost:3000/api/chat/completions
• Models URL：http://localhost:3000/api/models

保存后，从列表里选一个你的 OpenWebUI 模型，随便打开一篇文章，让 SurfMind 帮你总结一下。

两个要避开的路径错误。 粘贴以 /api/chat/completions 结尾的完整端点，而不是只填主机地址或以 /api 结尾的地址。SurfMind 的 API URL 字段不会替你补全路径。另外，任何地方都不要加 /v1。/api/v1/chat/completions 和 /v1/chat/completions 都不是 OpenWebUI 的聊天端点。

故障排查：“模型能加载，聊天却失败”

这是 OpenWebUI 用户反馈最多的问题，所以单独拿出来讲。如果下拉菜单中能正常显示模型列表，说明你的 host、key 和网络路径都没问题，出错的是聊天请求本身的某个环节。按下面的顺序逐一排查。

首先，脱离 SurfMind 测试一下。 在终端里跑一条 curl，就能判断问题出在 OpenWebUI 还是你的 SurfMind 设置上。把 host、key 和模型 id 换成你自己的：

curl -X POST https://openwebui.example.com/api/chat/completions \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:latest", "messages": [{"role": "user", "content": "Say hi"}]}'

模型 id 要和 SurfMind 模型列表（或 GET /api/models）里显示的完全一致。如果这条命令能跑通，就回头检查 SurfMind 的各个字段。如果它也失败了，返回的报错会指向下面某一个原因。

1. 聊天路径不对。 Models URL 和 API URL 是两个独立的字段，所以可能一个对、一个错。检查 API URL 是否恰好以 /api/chat/completions 结尾：没有 /v1，没有结尾斜杠，也没有拼写错误。

2. 端点限制拦住了聊天。 管理员可以开启 API Key Endpoint Restrictions，也就是一份 API key 可调用路由的白名单。如果名单里有 /api/models 却没有 /api/chat/completions，就会出现一模一样的症状，通常表现为 403。请让管理员把 /api/chat/completions 加进去。

3. 某个模型设置强制了流式模式。 OpenWebUI 有一个 Stream Chat Response 设置，可以在每个模型的高级参数里单独设置，也可以由管理员在 Settings → Admin → Models 下设为默认值。根据 OpenWebUI 的文档，这个设置决定回复是否以流式返回，不管客户端请求的是什么。如果某个模型被强制成了客户端预料之外的模式，返回的回复格式就可能让客户端无法解析。如果只有某些模型聊天失败，检查一下它们的这个设置，把它改回 Default。

4. 反向代理吞掉了 Authorization 请求头。 如果 OpenWebUI 部署在一个自己也用 Authorization 做登录的网关后面（basic auth、SSO、API 网关），你的 key 根本到不了 OpenWebUI。OpenWebUI 也接受通过自定义请求头传递 key，默认是 x-api-key。这种情况下，在 SurfMind 的 API Key Header 里选择 x-api-key。如果管理员用 CUSTOM_API_KEY_HEADER 改过请求头的名字，代理就必须把那个请求头原样透传过去。

5. 模型 id 对不上。 从下拉菜单里选，别手动输入。OpenWebUI 里 Ollama 模型的 id 带有标签（llama3.2:latest），而工作区模型用的是你给它起的 id，不是它的显示名称。

6. OpenWebUI 背后的服务商出了问题。 当上游服务商拒绝请求时，OpenWebUI 会把它的状态码原样传回来。429 来自服务商的速率限制，而不是 OpenWebUI 或 SurfMind。在 OpenWebUI 自己的聊天界面里试一下同一个模型。如果那里也失败，问题就出在上游。

其他报错，速查一览

关于适用于所有自定义端点的通用规则（端口、http 与 https、基础 URL 与完整端点），请看我们的自定义 AI 连接指南。

该用 OpenWebUI、SurfMind，还是两个都用？

这不是一道单选题。

• 只用 OpenWebUI：如果你用 AI 主要是在一个专门的标签页里长时间对话——和知识库里的文档聊天、跑 pipeline、为团队管理模型——它就非常合适。
• 只用 SurfMind：如果你用 AI 大多是从屏幕上正在看的内容出发，而且乐意直接连接服务商或 Ollama 这类本地运行器，它就非常合适。
• 两个都用：如果你已经在 OpenWebUI 的配置上下了功夫，又希望在每个页面上都能用到它，而不必把所有东西再配一遍，那就两者兼用。

分工很简单：OpenWebUI 负责管理你的模型，SurfMind 让你在浏览器里直接使用这些模型。

常见问题

OpenWebUI 有 API 吗？ 有。OpenWebUI API 是一个使用 Bearer token 鉴权的 REST API。大多数工具需要的两个端点是：用于列出模型的 GET /api/models，以及用于聊天的 POST /api/chat/completions，后者接受 OpenAI 风格的请求。

OpenWebUI API 兼容 OpenAI 吗？ 请求和响应格式是兼容的，但路径不是标准路径：OpenWebUI 用的是 /api/chat/completions，而不是 /v1/chat/completions。任何允许你填写完整端点 URL 的客户端（比如 SurfMind）都能用它。

我的 OpenWebUI API key 在哪里找？ 进入 Settings → Account → API keys，点击 Show，再点 Create new secret key。如果找不到这个区域，需要管理员在 Settings → Admin → Authentication 下开启 API Keys，并给你的账号开通 API Keys 权限。

我能在 SurfMind 里使用 OpenWebUI 的工作区模型吗？ 能。工作区模型和其他模型一样，会被 /api/models 列出来。调用它们时，OpenWebUI 会套用它们保存好的设置。

连接 OpenWebUI 会把我的数据发到 SurfMind 的服务器吗？ 使用自定义端点时，SurfMind 会把请求发到你配置的 URL，在这里就是你的 OpenWebUI 服务器。然后由你的 OpenWebUI 服务器转发给你选中的模型。如果那个模型在本地运行，页面内容就始终留在你自己掌控的硬件上。

免费吗？ 免费。SurfMind 的自定义端点不收任何费用，我们也不设使用上限。你只需支付自己的服务商收取的费用，本地模型则分文不花。

还是没搞定？

如果 curl 测试能通过，但 SurfMind 依然无法和你的 OpenWebUI 模型聊天，请发邮件到 wave@surfmind.ai。邮件里请附上你的 API URL（不要带 key）、HTTP 状态码，以及是部分模型还是所有模型都失败。自托管的配置千差万别，这些反馈能帮我们让 SurfMind 和它们配合得更顺畅。

获取 SurfMind →