连接第三方与自托管提供商

Libre WebUI 0.16.0 在设置 > 插件中新增专门的提供商连接工作区。你可以 启用内置提供商、让兼容插件指向其他 API、检查有效模型目录，或在可信网络连接 自托管网关。

Libre WebUI 当前支持以下提供商线协议：

• OpenAI Chat Completions；
• OpenAI Responses；
• Anthropic Messages；以及
• Google Gemini contents 和 function calling。

内置 Anthropic 和 Gemini 定义使用由提供商身份选择的专用适配器。新导入提供商使用 OpenAI Chat Completions 或 Responses 语义；指向兼容 Anthropic/Gemini 的 API 不会选择内置适配器。其他请求、流式、工具调用或响应形状需要后端适配器。插件 JSON 描述路由和配置，不翻译无关协议。

打开提供商连接

1. 登录并打开设置 > 插件。
2. 在左侧搜索提供商。
3. 选择提供商，查看激活状态和有效模型目录。
4. 为账户激活提供商。
5. 只有需要保存凭据或覆盖连接设置时才选择配置。

提供商配置默认折叠。管理员首先看到连接设置；温度和令牌限制等采样控件位于单独折叠 的高级参数。继承默认值显示为提示，而不是预填账户覆盖值。

插件定义是实例共享配置，因此只有管理员能导入、安装、更新或删除。每个已认证用户 控制自己的激活状态、凭据和允许的生成设置。

快速添加连接

设置 > 连接是常见情况的快捷路径：一个兼容 OpenAI 的端点和一个 API 密钥。 管理员可看到本地 Ollama 运行时的健康和版本、现有连接列表以及添加表单。

添加时提供显示名称、完整聊天补全 URL 和可选 API 密钥。Libre WebUI 从名称派生 连接 ID，安装定义，在服务器保存密钥，激活连接并询问端点提供哪些模型。发现的模型 替换占位目录并出现在聊天选择器中。

每行显示端点、模型数、密钥状态、激活、刷新和删除。Responses 模式、基础 URL、 按能力目录和生成参数政策仍在完整插件工作区中。

Codex（ChatGPT 登录）

内置 Codex (ChatGPT) 提供商无需 API 密钥。服务器有 Codex CLI 登录 （以服务器系统用户运行 codex login）时，它会向管理员显示，并通过 ChatGPT 会话提供文档中的 Codex 模型系列。访问令牌从 CLI 的 auth.json 读取，使用同一 OAuth 客户端刷新并写回，让 CLI 保持工作；令牌值绝不进入日志。

请求来自后端而非任务容器，因此这些模型也能通过正常沙箱工具循环驱动 Work。 提供商仅限管理员，因为每次调用消耗服务器所有者的 ChatGPT 订阅。可用 CODEX_OAUTH_MODELS_ENABLED=false 完全隐藏，或用 CODEX_HOME 指向其他登录。

选择内置或导入提供商

Libre WebUI 包含 OpenAI、Anthropic、Gemini、Groq、Mistral、OpenRouter、 Moonshot AI 的 Kimi Code、Hugging Face、GitHub Models、本地 MLX LM 等定义。 协议和认证契约匹配时优先使用内置条目。

其他兼容服务可由管理员导入插件 JSON。最小 OpenAI 兼容网关示例：

{
  "id": "private-ai-gateway",
  "name": "Private AI Gateway",
  "type": "completion",
  "endpoint": "http://ai-gateway:8080/v1/chat/completions",
  "api_mode": "chat_completions",
  "auth": {
    "header": "Authorization",
    "prefix": "Bearer ",
    "key_env": "PRIVATE_AI_GATEWAY_API_KEY"
  },
  "model_map": ["gateway-chat"]
}

从设置 > 插件导入、激活，并为使用账户保存密钥。管理员需要可编辑基础 URL、 路径、发现或能力端点时，在定义中添加连接变量。内置 plugins/openai.json 是完整示例。

对于可信网络中明确无认证的网关，把 auth.header 和 auth.key_env 设为空字符串， 省略 auth.prefix；Libre WebUI 就不会要求或发送密钥。

选择 Chat Completions 或 Responses

OpenAI 兼容补全插件支持两种模式：

API 模式	默认请求路径	常用请求字段
chat_completions	/chat/completions	messages
responses	/responses	input

内置 OpenAI 提供商在配置中显示 API 模式。Libre WebUI 把完成和流式 Responses 输出映射回 Chat 和 Work，包括受限的推理及工具调用重放状态。

更改模式会影响默认操作路径，不会改变上游协议。仅当服务器实现兼容 Responses 请求和 事件形状时选择该模式。

配置基础 URL 或完整端点

补全路由解析顺序：

1. 非默认完整 endpoint 覆盖。
2. base_url 加可选 api_path。
3. 插件定义声明的端点。

基础 URL：

https://gateway.example/v1

无自定义路径时，Chat Completions 发送到：

https://gateway.example/v1/chat/completions

Responses 发送到：

https://gateway.example/v1/responses

提供商在根下其他路径暴露兼容操作时使用API 路径。只有必须提供完整操作 URL 时才使用旧完整端点；真正完整端点优先于基础 URL 和 API 路径。

已知后缀 /chat/completions、/completions、/responses 也识别请求语义。 未知自定义路径保留明确选择的模式。

路由或密钥变化后先重新保存再测试 Chat。声明认证的插件在自定义路由上要求同一账户 保存凭据。明确无认证插件可留空。Libre WebUI 不把运维环境密钥发送到用户定义目的地； 环境后备仅限可信内置路由。

发现或维护模型 ID

选择活动聊天提供商并点击刷新模型。Libre WebUI 会重新加载提供商目录和 Chat 模型列表。

活动目录缺失或超过 PLUGIN_MODEL_DISCOVERY_TTL_MS 时也会自动重新发现。 刷新模型强制立即检查：

结果	含义
目录已更新	提供商响应且模型列表有变化
目录已是最新	提供商响应了相同列表
需要 API 密钥	没有可用密钥；未发请求，仍显示旧目录
无法加载目录	提供商不可达或没有返回可用内容

仅在环境中设置的密钥不会用于安装定义而非内置定义；消息会说明。发现的语音、图像和嵌入 模型会带能力标签列出，但不进入聊天选择器。

OpenAI 兼容路由的模型列表 URL：

• 以 /models 结尾则原样使用；
• /chat/completions、/completions、/responses、/embeddings、/messages 等已知操作后缀替换为 /models；
• 否则附加 /models。

以下两个路由导出同一 URL：

https://gateway.example/v1/chat/completions
https://gateway.example/v1/responses

-> https://gateway.example/v1/models

无法正确派生时，在插件 variables 中公开 models_endpoint：

{
  "name": "models_endpoint",
  "type": "string",
  "label": "Models Endpoint",
  "default": "https://gateway.example/v1/models"
}

继承默认值或管理员保存值优先。顶层 models_endpoint 属性不读取。发现期望兼容 OpenAI 的响应，其中 data 数组含模型对象：

{
  "data": [{ "id": "gateway-chat" }, { "id": "gateway-code" }]
}

发现的 ID 按用户存储，不重写共享插件文件。不支持兼容发现时，在 JSON model_map 维护后备 ID。提供商连接目录只读；能力标签表示哪个插件路由列出模型，不是健康检查。

模型 ID 非全局唯一。Chat 保存原始 ID 和准确 Ollama/插件身份，因此可安全同名。 提供商不可用时显示选择不可用，不会静默路由到其他提供商。

单独配置图像生成

内置 OpenAI 提供商通过 https://api.openai.com/v1/images/generations 提供图像， 新配置当前默认 gpt-image-2。旧 GPT Image ID 仍保留在后备目录。

Chat 和图像路由明确隔离。自定义 Chat 基础 URL 不自动接收图像请求。将 image_endpoint 留空使用插件声明端点，或设为完整兼容 Image API URL。

图像选择同样按提供商标识。两个插件暴露相同 ID 时，只发送给图像面板所选提供商。

安全连接 HTTP 网关

提供商端点可用绝对 HTTP 或 HTTPS URL。HTTP 适合可信 LAN、Tailscale 或私有容器网， 但会无传输加密发送密钥、提示词、工具结果和生成内容。跨网络边界时优先 HTTPS。

请求来自后端而非浏览器，应选择后端可达地址：

后端位置	提供商根示例
原生进程，同一机器	http://127.0.0.1:8081/v1
Docker Compose 服务	http://ai-gateway:8080/v1
容器到受支持主机	http://host.docker.internal:8081/v1
可信 LAN/Tailscale 主机	http://192.168.1.20:8081/v1

容器内 localhost 指 Libre WebUI 容器自身，不是其他 Compose 服务或主机。

Libre WebUI 仅接受 HTTP/HTTPS，在选择凭据前验证最终目的地，不跟随提供商或发现请求 重定向。请直接配置最终操作 URL。

激活前验证网关

从运行后端的机器或容器测试模型发现：

curl http://ai-gateway:8080/v1/models \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY'

再测试所选模式操作。

Chat Completions：

curl http://ai-gateway:8080/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "messages": [{"role": "user", "content": "Reply with: ready"}],
    "stream": false
  }'

Responses：

curl http://ai-gateway:8080/v1/responses \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "input": "Reply with: ready",
    "store": false
  }'

两者成功后，在提供商连接中配置相同路由、模式、凭据和模型 ID。激活、刷新模型， 在 Chat 选择按提供商标识的模型。可靠支持工具调用时 Work 也可使用。

故障排除

症状	检查
请求仍到内置端点	删除陈旧完整端点覆盖，保存所需基础 URL 和 API 路径
提供商收到错误负载	使 API 模式匹配 Chat Completions 或 Responses，并检查最终后缀
刷新模型无 ID	测试 /models、验证 data[].id、配置 models_endpoint 或维护 model_map
路由编辑后旧模型仍在	保存更改；Libre WebUI 会在刷新前清除该用户旧发现目录
报告缺少 API 密钥	为自定义路由保存用户凭据；内置环境后备不跟随覆盖
Docker 无法访问 localhost	使用网关 Compose 服务名、受支持主机别名或可达私网地址
Chat 正常但图像不工作	单独配置完整 image_endpoint 并选择图像能力模型
Chat 正常但 Work 拒绝模型	确认兼容工具调用；普通文本补全不足
提供商返回重定向	直接配置最终验证 URL；Libre WebUI 不跟随重定向

路由、凭据、重放状态和授权详情见插件；部署故障见 故障排除。

社区致谢

本指南和 Libre WebUI 0.16.0 提供商连接体验受益于 ZhengJin (@fangzhengjin) 的详细第三方提供商反馈， 以及 #163 中 AI 辅助 UX 概念，帮助定义了该流程。

相关文档

• 插件
• 使用模型
• Apple Silicon 上的 MLX LM
• Work：隔离工作区
• 故障排除