# یکپارچه‌سازی Open WebUI

> **آخرین بررسی**: 2026-10-13 · 📄 بر پایه مستندات رسمی (Open WebUI v0.12.0)

## در یک نگاه

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ❌ **در دسترس نیست** (دو بخش بعدی را ببینید) · GPT ✅ · مدل‌های چینی ✅ · Gemini ❌ — QCode خانواده Gemini را ارائه نمی‌دهد، در عوض از یک مدل GPT یا چینی استفاده کنید |
| پروتکل و Base URL | فقط OpenAI Chat Completions: `https://api.qcode.cc/openai/v1` |
| محل پیکربندی | **تنظیمات → مدیریت → اتصال‌ها**، در فهرست **مدیریت اتصال‌های API OpenAI** |
| مستندات رسمی | [docs.openwebui.com](https://docs.openwebui.com/) |

🔴 **Claude در Open WebUI در دسترس نیست.** Open WebUI فقط درخواست‌های OpenAI Chat Completions را می‌فرستد و QCode مدل‌های Claude خود را منحصراً روی نقطه پایانی Anthropic Messages ارائه می‌دهد — برای Claude از ابزاری استفاده کنید که با پروتکل Anthropic صحبت می‌کند، یا از Claude Code. نمای کلی هر ابزار در [سازگاری ابزارها](/docs/ide/tool-compatibility) آمده است.

Open WebUI یک رابط وب چت خودمیزبان است که آن را با Docker، pip یا uv اجرا می‌کنید. مستندات خودش دامنه را صریح بیان می‌کند: Open WebUI «به هر سرور یا ارائه‌دهنده‌ای که API سازگار با OpenAI را پیاده‌سازی کند متصل می‌شود»، و در حالی که Open WebUI رابط و ابزارها را مدیریت می‌کند، «انتظار دارد بک‌اند شما از استاندارد جهانی Chat Completions پیروی کند». نسخه بررسی‌شده در اینجا **v0.12.0** است که در 2026-10-10 منتشر شده است. قیمت‌گذاری به‌ازای هر توکن است؛ نرخ هر مدل در [qcode.cc/models](https://qcode.cc/models) فهرست شده است.

## کدام پروتکل

مستندات چندین پروتکل اتصال را فهرست می‌کند — Ollama، APIهای سازگار با OpenAI، و پشتیبانی آزمایشی از Open Responses. این صفحه فقط مسیر **OpenAI Chat Completions** را پوشش می‌دهد که همان مسیری است که نقطه پایانی OpenAI در QCode ارائه می‌دهد.

| خانواده مدل | در 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 خانواده Gemini را ارائه نمی‌دهد | از یک مدل GPT یا چینی استفاده کنید |

دلیل اینکه ردیف Claude یک «نه» قطعی است، به زبان خود پروژه:

- Open WebUI خودش را «یک پلتفرم **پروتکل‌محور**» می‌نامد و حتی برای مدل‌های OpenAI نیز «این کار را عمدتاً از طریق **پروتکل API OpenAI Chat Completions** انجام می‌دهیم». مستندات درباره این مرز صریح است: «ما APIهای مخصوص ارائه‌دهنده و غیراستاندارد را در هسته پیاده‌سازی نمی‌کنیم»، و پرسش‌های متداول تکرار می‌کند: «ما از پیاده‌سازی APIهای اختصاصی و مخصوص ارائه‌دهنده در هسته اجتناب می‌کنیم».
- حالت ویژه داخلی Anthropic محدود است. راهنمای رسمی Anthropic: «Open WebUI نشانی‌های Anthropic را تشخیص می‌دهد (هر URLی که شامل `api.anthropic.com` باشد)» — و حتی برای چنین URLی، «خود درخواست‌های چت بدون تغییر به `/v1/chat/completions` سازگار با OpenAI در Anthropic با احراز هویت Bearer فرستاده می‌شوند». حالت ویژه همچنان Chat Completions است، وابسته به یک نام میزبان مشخص، و نشانی اتصال QCode آن را ندارد.
- در سورس منتشرشده همان نسخه (`backend/open_webui/config.py` در تگ `v0.12.0`)، همه متغیرهای Base URL مربوط به OpenAI وجود دارند، در حالی که جست‌وجوی غیرحساس به بزرگی و کوچکی حروف برای `anthropic` هیچ نتیجه‌ای برنمی‌گرداند — هیچ تنظیمات خروجی Anthropic Messages برای اشاره به یک دروازه وجود ندارد.
- جزئیاتی که اشتباه خوانده می‌شود: Open WebUI نقطه پایانی سازگار با Anthropic Messages مخصوص خودش را ارائه می‌دهد، اما مستندات هدف آن را چنین بیان می‌کنند: امکان دادن به «ابزارها، SDKها و برنامه‌هایی که برای API Anthropic ساخته شده‌اند تا مستقیماً در برابر Open WebUI کار کنند» — جهت آن **به سمت داخل** است. این کار Open WebUI را به کلاینتی با پروتکل Anthropic برای ارائه‌دهنده شما تبدیل نمی‌کند.
- جایی که یک ارائه‌دهنده با APIی صحبت می‌کند که Open WebUI آن را پیاده‌سازی نمی‌کند، مسیر مستندشده یک تابع pipe یا یک پروکسی ترجمه مانند LiteLLM است. هیچ‌کدام را در برابر QCode بررسی نکرده‌ایم، بنابراین این صفحه هیچ دستورالعمل مشابهی ارائه نمی‌دهد — اگر امروز به Claude نیاز دارید، کلاینتی انتخاب کنید که با پروتکل Anthropic صحبت می‌کند.

برای جدول کامل پروتکل × خانواده مدل، [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) را ببینید.
## نصب

هر سه فرمان زیر از شروع سریع رسمی کپی شده‌اند.

**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
```

خواندن نگاشت پورت: جدول پرچم رسمی می‌گوید «رابط کاربری روی پورت 3000 ماشین شما است. اگر 3000 اشغال است، عدد سمت چپ را تغییر دهید.»

**pip**:

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

طبق مستندات، «Open WebUI اکنون روی [http://localhost:8080](http://localhost:8080) است. `DATA_DIR` را تنظیم کنید تا محل نگهداری داده‌هایتان را انتخاب کنید».

**uv** (بدون نصب سراسری؛ نمونه macOS/Linux):

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

نسخه‌های Python: «Open WebUI از **Python 3.11 و 3.12** پشتیبانی می‌کند. **Python 3.13 هنوز پشتیبانی نمی‌شود**.»

## پیکربندی

### مسیر اتصال‌های مدیر (توصیه‌شده)

1. Open WebUI را در مرورگر خود باز کنید.
2. همان‌طور که مستندات می‌گوید، «به **Settings > Admin > Connections** بروید و فهرست **Manage OpenAI API Connections** را پیدا کنید.»
3. «روی ➕ **Add Connection** کلیک کنید.»
4. **Connection Type** را روی External نگه دارید.
5. **URL**: `https://api.qcode.cc/openai/v1`. راهنمای رسمی اشاره می‌کند که «فیلد URL هنگام تایپ، **نقاط پایانی رایج ارائه‌دهنده** را پیشنهاد می‌دهد» — این پیشنهادها نشانی‌های فروشندگان دیگر هستند، پس نشانی QCode را کامل تایپ کنید. مستندات مشخص نمی‌کنند که آیا نشانی یک دروازه سفارشی باید به `/v1` ختم شود؛ دقیقاً از همان نشانی‌ای استفاده کنید که دروازه شما منتشر می‌کند. برای QCode این نشانی `https://api.qcode.cc/openai/v1` است، بدون اسلش پایانی.
6. **API Key**: کلید QCode شما (با `cr_` شروع می‌شود).
7. **Model IDs** (زیر **Advanced**): هر ID را که می‌خواهید در انتخاب‌گر مدل ببینید، یکی‌یکی اضافه کنید — عبارت رسمی این است: «در تنظیمات اتصال، **Model IDs** را پیدا کنید، ID مدل را تایپ کنید و روی آیکون **+** کلیک کنید، سپس ذخیره کنید.» پس از تأیید یک اتصال، «فیلد **Model IDs** هنگام تایپ، IDهای مدل ارائه‌دهنده را پیشنهاد می‌دهد».
   خالی گذاشتن فیلد، تشخیص خودکار را حفظ می‌کند («_Default (Empty)_: همه مدل‌های موجود از ارائه‌دهنده را به‌طور خودکار تشخیص می‌دهد.»)؛ پر کردن آن رفتار را تغییر می‌دهد: «Open WebUI برای آن اتصال، فراخوانی `/models` ارائه‌دهنده را متوقف می‌کند و دقیقاً IDهایی را که تایپ کرده‌اید فهرست می‌کند».
8. **Prefix ID** (اختیاری): مستندات زمانی پیشوند را توصیه می‌کنند که «چند ارائه‌دهنده را که مدل‌هایی با نام یکسان دارند وصل می‌کنید» و بیان می‌کنند که «Open WebUI پیشوند و ID مدل را با یک نقطه به هم می‌چسباند» — بنابراین با پیشوند `qcode` و id `glm-5.3`، انتخاب‌گر `qcode.glm-5.3` را نشان می‌دهد.
9. **Provider** (زیر **Advanced**): آن را روی **Default** بگذارید. «گذاشتن آن روی **Default** همیشه ایمن است.» این منوی کشویی فقط برای اتصال‌های OpenAI وجود دارد.
10. روی **Save** کلیک کنید. هر اتصال ذخیره‌شده همچنین یک سوئیچ فعال/غیرفعال دارد که به شما امکان می‌دهد آن را بدون حذف کردن، فعال یا غیرفعال کنید.

IDهایی را که واقعاً می‌خواهید از [مدل‌های خانواده چین](/docs/usage/cn-models) و [انتخاب مدل](/docs/usage/model-selection) انتخاب کنید؛ صورت‌حساب به‌ازای توکن است، نرخ‌ها در [qcode.cc/models](https://qcode.cc/models).

### متغیرهای محیطی (نمونه‌های خودمیزبان)

مستندات این دو مسیر را معادل می‌داند: «Open WebUI از طریق متغیرهای محیطی پیکربندی می‌شود و می‌توانید همان مقادیر را از پنل مدیریت Open WebUI نیز تنظیم کنید.»

```bash
# add these -e flags to the docker command above, or export them before `open-webui serve`
OPENAI_API_BASE_URL=https://api.qcode.cc/openai/v1
OPENAI_API_KEY=cr_your_qcode_key
```

معانی مستندشده: `OPENAI_API_BASE_URL` «URL پایه API مربوط به OpenAI را پیکربندی می‌کند» (مقدار پیش‌فرض همراه آن `https://api.openai.com/v1` است)، `OPENAI_API_KEY` «کلید API مربوط به OpenAI را تنظیم می‌کند». برای متعادل‌سازی دو دروازه در یک نمونه، `OPENAI_API_BASE_URLS` «از URLهای پایه API متعادل‌شده OpenAI پشتیبانی می‌کند، جداشده با نقطه‌ویرگول.»

دو هشدار مستقیماً از همان صفحه مرجع:

- این متغیرها با `ConfigVar` علامت‌گذاری شده‌اند، بنابراین «پس از اجرای اولیه، اگر کانتینر را دوباره راه‌اندازی کنید، متغیرهای محیطی `ConfigVar` دیگر از مقادیر متغیرهای محیطی خارجی استفاده نمی‌کنند. در عوض، از مقادیر ذخیره‌شده در داخل استفاده می‌کنند.» آن‌ها را پیش از اولین اجرا تنظیم کنید، یا بعداً در رابط کاربری مدیریت تغییر دهید.
- همان صفحه می‌گوید «با نسخه انتشار Open WebUI [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`. موارد دلخواه را به **Model IDs** اضافه کنید، سپس برای آگاهی از تفاوت‌ها [مدل‌های خانواده چین](/docs/usage/cn-models) را بخوانید.
## تأیید

مستندات خود Open WebUI این انتظار را تعیین می‌کند: «**ذخیره یک اتصال آن را آزمایش نمی‌کند.**» دکمه کنار فیلد URL دقیقاً این‌گونه توصیف شده است: «کلیک روی دکمه **Verify Connection** کنار فیلد URL، نقطه پایانی `/models` ارائه‌دهنده را با یک توکن استاندارد `Bearer` فراخوانی می‌کند و **Server connection verified** را گزارش می‌دهد.» ارائه‌دهندگانی که آن نقطه پایانی را پیاده‌سازی نمی‌کنند یا آن را به شکل دیگری محافظت می‌کنند، مستند شده‌اند که این‌گونه رفتار می‌کنند: «تأیید اتصال **با خطا شکست می‌خورد** (مثلاً 400، 401 یا 403).» — و «این به معنای ناسازگاری ارائه‌دهنده **نیست**: **تکمیل‌های چت همچنان کار خواهند کرد**.» راه‌حل مستندشده دستی است: «شما فقط باید **نام مدل‌ها را به‌صورت دستی** به فهرست مجاز **Model IDs** در تنظیمات اتصال اضافه کنید.»

بنابراین، در عمل:

1. شناسه‌هایی را که قصد دارید استفاده کنید در **Model IDs** قرار دهید — این مسیر قابل‌اعتماد است، صرف‌نظر از آنچه دکمه تأیید می‌گوید.
2. یک پیام به یکی از مدل‌های موجود در فهرست مجاز در چت بفرستید. همان رفت‌وبرگشت، آزمون واقعی است.
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` «برای کشف مدل و انتخاب مدل‌ها در رابط کاربری استفاده می‌شود. اگر در دسترس نیست، مدل‌ها را به‌صورت دستی به فهرست مجاز اضافه کنید.» | هر شناسه را زیر **Model IDs** اضافه کنید |
| واکشی فهرست مدل کند است، یا نشانی ذخیره‌شده‌ای که در دسترس نیست رابط کاربری را معطل می‌کند | «زمان انتظار را برای اتصال‌های کندتر افزایش دهید. مقدار پیش‌فرض 10 ثانیه است و مقدار خالی آن را غیرفعال می‌کند»، مثلاً `AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=30` | متغیر را تنظیم کنید، یا URL خراب را پاک کنید |
| سروری روی ماشین خودتان از داخل کانتینر در دسترس نیست | «اگر Open WebUI را در Docker اجرا می‌کنید و سرور مدل شما روی ماشین میزبان است، در URL عبارت `localhost` را با `host.docker.internal` جایگزین کنید.» | URL را بازنویسی کنید |
| اتصال مدیر شکست می‌خورد در حالی که اتصال‌های کاربران کار می‌کنند | مستندات «502 Bad Gateway در اتصال‌های پیکربندی‌شده توسط مدیر در حالی که اتصال‌های کاربران درست کار می‌کنند» را فهرست می‌کند و توضیح می‌دهد که برای درخواست‌های مدیر/سراسری «بک‌اند Open WebUI آن نام میزبان را حل می‌کند و درون یک کانتینر Docker ممکن است به `127.0.0.1` حل شود»؛ توصیه رسمی: «برای اتصال‌های بک‌اند/مدیر، از **URL داخلی** استفاده کنید که بک‌اند واقعاً می‌تواند به آن دسترسی داشته باشد» | نشانی‌ای را که بک‌اند حل می‌کند بررسی کنید، نه نشانی‌ای را که مرورگر شما می‌بیند |
| نصب pip یا uv خراب می‌شود | «Open WebUI از **Python 3.11 و 3.12** پشتیبانی می‌کند. **Python 3.13 هنوز پشتیبانی نمی‌شود**» | از 3.11 یا 3.12 استفاده کنید |
| منوی کشویی Provider هیچ‌جا پیدا نمی‌شود | «منوی کشویی **Provider** فقط به اتصال‌های OpenAI تعلق دارد.» | روی انواع دیگر اتصال ارائه نمی‌شود |

محدودیت‌های سمت QCode که پیش از برنامه‌ریزی برای استقرار گسترده باید بدانید:

- **Claude از این ابزار در دسترس نیست.** QCode مسیری برای Claude روی نقطه پایانی سازگار با OpenAI منتشر نمی‌کند؛ درخواست‌های 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** (کاربرانی که مرورگر خود را مستقیماً به یک ارائه‌دهنده متصل می‌کنند) مستند شده است که «در حال حاضر **آزمایشی**» است و تا زمانی که مدیر آن را روشن نکند خاموش است — «**Settings > Admin > Connections > Direct Connections**: گزینه **On** را روشن کنید»، یا `ENABLE_DIRECT_CONNECTIONS=true` که «اتصال‌های مستقیم را فعال یا غیرفعال می‌کند» — و در آنجا کلید سمت کلاینت قرار دارد: «کلیدها در حافظه محلی مرورگر ذخیره می‌شوند». چون مرورگر درخواست را انجام می‌دهد، صفحه رسمی الزام می‌کند که «ارائه‌دهنده API باید **Cross-Origin Resource Sharing (CORS)** را طوری پیکربندی کرده باشد که درخواست‌ها از دامنه Open WebUI شما را مجاز کند»؛ اینکه QCode به درخواست‌های مستقیم مرورگر برای دامنه شما پاسخ می‌دهد یا نه، در اینجا تأیید نشده است، پس اتصال مدیر را مسیر پشتیبانی‌شده در نظر بگیرید.
- هیچ‌چیز در این صفحه با یک کلید واقعی اجرا نشد. نام فیلدها، مسیرهای منو، نام متغیرها و فرمان‌ها از مستندات رسمی نقل شده‌اند؛ مقادیر نقطه پایانی QCode از [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) آمده‌اند.
## مرتبط

- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — این‌که کدام خانواده مدل با کدام پروتکل کار می‌کند
- [سازگاری ابزارها](/docs/ide/tool-compatibility) — ابزارهایی که با پروتکل Anthropic کار می‌کنند، برای Claude
- [مدل‌های خانواده چین](/docs/usage/cn-models) — شناسه‌ها و تفاوت‌ها برای GLM / Kimi / DeepSeek / Qwen
- [انتخاب مدل](/docs/usage/model-selection) — انتخاب شناسه برای یک وظیفه
- [عیب‌یابی](/docs/reference/troubleshooting) — جست‌وجوی خطا از سمت QCode
- [یکپارچه‌سازی Cherry Studio](/docs/ide/cherry-studio) — کلاینتی با اتصال از نوع Anthropic، اگر به Claude نیاز دارید
- [یکپارچه‌سازی SillyTavern](/docs/ide/sillytavern) — کلاینت دیگری سازگار با OpenAI