Open WebUI Kurulumu ve OmniProxy Yapılandırması

Open WebUI, kendi bilgisayarınıza veya sunucunuza kurabileceğiniz ve tamamen çevrimdışı da çalışabilen bir sohbet arayüzüdür. Belirli bir model sağlayıcısına bağlı değildir: Ollama gibi modelleri yerel olarak çalıştıran araçlara bağlanabildiği gibi, aynı istek biçimiyle model hizmeti sunan OpenAI uyumlu arayüzlere de bağlanabilir. Böylece yerel ve bulut modelleri arasında aynı pencere içinde geçiş yapabilirsiniz.

Ekiplerin ve kuruluşların uzun süreli kullanımı için uygundur. Daha hızlı güncellenen özellikler önce Open WebUI’nin yeni özellikleri denemek için kullandığı Computer ürününde sunulur.

Kurulum öncesi hazırlık

Open WebUI; macOS, Linux ve Windows üzerinde kullanılabilir. Docker, Python veya Kubernetes ile kurulabilir. Docker, uygulamayı ve çalışma ortamını nispeten bağımsız bir kapsayıcıya kurduğu için önerilen yöntemdir. Docker yoksa aşağıda test edilmiş Python komutunu da kullanabilirsiniz. Kubernetes, kapsayıcıları dağıtmak ve yönetmek için kullanılan bir sistemdir; ilgili adımlar için belgenin sonundaki Quick Start bağlantısına bakın.

Resmi öneri

Docker

• Tek bir docker run
• Tarayıcıda 3000 portunu açın
• Veriler veri biriminde tutulur

Yalnızca sohbet etmek istiyorsanız

slim imajı

• İndirme boyutu daha küçüktür
• Etiketi :slim olarak değiştirin
• Sohbet özelliği kullanılabilir

Burada ayrıntılandırılmıyor

Diğer iki yöntem

• Python ile elle kurulum
• Kubernetes dağıtımı
• Resmi Hızlı Başlangıç'a bakın

Başlamadan önce şunları hazırlayın:

• Kurulmuş ve çalışır durumda bir Docker.
• Yalnızca sizin kullanacağınız bir gizli anahtar dizisi. openssl rand -hex 32 komutunu çalıştırarak oluşturun ve ardından WEBUI_SECRET_KEY içine girin. Bu değeri değiştirmeden saklayın; kapsayıcı yeniden oluşturulurken değiştirilirse oturum açmış kullanıcıların oturumları kapatılır.
• Çalışır durumdaki OmniProxy ve mevcut model listesindeki model kimliği. Model kimliği, belirli bir modeli seçmek için kullanılan tam addır.

Kurulum ve ilk başlatma

Terminali açın ve Quick Start içindeki komutu çalıştırın. Önce your-secret-key değerini az önce oluşturduğunuz gizli anahtarla değiştirin:

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

Bu komuttaki seçeneklerin görevleri şöyledir:

• -p 3000:8080: Arayüzü bu bilgisayarın 3000 numaralı portu üzerinden açmanızı sağlar. 3000 kullanımdaysa soldaki sayıyı değiştirin.
• -v open-webui:/app/backend/data: Sohbetleri, kullanıcıları ve ayarları bir veri biriminde saklar. Veri birimi, verilerin kapsayıcının dışında kalıcı olarak tutulduğu yerdir; kapsayıcı güncellendikten sonra içerik korunur. Bu nedenle bu seçeneği kaldırmayın.
• --add-host=host.docker.internal:host-gateway: Kapsayıcının bu bilgisayarda çalışan diğer hizmetlere erişmesini sağlar.
• --restart always: Bilgisayar yeniden başlatıldığında kapsayıcının yeniden çalışmasını sağlar.

Komut tamamlandıktan sonra tarayıcıda http://localhost:3000 adresini açın ve sayfadaki talimatları izleyerek ilk hesabı oluşturun.

Yalnızca arayüz üzerinden sohbet edecekseniz imaj etiketini :main yerine :slim olarak değiştirebilirsiniz. slim, kapsayıcı içindeki yerel konuşma ve gömme modellerini içermeyen, daha küçük boyutlu bir imajdır; sohbet arayüzü kullanılmaya devam eder. Bu yerel özelliklere ihtiyacınız varsa :main kullanmayı sürdürün.

Güncelleme sırasında önce docker rm -f open-webui, ardından docker pull ghcr.io/open-webui/open-webui:main komutunu çalıştırın ve aynı docker run komutunu kullanarak yeniden başlatın. Veri birimi ile WEBUI_SECRET_KEY değiştirilmeden korunmalıdır.

Docker yoksa

Quick Start, Python ile kurulum yöntemini de sunar. 2026-10-09 tarihinde aşağıdaki komut kullanılarak macOS üzerinde Open WebUI v0.11.4 kuruldu ve bir sohbet tamamlandı. O sırada bilgisayarda Docker Desktop yoktu.

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

Başlattıktan sonra tarayıcıda http://localhost:8080 adresini açın. Bu, Python kurulum yönteminin kullandığı porttur; Docker’ın kullandığı 3000 numaralı port değildir.

İlk başlatmada bir gömme modeli indirilir ve bu işlem birkaç dakika sürebilir. Gömme modeli, metni arama ve eşleştirme için uygun verilere dönüştürür. Devam etmeden önce oturum açma sayfasının görünmesini bekleyin. İlk kaydedilen hesap yönetici olur. Arayüz dili sistem dilini izler; bu testte Basitleştirilmiş Çince görüntülendi.

DATA_DIR, Open WebUI verilerini saklamak için uzun süre korunacak bir dizini göstermelidir. Ayarlanmazsa veriler geçici bir dizine kaydedilebilir ve uygulama kapatıldığında kaybolabilir. WEBUI_SECRET_KEY ayarlanmadığında program mevcut dizine .webui_secret_key dosyasını yazar. Programı korumayı planladığınız bir dizinden başlatın veya bu değişkeni kendiniz ayarlayın.

OmniProxy’den bağlantı parametrelerini alma

Kendi OmniProxy’nizden aşağıdaki üç öğeyi kopyalayın:

URL:      https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: OmniProxy'nin mevcut model listesinden kopyalayın

URL, Open WebUI’nin uç noktaya bağlanmak için kullandığı adrestir ve /v1 ile bitmelidir. Sonuna /chat/completions eklemeyin; bu bölüm Open WebUI tarafından otomatik olarak eklenir.

Model kimliğini OmniProxy’nin mevcut listesinden eksiksiz olarak kopyalayın. Kimlik bir kaynak ön eki ve eğik çizgi içeriyorsa bunları da koruyun. Aşağıdaki iki kısa ad yalnızca 2026-10-09 tarihindeki sağlayıcı belgelerinde karşılaştırma amacıyla verilmiştir. Mevcut listede yoklarsa kullanmayın:

• Claude Sonnet 5.5 için Claude API kimliği: claude-sonnet-5-5
• Gemini 3.8 Flash arayüz adı: gemini-3.8-flash

Sağlayıcı anahtarını Open WebUI’ye girmeyin. Ağ geçidi anahtarı doğrulamıyorsa API anahtarı alanını boş bırakabilirsiniz; ayrıca yeni bir anahtar uydurmayın.

Tarayıcı

Yerel 3000

• Sohbet sayfasını açın
• Önce kaydı tamamlayın
• Ardından ayarlara gidin

Kapsayıcının içinde

Open WebUI

• localhost yazmayın
• Bunun yerine ana makine adını kullanın
• URL /v1 ile bitmeli

Aynı bilgisayar

OmniProxy

• Anahtarı ağ geçidinde tutun
• Model listesi için ağ geçidini esas alın
• Ardından çağrı kayıtlarını inceleyin

Model hizmeti ana makinede, Open WebUI ise Docker kapsayıcısında çalışıyorsa URL içindeki localhost değerini host.docker.internal olarak değiştirin. Ana makine, Docker’ın doğrudan çalıştığı bilgisayardır. OmniProxy yalnızca bu bilgisayarı dinliyorsa URL’yi http://host.docker.internal:port/v1 biçiminde yazabilirsiniz; buradaki port yerine OmniProxy’nin gerçekten kullandığı portu girin.

Open WebUI önceki bölümdeki Python komutuyla yerel olarak çalıştırılıyorsa ve OmniProxy de aynı bilgisayardaysa adres olarak 127.0.0.1 veya localhost kullanın. Bu durumda host.docker.internal yazmayın.

Araç yapılandırmasını girme

2026-10-09 tarihindeki v0.11.4 Basitleştirilmiş Çince arayüzündeki adlar, İngilizce açıklamalarda kullanılan Settings > Admin > Connections adlarından farklıydı. Ekranda görülen seçeneklere göre şu adımları uygulayın:

1. Sol kenar çubuğunu genişletin.
2. Alt kısımdaki kullanıcı menüsüne tıklayın.
3. Ayarlar seçeneğine tıklayın.
4. Alt taraftaki yönetici grubunda Harici Bağlantılar seçeneğine tıklayın.
5. OpenAI Arayüzü seçeneğini açın.
6. OpenAI Arayüz Bağlantılarını Yönet bölümünün sağındaki + düğmesine tıklayın.
7. Açılan Bağlantıyı Düzenle penceresinde URL’yi /v1 ile bitecek şekilde girin. Arayüz türünü Chat Completions olarak bırakın.
8. Kimlik doğrulama yöntemi olarak Anahtar (Bearer) seçili kalsın. Bearer, kimlik doğrulaması için API anahtarını isteğe ekleyen yöntemdir. OmniProxy size bir anahtar verdiyse bunu API anahtarı alanına girin. Ağ geçidi anahtarı doğrulamıyorsa bu alanı boş bırakın. 2026-10-09 tarihinde alan boş bırakıldığında hem doğrulama hem de bir sohbet başarıyla tamamlandı.
9. URL’nin yanındaki Bağlantıyı doğrula seçeneğine tıklayın. OmniProxy /models sağlıyorsa model listesi buradan alınır.
10. Gelişmiş bölümünü açın. Model ID boş bırakıldığında adresin /models yanıtında döndürdüğü tüm modeller kullanılır. Yalnızca doğrulama başarısız olursa Model ID ekle alanına listedeki tam kimliği girip Ekle seçeneğine tıklayın. Her kimliği yalnızca bir kez ekleyin; başındaki ve sonundaki boşluklar kaldırılır.
11. Bu pencerede Kaydet seçeneğine, ardından Harici Bağlantılar sayfasının sağ alt köşesindeki Kaydet seçeneğine tıklayın.

Yalnızca yapılandırmayı kaydetmek doğrulamanın yerini tutmaz. Bağlantıyı doğrula, kullanılabilir modelleri listeleyen karşı tarafın /models arayüzüne istek gönderir. Bazı hizmetlerde bu arayüz bulunmaz; bu durumda doğrulama hata verse bile sohbet çalışabilir. Böyle bir durumda model kimliğini elle ekleyin.

Gerçek bir görevle doğrulama

Sohbet sayfasına dönün, giriş kutusunun yanındaki model menüsünü açın ve OmniProxy listesindeki tam kimliği seçin. Yalnızca tek kelimeyle yanıt vermesini istemek gibi çok kısa bir mesaj gönderin. Yanıtın sohbet kutusunda gerçekten görünmesi gerekir.

2026-10-09 tarihinde bu sohbet, v0.11.4’ün Python kurulumu kullanılarak tamamlandı. Docker hâlâ önerilen yöntemdir ancak bu test Docker içinde tekrar yapılmadı.

Ardından OmniProxy çağrı kayıtlarını açarak bu isteğin kaynağını ve model kimliğini doğrulayın. Yalnızca kaydetme işleminin başarılı olduğunu görmek veya modelin menüde görünmesi işlemin tamamlandığı anlamına gelmez.

Arayüz

Model seçilebiliyor

• Bağlantılar kaydedildi
• Model listede görünüyor
• Kısa bir soru gönderin

Yanıt

Sohbet kutusunda yanıt var

• Boş bir mesaj değil
• Bağlantı hatası değil
• Başka bir modelle yeniden deneyin

Kayıtlar

Ağ geçidinde görünüyor

• Kaynak bu bağlantı
• Model ID eşleşiyor
• Sayfaya anahtar girilmedi

Yaygın hatalar

• Kapsayıcı içinde localhost veya 127.0.0.1 kullanmak: Bu iki adres ana makineyi değil, kapsayıcının kendisini gösterir. Adresi host.docker.internal olarak değiştirin ve başlatma komutunda --add-host=host.docker.internal:host-gateway bulunduğunu doğrulayın. Open WebUI kapsayıcı içinde çalışmıyorsa bunun tersine yerel adresi kullanın.
• Tarayıcıda sayfanın açılmaması: Docker için 3000, Python için 8080 numaralı portu kontrol edin. İlk başlatmada gömme modelinin indirilmesinin tamamlanmasını bekleyin. Kapsayıcının çalışıp çalışmadığını docker ps ile doğrulayabilirsiniz. 3000 kullanımdaysa -p seçeneğinin solundaki portu değiştirin.
• Model menüsündeki kimliğin sağlayıcının kısa adından daha uzun olması: Eğik çizgiler dâhil olmak üzere menüdeki tam kimliği kullanın.
• Güncellemeden sonra tüm oturumların kapanması: WEBUI_SECRET_KEY değişmiştir. İlk kez oluşturduğunuz gizli anahtarı kullanarak yeniden başlatın.
• Bağlantıyı doğrula işleminin başarısız olması: Önce Gelişmiş bölümünde model kimliğini elle ekleyin, ardından gerçek bir sohbet mesajıyla kontrol edin. Bazı hizmetlerde /models bulunmaz; doğrulama hata verse bile sohbet çalışabilir.
• Modelin bulunmaması: Kimliği OmniProxy’nin mevcut listesinden yeniden kopyalayın; eski adları kullanmaya devam etmeyin.

Resmî başvurular

Kurulum komutları için Open WebUI Quick Start belgesine bakın. Bağlantı adımları için OpenAI-compatible bağlantı açıklamasına bakın. Örneklerde kullanılan model kimlikleri için Claude model genel görünümüne ve Gemini model listesine bakın.

Tüm yer tutucuları kendi OmniProxy yapılandırmanızdaki değerlerle değiştirin. Gerçek bir anahtar asla paylaşmayın.

Kaydedilmiş bir sonuç veya yalnızca HTTP 200, tam Aracı uyumluluğunu kanıtlamaz. OmniProxy'nin çağrı kaydındaki kaynağı ve modeli kontrol edin.

Resmi kaynaklar · Open WebUI ↗