# Open WebUI 接続

> **最終確認**：2026-10-13 · 📄 公式ドキュメント準拠（Open WebUI v0.12.0）

## 接続の概要

| 項目 | 内容 |
|---|---|
| 利用できるモデル | Claude ❌ **利用不可**（次の 2 節参照）· GPT ✅ · 中国系モデル ✅ · Gemini ❌（QCode は Gemini シリーズを提供していません。GPT または中国系モデルをご利用ください） |
| プロトコルと Base URL | OpenAI Chat Completions のみ：`https://api.qcode.cc/openai/v1` |
| 設定場所 | **Settings → Admin → Connections** の **Manage OpenAI API Connections** 一覧 |
| 公式ドキュメント | [docs.openwebui.com](https://docs.openwebui.com/) |

🔴 **Open WebUI では Claude を使えません。** Open WebUI は OpenAI Chat Completions のリクエストしか送信せず、QCode の Claude モデルは Anthropic プロトコルのエンドポイント専用です ⇒ Claude が必要な場合は、Anthropic プロトコルに対応したツール、または Claude Code をお使いください。ツール別の対応状況は[ツール互換性の一覧](/docs/ide/tool-compatibility)にあります。

Open WebUI は Docker・pip・uv で立てるセルフホスト型のチャット Web インターフェースです。公式ドキュメントは範囲をはっきり書き、「Open WebUI connects to any server or provider that implements the OpenAI-compatible API」と述べ、UI とツール側を Open WebUI が担う代わりに「it expects your backend to follow the universal Chat Completions standard」としています。本ページで確認した版は **v0.12.0**（2026-10-10 公開）。課金はトークン単位で、モデル別の単価は [qcode.cc/models](https://qcode.cc/models) に掲載されています。

## どのプロトコルか

公式が挙げる接続プロトコルはいくつかあります——Ollama、OpenAI 互換 API、そして Open Responses に対する実験的な対応です。本ページが扱うのは **OpenAI Chat Completions** の経路だけで、QCode の OpenAI エンドポイントが提供するのもこのプロトコルです。

| モデル群 | Open WebUI で使えるか | 入力する内容 |
|---|---|---|
| GPT——`gpt-6.1-sol`、`gpt-6-sol`、`gpt-6-astra`、`gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.5` | ✅ | URL に `https://api.qcode.cc/openai/v1` |
| GLM / Kimi / DeepSeek / Qwen——`deepseek-v4.1-flash`、`deepseek-v4-flash`、`deepseek-v4-pro`、`glm-5.3`、`glm-5.2`、`qwen3.8-max`、`qwen3.8-flash`、`qwen3.7-plus`、`kimi-k3` | ✅ | 同じ URL |
| Claude | ❌ **利用不可**——Anthropic プロトコルに対応したツール、または Claude Code をお使いください | QCode の Claude モデルは Anthropic Messages エンドポイント `https://api.qcode.cc/api` 専用で、Open WebUI はこのプロトコルを呼びません |
| Gemini シリーズ | ❌ QCode は提供していません | GPT または中国系モデルへ |

Claude の行が明確に「使えない」である理由を、公式の文言で示します。

- Open WebUI は自身を「a **protocol-centric** platform」と呼び、OpenAI モデルですら「we do so mainly through the **OpenAI Chat Completions API protocol**」の形でサポートしています。境界線について公式は「We do not implement provider-specific, non-standard APIs in the core」と述べ、FAQ でも「We avoid implementing proprietary, provider-specific APIs in the core」と繰り返しています。
- Anthropic の組み込み特例は範囲が狭い。公式の Anthropic ページには「Open WebUI detects Anthropic URLs (any URL containing `api.anthropic.com`)」とあり、その URL に当たっても「Chat requests themselves are sent unchanged to Anthropic's OpenAI-compatible `/v1/chat/completions` with Bearer auth.」——つまり例外でもやはり Chat Completions で、しかも特定のホスト名に紐づきます。QCode の接続アドレスにはこのホスト名は含まれません。
- 同じ版のリリース済みソース（tag `v0.12.0` の `backend/open_webui/config.py`）には OpenAI のベースアドレス関連変数が揃って存在し、`anthropic` を大文字小文字を区別せずに検索しても一致は 0 件です——外部ゲートウェイに向ける Anthropic Messages の送信設定は存在しません。
- 誤読しやすい点が一つあります。Open WebUI 自身は Anthropic Messages 互換エンドポイントを公開していますが、公式の記述は「This allows tools, SDKs, and applications built for the Anthropic API to work directly against Open WebUI」——方向は **Open WebUI の内側へ向かう受信**です。Open WebUI がゲートウェイに対して Anthropic プロトコルのクライアントになるわけではありません。
- Open WebUI が実装していない API を扱う場合、公式の案内は pipe 関数、または LiteLLM のようなプロトコル変換プロキシです。どちらも QCode では検証していないため、本ページでは手順を出しません。今日 Claude が必要なら、Anthropic プロトコルを扱えるクライアントを選んでください。

プロトコル × モデル群の対応表全体は[エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths)にあります。

## インストール

以下の 3 コマンドはすべて公式の Quick Start からの転記です。

**Docker**——公式は Docker を必須とし、`your-secret-key` を `openssl rand -hex 32` の出力に置き換えるよう指示します：

```bash
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data -e WEBUI_SECRET_KEY=your-secret-key --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```

ポートマッピングの読み方について、公式のパラメータ表は「The UI is on port 3000 of your machine. Change the left number if 3000 is taken.」と説明しています。

**pip**：

```bash
pip install open-webui
open-webui serve
```

公式の記述は「Open WebUI is now on [http://localhost:8080](http://localhost:8080). Set `DATA_DIR` to choose where your data lives」。

**uv**（グローバルに入れず実行、macOS/Linux の例）：

```bash
DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve
```

Python のバージョン：「Open WebUI supports **Python 3.11 and 3.12**. **Python 3.13 is not supported yet**」。

## 設定

### 管理者の Connections 画面から（推奨）

1. ブラウザで Open WebUI を開きます。
2. 公式の文どおり、「Go to **Settings > Admin > Connections** and find the **Manage OpenAI API Connections** list.」へ進みます。
3. 「Click ➕ **Add Connection**.」
4. **Connection Type** は External のままにします。
5. **URL**：`https://api.qcode.cc/openai/v1`。公式は「The URL field will **suggest common provider endpoints** as you type」と説明しますが、補完で出るのは他社のアドレスです。QCode のアドレスは最後まで自入力してください。カスタムゲートウェイのアドレス末尾に `/v1` が必要かどうかは公式に書かれていません。ゲートウェイが提示するアドレスをそのまま使い、QCode の場合は `https://api.qcode.cc/openai/v1` で、末尾スラッシュは付けません。
6. **API Key**：あなたの QCode キー（`cr_` 始まり）。
7. **Model IDs**（**Advanced** の中）：モデル選択器に出したい ID を 1 件ずつ追加します。公式の操作説明は「In the connection settings, find **Model IDs**, type the model ID, and click the **+** icon, then save.」接続の検証に成功すると、「the **Model IDs** field suggests the provider's model IDs as you type」。
   この欄が空のうちは自動検出が続きます（「_Default (Empty)_: Auto-detects all available models from the provider.」）。一度入力すると挙動が変わり、「Open WebUI stops calling the provider's `/models` for that connection and lists exactly the IDs you typed」。
8. **Prefix ID**（任意）：公式が前付けを勧めるのは「you connect multiple providers that have models with the same name」の場面で、記述は「Open WebUI joins the prefix and the model ID with a dot」——前置を `qcode`、ID を `glm-5.3` にすると、選択器には `qcode.glm-5.3` と出ます。
9. **Provider**（**Advanced** の中）：**Default** のままで構いません——「Leaving it at **Default** is always safe.」このドロップダウンは OpenAI 接続にしか存在しません。
10. **Save** を押します。保存済みの接続にはそれぞれトグルがあり、削除せずに有効・無効を切り替えられます。

選ぶ ID は[中国系モデル](/docs/usage/cn-models)と[モデル選択](/docs/usage/model-selection)を参照してください。課金はトークン単位、単価は [qcode.cc/models](https://qcode.cc/models) です。

### セルフホストの環境変数

公式は 2 つの経路を同等として扱います——「Open WebUI is configured via environment variables, and you can also set the same values from the Open WebUI admin panel.」

```bash
# 上の docker コマンドに -e で足すか、open-webui serve の前に export する
OPENAI_API_BASE_URL=https://api.qcode.cc/openai/v1
OPENAI_API_KEY=cr_your_qcode_key
```

公式の定義は `OPENAI_API_BASE_URL`「Configures the OpenAI base API URL」（出荷時の既定値は `https://api.openai.com/v1`）、`OPENAI_API_KEY`「Sets the OpenAI API key」。1 つのインスタンスで 2 つのゲートウェイをならべたい場合は `OPENAI_API_BASE_URLS` を使い、公式の説明は「Supports balanced OpenAI base API URLs, semicolon-separated.」

同じページから注意点を 2 つ：

- これらの変数は `ConfigVar` 指定で、「After the initial launch, if you restart the container, `ConfigVar` environment variables will no longer use the external environment variable values. Instead, they will use the internally stored values.」初回起動前に設定するか、その後は管理画面で変更してください。
- この参照ページは自分自身を「is up-to-date with Open WebUI release version [v0.11.1]」としていますが、本ページで確認したのは v0.12.0 です。アップグレード後は変数名を改めて確かめてください。

### 中国系モデル

中国系ファミリーはこの OpenAI 互換接続でいずれも利用できます：`deepseek-v4.1-flash`、`deepseek-v4-flash`、`deepseek-v4-pro`、`glm-5.3`、`glm-5.2`、`qwen3.8-max`、`qwen3.8-flash`、`qwen3.7-plus`、`kimi-k3`。使う ID を **Model IDs** に入れ、差異は[中国系モデル](/docs/usage/cn-models)で確認してください。

## 動作確認

公式が期待値をはっきり示しています——「**Saving a connection does not test it.**」URL 横のボタンについても原文があります：「Clicking the **Verify Connection** button beside the URL field calls the provider's `/models` endpoint using a standard `Bearer` token and reports **Server connection verified**」。そのエンドポイントを実装していない、または認証方式が違うプロバイダでは「The connection verification will **fail with an error** (e.g., 400, 401 or 403).」となり、「This does **not** mean the provider is incompatible: **chat completions will still work**.」公式の対処は手動追加です——「You just need to **manually add model names** to the **Model IDs** allowlist in the connection settings.」

実務上の手順：

1. 使う ID を **Model IDs** に入れてください。検証ボタンの結果にかかわらず、こちらが確実な経路です。
2. ホワイトリストのモデルを 1 つ選んでチャットでひとこと送信します。この往復が実質的なテストです。
3. QCode 側と Open WebUI 側を切り分けたければ、エンドポイントを直接叩けます：

```bash
curl -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $QCODE_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"deepseek-v4.1-flash","messages":[{"role":"user","content":"ping"}]}'
```

今回の検証用キーは持っていないため、冒頭のマークは 📄 のみです。本ページはステータスコードもレスポンス内容も主張しません。ご自分のリクエストで返った結果は[トラブルシューティング](/docs/reference/troubleshooting)と見比べてください。

## 既知の制限

| 症状 | 公式の原文 | 対処 |
|---|---|---|
| モデル一覧が空、または一部足りない | `/models` の役割は「Used for model discovery and selecting models in the UI. If not available, add models to the allowlist manually.」 | **Model IDs** に各 ID を追加 |
| 一覧取得が遅い、到達不能なアドレスを保存して UI が重くなる | 「Raise the timeout for slower connections. The default is 10 seconds, and an empty value disables it」例：`AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=30` | 変数を設定、または誤ったアドレスを消す |
| コンテナからホストのマシンが見えない | 「If running Open WebUI in Docker and your model server is on the host machine, replace `localhost` with `host.docker.internal` in the URL.」 | URL を書き換える |
| 管理者の接続だけ失敗し、ユーザー自身の接続は通る | 公式は「502 Bad Gateway on admin-configured connections while user connections work fine」を挙げ、管理者・グローバル要求では「the Open WebUI backend resolves that hostname, and inside a Docker container, it may resolve to `127.0.0.1`」と説明。公式の指示は「For backend/admin connections, use the **internal URL** that the backend can actually reach」 | ブラウザが見るアドレスではなく、バックエンドが解決するアドレスを確かめる |
| pip や uv での導入が失敗する | 「Open WebUI supports **Python 3.11 and 3.12**. **Python 3.13 is not supported yet**」 | 3.11 か 3.12 を使う |
| 他の接続タイプで Provider のドロップダウンが見つからない | 「The **Provider** dropdown belongs to OpenAI connections only.」 | 他の接続では提供されません |

QCode 側でも知っておいてほしい制限：

- **このツールでは Claude が使えません**：QCode は OpenAI 互換エンドポイントに Claude の経路を用意しておらず、Claude のリクエストは Anthropic Messages エンドポイント側のもので、Open WebUI はそのプロトコルを呼びません。Claude は、Anthropic プロトコルに対応したツール、または Claude Code をお使いください——[ツール互換性の一覧](/docs/ide/tool-compatibility)参照。
- QCode は `gpt-6-luna` / `gpt-5.6-luna` を提供していません。Gemini シリーズも同様です。`gpt-6.1-sol`、`gpt-6-sol`、`gpt-5.6-terra` または中国系モデルをご利用ください。
- **Direct Connections**（ユーザーのブラウザがプロバイダへ直接つながる機能）は公式に「currently **experimental**」とされ、既定は無効で管理者のスイッチが必要です——「**Settings > Admin > Connections > Direct Connections**: Toggle **On**」または `ENABLE_DIRECT_CONNECTIONS=true`（公式の説明は「Enables or disables direct connections.」）。この経路ではキーがクライアント側に置かれます——「keys are stored in the browser's local storage」。ブラウザが直接リクエストを送るため、公式は「the API provider must have **Cross-Origin Resource Sharing (CORS)** configured to allow requests from your Open WebUI domain」を要求します。QCode があなたのドメインに対するブラウザ直結に応えるかは本ページで未検証なので、管理者接続を推奨経路としてください。
- 本ページのどこにも実キーでの実行はありません。項目名、メニューの階層、変数名、コマンドはすべて公式ドキュメントからの転記で、QCode のエンドポイント値は[エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths)に基づきます。

## 関連ドキュメント

- [エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths)——どのモデル群がどのプロトコルで使えるか
- [ツール互換性の一覧](/docs/ide/tool-compatibility)——Claude が必要なとき、Anthropic プロトコル対応のツールを選ぶ
- [中国系モデル](/docs/usage/cn-models)——GLM / Kimi / DeepSeek / Qwen の ID と違い
- [モデル選択](/docs/usage/model-selection)——用途別に ID を決める
- [トラブルシューティング](/docs/reference/troubleshooting)——QCode 側のエラーの確認
- [Cherry Studio 接続](/docs/ide/cherry-studio)——Anthropic タイプの接続を持つクライアント
- [SillyTavern 接続](/docs/ide/sillytavern)——別の OpenAI 互換クライアント