OpenHands + JoinGonka Gateway: agente en su propio endpoint

El proyecto cuenta hoy con varias interfaces, y dependiendo de cuál esté ejecutando, dependerá dónde buscar la configuración del modelo. Los valores en sí son los mismos en todas partes; solo cambia la ruta para acceder a ellos.

Para Agent Canvas necesita Node.js y uv: sobre él funciona el servidor local del agente (detalles en la guía de instalación). La instrucción menciona Node.js 22.12 o superior, pero el paquete a partir de la versión 1.17 requiere Node.js 24 o superior: instale la versión 24 para evitar advertencias sobre una versión incompatible. Existe una opción en contenedor: la imagen ghcr.io/openhands/agent-canvas ofrece la interfaz en http://localhost:8000/canvas y solo ve los directorios que usted ha montado.

Clave JoinGonka. Regístrese en gate.joingonka.ai/register, confirme su dirección y cree una clave con el prefijo jg- en la sección "API-keys". Una sola clave y un solo saldo sirven para todos los modelos de la red. La herramienta @joingonka/setup no incluye OpenHands, y no es una omisión: su configuración reside en la interfaz y en el almacenamiento seguro del backend, no en un archivo de configuración de texto que se pueda editar externamente.

Paso 1. Inicie Agent Canvas y abra Settings > LLM. El asistente de configuración inicial sugiere su propio proveedor de OpenHands; puede omitir este paso, ya que es fácil volver a la configuración más tarde.

Paso 2. Haga clic en Add LLM Profile y vaya a la pestaña Advanced: la pestaña Basic solo ofrece proveedores y modelos de la lista integrada.

Paso 3. Rellene los tres campos:

Paso 4. Guarde el perfil. Antes de guardar, Canvas comprueba la configuración con una solicitud desde el backend: si la clave es rechazada o el modelo no está disponible, el perfil no se guardará y verá un mensaje de error.

Paso 5. Inicie una nueva conversación y envíe un mensaje corto. Las conversaciones ya abiertas siguen funcionando con el modelo con el que comenzaron.

Por qué openai/. LiteLLM determina el proveedor según el prefijo del modelo. El prefijo openai/ no significa «modelo de OpenAI», sino «hablar con el servidor mediante el protocolo OpenAI Chat Completions». Solo se elimina el primer segmento, por lo que el identificador real llega a la pasarela: deepseek-ai/DeepSeek-V4-Flash-0731. En la documentación de OpenHands se muestra el mismo esquema con el ejemplo openai/qwen/qwen3.6-35b-a3b. Sin el prefijo, LiteLLM se negará a trabajar con el mensaje LLM Provider NOT provided.

Por qué /v1 y nada más. LiteLLM se conecta al servidor a través del cliente oficial de OpenAI, que añade /chat/completions automáticamente. Por eso la dirección debe terminar en /v1: sin el sufijo, la solicitud fallará fuera de la API; con un exceso de caracteres, irá a una ruta inexistente. Y otro requisito de Canvas: la dirección debe ser accesible desde el backend, no solo desde el navegador. La pasarela es una dirección HTTPS pública; desde un contenedor Docker es visible igual que desde el host; técnicas como host.docker.internal solo son necesarias para modelos en su propia máquina.

Perfiles para los tres modelos. Cree un perfil para cada modelo de la red y nómbrelos de forma corta, por ejemplo deepseek, glm y minimax (la documentación menciona un límite de diez perfiles). Puede cambiar entre ellos directamente en la conversación sin perder el contexto: mediante el botón de selección de perfil en el campo de entrada o con el comando /model glm; /model sin argumentos mostrará la lista. Para no insertar la clave en cada perfil, puede guardarla una vez en el bloque Provider Connections, que está disponible en el backend local.

Interfaz anterior en Docker. Los campos son los mismos: Settings → pestaña LLM → activar Advanced → Custom Model, Base URL, API Key → Save Changes.

La CLI se instala con un solo comando mediante uv y en el primer arranque te guía por la configuración del modelo; más tarde puedes volver a ella con Ctrl+P → Settings:

uv tool install openhands --python 3.12
openhands

Para scripts resultan más prácticas las variables de entorno. Un detalle importante: por defecto la CLI las ignora y solo las aplica con el flag --override-with-envs, para una única ejecución, sin guardar nada:

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

El mismo conjunto funciona sin interfaz, para CI y tareas por lotes:

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

En modo headless el agente actúa siempre con autoaprobación, así que ejecútalo donde pueda hacerlo todo: en un directorio aparte o en un contenedor. El flag --json convierte la salida en un flujo de eventos JSONL, cómodo de procesar en un pipeline. Así comprobamos la integración el 21 de septiembre de 2026 con la CLI 1.16.0: en la cabecera la CLI imprime Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731, luego el agente lee el archivo y responde con fundamento.

La configuración guardada de la CLI está en ~/.openhands/agent_settings.json: el modelo se cambia editando tres campos del bloque llm: model, api_key y base_url. No conviene crear el archivo desde cero: el asistente del primer arranque escribe allí también el resto de la configuración del agente, incluida la compactación del historial, sin la cual una conversación larga chocará con la ventana de contexto.

Si integras el agente en tu propio código, el SDK de OpenHands acepta esos mismos tres valores:

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

El precio de los modelos de la red es el mismo, por lo que la elección depende del comportamiento. Para un agente autónomo, dos cifras son fundamentales. Ventana de contexto: cada paso envía el historial de nuevo, y cuanto más larga es la ventana, más tiempo trabaja el agente sin pérdidas. Límite de respuesta: el paso en el que el agente escribe un archivo grande completo debe caber en una sola respuesta. La tabla muestra los resultados de nuestra ejecución de la misma tarea (leer un archivo y encontrar un error) a través de OpenHands CLI 1.16.0 con SDK 1.21.0.

Un esquema de trabajo para tareas largas repite el consejo de la documentación de OpenHands: planificar con un modelo y ejecutar con otro. Comience la conversación en el perfil glm y pida un plan sin editar archivos; luego envíe /model deepseek y dé la orden de ejecutar. El historial, los archivos y el estado de la tarea se conservan al cambiar. Mantenga el perfil minimax como tercera opción: es útil cambiar a él cuando los otros dos se quedan sin capacidad en horas pico, y en Settings > Application se le puede asignar la generación de títulos de conversaciones.

Compresión del historial. Incluso una ventana de cientos de miles de tokens es finita en una tarea de muchas horas. En OpenHands, el condensador se encarga de esto: colapsa eventos antiguos en un breve resumen, lo que, según la documentación, reduce la latencia y el consumo de tokens en conversaciones largas. En Agent Canvas se configura en la sección Settings > Condenser; en nuestra ejecución de CLI, se activó solo con un umbral de 80 eventos.

Límites del modelo. OpenHands toma la ventana de contexto y el límite de respuesta del directorio LiteLLM, y como no contiene identificadores de la red Gonka (verificamos en LiteLLM 1.81), el agente no tiene valores propios para estos modelos. Esto no impide el funcionamiento: la puerta de enlace aplica el límite de respuesta por sí misma, según la tabla anterior. Si desea establecer límites explícitamente, los campos en el SDK son max_input_tokens y max_output_tokens, y en Canvas, la pestaña All abre el conjunto completo de campos del perfil. Detalles sobre el modelo predeterminado en la reseña de DeepSeek V4 Flash.

Puede verificar que las solicitudes realmente pasan por la puerta de enlace (gateway) desde dos lados. Por parte de OpenHands: un nuevo chat y una tarea corta como «lee el README y resúmelo en una frase»; el agente debe invocar una herramienta y responder. Por parte de la puerta de enlace: el panel de control, sección «Uso»: la solicitud aparecerá en el desglose «Por modelos», y en el bloque «Por claves» se actualizará la hora de la última solicitud. Si está vacío, significa que el chat está en otro perfil: verifique cuál está marcado como activo.

Según la documentación de OpenHands, el número de reintentos y las pausas entre ellos en caso de error 429 se configuran mediante las variables LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT y LLM_RETRY_MAX_WAIT. Los valores predeterminados en la documentación y en el SDK difieren, por lo que debe guiarse por los reales: en el estado de conversación de la CLI 1.16.0 vimos 5 intentos con pausas de 8 a 64 segundos.

A través de JoinGonka Gateway, los tokens cuestan $0.0069 por millón en la entrada y $0.021 por millón en la salida; el precio es el mismo para todos los modelos de la red y se obtiene en esta página desde una fuente en tiempo real.

Las estimaciones en la columna derecha se basan en los precios de septiembre de 2026; la economía de los agentes se explica detalladamente en el artículo sobre la API más barata para agentes de IA.

Límite de gasto. OpenHands sugiere establecer límites de gasto; la puerta de enlace tiene esto integrado en el modelo de pago: el saldo es prepago y el agente no gastará más de lo que hay en la cuenta. El saldo restante y el gasto diario se pueden ver en el panel. Para CI y automatizaciones en segundo plano, cree una clave separada para que su consumo no se mezcle con el suyo; las claves secundarias con límite diario se describen en el artículo sobre Management Keys.

Nivel de confianza. Agent Canvas, ejecutado a través de npm, trabaja con los permisos de su usuario y ve todo el sistema de archivos. Para código de terceros, use la versión en Docker: el agente solo verá el directorio montado. Esto es una característica propia de OpenHands, no depende del proveedor del modelo.

La correspondencia se queda con usted. OpenHands almacena el historial de la conversación localmente, en ~/.openhands, y lo envía al modelo en cada paso; la puerta de enlace no guarda la correspondencia: sus prompts y su código no permanecen allí después de la respuesta.

Si la tarea incluye imágenes —capturas de pantalla de interfaces, diagramas—, cree un perfil separado para ella con un modelo de visión: los modelos de la red Gonka son de texto. Para código, comandos y archivos, esto no es una limitación.