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

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

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

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

در یک نگاه¶

🔴 Claude در Open WebUI در دسترس نیست. Open WebUI فقط درخواست‌های OpenAI Chat Completions را می‌فرستد و QCode مدل‌های Claude خود را منحصراً روی نقطه پایانی Anthropic Messages ارائه می‌دهد — برای Claude از ابزاری استفاده کنید که با پروتکل Anthropic صحبت می‌کند، یا از Claude Code. نمای کلی هر ابزار در سازگاری ابزارها آمده است.

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

کدام پروتکل¶

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

دلیل اینکه ردیف 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 را ببینید.

نصب¶

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

Docker — مستندات به Docker نیاز دارند و به شما می‌گویند your-secret-key را با خروجی openssl rand -hex 32 جایگزین کنید:

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:

pip install open-webui
open-webui serve

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

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

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هایی را که واقعاً می‌خواهید از مدل‌های خانواده چین و انتخاب مدل انتخاب کنید؛ صورت‌حساب به‌ازای توکن است، نرخ‌ها در qcode.cc/models.

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

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

# 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 اضافه کنید، سپس برای آگاهی از تفاوت‌ها مدل‌های خانواده چین را بخوانید.

تأیید¶

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

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

1. شناسه‌هایی را که قصد دارید استفاده کنید در Model IDs قرار دهید — این مسیر قابل‌اعتماد است، صرف‌نظر از آنچه دکمه تأیید می‌گوید.
2. یک پیام به یکی از مدل‌های موجود در فهرست مجاز در چت بفرستید. همان رفت‌وبرگشت، آزمون واقعی است.
3. اگر می‌خواهید سمت QCode را از سمت Open WebUI جدا کنید، نقطه پایانی را مستقیماً فراخوانی کنید:

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"}]}'

ما برای این دور، کلید آزمایشی نداریم؛ به همین دلیل نشانگر بالای صفحه 📄 باقی می‌ماند: هیچ کد وضعیت و بدنه پاسخی در اینجا ادعا نمی‌شود. آنچه درخواست خودتان برگردانده است را با مدخل‌های زیر عیب‌یابی مقایسه کنید.

عیب‌یابی / محدودیت‌های شناخته‌شده¶

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

• Claude از این ابزار در دسترس نیست. QCode مسیری برای Claude روی نقطه پایانی سازگار با OpenAI منتشر نمی‌کند؛ درخواست‌های Claude به نقطه پایانی Anthropic Messages تعلق دارند که Open WebUI آن را فراخوانی نمی‌کند. برای Claude، از ابزاری استفاده کنید که با پروتکل Anthropic صحبت می‌کند، یا از Claude Code — به سازگاری ابزارها مراجعه کنید.
• 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 آمده‌اند.

مرتبط¶

• نقاط پایانی و مسیرهای API — این‌که کدام خانواده مدل با کدام پروتکل کار می‌کند
• سازگاری ابزارها — ابزارهایی که با پروتکل Anthropic کار می‌کنند، برای Claude
• مدل‌های خانواده چین — شناسه‌ها و تفاوت‌ها برای GLM / Kimi / DeepSeek / Qwen
• انتخاب مدل — انتخاب شناسه برای یک وظیفه
• عیب‌یابی — جست‌وجوی خطا از سمت QCode
• یکپارچه‌سازی Cherry Studio — کلاینتی با اتصال از نوع Anthropic، اگر به Claude نیاز دارید
• یکپارچه‌سازی SillyTavern — کلاینت دیگری سازگار با OpenAI

سازمانی ←