نصب Open WebUI و پیکربندی OmniProxy

Open WebUI یک رابط چت خود-میزبانی (self-hosted) است که می‌تواند روی رایانه یا سرور شخصی شما نصب شود و همچنین به صورت کاملاً آفلاین اجرا گردد. این ابزار به هیچ ارائه‌دهنده مدل خاصی وابسته نیست: می‌تواند به ابزارهایی مانند Ollama که مدل‌ها را به صورت محلی اجرا می‌کنند، و همچنین به نقاط پایانی (endpoints) سازگار با OpenAI متصل شود؛ یعنی آدرس‌هایی که خدمات مدل را با همان فرمت درخواست ارائه می‌دهند. این ویژگی به شما امکان می‌دهد در یک پنجره واحد بین مدل‌های محلی و ابری جابه‌جا شوید.

این ابزار برای استفاده طولانی‌مدت توسط تیم‌ها و سازمان‌ها مناسب است. قابلیت‌هایی که به‌روزرسانی‌های سریع‌تری دریافت می‌کنند، ابتدا در Computer ظاهر می‌شوند، محصولی که Open WebUI برای آزمایش ویژگی‌های جدید از آن استفاده می‌کند.

پیش از شروع

Open WebUI در سیستم‌عامل‌های macOS، لینوکس و ویندوز در دسترس است. شما می‌توانید آن را با استفاده از Docker، پایتون یا Kubernetes نصب کنید. Docker برنامه و محیط اجرای آن را در یک کانتینر نسبتاً ایزوله بسته‌بندی می‌کند و روش پیشنهادی است. اگر Docker در دسترس نیست، می‌توانید از دستور پایتون آزمایش‌شده در زیر استفاده کنید. Kubernetes سیستمی برای استقرار و مدیریت کانتینرها است؛ برای مراحل مربوطه، به «شروع سریع» که در انتهای این راهنما لینک شده است، مراجعه کنید.

پیشنهاد رسمی

Docker

• یک دستور docker run
• باز کردن پورت 3000 در مرورگر
• داده‌ها در volume ذخیره می‌شوند

فقط برای چت

ایمیج slim

• حجم دانلود کمتر
• تغییر تگ به :slim
• قابلیت چت همچنان در دسترس است

در اینجا پوشش داده نشده است

دو گزینه دیگر

• نصب دستی پایتون
• استقرار Kubernetes
• مشاهده شروع سریع رسمی

پیش از شروع، موارد زیر را آماده کنید:

• Docker نصب و در حال اجرا باشد.
• یک رشته امنیتی که فقط توسط شما استفاده می‌شود. برای تولید آن openssl rand -hex 32 را اجرا کنید و سپس آن را به عنوان WEBUI_SECRET_KEY وارد نمایید. این مقدار را به صورت دائمی ذخیره کنید. اگر هنگام بازسازی کانتینر آن را تغییر دهید، کاربرانی که قبلاً وارد شده‌اند، خارج خواهند شد.
• یک نمونه در حال اجرای OmniProxy و یک شناسه مدل (Model ID) از لیست مدل‌های فعلی آن. شناسه مدل، نام کاملی است که برای انتخاب یک مدل خاص استفاده می‌شود.

نصب و اولین اجرا

یک ترمینال باز کنید و دستور موجود در «شروع سریع» را اجرا کنید. ابتدا your-secret-key را با رمز امنیتی که تولید کرده‌اید جایگزین کنید:

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

بخش‌های زیر در این دستور اهداف متفاوتی دارند:

• -p 3000:8080: به شما امکان می‌دهد رابط کاربری را از طریق پورت 3000 روی این رایانه باز کنید. اگر پورت 3000 در حال استفاده است، عدد سمت چپ را تغییر دهید.
• -v open-webui:/app/backend/data: چت‌ها، کاربران و تنظیمات را در یک volume داده ذخیره می‌کند. volume داده مکانی خارج از کانتینر است که داده‌ها در آن به صورت طولانی‌مدت حفظ می‌شوند، بنابراین محتویات آن پس از به‌روزرسانی کانتینر باقی می‌مانند. این گزینه را حذف نکنید.
• --add-host=host.docker.internal:host-gateway: به کانتینر اجازه می‌دهد به سایر سرویس‌های در حال اجرا روی این رایانه دسترسی پیدا کند.
• --restart always: کانتینر را پس از راه‌اندازی مجدد رایانه، دوباره اجرا می‌کند.

پس از پایان دستور، http://localhost:3000 را در مرورگر باز کنید و دستورالعمل‌های روی صفحه را برای ایجاد اولین حساب کاربری دنبال کنید.

اگر فقط نیاز به چت از طریق API دارید، می‌توانید تگ ایمیج را از :main به :slim تغییر دهید. slim یک ایمیج کوچک‌تر است که شامل مدل‌های گفتار و تعبیه (embedding) محلی در داخل کانتینر نیست، اما رابط چت همچنان در دسترس است. اگر به آن قابلیت‌های محلی نیاز دارید، به استفاده از :main ادامه دهید.

برای به‌روزرسانی‌های دستی، ابتدا docker rm -f open-webui را اجرا کنید، سپس docker pull ghcr.io/open-webui/open-webui:main را اجرا کرده و آن را با همان دستور docker run مجدداً راه‌اندازی کنید. هم volume داده و هم WEBUI_SECRET_KEY را بدون تغییر نگه دارید.

اگر Docker در دسترس نیست

«شروع سریع» همچنین یک روش نصب پایتون ارائه می‌دهد. در تاریخ 2026-10-09، دستور زیر روی macOS برای نصب Open WebUI v0.11.4 و تکمیل یک مکالمه استفاده شد. در آن زمان Docker Desktop روی آن رایانه نصب نبود.

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

پس از راه‌اندازی، http://localhost:8080 را در مرورگر باز کنید. این پورتی است که توسط نصب پایتون استفاده می‌شود، نه پورت 3000 داکر.

یک مدل تعبیه (embedding) در طول اولین راه‌اندازی دانلود می‌شود که ممکن است چند دقیقه طول بکشد. مدل تعبیه، متن را به داده‌هایی تبدیل می‌کند که جستجو و تطبیق آن‌ها آسان‌تر است. پیش از ادامه، منتظر بمانید تا صفحه ورود ظاهر شود. اولین حساب ثبت‌شده به مدیر تبدیل می‌شود. زبان رابط کاربری از زبان سیستم پیروی می‌کند؛ در طول این آزمایش، زبان چینی ساده‌شده نمایش داده شد.

DATA_DIR باید به دایرکتوری اشاره کند که برای طولانی‌مدت حفظ شده و برای ذخیره داده‌های Open WebUI استفاده می‌شود. اگر تنظیم نشود، ممکن است داده‌ها در یک دایرکتوری موقت ذخیره شده و پس از خاموش شدن از بین بروند. اگر WEBUI_SECRET_KEY تنظیم نشود، برنامه .webui_secret_key را در دایرکتوری فعلی می‌نویسد. آن را از دایرکتوری که قصد دارید حفظ کنید اجرا کنید، یا خودتان این متغیر را تنظیم نمایید.

دریافت جزئیات اتصال از OmniProxy

سه مورد زیر را از نمونه OmniProxy خود کپی کنید:

URL:      https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy from the current OmniProxy model list

URL آدرسی است که Open WebUI برای اتصال به نقطه پایانی استفاده می‌کند و باید با /v1 پایان یابد. پس از آن /chat/completions را اضافه نکنید؛ Open WebUI آن بخش را به صورت خودکار اضافه می‌کند.

شناسه کامل مدل را از لیست فعلی OmniProxy کپی کنید. اگر شناسه شامل پیشوند منبع و اسلش است، آن‌ها را نیز حفظ کنید. دو نام کوتاه زیر فقط ارجاعاتی از مستندات ارائه‌دهنده تا تاریخ 2026-10-09 هستند. اگر در لیست فعلی نیستند، از آن‌ها استفاده نکنید:

• شناسه API کلود برای Claude Sonnet 5.5: claude-sonnet-5-5
• نام API برای Gemini 3.8 Flash: gemini-3.8-flash

در Open WebUI کلید ارائه‌دهنده را وارد نکنید. اگر درگاه (gateway) کلیدها را اعتبارسنجی نمی‌کند، به جای اختراع یک کلید دیگر، فیلد API key را خالی بگذارید.

مرورگر

پورت محلی 3000

• باز کردن صفحه چت
• ابتدا ثبت‌نام را کامل کنید
• سپس تنظیمات را باز کنید

داخل کانتینر

Open WebUI

• از localhost استفاده نکنید
• به جای آن از نام ماشین میزبان استفاده کنید
• URL با /v1 پایان می‌یابد

همان رایانه

OmniProxy

• کلید را در درگاه نگه دارید
• از لیست مدل درگاه استفاده کنید
• سپس لاگ‌های درخواست را بررسی کنید

اگر سرویس مدل روی میزبان اجرا می‌شود در حالی که Open WebUI در یک کانتینر Docker است، localhost را در URL با host.docker.internal جایگزین کنید. میزبان رایانه‌ای است که Docker را مستقیماً اجرا می‌کند. اگر OmniProxy فقط روی این رایانه گوش می‌دهد، URL می‌تواند به صورت http://host.docker.internal:port/v1 نوشته شود، که در آن port با پورتی که OmniProxy واقعاً استفاده می‌کند جایگزین می‌شود.

اگر Open WebUI از طریق دستور پایتون در بخش قبلی به صورت محلی در حال اجرا است و OmniProxy نیز به صورت محلی اجرا می‌شود، از 127.0.0.1 یا localhost در آدرس استفاده کنید. در این مورد از host.docker.internal استفاده نکنید.

وارد کردن پیکربندی

در رابط چینی ساده‌شده v0.11.4 که در تاریخ 2026-10-09 آزمایش شد، نام‌ها با Settings > Admin > Connections در دستورالعمل‌های انگلیسی متفاوت بودند. گزینه‌های نشان داده شده در رابط آزمایش‌شده را که در زیر ترجمه شده‌اند دنبال کنید:

1. نوار کناری سمت چپ را باز کنید.
2. روی منوی کاربر در پایین کلیک کنید.
3. روی Settings کلیک کنید.
4. در بخش مدیریت در پایین، روی External Connections کلیک کنید.
5. OpenAI API را باز کنید.
6. روی + در سمت راست Manage OpenAI API Connections کلیک کنید.
7. در کادر Edit Connection، URL را که با /v1 پایان می‌یابد وارد کنید. نوع API را روی Chat Completions نگه دارید.
8. Authentication Method را روی Key (Bearer) نگه دارید. احراز هویت Bearer کلید API را برای تأیید هویت در درخواست قرار می‌دهد. اگر OmniProxy به شما کلیدی داده است، آن را در API Key وارد کنید. اگر درگاه کلیدها را اعتبارسنجی نمی‌کند، این فیلد را خالی بگذارید. در تاریخ 2026-10-09، هم اعتبارسنجی و هم یک مکالمه با خالی گذاشتن فیلد با موفقیت انجام شد.
9. روی Verify Connection در کنار URL کلیک کنید. اگر OmniProxy مقدار /models را ارائه دهد، لیست مدل‌ها در اینجا بازیابی می‌شود.
10. Advanced را باز کنید. اگر Model ID خالی بماند، از تمام مدل‌های بازگردانده شده توسط /models در آن آدرس استفاده خواهد شد. فقط در صورتی که اعتبارسنجی شکست خورد، یک شناسه کامل از لیست را در Add Model ID وارد کرده و سپس روی Add کلیک کنید. هر شناسه را فقط یک بار اضافه کنید؛ فضاهای خالی ابتدا و انتهای آن حذف می‌شوند.
11. در این پنجره روی Save کلیک کنید، سپس در گوشه پایین سمت راست صفحه External Connections روی Save کلیک کنید.

ذخیره پیکربندی به تنهایی جایگزین اعتبارسنجی نمی‌شود. Verify Connection نقطه پایانی /models سرویس دیگر را درخواست می‌کند که مدل‌های موجود را فهرست می‌کند. برخی سرویس‌ها این نقطه پایانی را ارائه نمی‌دهند، بنابراین ممکن است اعتبارسنجی خطا گزارش دهد در حالی که چت همچنان می‌تواند کار کند. در آن صورت، شناسه مدل را به صورت دستی اضافه کنید.

تأیید با یک کار واقعی

به صفحه چت برگردید، منوی مدل را در کنار کادر ورودی باز کنید و شناسه کامل را از لیست OmniProxy انتخاب کنید. یک پیام بسیار کوتاه بفرستید، مثلاً از آن بخواهید فقط با یک کلمه پاسخ دهد. پاسخ باید واقعاً در کادر چت ظاهر شود.

در تاریخ 2026-10-09، این مکالمه با استفاده از نصب پایتون v0.11.4 تکمیل شد. Docker همچنان روش پیشنهادی است، اما آزمایش در Docker تکرار نشد.

سپس، لاگ‌های درخواست OmniProxy را باز کرده و منبع و شناسه مدل را برای این درخواست تأیید کنید. فقط دیدن یک ذخیره موفق، یا فقط دیدن مدل در منو، به معنای تکمیل کار نیست.

رابط کاربری

مدل قابل انتخاب است

• اتصالات ذخیره شده است
• مدل در لیست ظاهر می‌شود
• یک سوال کوتاه بفرستید

پاسخ

کادر چت پاسخ را نشان می‌دهد

• این یک پیام خالی نیست
• این یک خطای اتصال نیست
• دوباره با مدل دیگری امتحان کنید

لاگ‌ها

در درگاه قابل مشاهده است

• منبع این اتصال است
• شناسه مدل مطابقت دارد
• هیچ کلیدی در صفحه وارد نشد

خطاهای رایج

• localhost یا 127.0.0.1 در داخل کانتینر استفاده شد: این آدرس‌ها به خود کانتینر اشاره دارند، نه میزبان. آدرس را به host.docker.internal تغییر دهید و تأیید کنید که دستور راه‌اندازی شامل --add-host=host.docker.internal:host-gateway است. عکس این موضوع زمانی صادق است که Open WebUI در کانتینر اجرا نمی‌شود: از یک آدرس محلی استفاده کنید.
• مرورگر نمی‌تواند صفحه را باز کند: برای Docker، پورت 3000 را بررسی کنید؛ برای پایتون، پورت 8080 را بررسی کنید. در طول اولین راه‌اندازی، منتظر بمانید تا دانلود مدل تعبیه تمام شود. می‌توانید از docker ps برای تأیید اینکه آیا کانتینر در حال اجرا است استفاده کنید. اگر پورت 3000 در حال استفاده است، پورت سمت چپ -p را تغییر دهید.
• شناسه در منوی مدل طولانی‌تر از نام کوتاه ارائه‌دهنده است: از شناسه کامل موجود در منو، شامل هرگونه اسلش، استفاده کنید.
• همه پس از به‌روزرسانی خارج شده‌اند: WEBUI_SECRET_KEY تغییر کرده است. با استفاده از رمز تولید شده در اولین بار، مجدداً راه‌اندازی کنید.
• Verify Connection شکست می‌خورد: ابتدا شناسه مدل را به صورت دستی در Advanced اضافه کنید، سپس آن را با یک چت واقعی یک‌جمله‌ای تأیید کنید. برخی سرویس‌ها /models را ارائه نمی‌دهند، بنابراین ممکن است چت همچنان کار کند در حالی که اعتبارسنجی خطا گزارش می‌دهد.
• مدل وجود ندارد: شناسه را دوباره از لیست فعلی OmniProxy کپی کنید و به استفاده از نام قدیمی ادامه ندهید.

مراجع رسمی

برای دستورات نصب، به شروع سریع Open WebUI مراجعه کنید. برای مراحل اتصال، به دستورالعمل‌های اتصال سازگار با OpenAI مراجعه کنید. برای شناسه‌های مدل استفاده شده در مثال‌ها، به نمای کلی مدل Claude و لیست مدل Gemini مراجعه کنید.

هر جایگاه را با مقادیر از پیکربندی OmniProxy خود جایگزین کنید. هرگز یک کلید واقعی را منتشر نکنید.

یک نتیجه ذخیره شده یا HTTP 200 به تنهایی سازگاری کامل عامل را اثبات نمی‌کند. منبع و مدل را در گزارش درخواست OmniProxy بررسی کنید.

منابع رسمی · Open WebUI ↗