OpenHands

Settings → LLM → Advanced acepta tres campos — Custom Model, Base URL, API Key — con el ID del modelo llevando el prefijo openai/ y la URL base conservando /v1.

# Settings → LLM → Advanced  (toggle "Advanced" on first)
Custom Model   openai/claude-sonnet-5
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...

# The "openai/" prefix is the provider, not a vendor: it tells OpenHands to
# speak the OpenAI Chat Completions protocol to the Base URL above. The model
# id after the slash is Kunavo's, and resolves at Kunavo.
#
# Keep the /v1. It belongs to the openai/ prefix — a litellm_proxy/ model
# takes the bare origin instead, which is the opposite convention.

Paso a paso

1. Cree una clave en /app/keys y cópiela: se muestra una sola vez.
2. Abra Settings → LLM y active el interruptor Advanced. Aparecerán los tres campos en este orden: Custom Model, Base URL, API Key.
3. Introduzca el identificador del modelo con su prefijo: openai/claude-sonnet-5, no claude-sonnet-5. Los identificadores que ofrece Kunavo son los que devuelve GET /v1/models, la misma lista de la que, según la documentación oficial de OpenHands, debe obtenerse un identificador personalizado.
4. Pegue https://api.kunavo.com/v1 en Base URL y la clave en API Key; después, haga clic en Save Changes. OpenHands documenta que, al guardar un perfil local, primero se valida la configuración con el backend y el guardado se bloquea si falla. Por tanto, un error aquí es un rechazo real, no meramente estético.
5. Compruebe a qué puede acceder el backend, no su navegador. La URL base debe resolverse desde el equipo que ejecuta Agent Server. La documentación especifica que, si Agent Canvas se ejecuta en Docker, 127.0.0.1 es el contenedor. Un endpoint público como el de Kunavo es el caso sencillo; uno detrás de un proxy corporativo no lo es.
6. Inicie una conversación nueva y asígnele una tarea que lea y edite un archivo. OpenHands indica que un LLM guardado se aplica a las conversaciones nuevas y que primero hay que reiniciar las anteriores. Una ejecución que use las herramientas permite evaluar la configuración mejor que un simple saludo.

Comprobado con Página de configuración de Language Model (LLM) de OpenHands el 21 de septiembre de 2026. La configuración de terceros puede cambiar; si el nombre de un campo ya no coincide con lo que ves, esa página es la autoridad, no esta.

Verifica antes de depurar el cliente

Una solicitud determina si el fallo está en el endpoint, la clave o el archivo de configuración. Si devuelve JSON, la misma URL base y la misma clave funcionan en OpenHands.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Qué ID de modelo introducir en el campo

Todos los modelos de texto están disponibles mediante un ID de modelo; la lista activa está en GET /v1/models, y el catálogo con precios está en la página de modelos. Las tarifas son USD por 1M de tokens, entrada / salida.

Tres aspectos que conviene conocer antes de depurar problemas

OpenHands tiene más componentes que una CLI de proceso único, y dos de ellos parecen el endpoint LLM sin serlo. Esta información proviene de la documentación oficial, consultada en la fecha indicada arriba:

1. El entorno aislado no es el modelo. OpenHands ejecuta el trabajo en un entorno aislado de agent-server y se comunica con el modelo a través de la red: son componentes distintos y usan credenciales diferentes. La clave configurada aquí sirve para las llamadas al modelo. No determina a qué puede acceder el entorno aislado, y un problema de conectividad de ese entorno no parece un error de autenticación.
2. Los agentes ACP son independientes. Agent Canvas puede delegar tareas a Claude Code, Codex o Gemini CLI como agentes ACP, y la página «Configure a Model» señala que estos «gestionan su propio acceso a los modelos», así que un perfil LLM no redirige ese subproceso. Si esperaba ver tráfico con su clave y no aparece, compruebe qué agente se está ejecutando. La comparación entre OpenHands y Claude Code explica esa diferencia, incluida la regla de prioridad de credenciales que la determina.
3. Perfiles y límite de 10 perfiles. Una configuración guardada se convierte en un perfil LLM; el perfil guardado más recientemente pasa a ser el activo para las conversaciones nuevas, y se puede cambiar de perfil a mitad de una conversación sin perder el contexto. Este mecanismo permite usar con una sola clave un identificador económico y otro caro. La documentación limita el número a 10 perfiles por cuenta. Un Provider Connection guarda una sola vez el proveedor, la clave API y una URL base opcional para varios perfiles. La misma página indica que el panel está disponible en los backends locales de agent-server y oculto en los de OpenHands Cloud.