Odysseus AI: Cómo Instalar y Configurar Modelos en Local Paso a Paso

Qué es Odysseus

Odysseus es una interfaz de chat con inteligencia artificial que permite trabajar con distintos proveedores de modelos. Puedes conectarlo a servicios externos mediante API, como OpenAI, DeepSeek, OpenRouter o Anthropic, pero también puedes usarlo con servidores locales compatibles con OpenAI, como Ollama.

La ventaja de instalarlo desde Pinokio es que buena parte del proceso queda automatizado: creación del entorno, instalación de dependencias, ejecución de scripts y arranque de la aplicación.

El problema es que, en algunos casos, Odysseus parece arrancar correctamente en la consola de Pinokio, pero al abrir la interfaz web aparece el clásico error:

connection refused

Ese fue precisamente el problema que vamos a resolver en esta guía.

Requisitos previos

Antes de empezar, conviene tener preparado lo siguiente:

• Un ordenador con Windows.
• Pinokio instalado. Puedes descargarlo desde desktop.pinokio.co .
• Odysseus instalado o añadido como app dentro de Pinokio.
• PowerShell, para comprobar puertos y ejecutar comandos básicos.
• Ollama instalado, solo si quieres usar modelos desde Ollama.

Si quieres usar Odysseus con una API externa, como OpenAI, DeepSeek u OpenRouter, no necesitas Ollama. En ese caso solo necesitarás una clave API del proveedor correspondiente.

Instalar Odysseus en Pinokio

El proceso inicial es el habitual en Pinokio:

1. Abre Pinokio.
2. Clica en la sección «Explore», que encontrarás en la parte superior derecha de la ventana inicial. Busca Odysseus en el buscador o en la lista de apps que verás.
3. Ejecuta Install y sigue los pasos de instalación, no tiene pérdida.
4. Cuando termine la instalación, pulsa Start. A veces se ejecuta de manera automática y no tenéis que hacer nada más.

Durante el arranque verás una consola con muchos mensajes. Algunos pueden parecer errores graves, pero no siempre impiden que Odysseus funcione.

Por ejemplo, en Windows puede aparecer un error de codificación parecido a este:

UnicodeDecodeError: 'charmap' codec can't decode byte...
AttributeError: 'NoneType' object has no attribute 'strip'

También pueden aparecer avisos relacionados con ChromaDB:

ChromaDB is not reachable at localhost:8100
MemoryVectorStore DEGRADED

Estos mensajes indican que algunas funciones internas, como memoria vectorial o RAG, no están disponibles. Sin embargo, Odysseus puede arrancar igualmente y mostrar la interfaz.

Lo importante es encontrar una línea como esta:

Application startup complete

Y después otra similar a esta:

Uvicorn running on http://127.0.0.1:42003

El número final puede cambiar. En este ejemplo, el puerto es 42003.

Solucionar el error connection refused

El error más confuso aparece cuando la consola indica que Uvicorn está corriendo, pero al abrir la URL en el navegador aparece:

connection refused

Esto significa que el navegador intenta conectarse al puerto de Odysseus, pero Windows no encuentra ningún servicio escuchando en ese puerto.

Para comprobarlo, abre PowerShell y ejecuta:

netstat -ano | findstr :42003

Sustituye 42003 por el puerto que aparezca en tu consola.

Si el puerto está activo, deberías ver una línea parecida a esta:

TCP    127.0.0.1:42003    0.0.0.0:0    LISTENING    12345

Si no aparece nada, Odysseus no se ha quedado realmente escuchando, aunque Uvicorn haya llegado a imprimir el mensaje de arranque.

En esta instalación, el problema estaba en el archivo start.js usado por Pinokio para arrancar la aplicación.

Archivo start.js corregido

La solución fue simplificar el archivo start.js, quitar el bloque que marcaba el proceso como completado demasiado pronto y lanzar Uvicorn con python -m uvicorn.

Este es el archivo start.js corregido:

const SEARXNG_REPO_URI = "https://github.com/cocktailpeanut/searxng.pinokio.git"
const SEARXNG_START_URI = `${SEARXNG_REPO_URI}/start.js`

module.exports = {
  daemon: true,
  run: [
    {
      method: "script.run",
      params: {
        uri: SEARXNG_START_URI
      }
    },
    {
      method: "local.set",
      params: {
        searxng_url: `{{script.local('${SEARXNG_START_URI}').url}}`
      }
    },
    {
      method: "local.set",
      params: {
        odysseus_port: "{{port}}"
      }
    },
    {
      method: "local.set",
      params: {
        url: "http://127.0.0.1:{{local.odysseus_port}}"
      }
    },
    {
      method: "shell.run",
      params: {
        path: "app",
        venv: "env",
        venv_python: "3.12",
        env: {
          "HOST": "127.0.0.1",
          "AUTH_ENABLED": "false",
          "LOCALHOST_BYPASS": "false",
          "ODYSSEUS_LOCAL_USER": "admin",
          "SEARXNG_INSTANCE": "{{local.searxng_url}}",
          "PYTHONPATH": ".."
        },
        shell: "{{which('bash')}}",
        message: [
          "python -m uvicorn pinokio_noauth:app --host 127.0.0.1 --port {{local.odysseus_port}}"
        ]
      }
    }
  ]
}

La parte más importante es esta:

python -m uvicorn pinokio_noauth:app --host 127.0.0.1 --port {{local.odysseus_port}}

También es importante no usar un bloque de este tipo dentro del shell.run:

on: [{
  event: "...",
  done: true
}]

En esta instalación, ese bloque hacía que Pinokio detectara el arranque, diera el paso por terminado y el servidor no quedara realmente activo.

Comprobar que el puerto está activo

Después de modificar el archivo start.js, detén Odysseus y vuelve a iniciarlo desde Pinokio.

Cuando aparezca el mensaje de Uvicorn, comprueba de nuevo el puerto en PowerShell:

netstat -ano | findstr :42003

Si ahora aparece LISTENING, Odysseus ya está funcionando correctamente.

Después abre en el navegador:

http://127.0.0.1:42003

Cambia el puerto por el que aparezca en tu instalación.

Si todo ha ido bien, verás la interfaz de Odysseus y un mensaje de configuración inicial parecido a este:

Quick start: add your first AI endpoint by pasting it in chat.

Configurar un proveedor de IA en Odysseus

Una vez que Odysseus carga, todavía falta configurar el modelo de inteligencia artificial. La propia interfaz te pedirá que pegues un endpoint o un proveedor directamente en el chat.

Puedes usar varias opciones:

• OpenAI
• DeepSeek
• OpenRouter
• Anthropic
• Groq
• Gemini
• Ollama
• Un endpoint local compatible con OpenAI

Para usar OpenAI, por ejemplo, tendrías que pegar algo como esto:

openai sk-tu_clave_api_aqui

No compartas nunca tu API key públicamente ni la incluyas en capturas de pantalla.

Usar Ollama con Odysseus

Si prefieres usar Ollama, Odysseus puede conectarse mediante el endpoint compatible con OpenAI que expone Ollama.

Primero comprueba que Ollama está instalado y funcionando. En PowerShell ejecuta:

ollama list

Si todo está correcto, verás una lista de modelos disponibles. Por ejemplo:

NAME                     ID              SIZE    MODIFIED
gpt-oss:120b-cloud       ...             -       ...
deepseek-v3.2:cloud      ...             -       ...
deepseek-v3.1:671b-cloud ...             -       ...

Los modelos terminados en :cloud están gestionados por Ollama en la nube. No están descargados completamente en tu ordenador, por eso el tamaño puede aparecer como -.

Para comprobar que Ollama responde, puedes abrir esta URL en el navegador:

http://localhost:11434

O ejecutar este comando en PowerShell:

curl http://localhost:11434

Si Ollama está activo, debería responder algo parecido a:

Ollama is running

Después, en Odysseus, pega este endpoint en el chat:

http://localhost:11434/v1

Con eso, Odysseus quedará conectado a Ollama.

Errores habituales al instalar Odysseus en Pinokio

Error connection refused

Este error aparece cuando el navegador intenta abrir Odysseus, pero el puerto no está activo.

La solución es comprobar el puerto con netstat, modificar el archivo start.js y reiniciar Odysseus desde Pinokio.

Error de ChromaDB

Puede aparecer un mensaje como este:

ChromaDB is not reachable at localhost:8100
MemoryVectorStore DEGRADED

No impide necesariamente que Odysseus cargue. Significa que la parte de memoria vectorial o RAG no está disponible.

Error de Ollama en localhost:11434

Si Odysseus intenta conectar con localhost:11434 y falla, significa que Ollama no está activo o no está escuchando en ese puerto.

Puedes comprobarlo con:

curl http://localhost:11434

Si no responde, ejecuta:

ollama serve

Error UnicodeDecodeError en Windows

También puede aparecer un error de codificación como este:

UnicodeDecodeError: 'charmap' codec can't decode byte...

En esta instalación apareció durante el arranque, pero Odysseus siguió cargando. No fue la causa del problema de conexión.