サードパーティおよびセルフホスト型プロバイダーに接続

Libre WebUI 0.16.0 では、設定 > プラグイン内に専用のプロバイダー接続ワークスペースが追加されました。同梱プロバイダーの有効化、互換プラグインの別 API への接続、実際に有効なモデルカタログの確認、信頼できるネットワーク上のセルフホスト型ゲートウェイへの接続に利用できます。

プロバイダー検索と選択、接続操作、モデル更新、プロバイダーを識別した機能カタログを表示する Libre WebUI のプロバイダー接続。

現在の Libre WebUI は、次のプロバイダー通信形式に対応しています。

OpenAI Chat Completions。
OpenAI Responses。
Anthropic Messages。
Google Gemini の contents と function calling。

同梱の Anthropic および Gemini 定義では、それぞれのプロバイダー ID で選ばれる専用アダプターを使用します。新しくインポートしたプロバイダーは、OpenAI Chat Completions または OpenAI Responses のセマンティクスを使用します。Anthropic または Gemini 互換 API を指定しても、これらの同梱アダプターは選択されません。リクエスト、ストリーミング、ツール呼び出し、応答の形式が異なるプロバイダーには、バックエンドアダプターが必要です。プラグイン JSON が記述するのはルーティングと設定であり、無関係なプロトコルを変換するものではありません。

プロバイダー接続を開く

サインインして、設定 > プラグインを開きます。
左側のペインでプロバイダー一覧を検索します。
プロバイダーを選び、有効状態と実際のモデルカタログを確認します。
自分のアカウントでプロバイダーを有効にします。
資格情報を保存するか接続設定を上書きするときだけ、設定を選択します。

プロバイダー設定はデフォルトで閉じています。管理者には接続設定が先に表示され、Temperature やトークン上限などのサンプリングコントロールは、別に折りたたまれた詳細パラメーターセクションに残ります。継承したデフォルトは、アカウントの上書きとして事前入力されず、ヒントとして表示されます。

プラグイン定義はインスタンス全体で共有する設定なので、インポート、インストール、更新、削除を行えるのは管理者だけです。各認証済みユーザーは、自分の有効化状態、資格情報、許可された生成設定を管理します。

接続をすばやく追加する

一般的な 1 つの OpenAI 互換エンドポイントと 1 つの API キーという構成には、設定 > 接続が短い経路です。管理者には、状態とバージョンを表示するローカル Ollama ランタイムのカード、既存の OpenAI 互換接続一覧、新しい接続を追加する小さなフォームが表示されます。

接続の追加には、表示名、完全な chat completions URL、任意の API キーを指定します。Libre WebUI は名前から接続 ID を生成し、プロバイダー定義をインストールし、キーをサーバー側に保存して接続を有効化し、そのエンドポイントが提供するモデルを問い合わせます。検出されたモデルが仮のカタログを置き換え、チャットのモデル選択画面に表示されます。

各行には、エンドポイント、モデル数、キー保存の有無、有効化スイッチ、モデル更新、削除があります。response API モード、ベース URL の上書き、機能ごとのカタログ、生成パラメーターのポリシーなど、それ以上の設定は上記の設定 > プラグインワークスペースで行います。

Codex（ChatGPT でサインイン）

同梱の Codex (ChatGPT) プロバイダーには API キーが不要です。サーバーの OS ユーザーで Codex CLI にサインインしている場合（codex login）、このプロバイダーが管理者に表示され、文書化された Codex モデルファミリーを ChatGPT セッション経由で利用できます。アクセストークンは CLI 自身の auth.json から読み取り、CLI と同じ 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"]
}

設定 > プラグインからファイルをインポートし、有効化して、この接続を使うアカウント用の API キーを保存します。管理者がベース URL、パス、検索、機能固有のエンドポイントを編集する必要がある場合は、定義に接続変数を追加します。同梱の plugins/openai.json が完全な例です。

信頼できるネットワーク上で意図的に認証なしのゲートウェイを使う場合、auth.header と auth.key_env の両方を空文字列にし、auth.prefix は省略します。この場合、Libre WebUI はそのプラグインで API キーを要求も送信もしません。

Chat Completions と Responses を選ぶ

OpenAI 互換の補完プラグインでは、次のどちらかの API モードを利用できます。

API モード	デフォルトのリクエストパス	一般的なリクエストフィールド
`chat_completions`	`/chat/completions`	`messages`
`responses`	`/responses`	`input`

同梱の OpenAI プロバイダーは、設定に API モードを表示します。Libre WebUI は、完了した Responses 出力とストリーミング中の出力を Chat と Work へ対応付けます。推論とツール呼び出し用の、上限付き再生状態も含まれます。

モードを変更すると、デフォルトの操作パスが変わります。上流サーバーが話すプロトコルは変わらないので、サーバーが互換性のある Responses のリクエスト形式とイベント形式を実装している場合だけ Responses を選択してください。

ベース URL または完全なエンドポイントを設定する

Libre WebUI は、次の優先順で補完経路を解決します。

デフォルトではない完全な endpoint の上書き。
base_url と任意の api_path。
プラグイン定義で宣言されたエンドポイント。

API ルートにはベース 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 エンドポイントサフィックスも、リクエストのセマンティクスを識別します。未認識のカスタム操作パスでは、明示的に選択した API モードを維持します。

経路または API キーを変更した後は、Chat でテストする前にプロバイダーをもう一度保存してください。プラグインが認証を宣言している場合、カスタム接続経路には同じアカウントで保存した資格情報が必要です。意図的に認証なしのプラグインでは、両方の認証フィールドを空のままにできます。Libre WebUI は、運用担当者が管理する環境変数のキーをユーザー定義の宛先へ送信しません。環境変数によるフォールバックは、信頼済みの同梱経路だけに限られます。

モデル ID を検索または管理する

有効なチャットプロバイダーを選び、モデルを更新を実行すると検索が行われます。Libre WebUI は、選択したプロバイダーのカタログと Chat のモデル一覧の両方を再読み込みします。

検索は手動操作なしでも実行されます。有効なプロバイダーのカタログがないか、PLUGIN_MODEL_DISCOVERY_TTL_MS を超えて古くなると再検索されます。そのため、表示されるモデルは有効化した時点ではなく、プロバイダーの現在の状態に追随します。モデルを更新すると即座に確認し、結果を報告します。

結果	意味
カタログを更新	プロバイダーが応答し、モデル一覧が保存済みの一覧と異なる
カタログは最新	プロバイダーが同じ一覧を返した
API キーが必要	使用可能なキーがなく、リクエストは未送信。以前のカタログを引き続き表示
カタログを読み込めない	プロバイダーに到達できないか、有効な内容が返されなかった

インストール済み定義を使うプロバイダーでは、同梱定義と異なり、環境変数だけで設定したキーは使用されません。該当する場合は、その旨がメッセージに表示されます。プロバイダーのカタログで見つかった音声、画像、埋め込みモデルは、機能ラベル付きでここに掲載されますが、チャットのモデル選択画面からは除外されます。

OpenAI 互換経路のモデル一覧 URL は、次のように決まります。

/models で終わる経路は、そのまま使用。
/chat/completions、/completions、/responses、/embeddings、/messages など既知の操作サフィックスは /models に置換。
それ以外では、経路に /models を付加。

たとえば、次の 2 つの補完経路は、どちらも同じ検索 URL になります。

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

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

正しい完全 URL を導出できない場合は、プラグインの variables 配列で models_endpoint を公開します。

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

継承したデフォルトまたは管理者が保存した値は、導出したアドレスより優先されます。トップレベルの models_endpoint マニフェストプロパティは読み取られません。検索では、data 配列内にモデルオブジェクトがある OpenAI 互換応答を想定します。

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

検出された ID はユーザーごとに保存され、共有プラグインファイルを書き換えません。プロバイダーが互換検索を実装していない場合は、プラグイン JSON の model_map にフォールバック用モデル ID を維持します。プロバイダー接続のカタログは読み取り専用です。機能ラベルは、どのプラグイン経路がモデルを掲載しているかを示すもので、ヘルスチェックではありません。

モデル ID は全体で一意ではありません。Chat は元のモデル ID と、正確な Ollama またはプラグインのプロバイダー ID を一緒に保存します。そのため、Ollama モデルと複数のプラグインが同じ名前を安全に公開できます。保存済みプロバイダーが利用できなくなった場合、Libre WebUI は別のプロバイダーへ黙ってルーティングせず、その選択を利用不可として表示します。

画像生成を個別に設定する

同梱の OpenAI プロバイダーは https://api.openai.com/v1/images/generations を通じて画像生成を公開し、新しい設定のデフォルトは現在 gpt-image-2 です。以前の GPT Image ID は、互換性のある既存デプロイ向けにフォールバックカタログへ残ります。

Chat と画像の経路は意図的に分離されています。カスタムの Chat ベース URL が自動的に画像リクエストを受け取ることはありません。プラグインで宣言された画像エンドポイントを使うには image_endpoint を空のままにします。プロバイダーが対応している場合は、完全な互換 Image API 操作 URL を設定します。

画像の選択も Chat と同様にプロバイダーを識別して保存されます。有効な 2 つのプラグインが同じ画像モデル ID を公開している場合、Libre WebUI は画像パネルで選択されたプロバイダーだけにリクエストを送ります。

HTTP ゲートウェイへ安全に接続する

プロバイダーのエンドポイントには、絶対 HTTP または HTTPS URL を使用できます。HTTP は、信頼できる LAN、Tailscale ネットワーク、プライベートコンテナネットワーク上のセルフホスト型ゲートウェイに便利ですが、API キー、プロンプト、ツール結果、生成コンテンツが通信経路で暗号化されません。経路がネットワーク境界を越える場合、またはゲートウェイが TLS に対応している場合は HTTPS を優先してください。

リクエストはブラウザではなく Libre WebUI バックエンドから発信されます。そのバックエンドから到達可能なアドレスを選んでください。

バックエンドの場所	プロバイダールートの例
同じマシンのネイティブプロセス	`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 が受け付けるプロバイダー URL は HTTP と HTTPS だけです。資格情報を選択する前に最終的な宛先を検証し、プロバイダーまたは検索リクエストのリダイレクトには従いません。最終的な操作 URL を直接設定してください。

有効化する前にゲートウェイを検証する

Libre WebUI バックエンドを実行するマシンまたはコンテナから、モデル検索をテストします。

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

次に、選択した API モードに合う操作をテストします。

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 コンセプトが、ワークフローの設計に役立ちました。

プロバイダー接続を開く​

接続をすばやく追加する​

Codex（ChatGPT でサインイン）​

同梱またはインポート済みのプロバイダーを選ぶ​

Chat Completions と Responses を選ぶ​

ベース URL または完全なエンドポイントを設定する​

モデル ID を検索または管理する​

画像生成を個別に設定する​

HTTP ゲートウェイへ安全に接続する​

有効化する前にゲートウェイを検証する​

トラブルシューティング​

コミュニティへの謝辞​

関連ドキュメント​