9 min de lectura 7 de junio de 2026

Configurar Odysseus AI con Ollama sin adivinar endpoints

Guía práctica para apuntar Odysseus AI a un servidor Ollama existente, con rutas para Docker y nativo, pruebas de endpoint y soluciones a los primeros errores.

Odysseus AI Wiki
Odysseus AI Wiki
Notas editoriales creadas por fans a partir de documentación pública y patrones de autoalojamiento local.
Diagrama de Odysseus AI conectado a Ollama mediante localhost y endpoint de host Docker

Respuesta corta: Si Odysseus AI corre en Docker y Ollama en el host, usa http://host.docker.internal:11434/v1 en Settings. Si ambos corren de forma nativa en la misma máquina, localhost suele ser correcto. El fallo típico es usar el puerto correcto desde el espacio de red equivocado.

En esta guía

Odysseus AI es un espacio de trabajo autoalojado y Ollama es un servidor local de modelos. Funcionan bien juntos, pero Docker cambia el significado de localhost. Esta guía se centra en lograr que Odysseus AI vea los modelos servidos por Ollama y en verificar la conexión antes de depurar capas superiores.

Usa el endpoint según dónde corre Odysseus AI

La documentación pública de Odysseus destaca un endpoint específico para Docker: cuando Ollama se ejecuta en el host y Odysseus en un contenedor, hay que añadir el endpoint del host en Settings.

Para Docker, el valor práctico es host.docker.internal en el puerto 11434 con la ruta /v1. En instalaciones nativas, donde Odysseus AI y Ollama comparten la misma sesión del sistema, empieza con localhost o 127.0.0.1.

Trata “instalar Ollama” y “conectar Odysseus AI con Ollama” como dos comprobaciones distintas. Primero confirma que Ollama responde en el puerto 11434 y tiene al menos un modelo; después configura una URL accesible desde el mismo entorno que Odysseus AI.

Endpoint Docker hacia Ollama en el host
http://host.docker.internal:11434/v1

Docker: contenedor Odysseus hacia Ollama en el host

Este caso es importante porque muchos usuarios instalan Odysseus AI con Docker pero ya tienen Ollama funcionando en la máquina anfitriona. En ese diseño, localhost dentro del contenedor apunta al propio contenedor.

La conexión exige tres cosas: Ollama debe estar activo, debe escuchar en una dirección alcanzable desde Docker y Odysseus AI debe guardar el endpoint correcto.

1. Arranca Ollama con una dirección alcanzable

Si Docker no puede llegar a Ollama, inicia Ollama con un binding explícito y úsalo solo en redes de confianza.

OLLAMA_HOST=0.0.0.0:11434 ollama serve

2. Comprueba que hay al menos un modelo

El endpoint puede responder aunque no haya modelos útiles. Descarga un modelo pequeño antes de probar agentes o documentos.

ollama list
ollama pull llama3.2:3b

3. Guarda el endpoint en Settings

Usa la URL compatible con OpenAI en el área de modelos o servicios. No uses localhost para Docker hacia host salvo que tu red Docker sea distinta.

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

4. Revisa la salud del contenedor

Si Odysseus está degradado, corrige eso antes de depurar prompts o modelos.

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

Nativo: endpoints para Windows, Linux y macOS

Cuando Odysseus AI y Ollama corren de forma nativa en la misma máquina, normalmente no necesitas host.docker.internal.

Los scripts de arranque pueden cambiar el puerto de la interfaz web de Odysseus, pero la API de Ollama suele seguir en 11434 salvo que cambies OLLAMA_HOST.

Configuración Endpoint inicial Qué vigilar
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.

Errores de conexión entre Odysseus AI y Ollama

Trabaja desde la red hacia arriba: primero Ollama local, luego acceso desde Docker y después Settings de Odysseus.

Síntoma Causa probable Solución
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.

Checklist final antes de confiar en la configuración

Un setup correcto debería superar estas comprobaciones en orden.

  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.
Mantén el primer setup local

Conectar Odysseus AI con Ollama no requiere publicar ningún servicio en internet. Mantén ambos locales hasta tener autenticación, firewall y proxy decididos.

Notas de verificacion 2026 antes de cambiar el endpoint

Antes de editar la configuracion de Odysseus AI, verifica el limite de ejecucion. El mismo servidor Ollama puede necesitar una URL base distinta si Odysseus corre nativo, en Docker o en otro host.

Usa estas comprobaciones para evitar el falso arreglo mas comun: cambiar nombres de modelos cuando el problema real es que la app no llega al puerto 11434 desde su propia red.

Comprobacion Resultado correcto Si falla
API Ollama del host El host alcanza http://127.0.0.1:11434 antes de usar Odysseus. Inicia Ollama, descarga un modelo pequeno y prueba la API primero.
Ruta Docker al host Odysseus en contenedor usa host.docker.internal:11434/v1. No uses localhost dentro del contenedor salvo que Ollama este en la misma red.
Ruta nativa Odysseus nativo usa 127.0.0.1:11434/v1 si Ollama esta en la misma maquina. Quita hostnames de Docker y prueba con un prompt pequeno.
  1. Mantener Ollama local durante las pruebas salvo que firewall y autenticacion esten definidos.
  2. Confirmar que el tag del modelo existe en ollama list.
  3. Anotar que endpoint funciono para no migrar una URL incorrecta.

FAQ de Odysseus AI y Ollama

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.

No. Ollama es un servidor de modelos independiente. Instálalo y pruébalo primero, descarga un modelo y luego configura en Odysseus AI la URL accesible desde su entorno de ejecución.

Fuentes y referencias oficiales

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

Rutas relacionadas de configuración de Odysseus AI

2026-07-11

Volver a la Wiki de Odysseus AI