Instalasi Open WebUI dan Konfigurasi OmniProxy

Open WebUI adalah antarmuka percakapan yang dapat Anda terapkan sendiri di komputer atau server, dan juga dapat berjalan sepenuhnya secara luring. Aplikasi ini tidak terikat pada penyedia model tertentu: Anda dapat menghubungkannya ke alat seperti Ollama yang menjalankan model secara lokal, atau ke endpoint yang kompatibel dengan format OpenAI, yaitu alamat layanan model yang menggunakan format permintaan yang sama. Dengan demikian, Anda dapat beralih antara model lokal dan model cloud dalam satu jendela.

Aplikasi ini cocok digunakan dalam jangka panjang oleh tim dan organisasi. Kemampuan yang diperbarui lebih cepat akan tersedia lebih dahulu di Computer, yaitu produk yang digunakan Open WebUI untuk mencoba fitur baru.

Persiapan sebelum instalasi

Open WebUI dapat digunakan di macOS, Linux, dan Windows. Anda dapat menginstalnya melalui Docker, Python, atau Kubernetes. Docker menempatkan aplikasi dan lingkungan runtime dalam container yang relatif terisolasi dan merupakan metode yang direkomendasikan. Jika tidak memiliki Docker, Anda juga dapat menggunakan perintah Python yang telah diuji di bawah ini. Kubernetes adalah sistem untuk menerapkan dan mengelola container; langkah-langkahnya tersedia di Quick Start yang ditautkan pada bagian akhir.

Rekomendasi resmi

Docker

• Gunakan satu docker run
• Buka 3000 di browser
• Data berada di volume data

Jika hanya ingin mengobrol

Image slim

• Ukuran unduhan lebih kecil
• Ubah tag menjadi :slim
• Fitur obrolan tetap tersedia

Tidak dibahas di sini

Dua cara lainnya

• Instalasi manual dengan Python
• Deployment Kubernetes
• Lihat Mulai Cepat resmi

Siapkan hal-hal berikut sebelum memulai:

• Docker yang sudah terinstal dan dapat dijalankan.
• String rahasia yang hanya digunakan oleh Anda. Jalankan openssl rand -hex 32 untuk membuatnya, lalu masukkan hasilnya ke WEBUI_SECRET_KEY. Simpan nilai ini tanpa mengubahnya. Jika nilainya berubah ketika container dibuat ulang, pengguna yang sudah masuk akan dikeluarkan.
• OmniProxy yang sedang berjalan dan ID model dari daftar modelnya saat ini. ID model adalah nama lengkap yang digunakan untuk memilih model tertentu.

Instalasi dan peluncuran pertama

Buka terminal dan jalankan perintah dari Quick Start. Ganti your-secret-key terlebih dahulu dengan string rahasia yang baru dibuat:

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

Bagian-bagian dalam perintah ini memiliki fungsi berikut:

• -p 3000:8080: memungkinkan Anda membuka antarmuka melalui port 3000 pada komputer ini. Jika port 3000 sudah digunakan, ubah angka di sebelah kiri.
• -v open-webui:/app/backend/data: menyimpan percakapan, pengguna, dan pengaturan dalam volume data. Volume data adalah lokasi penyimpanan jangka panjang di luar container. Isinya tetap tersedia setelah container diperbarui, jadi jangan hapus opsi ini.
• --add-host=host.docker.internal:host-gateway: memungkinkan container mengakses layanan lain yang berjalan pada komputer ini.
• --restart always: menjalankan kembali container setelah komputer dinyalakan ulang.

Setelah perintah selesai dijalankan, buka http://localhost:3000 di browser, lalu ikuti petunjuk pada halaman untuk membuat akun pertama.

Jika Anda hanya menggunakan percakapan melalui endpoint, tag image dapat diubah dari :main menjadi :slim. slim adalah image berukuran lebih kecil yang tidak menyertakan model suara dan embedding lokal di dalam container, tetapi antarmuka percakapan tetap dapat digunakan. Jika memerlukan kemampuan lokal tersebut, tetap gunakan :main.

Untuk memperbarui secara manual, jalankan docker rm -f open-webui, kemudian docker pull ghcr.io/open-webui/open-webui:main, lalu jalankan kembali perintah docker run yang sama. Volume data dan WEBUI_SECRET_KEY harus tetap menggunakan nilai yang sama.

Jika tidak memiliki Docker

Quick Start juga menyediakan metode instalasi dengan Python. Pada 2026-10-09, perintah berikut digunakan untuk menginstal Open WebUI v0.11.4 di macOS dan berhasil menyelesaikan satu percakapan. Komputer tersebut tidak memiliki Docker Desktop pada saat pengujian.

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

Setelah aplikasi dimulai, buka http://localhost:8080 di browser. Ini adalah port yang digunakan oleh metode instalasi Python, bukan port 3000 yang digunakan Docker.

Pada peluncuran pertama, aplikasi akan mengunduh model embedding dan prosesnya mungkin memerlukan beberapa menit. Model embedding mengubah teks menjadi data yang lebih mudah digunakan untuk pencarian dan pencocokan. Tunggu hingga halaman masuk muncul sebelum melanjutkan. Akun pertama yang didaftarkan akan menjadi administrator. Bahasa antarmuka mengikuti bahasa sistem; dalam pengujian ini, antarmuka ditampilkan dalam Bahasa Tionghoa Sederhana.

DATA_DIR harus mengarah ke direktori yang akan disimpan dalam jangka panjang karena digunakan untuk menyimpan data Open WebUI. Jika tidak diatur, data mungkin disimpan dalam direktori sementara dan hilang setelah aplikasi ditutup. Jika WEBUI_SECRET_KEY tidak diatur, program akan menulis .webui_secret_key ke direktori saat ini. Jalankan aplikasi dari direktori yang ingin dipertahankan, atau atur variabel tersebut sendiri.

Mendapatkan parameter koneksi dari OmniProxy

Salin tiga nilai berikut dari OmniProxy Anda:

URL:      https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Salin ID lengkap dari daftar model OmniProxy saat ini

URL adalah alamat yang digunakan Open WebUI untuk terhubung ke endpoint dan harus diakhiri dengan /v1. Jangan tambahkan /chat/completions setelahnya karena bagian tersebut akan ditambahkan sendiri oleh Open WebUI.

ID model harus disalin secara lengkap dari daftar OmniProxy saat ini. Jika ID berisi prefiks sumber dan garis miring, pertahankan semuanya. Dua nama pendek berikut hanya merupakan acuan dari dokumentasi penyedia pada 2026-10-09. Jangan menggunakannya jika tidak tersedia dalam daftar saat ini:

• ID Claude API untuk Claude Sonnet 5.5: claude-sonnet-5-5
• Nama endpoint untuk Gemini 3.8 Flash: gemini-3.8-flash

Jangan masukkan kunci penyedia ke Open WebUI. Jika gateway tidak memvalidasi kunci, kolom API key dapat dibiarkan kosong. Jangan membuat sendiri string kunci lain.

Browser

Lokal 3000

• Buka halaman obrolan
• Selesaikan pendaftaran terlebih dahulu
• Lalu buka pengaturan

Di dalam kontainer

Open WebUI

• Jangan gunakan localhost
• Gunakan nama host mesin induk
• Akhiri URL dengan /v1

Di komputer yang sama

OmniProxy

• Biarkan kunci tetap di gateway
• Gunakan daftar model dari gateway
• Lalu periksa log permintaan

Jika layanan model berjalan pada host sementara Open WebUI berjalan di dalam container Docker, ganti localhost dalam URL dengan host.docker.internal. Host adalah komputer yang menjalankan Docker secara langsung. Jika OmniProxy hanya mendengarkan koneksi pada komputer ini, URL dapat ditulis sebagai http://host.docker.internal:port/v1, dengan port diganti menjadi port yang benar-benar digunakan OmniProxy.

Jika Open WebUI dijalankan secara lokal menggunakan perintah Python pada bagian sebelumnya dan OmniProxy juga berjalan secara lokal, gunakan 127.0.0.1 atau localhost sebagai alamat. Dalam kondisi ini, jangan gunakan host.docker.internal.

Mengisi konfigurasi alat

Pada 2026-10-09, antarmuka Bahasa Tionghoa Sederhana di v0.11.4 menggunakan nama yang berbeda dari Settings > Admin > Connections dalam petunjuk berbahasa Inggris. Ikuti opsi yang benar-benar terlihat pada antarmuka:

1. Perluas bilah samping kiri.
2. Klik menu pengguna di bagian bawah.
3. Klik Pengaturan.
4. Di bagian administrator pada area bawah, klik Koneksi eksternal.
5. Aktifkan Endpoint OpenAI.
6. Klik + di sebelah kanan Kelola koneksi endpoint OpenAI.
7. Dalam jendela Edit koneksi yang muncul, masukkan URL sampai /v1. Biarkan jenis endpoint tetap Chat Completions.
8. Biarkan Metode autentikasi sebagai Kunci (Bearer). Bearer adalah metode autentikasi dengan menyertakan API key dalam permintaan. Jika OmniProxy memberikan kunci kepada Anda, masukkan kunci tersebut ke API key. Jika gateway tidak memvalidasi kunci, biarkan kolom ini kosong. Pada 2026-10-09, verifikasi dan satu percakapan berhasil dilakukan dengan kolom tersebut dibiarkan kosong.
9. Klik Verifikasi koneksi di sebelah URL. Jika OmniProxy menyediakan /models, daftar model akan diambil pada tahap ini.
10. Buka Lanjutan. Jika ID model dibiarkan kosong, semua model yang dikembalikan oleh /models pada alamat tersebut akan digunakan. Hanya jika verifikasi gagal, masukkan ID lengkap dari daftar ke Tambahkan ID model, lalu klik Tambahkan. Tambahkan setiap ID hanya satu kali. Spasi sebelum dan sesudah ID akan dihapus.
11. Klik Simpan di jendela ini, lalu klik Simpan di sudut kanan bawah halaman koneksi eksternal.

Menyimpan konfigurasi saja tidak menggantikan verifikasi. Verifikasi koneksi mengirim permintaan ke /models milik layanan tujuan, yaitu endpoint untuk menampilkan daftar model yang tersedia. Beberapa layanan tidak menyediakan endpoint ini sehingga verifikasi akan menampilkan kesalahan, tetapi percakapan mungkin tetap dapat digunakan. Dalam kondisi tersebut, tambahkan ID model secara manual.

Memverifikasi tugas nyata

Kembali ke halaman percakapan, buka menu model di samping kolom input, lalu pilih ID lengkap dari daftar OmniProxy. Kirim kalimat yang sangat pendek, misalnya minta model hanya membalas dengan satu kata. Balasan harus benar-benar muncul di kotak percakapan.

Pada 2026-10-09, percakapan ini berhasil diselesaikan menggunakan instalasi Python v0.11.4. Docker tetap menjadi metode yang direkomendasikan, tetapi pengujian ini tidak diulangi menggunakan Docker.

Selanjutnya, buka catatan pemanggilan OmniProxy dan pastikan sumber permintaan serta ID model sesuai. Hanya melihat konfigurasi berhasil disimpan atau model muncul dalam menu belum berarti proses ini selesai.

Antarmuka

Model dapat dipilih

• Connections sudah disimpan
• Model muncul dalam daftar
• Kirim satu pertanyaan singkat

Balasan

Kotak obrolan menampilkan jawaban

• Bukan pesan kosong
• Bukan kesalahan koneksi
• Coba lagi dengan model lain

Catatan

Terlihat di gateway

• Sumbernya adalah koneksi ini
• ID model sesuai
• Tidak ada kunci yang masuk ke halaman

Kesalahan umum

• Menggunakan localhost atau 127.0.0.1 di dalam container: kedua alamat ini mengarah ke container itu sendiri, bukan host. Ganti dengan host.docker.internal dan pastikan perintah peluncuran menyertakan --add-host=host.docker.internal:host-gateway. Jika Open WebUI tidak berjalan di dalam container, lakukan sebaliknya dan gunakan alamat lokal.
• Browser tidak dapat membuka halaman: periksa port 3000 untuk Docker dan port 8080 untuk Python. Pada peluncuran pertama, tunggu hingga pengunduhan model embedding selesai. Gunakan docker ps untuk memastikan container sedang berjalan. Jika port 3000 sudah digunakan, ubah port di sebelah kiri opsi -p.
• ID dalam menu model lebih panjang daripada nama pendek dari penyedia: gunakan ID lengkap dari menu, termasuk garis miring di dalamnya.
• Semua pengguna dikeluarkan setelah pembaruan: nilai WEBUI_SECRET_KEY telah berubah. Jalankan ulang aplikasi menggunakan string rahasia yang dibuat pertama kali.
• Verifikasi koneksi gagal: tambahkan ID model secara manual di bagian Lanjutan, lalu konfirmasikan menggunakan percakapan nyata dengan satu kalimat. Beberapa layanan tidak menyediakan /models, sehingga percakapan mungkin tetap dapat digunakan meskipun verifikasi menampilkan kesalahan.
• Model tidak tersedia: salin ulang ID dari daftar OmniProxy saat ini dan jangan terus menggunakan nama yang sudah kedaluwarsa.

Referensi resmi

Perintah instalasi tersedia di Open WebUI Quick Start. Langkah-langkah koneksi tersedia di petunjuk koneksi OpenAI-compatible. ID model yang digunakan sebagai contoh tersedia di ringkasan model Claude dan daftar model Gemini.

Ganti setiap placeholder dengan nilai dari konfigurasi OmniProxy Anda sendiri. Jangan pernah menerbitkan kunci asli.

Hasil tersimpan atau HTTP 200 saja tidak membuktikan kompatibilitas Agen penuh. Periksa sumber dan model dalam catatan panggilan OmniProxy.

Sumber resmi · Open WebUI ↗