插件

Libre WebUI 使用插件连接外部 AI 提供商和模型能力，与本地 Ollama 配合使用。

插件类型

类型	用途
聊天/补全	来自提供商 API 的文本和聊天模型
嵌入	用于文档搜索和记忆的向量嵌入
图片生成	图片模型和 ComfyUI 风格后端
文字转语音	语音合成提供商
语音转文字	转录提供商
音频生成	声音和音频生成提供商
视频生成	异步视频生成提供商

插件可公开静态模型映射，并在受支持时从提供商 API 刷新可用模型。

内置提供商系列

Libre WebUI 包含常见服务的提供商定义：

• OpenAI 和 OpenAI 兼容 API
• Anthropic
• Google Gemini
• Groq
• Moonshot AI 的 Kimi Code
• Mistral
• OpenRouter
• Hugging Face
• GitHub Models
• 用于 Apple Silicon 本地推理的 MLX LM
• ComfyUI
• ElevenLabs

提供商目录经常变化。插件支持实时模型发现时，应以界面为当前事实来源。

所有权与授权

插件定义是共享实例配置。所有 /api/plugins 路由都需要身份验证，只有管理员可上传、安装、更新或删除定义。激活与此不同：每位已验证用户只能为自己的账户激活或停用共享插件。该状态存储在 SQLite 中，后端重启后仍保留，不影响其他用户的活跃提供商。

升级时，旧版全局 .status.json 激活列表会一次性复制到现有账户，但仅复制与 Libre WebUI 编译信任锚完全匹配的定义。旧的自定义或遮蔽定义保持隔离且未激活。迁移后创建的账户初始不激活任何插件。

内置定义只有在规范化内容与后端编译哈希匹配时才受信任。可写定义按规范化源路径和完整定义哈希在 SQLite 中批准。管理员安装、更新或重新导入会记录批准；直接更改文件会使其失效。批准和更新在替换文件前清除所有账户的激活状态，因此每位用户都必须重新激活审核后的定义。升级前的自定义定义必须由管理员重新导入，才能出现在目录中、发现模型、接受凭据或执行能力。

插件变量按用途划分。只有管理员可存储已识别的连接路由变量：

endpoint、base_url、api_path、models_endpoint、api_url、image_endpoint、embedding_endpoint、stt_endpoint、tts_endpoint、voice_clone_endpoint、api_mode、model 和 model_id。能力声明的 config.endpoint_variable、config.models_endpoint_variable 或 config.voice_clone_endpoint_variable 即使使用其他名称，也属于连接路由。

非管理员仍可保存温度和流式偏好等生成控制。属于非管理员的旧路由记录会被忽略，不作为已配置值返回，并在该账户完全重置插件变量时删除。这样，之后提升角色也不会悄然恢复休眠路由。

凭据

凭据可来自环境变量或用户设置。

环境示例：

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
GEMINI_API_KEY=...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=sk-or-...
KIMI_API_KEY=...
GITHUB_API_KEY=github_pat_...
ELEVENLABS_API_KEY=...

共享部署通常更适合使用用户级凭据，因为每位用户可控制自己的提供商计费和限制。环境密钥适用于单用户安装、演示或受管部署。

只有请求使用未遮蔽内置插件定义的路由与身份验证投影时，环境密钥才作为回退。导入定义、遮蔽内置 ID 的可写定义或管理员保存的连接路由覆盖，都需要同一账户保存凭据。允许环境回退前，Libre WebUI 会比较根端点、身份验证字段、能力端点与选择器，以及已识别路由变量的定义和默认值。即使旧插件目录与内置目录共享路径（如标准容器布局），编译清单哈希仍为权威；被覆盖的软件包清单不能自行建立信任。

此规则适用于发现、Chat、Work、可用性检查和能力目录，可防止自定义端点或升级前的自定义清单接收操作员管理的密钥。

用户存储的凭据在保存时绑定到有效定义源、完整哈希、身份验证契约、能力端点与选择器，以及有效路由值。更改路由或定义后，旧凭据不可用，直到用户审核新目标并重新保存。没有绑定的旧凭据只在完全匹配的锚定内置路由上接受；首次成功使用会先写入绑定，再返回解密密钥。

OpenAI 兼容提供商

许多提供商公开 OpenAI 兼容 API。插件可定义：

• 完整 API 端点 URL
• API 密钥环境变量
• 聊天端点行为
• 嵌入支持
• 模型发现行为
• 可选模型映射回退

不支持实时发现时，Libre WebUI 使用配置的模型映射。导入插件 JSON 可配置已使用 Libre WebUI 支持协议的提供商：OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 或 Gemini。JSON 本身不能翻译任意专有协议；请求、流式、工具调用或响应格式不同的提供商需要小型后端适配器。

OpenAI 图片生成

内置 OpenAI 提供商在 https://api.openai.com/v1/images/generations 提供 Image API。当前模型为 gpt-image-2。目录还保留已弃用的 gpt-image-1.5、gpt-image-1 和 gpt-image-1-mini ID，以兼容现有部署；新配置应选择 gpt-image-2。

图片生成使用与 Chat 相同的有效 OpenAI 凭据：当前用户保存的密钥，或可信内置提供商的环境回退。它有独立可选 image_endpoint 覆盖，防止自定义 Chat 端点误收图片请求。留空则继承内置 Image API 端点。

图片选择按提供商限定。两个图片插件公开相同模型 ID 时，Libre WebUI 只向图片面板中选定的提供商发送请求。GPT Image 响应使用 Base64 图片数据；Libre WebUI 将其转换为应用内图片并保存到当前用户媒体库。Image API 路由需要身份验证，直接生成请求必须同时包含 pluginId 和 model。n 可设置为 1 到 10 的 JSON 整数；数字字符串和小数在到达提供商前会被拒绝。

Chat Completions 与 Responses API 模式

OpenAI 兼容补全插件可使用 chat_completions 或 responses 请求语义。内置 OpenAI 插件在 设置 → 插件 中提供选择。

连接设置按以下顺序解析：

1. 已配置时使用完整 endpoint 覆盖。
2. base_url 加可选 api_path。
3. 插件旧版 endpoint。

与插件清单端点完全相同的值视为清单默认值，而非覆盖。这避免升级后旧的已存默认值遮蔽新基础 URL。真正的自定义完整端点仍有最高优先级。

Chat Completions 模式默认路径为 /chat/completions，Responses 模式为 /responses。base_url 应为 API 根，例如 https://api.example.com/v1；兼容提供商在其他相对路径公开操作时使用 api_path。完整端点必须包含完整操作路径，并优先于两字段。已知 /chat/completions、/completions 或 /responses 后缀决定请求语义；自定义端点路径保留所选 api_mode。

导入插件 JSON 可提供相同默认值：

{
  "endpoint": "https://api.example.com/v1/chat/completions",
  "api_mode": "responses",
  "base_url": "https://api.example.com/v1",
  "api_path": "/responses"
}

Responses 请求使用 input、max_output_tokens、扁平函数工具、store: false，并请求加密推理内容以无状态继续。完成和流式 Responses 输出会规范化为 Libre WebUI 的 Chat 和 Work 事件格式。只有完整有序 Item 数组不超过 64 Items 和 90 KB 时才保留重放状态；Item 保持精确，字段绝不截断。可重放 Item 需要唯一、非空 ID 和类型；消息、推理和函数调用结构会在发出任何工具调用前验证。过大的 Chat 状态回退到规范化可见历史。Chat 还会丢弃原始函数调用 Item，因为它不持久化对应工具输出。带工具的 Work 响应若没有受限、精确重放状态，会在任何工具副作用前拒绝。

基于 SQLite 的 Chat 存储会随消息加密保留的提供商状态；Work 将纯工具状态存储在消息 API 不返回的隐藏上下文记录中。哈希范围将重放绑定到相同提供商、模型、Responses 模式、最终配置端点和所选凭据的不透明单向指纹。范围变化时（包括 API 密钥轮换），Libre WebUI 回退到规范化消息历史，而不会跨身份验证边界发送提供商特定 Item。活跃 Work 运行也会生成路由和凭据指纹，并在每轮提供商调用前重新验证；更改模式、端点或密钥会在另一请求收到先前工具状态前停止运行。

Work 执行副作用前，带工具状态必须同时符合重放限制和完整 100 KB 持久元数据封装。持久 Work 批次中断时，每个缺失工具结果会以确切调用 ID 和结果未知警告恢复，让提供商检查工作区，而不是盲目重复潜在副作用。未完成 Responses 结果不视为成功 Chat 或 Work 轮次；其 incomplete_details.reason 会保留并显示给调用者。

模型发现从操作路径推导 /models。例如，https://api.example.com/v1/responses 从 https://api.example.com/v1/models 发现。不提供兼容模型列表的提供商仍可使用手动 model_map。发现限定到当前用户变量和凭据；结果按用户持久化，而不写入共享插件清单。激活、显式刷新、API 密钥更改、连接变量更改和变量重置后会运行发现；保存无关生成变量不会触发网络请求。

发现也会自动运行。读取插件列表时，会重新发现目录缺失或早于 PLUGIN_MODEL_DISCOVERY_TTL_MS 的活跃补全提供商，因此重新加载应用能反映当前模型。每提供商退避避免无法访问的提供商在每次请求中被探测，截止时间防止慢提供商延迟响应；超出截止时间的刷新会在下一次请求中提供。最终发现 URL 会在读取用户凭据或构建授权标头前检查，即使来自导入清单。发现和提供商能力请求不跟随 HTTP 重定向。请直接配置最终 Chat、Work、模型列表、图片、嵌入、转录、语音、声音克隆、音频或视频端点，避免凭据从已验证 URL 转发到未验证重定向目标。

提供商端点可使用 HTTP 或 HTTPS。HTTP 会在无传输加密的情况下发送 API 密钥、提示词、工具结果和生成内容，因此只能用于可信网络上的自托管网关；支持 TLS 时优先 HTTPS。请求来自后端：容器部署应使用 http://ai-gateway:8080/v1 等服务 URL，而 localhost 指 Libre WebUI 容器本身。插件能力路由（包括图片生成）按请求账户解析端点变量和凭据。Libre WebUI 没有未验证单用户模式。

能力专属端点

Chat 端点覆盖与图片、嵌入、转录、文字转语音、音频和视频能力隔离。多能力插件可公开 image_endpoint、embedding_endpoint、stt_endpoint、tts_endpoint 或 config.endpoint_variable 命名的其他变量。声音克隆路由也可命名 config.voice_clone_endpoint_variable。字段留空时使用插件声明的能力端点；通用 Chat endpoint 绝不作为能力覆盖。

内置 GitHub Models 插件在可选覆盖为空时继承当前 models.github.ai/inference/chat/completions 端点。Hugging Face 插件为嵌入、图片和文字转语音使用任务专属 hf-inference/models/{model} 路由和载荷，而不是发送到 Chat 端点。

端点覆盖

endpoint 变量是完整请求 URL，包括操作路径。例如，OpenAI 兼容聊天插件通常使用 https://provider.example/v1/chat/completions，而不只是 https://provider.example。导入的旧版配置可能称其为 api_url；Libre WebUI 接受该别名，但两者都有值时非空 endpoint 始终优先。

接受绝对 HTTP 和 HTTPS URL，拒绝其他协议。HTTP 用于可信网络中的自托管网关，因为它在无传输加密时发送凭据和请求内容。离开私有部署边界的路由应优先 HTTPS。覆盖留空时使用插件定义的完整端点；显式无效覆盖会被拒绝，而不会悄然路由到默认值。

提供商请求不跟随重定向。直接配置最终已验证操作 URL；重定向响应会作为提供商错误报告，不把凭据或请求内容转发到下一跳。

请求来自 Libre WebUI 后端。容器中的 localhost 指容器本身，不会自动指向宿主机或其他服务。请使用网关容器服务名，或运行时提供的 host.docker.internal 等宿主机可访问名称。

模型发现

设置 → 插件提供 提供商连接 工作区。左侧搜索并选择提供商，右侧查看活跃状态和有效模型目录。选择 配置 前，提供商配置保持折叠，使端点、凭据和高级生成控制不出现在默认视图。

对聊天和补全提供商，刷新模型 会为所选提供商运行发现，再重新加载插件目录和 Chat 模型列表。目录只读：记录来自当前用户发现的 ID 与插件定义的能力模型映射。能力标签说明哪条插件路由列出模型，而非健康检查。请通过插件 JSON model_map 添加回退或手动模型 ID，不要编辑发现记录。

激活插件时，Libre WebUI 使用该账户的有效端点和凭据尝试模型发现。管理员自定义路由需要同一账户保存凭据；环境回退只用于可信清单路由。对兼容 API，Libre WebUI 从完整端点推导模型列表 URL：

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

无法使用推导 URL 的插件可公开 models_endpoint 作为显式完整模型列表 URL。它优先于推导，受相同出站 URL 策略约束，请求时不跟随重定向。保存或重置 endpoint、api_url、models_endpoint、base_url、api_path 或 api_mode 会在界面重新加载前清除并刷新当前用户发现目录。

所有自定义路由在选择凭据前解析和验证。凭据策略不得为已存自定义路由回退到服务器环境密钥；请为该路由配置按用户密钥。环境回退仅限可信插件定义提供的端点。

发现期望包含模型 ID data 数组的 OpenAI 兼容响应。激活会等待尝试完成，因此首次插件列表刷新可以包含发现目录。成功结果按用户存储并叠加在其插件视图上；Libre WebUI 不重写共享插件 JSON，也不向其他账户公开某用户发现的模型 ID。提供商没有兼容列表、无法访问或返回其他格式时，普通激活保留该用户之前的发现结果。主动更改连接字段会先清除过期目录，因此新路由无法发现时使用插件 model_map 回退。

保存或重置连接路由会在下一次发现尝试前清除账户旧目录，防止从一个目标学习的模型在路由变化后仍可选择。

插件状态、Work 可用性、模型目录和能力路由使用相同用户上下文和凭据边界。例如，图片模型可用性、端点变量和凭据都针对请求用户解析。

Chat 中的精确提供商选择

模型 ID 并非全局唯一。Ollama 模型和多个活跃插件都可能公开 example-model。因此，Chat 将原始模型 ID 与可选提供商身份一起存储：

• providerType: "ollama" 标识本地或已配置 Ollama 路由；
• providerType: "plugin" 加 providerId 标识确切插件。

按提供商限定并进行 URL 编码的值只用作模型选择器中的无冲突键。请求仍发送提供商原始模型 ID。重复的 Ollama/插件和插件/插件模型名保持独立选择，重新打开聊天会恢复保存的确切选择。

显式提供商身份会安全失败。若所选插件停用、移除或不再公布该模型，Libre WebUI 将保存选择显示为不可用，不会悄然切换到同名其他提供商。重新激活提供商或明确选择其他模型后才能再次生成。

存储提供商身份前创建的会话和偏好设置可能没有设置 providerType 和 providerId，或值为 null。这些旧记录为兼容性保留历史按名称路由，因为无法可靠重建原提供商。选择器显示“未记录提供商”，而不会猜测 Ollama 或插件标签。选择具体提供商记录后，后续请求保存精确提供商。新的角色选择保留 persona:<id> UI 身份，并记录为 Ollama 后端。

提供商设置与继承

打开 设置 → 插件，为提供商选择 配置。提供商面板默认关闭。管理员可管理共享定义和连接路由值。其他已验证用户可激活提供商、保存自己的 API 密钥并更改生成控制，但界面不向其公开插件上传、安装、导出、删除或路由控制。

对管理员，连接覆盖优先显示。采样和其他专业控制位于默认也关闭的 高级参数 下。继承的连接和生成值显示为空输入及提供商默认提示。仅打开面板不会把清单默认值复制到账户设置。

保存只发送当前编辑会话中更改的字段。清空已存非敏感值会移除该账户覆盖并恢复提供商默认值；空白的掩码敏感字段保持不变。恢复默认值 移除账户允许管理的所有变量覆盖。保存或重置失败时，编辑器保留未保存值供重试。

此区别对自定义端点很重要：管理员将端点留空以继承内置 URL，或输入完整兼容 URL，为该管理员的提供商连接覆盖。

Work 中的插件

除 Ollama 和 Ollama Cloud 外，Work 还可使用活跃 completion 和 chat 插件。只有满足以下条件才接受插件支持的 Work 运行：

• 插件处于活跃状态；
• 模型存在于当前用户发现目录或插件配置的模型映射中；
• 当前管理员有可用凭据。

Work 在任务和每次运行中保存所选提供商类型和插件 ID。因此路由基于确切保存的提供商，而不只模型名。激活模型名与 Ollama 相同的插件不能悄然重定向现有任务。

Work 通过原生 OpenAI 兼容、Anthropic 和 Gemini 请求/响应格式适配工具调用。即使提供商支持普通聊天补全，所选模型也必须支持工具调用。若提供商拒绝工具或返回不兼容响应，运行失败，不回退到其他提供商。

远程 Work 运行可能发出多次提供商请求。提供商会收到 Work 系统提示词、对话上下文、工具定义和请求的工具结果。工具结果可能包含源文件、目录列表或命令输出。Libre WebUI 在 Work 中显示按用户、可关闭的远程提供商披露；为敏感项目启用服务前，操作员仍应审核提供商定价、保留和训练政策。

嵌入

支持嵌入的插件会出现在文档嵌入设置中。Libre WebUI 还会检测 nomic-embed-text、bge、e5、gte 等可能的 Ollama 嵌入模型。

未发现嵌入模型时，界面回退到 nomic-embed-text 作为本地默认候选。

插件开发说明

插件定义应清晰说明能力，不假装提供商支持其未公开的功能。模型映射应足够小，适合作为回退；对具有快速可靠模型列表 API 的提供商，优先使用发现。

添加提供商时：

1. 添加插件定义。
2. 定义凭据密钥或用户凭据字段。
3. 提供商有模型列表端点时实现模型发现。
4. 为聊天、嵌入、图片、TTS 或 STT 添加请求映射。
5. 测试缺少密钥、错误密钥和提供商错误状态。

相关文档

• 环境变量
• 使用模型
• Work：隔离工作区
• Kimi Code
• Apple Silicon 上的 MLX LM