9 min read 7 June 2026

Odysseus AI와 Ollama 연결 설정: endpoint를 헷갈리지 않는 방법

기존 Ollama 서버를 Odysseus AI에서 쓰기 위한 실전 가이드입니다. Docker와 네이티브 경로, endpoint 확인, 초기 오류 해결을 정리했습니다.

Odysseus AI Wiki

Fan-made editorial notes based on public Odysseus AI documentation and local self-hosting patterns.

Odysseus AI와 Ollama 연결 설정: endpoint를 헷갈리지 않는 방법

짧은 답: Odysseus AI가 Docker에서 실행되고 Ollama가 호스트에서 실행된다면 Settings에 http://host.docker.internal:11434/v1 을 사용하세요. 둘 다 같은 머신에서 네이티브로 실행된다면 보통 localhost가 맞습니다. 가장 흔한 문제는 올바른 포트를 잘못된 네트워크 공간에서 바라보는 것입니다.

Odysseus AI가 Docker에서 실행되고 Ollama가 호스트에서 실행된다면 Settings에 http://host.docker.internal:11434/v1 을 사용하세요. 둘 다 같은 머신에서 네이티브로 실행된다면 보통 localhost가 맞습니다. 가장 흔한 문제는 올바른 포트를 잘못된 네트워크 공간에서 바라보는 것입니다. 기존 Ollama 서버를 Odysseus AI에서 쓰기 위한 실전 가이드입니다. Docker와 네이티브 경로, endpoint 확인, 초기 오류 해결을 정리했습니다.

Odysseus AI가 실행되는 위치에 맞는 endpoint 사용

The official Odysseus README calls out a Docker-specific Ollama endpoint: when Ollama runs on the host and Odysseus runs in a container, add the host endpoint in Settings. That endpoint is not a magic model name; it is the network address that lets a container reach a service running on the host.

For Docker installs, the practical default is host.docker.internal on port 11434 with the OpenAI-compatible /v1 path. For native installs where Odysseus AI and Ollama run on the same operating system session, start with localhost or 127.0.0.1 instead. Choose one path first, then test it directly before changing model settings.

Docker to host Ollama endpoint

http://host.docker.internal:11434/v1

Docker: Odysseus 컨테이너에서 호스트 Ollama로

This is the highest-value setup because many people follow the recommended Docker path for Odysseus AI but already have Ollama installed on the host. In that layout, localhost inside the container points back to the container, not to your laptop or workstation.

The connection has three parts: Ollama must be running, it must listen on an address the container can reach, and Odysseus AI must store the correct endpoint in Settings.

1. Start Ollama so it listens beyond its own loopback when needed

If Docker cannot reach Ollama, start Ollama with an explicit host binding. Keep this binding limited to trusted local use unless you understand your network exposure.

OLLAMA_HOST=0.0.0.0:11434 ollama serve

2. Confirm Ollama has at least one model

Odysseus AI can connect to the endpoint and still show no useful model if Ollama has not pulled anything yet. Pull a small model first if you are only testing the connection.

ollama list
ollama pull llama3.2:3b

3. Put the Docker endpoint in Odysseus AI Settings

Use the OpenAI-compatible base URL in the model or service settings area. Do not use localhost for this Docker-to-host layout unless your Docker platform has been configured differently.

http://host.docker.internal:11434/v1

4. Check container health before debugging prompts

If the Odysseus service is degraded, fix that first. A model endpoint cannot repair a broken container startup, missing environment file, or unhealthy dependency.

docker compose ps
docker compose logs --tail=120 odysseus

네이티브: Windows, Linux, macOS endpoint

When Odysseus AI and Ollama both run natively on the same machine, you usually do not need host.docker.internal. You are no longer crossing from a container into the host, so localhost normally means the machine you expect.

Platform-specific launch scripts can still change ports for the Odysseus web app itself, but the Ollama API is normally on 11434 unless you changed OLLAMA_HOST.

Setup	Endpoint to try first	What to watch
Windows native Odysseus + Windows Ollama	http://127.0.0.1:11434/v1	Use localhost when both services run natively on the same Windows machine.
Linux native Odysseus + Ollama	http://127.0.0.1:11434/v1	Check service permissions if either process runs as a background service.
macOS or Apple Silicon native path	http://127.0.0.1:11434/v1	The Odysseus UI port can differ, but Ollama usually remains on 11434.
Odysseus in Docker + host Ollama	http://host.docker.internal:11434/v1	Use the Docker host name because container localhost is not the host machine.

Odysseus AI와 Ollama 연결 오류 해결

Work from the network layer upward. First prove Ollama answers locally, then prove Docker can reach it, then adjust Odysseus model settings. Randomly changing model names or ports usually makes the problem harder to isolate.

Symptom	Likely cause	Fix
Connection refused	Ollama is not running or is listening only where Odysseus cannot reach it.	Start Ollama, confirm port 11434, and use an explicit OLLAMA_HOST binding for Docker-to-host testing.
Host browser works but Docker fails	The endpoint uses localhost inside the container.	Switch the endpoint to http://host.docker.internal:11434/v1.
No model appears	No model has been pulled or the model tag is wrong.	Run ollama list, pull a small model, and select the exact tag.
Slow first response	The model is loading or too large for the machine.	Test a smaller model before agents, tools, or documents.
Unexpected LAN exposure	A service was bound to all interfaces without a trust boundary.	Return to localhost-only binding unless firewall, VPN, and auth are intentional.

설정을 신뢰하기 전 최종 체크리스트

A working setup should pass these checks in order. Stop at the first failure and fix that layer instead of jumping ahead.

Ollama responds on the host and ollama list shows a model.
The Odysseus service is healthy in Docker or native logs.
The endpoint matches the runtime layout.
A small prompt works before larger agents or document workflows.
Any LAN exposure is authenticated and intentional.

첫 설정은 로컬로 유지

Connecting Odysseus AI to Ollama does not require publishing either service to the public internet. Keep both local until authentication, firewall rules, and reverse proxy behavior are deliberate.

Odysseus AI Ollama FAQ

Because localhost inside a container points to the container itself. host.docker.internal is Docker's hostname for reaching the host machine from inside the container.

Use the OpenAI-compatible base URL form when Odysseus expects an OpenAI-style provider endpoint. For the Docker host setup, that means http://host.docker.internal:11434/v1.

No. Ollama is a separate model server in this setup. Odysseus AI connects to it; it does not start Ollama inside the container.

If both Odysseus AI and Ollama run natively on Windows, try http://127.0.0.1:11434/v1 first. Use host.docker.internal only when Odysseus is in Docker and Ollama is on the host.

The endpoint may be reachable while the chosen model is missing, too large, or loading slowly. Check ollama list, pull a small model, and test with the exact model tag.

출처와 공식 참고 자료

Official Odysseus AI GitHub repository - Docker, Windows, Apple Silicon, and Ollama endpoint guidance.
Ollama API documentation - Local model server API behavior.
Docker Desktop networking documentation - host.docker.internal host networking behavior.