Open WebUI로 사내 AI 채팅 설치하기 — Docker · pip 설치부터 관리자 설정까지

KAITABASE가 공식 문서와 원문을 직접 읽고 새로 쓴 가이드입니다.

이 가이드로 할 수 있는 것

Open WebUI는 README가 "자체 호스팅 AI 플랫폼"이라고 소개하는 오픈소스 채팅 화면입니다. Ollama로 돌리는 로컬 모델과 OpenAI 호환 API를 한 화면에서 쓰고, 사용자 · 그룹 권한(RBAC), 문서 검색(RAG), 웹 검색을 붙일 수 있습니다. 공식 문서는 인터넷 없이도 돌아가게 만들었다고 설명합니다.

이 가이드를 따라 하면 다음이 됩니다.

1. Docker나 Python(pip)으로 Open WebUI를 설치합니다.
2. 첫 관리자 계정을 만들고, 모델(Ollama · OpenAI)을 연결합니다.
3. 동료를 초대하되 승인제로 받고, 비밀키 · 외부 노출을 안전하게 정합니다.

2026-10-22 기준 최신 버전은 v0.12.3(2026-10-16 배포)입니다. 이 컴퓨터에는 지원 범위 밖인 Python 3.14만 있어 설치와 실행은 공식 문서 기준으로 적었습니다.

빠른 시작

Docker가 있다면 공식 Quick Start의 명령 한 줄로 시작합니다. 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

공식 문서 기준(직접 실행 안 함): 브라우저에서 http://localhost:3000 을 열면 Create Admin Account 화면이 나옵니다.

STEP 1. 설치 방법 고르기

목표: 내 환경에 맞는 설치 방법을 하나 고릅니다. · 예상 시간: 3분

확인 내 Python 버전을 python --version 으로 봅니다. 3.11 · 3.12가 아니면 pip 방법 대신 Docker나 uv를 고릅니다.

막히면 직접 확인한 내용입니다. Python 3.14.3 가상환경에서 pip install open-webui 를 하자 Could not find a version that satisfies the requirement open-webui (from versions: none) 만 나왔습니다. 버전이 안 맞는다는 말이 없어 패키지가 없는 것처럼 보이지만, 실제 원인은 Python 버전입니다(PyPI 표기 <3.13.0a1,>=3.11).

STEP 2. Docker로 설치하기

목표: 데이터가 보존되는 컨테이너로 띄웁니다. · 예상 시간: 10분

공식 문서 기준(직접 실행 안 함):

1. 비밀키를 만듭니다: openssl rand -hex 32
2. 빠른 시작의 docker run 명령을 실행합니다. Ollama를 이 컴퓨터에서 이미 쓰고 있다면 이 명령이 그대로 맞습니다.
3. Ollama가 다른 서버에 있다면 -e OLLAMA_BASE_URL=https://example.com 을 붙입니다.
4. OpenAI API만 쓴다면 README의 -e OPENAI_API_KEY=your_secret_key 방식도 있습니다.
5. 이미지 크기가 부담되면 :main 대신 :slim 을 씁니다(:cuda · :ollama 와는 함께 못 씀).

확인 docker ps 에 open-webui 가 보이고, http://localhost:3000 이 열립니다.

막히면 모델 연결이 안 되면 대개 컨테이너가 127.0.0.1:11434 의 Ollama에 닿지 못한 것입니다. README는 --network=host 를 붙이고 OLLAMA_BASE_URL=http://127.0.0.1:11434 로 실행하라고 안내합니다. 이때 주소는 http://localhost:8080 으로 바뀝니다. Windows는 공식 문서가 PowerShell이 아닌 WSL 터미널에서 실행하라고 합니다.

주의 README는 -v open-webui:/app/backend/data 를 빼면 데이터베이스가 사라질 수 있다고 경고합니다. :dev 이미지는 야간 빌드라 운영 볼륨과 함께 쓰지 말라고 합니다.

되돌리기 docker rm -f open-webui 로 컨테이너를 지웁니다. 대화 · 계정까지 지우려면 docker volume rm open-webui 를 추가로 실행합니다. 볼륨을 지우면 되살릴 수 없습니다.

STEP 3. Python(pip · uv)으로 설치하기

목표: Docker 없이 내 PC에서 띄웁니다. · 예상 시간: 10분

공식 문서 기준(직접 실행 안 함). Python 3.11 가상환경에서:

1234python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install open-webui
open-webui serve

uv가 있다면 Python 버전을 따로 설치하지 않아도 됩니다. Windows PowerShell 예:

$env:DATA_DIR="C:\open-webui\data"; uvx --python 3.11 open-webui@latest serve

• 주소는 http://localhost:8080 입니다. --port, --host 로 바꿀 수 있습니다.
• DATA_DIR 로 데이터 저장 위치를 정합니다. uvx는 임시 캐시에서 돌기 때문에 꼭 지정하라고 문서가 강조합니다.
• pip 설치는 실행한 폴더에 .webui_secret_key 파일을 만듭니다. 매번 같은 폴더에서 시작하거나 WEBUI_SECRET_KEY 를 고정하지 않으면 모두 로그아웃됩니다.
• NVIDIA GPU가 없는 Linux x86_64에서는 먼저 pip install torch --index-url https://download.pytorch.org/whl/cpu 로 CPU용 PyTorch를 설치합니다.

확인 터미널에 서버 로그가 이어지고, 브라우저에서 8080 포트가 열립니다.

되돌리기 가상환경 폴더와 DATA_DIR 폴더를 지우면 모두 사라집니다.

STEP 4. 첫 관리자 계정 만들기

목표: 이 서버의 관리자를 정합니다. · 예상 시간: 2분

공식 문서 기준(직접 실행 안 함): 첫 화면의 Create Admin Account 로 만든 첫 계정이 관리자입니다. 그 뒤로는 가입이 자동으로 닫힙니다.

주의 서버를 띄우자마자 다른 사람이 먼저 접속하면 그 사람이 관리자가 됩니다. 외부에서 접속할 수 있게 열기 전에 관리자 계정부터 만듭니다.

막히면 혼자 쓰는 PC라면 -e WEBUI_AUTH=False 로 로그인 없이 쓸 수 있습니다. 다만 공식 문서는 이 모드와 다중 계정 모드를 나중에 서로 바꿀 수 없다고 밝힙니다. 팀에서 쓸 계획이면 켜지 않습니다. 관리자 비밀번호를 잃어버렸다면 공식 문서의 password-reset 절차를 따릅니다.

STEP 5. 모델 연결하기

목표: 채팅에서 쓸 모델을 붙입니다. · 예상 시간: 5분

공식 문서 기준(직접 실행 안 함). 관리자 화면 Settings > Admin > Connections 에서 연결합니다.

확인 저장하면 모델 목록이 자동으로 채워지고, 새 채팅 상단에서 모델을 고를 수 있습니다.

막히면 Ollama를 Docker 밖 PC에서 돌리는데 컨테이너에서 안 보이면, 공식 문서대로 Ollama가 0.0.0.0 에서 듣도록 설정합니다.

STEP 6. 동료 받기 — 승인제로 열기

목표: 아무나 쓰지 못하게 하면서 팀원을 받습니다. · 예상 시간: 5분

공식 문서 기준(직접 실행 안 함):

1. Settings > Admin > Authentication 에서 New Sign Ups 를 켭니다.
2. 새로 가입한 계정은 Pending 으로 대기합니다. 관리자 패널에서 승인합니다.
3. 보안 강화 문서는 가입을 열더라도 DEFAULT_USER_ROLE=pending 을 유지하라고 권합니다.
4. 비밀번호 규칙은 ENABLE_PASSWORD_VALIDATION=true, 2단계 인증은 ENABLE_MFA=true 로 켭니다.

확인 시험 계정으로 가입했을 때 바로 채팅이 되지 않고 승인 대기 화면이 나오면 맞게 된 것입니다.

되돌리기 New Sign Ups 를 다시 끄면 새 가입이 막힙니다. 이미 승인한 계정은 관리자 패널에서 따로 정리합니다.

STEP 7. 사내망에 열기 전 점검하기

목표: 외부에 노출하기 전 최소한의 안전장치를 겁니다. · 예상 시간: 5분

공식 보안 강화(Hardening) 문서는 Open WebUI가 "사적이고 신뢰할 수 있는 네트워크"용이며, 앞에 접근 제어 계층 없이 공용 인터넷에 직접 열지 말라고 합니다. 핵심만 추렸습니다.

주의 공식 문서는 기본 ChromaDB가 여러 워커 · 복제본 환경에서 안전하지 않다고 밝힙니다. 사용자가 늘어 여러 대로 돌릴 때는 외부 벡터 DB를 씁니다. 운영 DB는 DATABASE_URL 로 PostgreSQL을 권합니다.

STEP 8. 업데이트와 백업

목표: 데이터를 잃지 않고 새 버전으로 올립니다. · 예상 시간: 5분

공식 문서 기준(직접 실행 안 함): 업데이트 전에는 항상 데이터 볼륨(또는 DATA_DIR)을 백업합니다.

보안 강화 문서는 운영에서는 태그가 붙은 버전을 고정하고, 시험 환경에서 먼저 올려 보라고 권합니다.

잘못 쓰는 예 · 바르게 쓰는 예

바로 쓰는 프롬프트 · 템플릿

Open WebUI의 모델 설정에 넣는 사내 기본 지시(시스템 프롬프트) 예시입니다.

1234당신은 우리 회사 직원을 돕는 사내 AI 도우미입니다.
- 답은 한국어로, 결론을 먼저 쓰고 근거를 3줄 안으로 붙입니다.
- 고객 이름, 주민번호, 계좌번호 같은 개인정보가 입력되면 처리하지 말고 지우라고 안내합니다.
- 확실하지 않은 사실은 "확인 필요"라고 표시합니다.

설치 전 IT 담당자가 정리해 둘 체크리스트입니다.

12345678[ ] 설치 방법: Docker / pip(Python 3.11 · 3.12) / uv
[ ] 비밀키(WEBUI_SECRET_KEY) 보관 위치
[ ] 관리자 계정 담당자 1명
[ ] 가입 방식: 승인제(DEFAULT_USER_ROLE=pending)
[ ] 연결할 모델과 API 키 관리자
[ ] 접속 경로: 사내망 · VPN · 리버스 프록시
[ ] 백업 주기와 업데이트 담당
[ ] 예상 사용자 수(50명 초과 여부 → 라이선스)

주의할 점

• 요금: Open WebUI 자체는 무료로 설치할 수 있지만, 연결한 API(OpenAI 등)는 사용량만큼 요금이 나갑니다. 가격은 각 서비스 공식 요금 페이지에서 확인합니다. 기업 지원은 docs.openwebui.com/enterprise 의 Enterprise Plan으로 따로 안내합니다.
• 권한: 첫 계정이 관리자입니다. 관리자는 모든 사용자와 서버 설정을 관리하므로 담당자를 정해 둡니다.
• 보안: 공식 문서는 공용 인터넷에 직접 노출하지 말라고 명시합니다. 기본 설치는 시작할 때마다 GitHub(업데이트 확인), OpenAI(모델 목록), Hugging Face(임베딩 모델)에 연결하므로, 망 분리 환경이면 관련 환경 변수를 끄고 HF_HUB_OFFLINE=1 을 검토합니다.
• 데이터: 대화와 업로드 문서는 내 서버(볼륨 · DATA_DIR)에 쌓입니다. 외부 API 모델을 쓰면 질문 내용은 그 API로 나갑니다.
• 라이선스: 저장소의 Open WebUI License는 BSD 3조항 형태에 4번 조항이 붙어 있습니다. 30일 동안 직접 접속하는 사용자가 50명을 넘는 배포에서는, 저작권자의 서면 허락이나 기업 라이선스 없이 "Open WebUI" 이름 · 로고 등 브랜딩을 바꾸거나 지울 수 없습니다. 예전 코드는 LICENSE_HISTORY에 적힌 이전 라이선스를 따릅니다.

공식 자료

• Open WebUI 저장소 README — https://github.com/open-webui/open-webui
• Open WebUI License — https://github.com/open-webui/open-webui/blob/main/LICENSE
• Quick Start(설치 방법 전체) — https://docs.openwebui.com/getting-started/quick-start/
• 보안 강화(Hardening) — https://docs.openwebui.com/getting-started/advanced-topics/hardening/
• 업데이트 안내 — https://docs.openwebui.com/getting-started/updating/
• PyPI open-webui — https://pypi.org/project/open-webui/
• 릴리스 목록 — https://github.com/open-webui/open-webui/releases

더 보기

이 가이드는 KAITABASE가 공식 문서와 원문을 직접 읽고 실행해 본 뒤 새로 쓴 자료입니다. 같은 주제의 다른 글은 KAITABASE에서 이어서 볼 수 있습니다.

• 보안 · 조직 운영 자료 모음 — https://kaitabase.vercel.app/?area=secure-org
• KAITABASE 전체 자료 — https://kaitabase.vercel.app