Cài đặt Open WebUI và cấu hình OmniProxy

Open WebUI là giao diện trò chuyện có thể tự triển khai trên máy tính hoặc máy chủ của bạn, đồng thời cũng có thể hoạt động hoàn toàn ngoại tuyến. Công cụ này không bị ràng buộc với một nhà cung cấp mô hình cụ thể: bạn có thể kết nối với các công cụ chạy mô hình cục bộ như Ollama hoặc với API tương thích định dạng OpenAI, tức là những địa chỉ cung cấp dịch vụ mô hình bằng cùng định dạng yêu cầu. Nhờ đó, bạn có thể chuyển đổi giữa mô hình cục bộ và mô hình đám mây ngay trong cùng một cửa sổ.

Công cụ này phù hợp để các nhóm và tổ chức sử dụng lâu dài. Những tính năng được cập nhật nhanh hơn sẽ xuất hiện trước trong Computer, sản phẩm mà Open WebUI dùng để thử nghiệm các chức năng mới.

Chuẩn bị trước khi cài đặt

Open WebUI có thể được sử dụng trên macOS, Linux và Windows. Bạn có thể cài đặt bằng Docker, Python hoặc Kubernetes. Docker đóng gói ứng dụng và môi trường chạy trong một container tương đối độc lập, vì vậy đây là phương thức được khuyến nghị. Nếu không có Docker, bạn cũng có thể dùng lệnh Python đã được kiểm thử bên dưới. Kubernetes là hệ thống dùng để triển khai và quản lý container; các bước tương ứng có trong Quick Start ở cuối bài.

Khuyến nghị chính thức

Docker

• Một lệnh docker run
• Mở cổng 3000 trong trình duyệt
• Dữ liệu nằm trong volume

Chỉ muốn trò chuyện

Image slim

• Dung lượng tải xuống nhỏ hơn
• Đổi tag thành :slim
• Chức năng trò chuyện vẫn còn

Không trình bày chi tiết ở đây

Hai cách khác

• Cài đặt Python thủ công
• Triển khai Kubernetes
• Xem Quick Start chính thức

Trước khi bắt đầu, hãy chuẩn bị:

• Docker đã được cài đặt và có thể chạy.
• Một chuỗi khóa chỉ dành cho riêng bạn. Chạy openssl rand -hex 32 để tạo, sau đó điền vào WEBUI_SECRET_KEY. Giá trị này phải được lưu cố định; nếu thay đổi khi tạo lại container, những người đã đăng nhập sẽ bị đăng xuất.
• OmniProxy đang chạy và ID mô hình trong danh sách mô hình hiện tại của nó. ID mô hình là tên đầy đủ được dùng khi chọn một mô hình cụ thể.

Cài đặt và khởi chạy lần đầu

Mở terminal và chạy lệnh trong Quick Start. Trước tiên, thay your-secret-key bằng chuỗi khóa vừa tạo:

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

Các tùy chọn trong lệnh này có chức năng như sau:

• -p 3000:8080: cho phép bạn mở giao diện qua cổng 3000 của máy tính này. Nếu cổng 3000 đã được sử dụng, hãy đổi số ở bên trái.
• -v open-webui:/app/backend/data: lưu cuộc trò chuyện, người dùng và cài đặt vào volume dữ liệu. Volume dữ liệu là nơi lưu dữ liệu lâu dài bên ngoài container; nội dung vẫn còn sau khi cập nhật container, vì vậy đừng bỏ tùy chọn này.
• --add-host=host.docker.internal:host-gateway: cho phép container truy cập các dịch vụ khác đang chạy trên máy tính này.
• --restart always: container sẽ khởi động lại sau khi máy tính được khởi động lại.

Sau khi lệnh chạy xong, mở http://localhost:3000 trong trình duyệt và làm theo hướng dẫn trên trang để tạo tài khoản đầu tiên.

Nếu chỉ trò chuyện qua API, bạn có thể đổi thẻ image từ :main thành :slim. slim là image có dung lượng nhỏ hơn, không chứa các mô hình giọng nói và embedding cục bộ bên trong container, nhưng giao diện trò chuyện vẫn dùng được. Nếu cần những khả năng cục bộ này, hãy tiếp tục dùng :main.

Khi cập nhật thủ công, trước tiên chạy docker rm -f open-webui, sau đó chạy docker pull ghcr.io/open-webui/open-webui:main, rồi khởi động lại bằng chính lệnh docker run ở trên. Phải giữ nguyên cả volume dữ liệu và WEBUI_SECRET_KEY.

Khi không có Docker

Quick Start cũng cung cấp phương thức cài đặt bằng Python. Ngày 2026-10-09, lệnh bên dưới đã được dùng trên macOS để cài đặt Open WebUI v0.11.4 và hoàn thành một cuộc trò chuyện. Khi đó, máy tính này không cài Docker Desktop.

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

Sau khi khởi chạy, mở http://localhost:8080 trong trình duyệt. Đây là cổng dùng cho phương thức cài đặt bằng Python, không phải cổng 3000 của Docker.

Trong lần khởi chạy đầu tiên, chương trình sẽ tải xuống một mô hình embedding và quá trình này có thể mất vài phút. Mô hình embedding chuyển văn bản thành dữ liệu thuận tiện cho việc tìm kiếm và đối chiếu. Hãy chờ đến khi trang đăng nhập xuất hiện rồi mới tiếp tục; tài khoản đăng ký đầu tiên sẽ trở thành quản trị viên. Ngôn ngữ giao diện phụ thuộc vào hệ thống; trong lần kiểm thử này, giao diện hiển thị bằng tiếng Trung giản thể.

DATA_DIR phải trỏ đến một thư mục được lưu giữ lâu dài để chứa dữ liệu của Open WebUI. Nếu không thiết lập, dữ liệu có thể được lưu trong thư mục tạm thời và bị mất sau khi đóng chương trình. Khi không thiết lập WEBUI_SECRET_KEY, chương trình sẽ ghi tệp .webui_secret_key vào thư mục hiện tại. Hãy khởi chạy từ thư mục bạn dự định lưu giữ hoặc tự thiết lập biến này.

Lấy thông số kết nối từ OmniProxy

Sao chép ba mục sau từ OmniProxy của bạn:

URL:      https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: sao chép ID đầy đủ từ danh sách mô hình hiện tại của OmniProxy

URL là địa chỉ mà Open WebUI dùng để kết nối với API và phải kết thúc bằng /v1. Không thêm /chat/completions vào phía sau vì Open WebUI sẽ tự nối phần này.

Phải sao chép đầy đủ ID mô hình từ danh sách hiện tại của OmniProxy. Nếu ID có tiền tố nguồn và dấu gạch chéo, bạn cũng phải giữ nguyên chúng. Hai tên ngắn dưới đây chỉ dùng để đối chiếu với tài liệu của nhà cung cấp vào ngày 2026-10-09; nếu không có trong danh sách hiện tại thì không được sử dụng:

• ID Claude API của Claude Sonnet 5.5: claude-sonnet-5-5
• Tên API của Gemini 3.8 Flash: gemini-3.8-flash

Không điền khóa của nhà cung cấp vào Open WebUI. Nếu gateway không xác minh khóa, bạn có thể để trống API key; không tự tạo thêm một chuỗi khóa khác.

Trình duyệt

Cổng 3000 trên máy cục bộ

• Mở trang trò chuyện
• Hoàn tất đăng ký trước
• Sau đó vào phần cài đặt

Trong container

Open WebUI

• Không dùng localhost
• Thay bằng tên máy chủ
• URL kết thúc bằng /v1

Trên cùng một máy tính

OmniProxy

• Giữ khóa tại gateway
• Danh sách mô hình phải theo gateway
• Sau đó xem nhật ký lệnh gọi

Nếu dịch vụ mô hình chạy trên máy chủ còn Open WebUI chạy trong container Docker, hãy thay localhost trong URL bằng host.docker.internal. Máy chủ ở đây là máy tính trực tiếp chạy Docker. Nếu OmniProxy chỉ lắng nghe trên máy tính này, URL có thể được viết là http://host.docker.internal:cổng/v1, trong đó cổng phải được thay bằng cổng thực tế mà OmniProxy sử dụng.

Nếu Open WebUI chạy cục bộ bằng lệnh Python ở phần trước và OmniProxy cũng chạy cục bộ, hãy dùng 127.0.0.1 hoặc localhost trong địa chỉ. Trong trường hợp này, không dùng host.docker.internal.

Điền cấu hình công cụ

Trong giao diện tiếng Trung giản thể của v0.11.4 vào ngày 2026-10-09, tên mục khác với Settings > Admin > Connections trong hướng dẫn tiếng Anh. Hãy thao tác theo các tùy chọn thực tế hiển thị trên giao diện:

1. Mở rộng thanh bên trái.
2. Nhấp vào menu người dùng ở phía dưới.
3. Nhấp vào Cài đặt.
4. Trong nhóm dành cho quản trị viên ở phía dưới, nhấp vào Kết nối bên ngoài.
5. Mở API OpenAI.
6. Nhấp vào + ở bên phải mục Quản lý kết nối API OpenAI.
7. Trong cửa sổ Chỉnh sửa kết nối xuất hiện, điền URL kết thúc bằng /v1. Giữ loại API là Chat Completions.
8. Giữ Phương thức xác thực là Khóa (Bearer). Bearer là phương thức đặt API key vào yêu cầu để xác thực danh tính. Khi OmniProxy cung cấp khóa cho bạn, hãy điền khóa đó vào API key. Nếu gateway không xác minh khóa, hãy để trống trường này. Ngày 2026-10-09, sau khi để trống, cả việc xác minh và một cuộc trò chuyện đều thành công.
9. Nhấp vào Xác minh kết nối bên cạnh URL. Nếu OmniProxy cung cấp /models, danh sách mô hình sẽ được lấy tại đây.
10. Mở Nâng cao. Khi để trống ID mô hình, hệ thống sẽ sử dụng tất cả mô hình do /models của địa chỉ này trả về. Chỉ khi xác minh thất bại, hãy điền ID đầy đủ trong danh sách vào Thêm ID mô hình, rồi nhấp vào Thêm. Mỗi ID chỉ thêm một lần; khoảng trắng ở đầu và cuối sẽ bị loại bỏ.
11. Nhấp vào Lưu trong cửa sổ này, sau đó nhấp vào Lưu ở góc dưới bên phải của trang kết nối bên ngoài.

Chỉ lưu cấu hình không thể thay thế bước xác minh. Xác minh kết nối gửi yêu cầu đến /models của bên kia, tức API dùng để liệt kê các mô hình khả dụng. Một số dịch vụ không có API này nên bước xác minh sẽ báo lỗi, nhưng tính năng trò chuyện vẫn có thể hoạt động. Khi đó, hãy thêm ID mô hình theo cách thủ công.

Xác minh bằng một tác vụ thực tế

Quay lại trang trò chuyện, mở menu mô hình bên cạnh ô nhập và chọn ID đầy đủ trong danh sách OmniProxy. Gửi một câu thật ngắn, chẳng hạn yêu cầu mô hình chỉ trả lời bằng một từ. Câu trả lời phải thực sự xuất hiện trong khung trò chuyện.

Ngày 2026-10-09, cuộc trò chuyện này đã được hoàn thành bằng bản cài đặt Python của v0.11.4. Docker vẫn là phương thức được khuyến nghị, nhưng lần kiểm thử này không được thực hiện lại trong Docker.

Sau đó, mở nhật ký lệnh gọi của OmniProxy và xác nhận nguồn cùng ID mô hình của yêu cầu này. Chỉ thấy thông báo lưu thành công hoặc chỉ thấy mô hình xuất hiện trong menu vẫn chưa được xem là hoàn tất.

Giao diện

Có thể chọn mô hình

• Connections đã được lưu
• Mô hình xuất hiện trong danh sách
• Gửi một câu hỏi ngắn

Phản hồi

Khung trò chuyện có câu trả lời

• Không phải tin nhắn trống
• Không phải lỗi kết nối
• Đổi sang mô hình khác rồi thử lại

Nhật ký

Có thể thấy trên gateway

• Nguồn là kết nối này
• ID mô hình khớp
• Không có khóa xuất hiện trên trang

Các lỗi thường gặp

• Dùng localhost hoặc 127.0.0.1 bên trong container: hai địa chỉ này trỏ đến chính container chứ không phải máy chủ. Hãy đổi thành host.docker.internal và xác nhận lệnh khởi chạy có --add-host=host.docker.internal:host-gateway. Nếu Open WebUI không chạy trong container thì ngược lại, hãy dùng địa chỉ cục bộ.
• Không mở được trong trình duyệt: với Docker, hãy kiểm tra cổng 3000; với Python, hãy kiểm tra cổng 8080. Trong lần khởi chạy đầu tiên, cần chờ mô hình embedding tải xuống hoàn tất. Có thể dùng docker ps để xác nhận container có đang chạy hay không. Nếu cổng 3000 đã được sử dụng, hãy thay đổi cổng ở bên trái của -p.
• ID trong menu mô hình dài hơn tên ngắn của nhà cung cấp: hãy dùng ID đầy đủ trong menu, bao gồm cả dấu gạch chéo.
• Tất cả người dùng bị đăng xuất sau khi cập nhật: WEBUI_SECRET_KEY đã thay đổi. Hãy khởi động lại bằng chuỗi khóa được tạo trong lần đầu tiên.
• Xác minh kết nối thất bại: trước tiên hãy thêm ID mô hình theo cách thủ công trong Nâng cao, sau đó dùng một câu trò chuyện thực tế để kiểm tra. Một số dịch vụ không có /models; khi bước xác minh báo lỗi, tính năng trò chuyện vẫn có thể hoạt động.
• Mô hình không tồn tại: sao chép lại ID từ danh sách hiện tại của OmniProxy, không tiếp tục dùng tên đã hết hiệu lực.

Tài liệu tham khảo chính thức

Xem lệnh cài đặt tại Open WebUI Quick Start. Xem các bước kết nối tại Hướng dẫn kết nối OpenAI-compatible. Xem ID mô hình được dùng làm ví dụ tại Tổng quan mô hình Claude và Danh sách mô hình Gemini.

Thay thế mọi chỗ giữ chỗ bằng giá trị từ cấu hình OmniProxy của riêng bạn. Không bao giờ công bố khóa thật.

Kết quả được lưu hoặc mã HTTP 200 đơn lẻ không chứng minh khả năng tương thích đầy đủ của Agent. Hãy kiểm tra nguồn và mô hình trong bản ghi lệnh gọi của OmniProxy.

Nguồn chính thức · Open WebUI ↗