Odysseus AI와 Ollama 연결 설정: 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.

“Ollama 설치”와 “Odysseus AI 연결”을 별도 단계로 확인하세요. 먼저 11434 포트와 모델을 검증한 다음 Odysseus AI 실행 환경에서 접근 가능한 주소를 설정합니다.

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.

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.

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

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

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

2026 검증 메모: Ollama 연결을 단계별로 분리하기

Odysseus AI와 Ollama 연결이 실패할 때는 앱 실행, 네트워크 경계, 모델 선택을 따로 확인해야 합니다. Docker 컨테이너 안의 localhost와 Windows 또는 Mac 호스트의 localhost는 같은 위치를 가리키지 않습니다. 그래서 같은 Ollama 서버라도 Odysseus가 어디에서 실행되는지에 따라 설정해야 할 URL이 달라집니다.

네이티브 실행에서는 127.0.0.1:11434/v1을 먼저 확인하고, Docker 안의 Odysseus가 호스트의 Ollama에 접근해야 한다면 host.docker.internal:11434/v1을 사용합니다. 설정 화면을 바꾸기 전에 Ollama 단독으로 모델 목록과 짧은 프롬프트가 동작하는지 확인하면 원인을 훨씬 빠르게 좁힐 수 있습니다.

외부 네트워크 노출은 마지막 단계로 미루는 것이 좋습니다. 첫 검증은 localhost 범위에서 끝내고, 인증, 방화벽, 리버스 프록시 규칙을 정한 뒤에만 LAN 또는 인터넷 접근을 고려하세요.

1. 앱 실행 확인, Ollama API 확인, 모델 태그 확인을 순서대로 진행합니다.
2. 설정은 한 번에 하나만 바꾸고 성공한 엔드포인트를 기록합니다.
3. 첫 검증에서는 LAN이나 인터넷에 공개하지 말고 로컬에서 안전하게 확인합니다.