Copy & Run

Open WebUI Ollama 연결: host.docker.internal:11434 고치기

Docker로 Open WebUI를 띄워 호스트의 Ollama에 연결하고, 주소를 localhost로 잘못 넣어 모델 목록이 비는 상태를 만든 뒤 원인을 찾아 고칩니다. 환경 변수를 바로잡아도 저장된 설정이 우선해 되돌아오지 않는 동작도 직접 확인합니다.

실습 노트 · 2026-10-27 발행 · 2026-11-12 수정 · 9분 · 2026-10 확인

Open WebUI는 Ollama에 브라우저 채팅 화면을 붙여 주는 오픈소스 웹 앱입니다. 설치 자체는 컨테이너 하나로 끝나지만, 처음 쓰는 사람은 "모델 목록이 비어 있다"는 증상에서 가장 많이 막힙니다. 이 글에서는 Docker로 Open WebUI를 띄워 호스트의 Ollama에 연결하고, 일부러 주소를 틀리게 넣어 모델이 보이지 않는 상태를 만든 뒤 원인을 찾아 고칩니다. 그 과정에서 환경 변수를 바로잡아도 설정이 돌아오지 않는 함정도 직접 확인했습니다.

준비물

항목 확인한 버전
Docker 29.5.3 (Docker Desktop, Windows 11)
Open WebUI v0.12.4 (ghcr.io/open-webui/open-webui:main, 이미지 약 6.4GB)
Ollama (호스트) 0.32.15, 모델 5개 설치
브라우저 Chrome

Ollama가 호스트에서 이미 실행 중이어야 합니다. 이 글의 이미지는 main 태그이므로 시간이 지나면 버전이 달라질 수 있습니다. 같은 결과를 원하면 docker-compose.yml의 태그를 위 버전에 맞는 고정 태그로 바꿉니다. 고정 태그 이름은 이 글에서 확인하지 않았습니다.

이 단계의 파일 내려받기:docker-compose.yml

1. 컨테이너 띄우기

docker-compose.yml을 만듭니다. 핵심은 두 가지입니다. OLLAMA_BASE_URL에 컨테이너 안에서 본 호스트 주소인 host.docker.internal을 쓰고, extra_hosts로 그 이름이 호스트를 가리키게 합니다. 포트는 127.0.0.1에만 열어 내 PC 밖에서 접속하지 못하게 했습니다.

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: cr-open-webui
    ports:
      - "127.0.0.1:5600:8080"
    environment:
      OLLAMA_BASE_URL: ${OLLAMA_BASE_URL:-http://host.docker.internal:11434}
      WEBUI_AUTH: "True"
      ENABLE_SIGNUP: "True"
      WEBUI_SECRET_KEY: lab-only-secret-change-me
      ANONYMIZED_TELEMETRY: "False"
      SCARF_NO_ANALYTICS: "true"
      DO_NOT_TRACK: "true"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - open-webui-data:/app/backend/data

volumes:
  open-webui-data:

OLLAMA_BASE_URL은 ${OLLAMA_BASE_URL:-기본값} 형식이라, 아무것도 지정하지 않으면 올바른 주소가 쓰이고 4단계의 실패 실험에서는 명령줄에서 값을 바꿀 수 있습니다. WEBUI_SECRET_KEY는 실습용 값이므로 실제로 쓸 때는 반드시 바꿉니다. 텔레메트리 관련 세 변수는 통계를 보내지 않게 끄는 값입니다.

docker compose up -d
curl -s localhost:5600/health
# 기대 출력
{"status":true}

처음 시작할 때는 준비하는 데 1분 안팎이 걸렸고, 그 사이에는 브라우저에서 ERR_EMPTY_RESPONSE가 나왔습니다. /health가 true를 돌려줄 때까지 기다립니다.

이 단계의 파일 내려받기:docker-compose.yml

2. 관리자 계정 만들고 모델 확인하기

브라우저에서 http://localhost:5600을 열면 환영 화면이 나옵니다.

Welcome to your AI home 문구와 Get started 버튼이 있는 Open WebUI 첫 화면
Welcome to your AI home 문구와 Get started 버튼이 있는 Open WebUI 첫 화면

Get started를 누르면 관리자 계정을 만드는 화면이 나옵니다. 이름, 이메일, 비밀번호를 입력합니다. 첫 번째로 만든 계정이 자동으로 관리자가 됩니다. 화면에는 외부 연결 없이 데이터가 이 서버에만 남는다고 적혀 있습니다.

Create Admin Account 버튼과 이름, 이메일, 비밀번호 입력칸이 있는 관리자 계정 생성 화면
Create Admin Account 버튼과 이름, 이메일, 비밀번호 입력칸이 있는 관리자 계정 생성 화면

가입 뒤 처음 열리는 새 소식 창은 Okay, Let's Go!로 닫습니다. 채팅 입력칸 오른쪽의 모델 이름을 누르면 Ollama에 설치된 모델이 목록으로 나옵니다.

모델 선택 목록에 호스트 Ollama의 모델 다섯 개가 크기와 함께 나열된 Open WebUI 화면
모델 선택 목록에 호스트 Ollama의 모델 다섯 개가 크기와 함께 나열된 Open WebUI 화면

목록에는 ollama list의 모델이 모두 나옵니다. 모델 이름 옆의 초록 점은 지금 Ollama가 메모리에 올려 둔 모델이라는 표시로 보입니다. 임베딩 모델(nomic-embed-text)도 목록에 같이 나오지만 채팅에는 쓸 수 없습니다.

모델 하나를 골라 질문해 봅니다.

gemma4:31b 모델이 안녕하세요로 시작하는 한국어 한 문장으로 연결이 완료되었다고 답한 채팅 화면
gemma4:31b 모델이 안녕하세요로 시작하는 한국어 한 문장으로 연결이 완료되었다고 답한 채팅 화면

메모리에 올라 있지 않은 모델은 첫 응답에 올리는 시간이 더해집니다. 같은 질문을 3B 모델(qwen2.5:3b-instruct-q4_K_M)로 보냈을 때는 질문과 상관없는 제목 제안 같은 답이 나왔습니다. 연결의 문제가 아니라 작은 모델의 품질 문제로 보이지만 원인은 확인하지 않았습니다.

3. 연결 설정은 어디에 있는가

연결 주소는 왼쪽 아래 프로필에서 관리자 설정을 열고 Connections로 가면 볼 수 있습니다. 주소 /admin/settings/connections를 바로 열어도 됩니다.

Connections 화면에 Ollama API가 켜져 있고 연결 주소 http://host.docker.internal:11434가 표시된 모습
Connections 화면에 Ollama API가 켜져 있고 연결 주소 http://host.docker.internal:11434가 표시된 모습

Ollama API 아래 연결 한 줄이 지금 쓰는 주소입니다. 같은 값을 스크립트로도 확인할 수 있게 check-ollama.sh를 만듭니다. 컨테이너에 설정된 환경 변수, Open WebUI가 저장해 둔 주소, 보이는 모델 수를 나란히 보여 줍니다. 인자로 주소를 주면 저장된 주소를 그 값으로 바꿉니다. 스크립트 위쪽의 USER_ID, MAIL_HOST, PASS는 2단계에서 만든 계정 값으로 맞춥니다.

#!/bin/bash
# Open WebUI 가 실제로 쓰는 Ollama 주소와 보이는 모델 수를 확인합니다.
# 사용법: ./check-ollama.sh [새 Ollama 주소]   (주소를 주면 그 값으로 바꿉니다)
BASE=http://localhost:5600
USER_ID=lab
MAIL_HOST=lab.test
EMAIL="$USER_ID@$MAIL_HOST"
PASS=lab-only-pass-123

TOKEN=$(curl -s -X POST $BASE/api/v1/auths/signin -H 'content-type: application/json' \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASS\"}" | python -c "import sys,json;print(json.load(sys.stdin)['token'])")

if [ -n "$1" ]; then
  curl -s -X POST $BASE/ollama/config/update -H "Authorization: Bearer $TOKEN" \
    -H 'content-type: application/json' \
    -d "{\"ENABLE_OLLAMA_API\":true,\"OLLAMA_BASE_URLS\":[\"$1\"],\"OLLAMA_API_CONFIGS\":{}}" > /dev/null
fi

echo "container env : $(docker exec cr-open-webui printenv OLLAMA_BASE_URL)"
echo "saved setting : $(curl -s $BASE/ollama/config -H "Authorization: Bearer $TOKEN" | python -c "import sys,json;print(json.load(sys.stdin)['OLLAMA_BASE_URLS'][0])")"
echo "models seen   : $(curl -s $BASE/api/models -H "Authorization: Bearer $TOKEN" | python -c "import sys,json;print(len(json.load(sys.stdin)['data']))")"
./check-ollama.sh
# 기대 출력
container env : http://host.docker.internal:11434
saved setting : http://host.docker.internal:11434
models seen   : 5
이 단계의 파일 내려받기:check-ollama.sh

4. 주소를 틀리게 넣어 보기

가장 흔한 실수는 Ollama 주소를 localhost로 쓰는 것입니다. 컨테이너 안에서 localhost는 호스트가 아니라 컨테이너 자신입니다. 데이터 볼륨까지 지우고 환경 변수만 틀리게 주어 처음부터 다시 시작합니다. 이 명령은 연습용 볼륨의 Open WebUI 데이터를 모두 지웁니다.

docker compose down -v
OLLAMA_BASE_URL=http://localhost:11434 docker compose up -d

관리자 계정을 다시 만들고 모델 목록을 열면 비어 있습니다.

모델 선택 목록에 No models available 문구와 Manage Connections 링크만 나오는 Open WebUI 화면
모델 선택 목록에 No models available 문구와 Manage Connections 링크만 나오는 Open WebUI 화면

No models available이라고만 나오고 오류 문구는 없습니다. 원인은 Connections 화면에서 보입니다.

Connections 화면의 Ollama 연결 주소가 http://localhost:11434로 되어 있는 모습
Connections 화면의 Ollama 연결 주소가 http://localhost:11434로 되어 있는 모습

주소가 http://localhost:11434입니다. 컨테이너 안에서 두 주소를 직접 시험하면 차이가 분명합니다.

for h in localhost host.docker.internal; do echo "== $h"; docker exec cr-open-webui curl -sS -m 5 http://$h:11434/api/version 2>&1; echo; done
# 기대 출력
== localhost
curl: (7) Failed to connect to localhost port 11434 after 0 ms: Could not connect to server

== host.docker.internal
{"version":"0.32.15"}

컨테이너 안에서 localhost는 연결 실패, host.docker.internal은 Ollama 버전을 돌려주는 터미널 화면
컨테이너 안에서 localhost는 연결 실패, host.docker.internal은 Ollama 버전을 돌려주는 터미널 화면

이 단계의 파일 내려받기:docker-compose.yml

5. 환경 변수를 고쳐도 되돌아오지 않습니다

이제 환경 변수를 바로잡아 다시 시작하면 될 것 같지만 그렇지 않았습니다.

docker compose up -d
./check-ollama.sh
# 기대 출력
container env : http://host.docker.internal:11434
saved setting : http://localhost:11434
models seen   : 0

컨테이너 환경 변수는 올바른 주소인데 저장된 설정은 localhost이고 보이는 모델이 0개인 터미널 화면
컨테이너 환경 변수는 올바른 주소인데 저장된 설정은 localhost이고 보이는 모델이 0개인 터미널 화면

컨테이너의 환경 변수는 올바른 값인데, Open WebUI가 저장한 설정은 여전히 localhost입니다. 처음 시작할 때 데이터 볼륨에 저장된 값이 그 뒤로는 환경 변수보다 우선하는 것으로 보입니다. 같은 현상을 반대 방향으로도 확인했습니다. 올바르게 연결된 상태에서 환경 변수만 틀린 값으로 바꿔 다시 시작해도 저장된 올바른 주소가 유지되었고 모델 5개가 그대로 보였습니다. 매번 환경 변수를 따르게 하는 ENABLE_PERSISTENT_CONFIG 옵션이 있다고 알려져 있지만, 이 글에서는 시험하지 않았습니다.

고치는 방법은 두 가지입니다. 화면의 Connections에서 주소 줄의 톱니 아이콘을 눌러 주소를 고치고 Save를 누르거나, 같은 설정을 API로 바꿉니다. 이 글에서는 스크립트에 주소를 주어 API로 바꿨습니다.

./check-ollama.sh http://host.docker.internal:11434
# 기대 출력
container env : http://host.docker.internal:11434
saved setting : http://host.docker.internal:11434
models seen   : 5

저장된 설정이 host.docker.internal로 바뀌고 보이는 모델이 5개로 돌아온 터미널 화면
저장된 설정이 host.docker.internal로 바뀌고 보이는 모델이 5개로 돌아온 터미널 화면

화면에서도 모델이 돌아왔습니다. 모델 선택 칸에 gemma4:31b가 기본으로 잡혀 있습니다.

주소를 고친 뒤 모델 선택 칸에 gemma4:31b가 선택되어 있고 채팅을 시작할 수 있는 Open WebUI 화면
주소를 고친 뒤 모델 선택 칸에 gemma4:31b가 선택되어 있고 채팅을 시작할 수 있는 Open WebUI 화면

이 단계의 파일 내려받기:check-ollama.sh

자주 막히는 곳

증상 원인과 해결
처음 접속할 때 ERR_EMPTY_RESPONSE 컨테이너가 아직 준비 중. curl localhost:5600/health가 true가 될 때까지 대기
모델 목록이 No models available Connections의 Ollama 주소 확인. 컨테이너 안에서는 localhost가 아니라 host.docker.internal 사용
환경 변수를 고쳐도 그대로임 저장된 설정이 우선. 화면의 Connections에서 고치거나, 데이터 볼륨을 지우고 다시 시작
모델은 보이는데 임베딩 모델로 채팅 불가 nomic-embed-text는 임베딩 전용. 채팅에는 일반 모델 선택
첫 응답이 매우 느림 모델을 메모리에 올리는 시간. 한 번 올라가면 다음부터 빨라짐
포트 5600이 이미 사용 중 docker-compose.yml의 왼쪽 포트 숫자 변경
이 단계의 파일 내려받기:docker-compose.yml

이어서 해 볼 것

  • 계정 가입 닫기: ENABLE_SIGNUP을 "False"로 바꿔 관리자 외의 가입을 막으면 화면이 어떻게 달라지는지 봅니다. 이 글에서는 시험하지 않았습니다.
  • 다른 접속 방식: Ollama가 호스트가 아니라 다른 컨테이너나 다른 PC에 있을 때의 주소 지정은 시험하지 않았습니다.
  • 정리: 실습이 끝나면 docker compose down -v로 컨테이너와 볼륨을 지웁니다. 이미지(docker image rm)는 6.4GB를 차지합니다.

확인 범위

  • 해 본 것: 2026-10-27, Windows 11 · Docker 29.5.3 · Open WebUI v0.12.4 · 호스트 Ollama 0.32.15에서 직접 실행했습니다. 컨테이너 시작, 관리자 계정 생성, 모델 목록, 채팅 응답을 확인했습니다. 주소를 틀리게 넣었을 때의 빈 목록, 환경 변수를 고쳐도 저장된 설정이 유지되는 동작, 주소를 고친 뒤의 복구도 실행 결과입니다.
  • 해 보지 않은 것: 환경 변수가 저장된 값에 밀리는 이유를 문서나 소스에서 확인하지 못했습니다. 화면의 Save 버튼으로 고치는 경로, ENABLE_PERSISTENT_CONFIG, 파일 업로드와 RAG 같은 다른 기능은 실행하지 못했습니다. Linux 호스트에서의 host.docker.internal 동작도 실행하지 못했습니다.

이 글은 Ollama와 로컬 LLM 실습 로드맵의 한 단계입니다.

이 글의 다음 단계

AI·LLM 활용 실무 과정의 일부입니다

이 실습은 교육에서 참가자마다 독립된 환경으로 진행합니다. 원하는 일정을 고르면 문의 양식에 미리 채워집니다.

과정 보기

팀이나 교육 담당자에게 이 글 제안하기

교육 진행 순서와 자주 묻는 질문 보기

같은 카테고리의 글