Open WebUI 설치 및 OmniProxy 구성

Open WebUI는 직접 배포할 수 있는 채팅 인터페이스입니다. 자신의 컴퓨터나 서버에 설치할 수 있으며 완전히 오프라인으로도 실행할 수 있습니다. 특정 모델 공급자에 종속되지 않으므로, Ollama처럼 로컬에서 모델을 실행하는 도구뿐 아니라 동일한 요청 형식으로 모델 서비스를 제공하는 OpenAI 호환 API에도 연결할 수 있습니다. 따라서 로컬 모델과 클라우드 모델을 하나의 창에서 전환하며 사용할 수 있습니다.

팀과 조직에서 장기간 사용하기에도 적합합니다. 더 빠르게 업데이트되는 기능은 Open WebUI에서 새로운 기능을 시험하는 제품인 Computer에 먼저 제공됩니다.

설치 전 준비

Open WebUI는 macOS, Linux, Windows에서 사용할 수 있습니다. Docker, Python 또는 Kubernetes를 통해 설치할 수 있습니다. Docker는 애플리케이션과 실행 환경을 비교적 독립적인 컨테이너에 설치하는 권장 방식입니다. Docker가 없다면 아래에서 실제 테스트한 Python 명령을 사용할 수도 있습니다. Kubernetes는 컨테이너를 배포하고 관리하는 시스템이며, 관련 절차는 문서 마지막의 Quick Start를 참고하십시오.

공식 권장

Docker

docker run 한 줄
브라우저에서 3000 열기
데이터는 볼륨에 저장됨

채팅만 필요한 경우

slim 이미지

다운로드 크기가 더 작음
태그를 :slim으로 변경
채팅 기능은 그대로 있음

여기서는 다루지 않음

다른 두 가지 방법

Python 수동 설치
Kubernetes 배포
공식 Quick Start 참조

먼저 Docker를 설치한 다음 권장 명령으로 실행합니다. API를 통한 채팅만 필요하다면 이미지 태그를 slim으로 변경할 수 있습니다.

시작하기 전에 다음을 준비하십시오.

설치되어 정상적으로 실행되는 Docker
본인만 사용할 비밀 키 문자열. openssl rand -hex 32를 실행해 생성한 다음 WEBUI_SECRET_KEY에 입력합니다. 이 값은 변경하지 말고 보관해야 합니다. 컨테이너를 다시 만들 때 값이 바뀌면 로그인되어 있던 사용자가 로그아웃됩니다.
실행 중인 OmniProxy와 현재 모델 목록에 있는 모델 ID. 모델 ID는 사용할 모델을 선택할 때 쓰는 전체 이름입니다.

설치 및 최초 실행

터미널을 열고 Quick Start의 명령을 실행합니다. 먼저 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: 채팅, 사용자, 설정을 데이터 볼륨에 저장합니다. 데이터 볼륨은 컨테이너 외부에 데이터를 장기간 보관하는 위치이므로 컨테이너를 업데이트해도 내용이 유지됩니다. 따라서 이 항목을 제거하지 마십시오.
--add-host=host.docker.internal:host-gateway: 컨테이너에서 이 컴퓨터에서 실행 중인 다른 서비스에 접근할 수 있게 합니다.
--restart always: 컴퓨터가 다시 시작된 후 컨테이너도 다시 실행됩니다.

명령 실행 후 브라우저에서 http://localhost:3000을 열고 화면 안내에 따라 첫 번째 계정을 만드십시오.

API를 통한 채팅만 사용한다면 이미지 태그를 :main에서 :slim으로 변경할 수 있습니다. slim은 크기가 더 작은 이미지로, 컨테이너 내부의 로컬 음성 및 임베딩 모델은 포함하지 않지만 채팅 인터페이스는 계속 사용할 수 있습니다. 이러한 로컬 기능이 필요하다면 :main을 계속 사용하십시오.

업데이트할 때는 먼저 docker rm -f open-webui를 실행하고, 이어서 docker pull ghcr.io/open-webui/open-webui:main을 실행한 다음 동일한 docker run 명령으로 다시 시작합니다. 데이터 볼륨과 WEBUI_SECRET_KEY는 모두 기존 값을 유지해야 합니다.

Docker가 없는 경우

Quick Start에서는 Python 설치 방식도 제공합니다. 2026-10-09에 macOS에서 아래 명령으로 Open WebUI v0.11.4를 설치하고 대화 1회를 완료했습니다. 당시 이 컴퓨터에는 Docker Desktop이 설치되어 있지 않았습니다.

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

실행 후 브라우저에서 http://localhost:8080을 여십시오. 이 포트는 Python 설치 방식에서 사용하는 포트이며 Docker의 3000번 포트와 다릅니다.

처음 실행할 때 임베딩 모델을 다운로드하므로 몇 분이 걸릴 수 있습니다. 임베딩 모델은 텍스트를 검색과 일치 판정에 적합한 데이터로 변환합니다. 로그인 페이지가 나타날 때까지 기다린 후 계속 진행하십시오. 처음 등록한 계정이 관리자가 됩니다. 인터페이스 언어는 시스템 설정을 따르며, 이번 테스트에서는 중국어 간체로 표시되었습니다.

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: OmniProxy의 현재 모델 목록에서 전체 ID 복사

URL은 Open WebUI가 API에 연결할 때 사용하는 주소이며 /v1로 끝나야 합니다. 뒤에 /chat/completions를 추가하지 마십시오. 이 부분은 Open WebUI가 자동으로 붙입니다.

모델 ID는 OmniProxy의 현재 목록에서 전체 값을 복사해야 합니다. ID에 공급자 접두사와 슬래시가 포함되어 있다면 모두 유지하십시오. 아래의 두 짧은 이름은 2026-10-09 기준 공급자 문서와 대조하기 위한 예시일 뿐입니다. 현재 목록에 없다면 사용하지 마십시오.

Claude Sonnet 5.5의 Claude API ID: claude-sonnet-5-5
Gemini 3.8 Flash의 API 이름: gemini-3.8-flash

공급자 키를 Open WebUI에 입력하지 마십시오. 게이트웨이에서 키를 검증하지 않는다면 API 키를 비워 두고 임의의 키를 만들지 마십시오.

브라우저

로컬 3000

채팅 페이지 열기
먼저 가입 완료
그다음 설정으로 이동

컨테이너 내부

Open WebUI

localhost를 입력하지 않기
호스트 머신 이름으로 변경
URL은 /v1로 끝나야 함

같은 컴퓨터

OmniProxy

키는 게이트웨이에 유지
모델 목록은 게이트웨이를 기준으로 함
그다음 호출 기록 확인

Open WebUI가 Docker 안에서 실행되고 OmniProxy가 호스트에서 실행된다면 주소에 컨테이너의 localhost를 사용하지 마십시오.

모델 서비스가 호스트에서 실행되고 Open WebUI가 Docker 컨테이너 안에서 실행된다면 URL의 localhost를 host.docker.internal로 변경하십시오. 호스트는 Docker를 직접 실행하는 컴퓨터를 뜻합니다. OmniProxy가 이 컴퓨터에서만 수신한다면 URL을 http://host.docker.internal:포트/v1 형식으로 입력할 수 있습니다. 여기서 포트는 OmniProxy가 실제로 사용하는 포트로 바꿔야 합니다.

Open WebUI가 이전 절의 Python 명령으로 로컬에서 실행되고 OmniProxy도 로컬에서 실행된다면 주소에 127.0.0.1 또는 localhost를 사용하십시오. 이 경우 host.docker.internal을 사용하면 안 됩니다.

도구 구성 입력

2026-10-09 기준 v0.11.4의 중국어 간체 인터페이스에서는 영어 설명에 나오는 Settings > Admin > Connections와 메뉴 이름이 달랐습니다. 실제로 표시된 현지화 메뉴에 따라 다음과 같이 진행하십시오.

왼쪽 사이드바를 펼칩니다.
아래쪽의 사용자 메뉴를 클릭합니다.
설정을 클릭합니다.
아래쪽의 관리자 그룹에서 외부 연결을 클릭합니다.
OpenAI 인터페이스를 엽니다.
OpenAI 인터페이스 연결 관리 오른쪽의 **+**를 클릭합니다.
표시되는 연결 편집 창에서 URL을 /v1까지 입력합니다. 인터페이스 유형은 Chat Completions로 유지합니다.
인증 방식은 **키(Bearer)**로 유지합니다. Bearer는 요청에 API 키를 넣어 인증하는 방식입니다. OmniProxy에서 키를 제공했다면 API 키에 입력하십시오. 게이트웨이에서 키를 검증하지 않는다면 이 필드는 비워 둡니다. 2026-10-09 테스트에서는 비워 둔 상태로 연결 검증과 대화 1회가 모두 성공했습니다.
URL 옆의 연결 검증을 클릭합니다. OmniProxy에서 /models를 제공하면 여기에서 모델 목록을 가져옵니다.
고급을 엽니다. 모델 ID를 비워 두면 해당 주소의 /models가 반환하는 모든 모델을 사용합니다. 검증에 실패한 경우에만 모델 ID 추가에 목록의 전체 ID를 입력한 다음 추가를 클릭하십시오. 각 ID는 한 번만 추가하며 앞뒤 공백은 제거됩니다.
이 창에서 저장을 클릭한 다음 외부 연결 페이지 오른쪽 아래의 저장을 클릭합니다.

구성 저장만으로는 검증을 대신할 수 없습니다. 연결 검증은 사용 가능한 모델을 나열하는 상대 서비스의 /models를 요청합니다. 일부 서비스에는 이 API가 없어 검증 오류가 발생하더라도 채팅은 작동할 수 있습니다. 이 경우 모델 ID를 직접 추가하십시오.

실제 작업 검증

채팅 페이지로 돌아가 입력란 옆의 모델 메뉴를 열고 OmniProxy 목록에 있는 전체 ID를 선택합니다. 한 단어로만 답하도록 요청하는 것처럼 아주 짧은 메시지를 보내십시오. 채팅 창에 실제 응답이 표시되어야 합니다.

2026-10-09에 v0.11.4의 Python 설치 환경에서 이 대화를 완료했습니다. Docker가 여전히 권장 방식이지만 이번 테스트를 Docker에서 다시 수행하지는 않았습니다.

이어서 OmniProxy의 호출 기록을 열고 이번 요청의 출처와 모델 ID를 확인합니다. 저장 성공만 확인했거나 모델이 메뉴에 표시되는 것만 확인했다면 완료된 것이 아닙니다.

인터페이스

모델을 선택할 수 있음

Connections가 저장됨
모델이 목록에 표시됨
짧은 질문 하나 보내기

응답

채팅창에 답변이 있음

빈 메시지가 아님
연결 오류가 아님
다른 모델로 한 번 더 시도

기록

게이트웨이에서 확인 가능

소스가 이번 연결임
모델 ID가 일치함
키가 페이지에 노출되지 않음

세 곳의 결과가 모두 일치해야 이 연결을 사용할 수 있습니다.

자주 발생하는 오류

컨테이너에서 localhost 또는 127.0.0.1을 사용함: 이 두 주소는 호스트가 아니라 컨테이너 자체를 가리킵니다. host.docker.internal로 변경하고 실행 명령에 --add-host=host.docker.internal:host-gateway가 포함되어 있는지 확인하십시오. Open WebUI가 컨테이너 밖에서 실행된다면 반대로 로컬 주소를 사용해야 합니다.
브라우저에서 열리지 않음: Docker는 3000번 포트, Python은 8080번 포트를 확인하십시오. 처음 실행할 때는 임베딩 모델 다운로드가 완료될 때까지 기다려야 합니다. docker ps로 컨테이너 실행 여부를 확인할 수 있습니다. 3000번 포트를 이미 사용 중이라면 -p 왼쪽의 포트를 변경하십시오.
모델 메뉴의 ID가 공급자의 짧은 이름보다 김: 슬래시를 포함해 메뉴에 표시된 전체 ID를 사용하십시오.
업데이트 후 모든 사용자가 로그아웃됨: WEBUI_SECRET_KEY가 변경되었습니다. 처음 생성한 비밀 키 문자열을 사용해 다시 시작하십시오.
연결 검증 실패: 먼저 고급에서 모델 ID를 직접 추가한 다음 실제 채팅 메시지 하나로 확인하십시오. 일부 서비스에는 /models가 없으므로 검증 오류가 발생해도 채팅은 작동할 수 있습니다.
모델이 존재하지 않음: OmniProxy의 현재 목록에서 ID를 다시 복사하고 더 이상 유효하지 않은 이름을 계속 사용하지 마십시오.

공식 참고 자료

설치 명령은 Open WebUI Quick Start를 참고하십시오. 연결 절차는 OpenAI-compatible 연결 안내를 참고하십시오. 예시에 사용된 모델 ID는 Claude 모델 개요와 Gemini 모델 목록을 참고하십시오.

모든 플레이스홀더를 고유한 OmniProxy 구성의 값으로 바꾸세요. 실제 키를 게시하지 마세요.

저장된 결과나 HTTP 200 만으로는 전체 에이전트 호환성이 입증되지 않습니다. OmniProxy 호출 기록에서 소스와 모델을 확인하세요.

공식 소스 · Open WebUI ↗