Configura Hermes Agent con BYOK: guía paso a paso

Qué significa realmente BYOK en Hermes Agent

Hermes Agent es BYOK por diseño. Apuntas a cualquier proveedor del que ya tengas credenciales y cada llamada de inferencia se factura a tu cuenta del proveedor, no a una capa intermedia que encarece los tokens. No es un truco para saltarse un muro de pago, es la postura por defecto del agente: agnóstico al modelo, agnóstico al proveedor y sesgado hacia el backend en el que tú confíes con tus datos.

Al principio hay dos cosas que suelen confundir. Primero, BYOK en Hermes incluye claves API de LLM reales (OpenAI, Anthropic, OpenRouter, Kimi, MiniMax y muchas otras) y también endpoints compatibles con OpenAI, lo que significa que un vLLM u Ollama auto-hospedado también cuenta. Segundo, BYOK va por backend, no es todo o nada. Puedes usar Anthropic para razonamiento y Ollama para resúmenes de fondo baratos en el mismo agente, si configuras ambos.

El resto de la guía te lleva por elegir un proveedor, guardar la clave sin filtrarla y cambiar más adelante sin rehacer la instalación.

Por qué BYOK importa más que "crédito gratis de API"

Todo SaaS de IA acaba pidiéndote confiar en su clave común opaca. BYOK rompe ese modelo. Tu credencial, tu factura, tu política de retención de datos, tu registro de auditoría. Si la plataforma desaparece mañana, tu cuenta del proveedor sigue funcionando.

Los beneficios prácticos, ordenados por lo a menudo que importan en despliegues reales de Hermes:

Control de datos. Los registros del proveedor, las reglas de retención y las cláusulas de Zero Data Retention las rige tu acuerdo con el proveedor del modelo, no los valores por defecto negociados por el proveedor del agente.
Transparencia de coste. Sin sobrecoste oculto entre tú y el modelo. Si usas OpenRouter ves el mismo coste por token que verías con un curl directo.
Sin dependencia de proveedor. Cambiar de proveedor son dos líneas de configuración, no un proyecto de migración. El comando hermes model te lleva entre Claude, GPT, Gemini o Llama sin tocar skills ni memoria.
Interruptor de apagado en tu lado. Si se filtra una clave o se dispara la factura, la rotas desde el panel del proveedor. El agente deja de funcionar en segundos y nadie más tiene que aprobar la rotación.

Para el plan Starter de Hermify, BYOK es la clave del asunto. La tarifa está diseñada alrededor de "tú pones la clave, nosotros ejecutamos el contenedor". Por eso vale la pena aprender la configuración de abajo aunque planees usar hosting gestionado más adelante.

Paso a paso: configura tu primer proveedor BYOK

Hermes necesita al menos un proveedor configurado para funcionar. El camino con menos fricción es OpenRouter (una clave, cientos de modelos), pero la mecánica es la misma para OpenAI, Anthropic y cualquier otro backend soportado.

1. Consigue una clave del proveedor

Elige uno y genera una clave desde el panel del proveedor:

OpenRouter en openrouter.ai. La clave empieza por sk-or-. Es la mejor opción por defecto para BYOK.
OpenAI en platform.openai.com. La clave empieza por sk-.
Anthropic en console.anthropic.com. La clave empieza por sk-ant-.
Kimi, MiniMax, GLM, Nous Portal y otros siguen el mismo patrón: te registras, generas una clave y la copias una vez.
Ollama o vLLM corriendo en tu máquina. No hace falta clave, solo la URL del endpoint compatible con OpenAI.

Añade crédito (o un método de pago) en el proveedor. Si la cuenta tiene saldo cero, Hermes fallará en la primera llamada con un error claro.

2. Ejecuta la configuración interactiva

Desde la terminal, en la máquina donde vive Hermes:

hermes setup

Elige tu proveedor de la lista, pega la clave y selecciona un modelo. Hermes escribe la configuración por ti.

Si prefieres hacerlo por script, lo mismo sin prompts:

hermes config set OPENROUTER_API_KEY sk-or-tu-clave-aqui
hermes config set MODEL "anthropic/claude-sonnet-latest"

El prefijo ~ en un identificador de modelo (~anthropic/claude-sonnet-latest) significa "última versión de esta familia", así no tienes que perseguir snapshots nuevas a mano.

3. Dónde vive la clave

Hermes guarda secretos y configuración en archivos separados, a propósito:

Los secretos van a ~/.hermes/.env (permisos 600 para que solo el usuario pueda leerlo).
El nombre del proveedor, el modelo y los flags van a ~/.hermes/config.yaml y son seguros de versionar.

Esta separación importa. Puedes versionar config.yaml en un repo privado o en tus dotfiles y reproducir una instalación de Hermes en otra máquina, y añadir la clave allí desde una variable de entorno o un gestor de secretos sin escribirla nunca en disco en claro.

Si versionas la configuración, añade ~/.hermes/.env a tu .gitignore. Si usas un gestor de secretos (1Password CLI, doppler, sops, Bitwarden) puedes generar el .env en el arranque en lugar de dejar la clave en disco permanentemente.

4. Verifica que funciona

Manda una prueba de humo a través de Hermes:

hermes chat "di hola y dime qué modelo eres"

Si la clave es incorrecta, la cuenta no tiene crédito o el endpoint no responde, el error te dirá cuál. Corrígelo y vuelve a probar. No pases a skills, tareas programadas o ajuste de memoria hasta que el proveedor responda limpiamente.

Cómo elegir el proveedor correcto

No te quedas atado a la primera elección. Pero la primera importa, porque marca el techo del trabajo con memoria, llamadas a herramientas y contexto largo que Hermes va a intentar.

Quieres cero fricción, "que funcione y ya": OpenRouter con ~anthropic/claude-sonnet-latest. Una clave, una factura, cambios de modelo fáciles.
Ya tienes cuenta en OpenAI o Anthropic: usa el proveedor directo. Coste por token ligeramente menor que ir vía OpenRouter, pero sin fallback entre proveedores.
Quieres quedarte en infraestructura de Nous Research: Nous Portal es el camino oficialmente bendecido y encaja de forma natural con los system prompts de Hermes.
Quieres correr en local: Ollama o vLLM como endpoint compatible con OpenAI. No cuesta por token, requiere una máquina con GPU y necesita un modelo con soporte real de tool calling para ser útil al agente.
Quieres aislamiento estricto de datos: Anthropic directo (Zero Data Retention bajo petición) o un endpoint auto-hospedado. No pases por agregadores si esta es tu prioridad.

Hermes necesita un modelo con al menos 64K tokens de contexto, porque los archivos de memoria persistente (MEMORY.md, USER.md, skills) se inyectan en cada llamada. Los modelos de contexto pequeño descartan contexto en silencio, y eso rompe el bucle de memoria que hace que Hermes no sea un chatbot sin estado.

Si quieres un análisis más profundo de cómo elegir el modelo, revisa cómo configurar Hermes Agent con OpenRouter.

Errores de configuración que debes evitar

Algunos patrones queman a los usuarios en su primera configuración BYOK:

Subir el archivo .env al repo. El error más común. Ni siquiera un repositorio "privado" de GitHub es un sitio seguro para claves sk-. Añade .env al .gitignore desde el primer día.
Elegir un modelo sin soporte de tool calls. Algunos modelos baratos de OpenRouter no pueden llamar herramientas. Hermes necesita tool calls para escritura de archivos, fetches web, tareas programadas y MCP. Si las skills dejan de funcionar en silencio, revisa las capacidades del modelo.
Dejar corta la cuenta del proveedor. Los proveedores pausan las peticiones cuando el crédito baja de un umbral. Configura una recarga automática en OpenRouter o una alerta de saldo bajo en OpenAI para que un cron largo de Hermes no muera a las 3 de la mañana.
Guardar la clave en el historial de la shell. hermes config set OPENROUTER_API_KEY sk-or-... se escribe en .bash_history por defecto. Prefiere hermes setup (interactivo, sin historial) o antepón un espacio al comando si tu shell está configurada para saltarse esas líneas.
Asumir que una clave lo cubre todo. Las herramientas MCP que necesitan sus propias credenciales (un token de GitHub, una clave de Notion) son slots BYOK separados. La clave del LLM no las desbloquea.
No rotar. Ponte un recordatorio cada 90 días para rotar la clave del proveedor. hermes config set sobrescribe el valor anterior limpiamente.

Si te atascas, Hermes Agent troubleshooting en Telegram cubre los modos de fallo comunes de principio a fin.

Qué cambia con hosting gestionado

Todo lo anterior es cómo se ve una instalación auto-hospedada de Hermes. Si despliegas a través de Hermify, el modelo BYOK es idéntico (tu clave, tu factura, tus datos), pero la mecánica se mueve al panel:

Pega la clave de OpenRouter, OpenAI o Anthropic una vez en el onboarding.
Hermify la cifra en reposo y la inyecta en tu contenedor al arrancar. Nunca aparece en logs, nunca se muestra tras guardarla y se rota limpiamente cuando lo pidas.
Cambia de modelo desde el panel sin hacer SSH a ningún sitio. El cambio surte efecto en el siguiente reinicio del agente, que está a un clic de distancia.
El plan Starter es BYOK-only por diseño. Pro y Dedicated incluyen una clave gestionada si prefieres saltarte el registro con el proveedor, pero puedes seguir trayendo la tuya si así lo prefieres.

El punto es que BYOK no es una característica solo del self-hosting. Es una postura: tu credencial, tus datos, tu interruptor de apagado. El hosting gestionado la conserva, solo se encarga de la operativa alrededor.

Empieza ya

Si te auto-hospedas, ejecuta hermes setup, pega la clave y listo. Si quieres el mismo modelo BYOK sin el mantenimiento del contenedor, empieza con Hermify y estarás en Telegram en alrededor de un minuto.

En cualquier caso, mantén la clave de tu lado. Para eso está BYOK.