Hermes Agent: Referencia para profesionales (2026)

TL;DR: Hermes Agent es un agente de IA open source de Nous Research. Funciona como una CLI y como un gateway de mensajería multiplataforma, almacena una identidad duradera y memoria persistente en disco, reúne skills que mejoran con el uso y funciona con cualquier proveedor LLM compatible con OpenAI: Nous Portal, OpenRouter, Anthropic, Copilot de GitHub, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok o tu propio endpoint autoalojado.¹²¹⁹ Desde la v0.14.0 (16 de mayo de 2026), Hermes añade SuperGrok OAuth con contexto grok-4.3 de 1M, un proxy local compatible con OpenAI para proveedores OAuth (hermes proxy), x_search de primera clase, soporte de instalación desde PyPI (obsoleto desde la v0.19.0; el instalador de una línea es la ruta compatible), instalaciones de dependencias bajo demanda, 28 plataformas de mensajería con LINE y SimpleX Chat, /handoff, diagnósticos semánticos de LSP después de las escrituras, video_generate unificado, computer_use mediante cua-driver para proveedores que no sean Anthropic, beta nativa para Windows y 12 cierres P0 / 50 P1.¹⁹ La parte más difícil para la mayoría de los usuarios nuevos es la autenticación de proveedores: Hermes admite aproximadamente 20 proveedores de primera clase, además de endpoints personalizados, y tres rutas de autenticación distintas (clave API en .env, OAuth mediante hermes model o endpoint personalizado en config.yaml). El modelo de autenticación es lo primero que debes aprender: todo lo demás depende del proveedor que se resuelva.

Hermes Agent funciona como un runtime completo de agentes, no como un contenedor de chat. Lee tu sistema de archivos, ejecuta comandos en backends aislados, extrae contenido de la web, genera subagentes, ejecuta trabajos cron programados, se comunica con Telegram/Discord/Slack/WhatsApp/Signal/Email desde un único proceso gateway y crea sus propios skills a partir de la experiencia.¹ La CLI es una interfaz de usuario de terminal construida sobre un bucle de conversación en run_agent.py; el gateway es un proceso de larga duración que enruta mensajes de plataformas de mensajería a través del mismo bucle de conversación.³

La diferencia entre el uso casual y el experto de Hermes se reduce a cinco sistemas. Domínalos y Hermes se convertirá en un multiplicador de fuerza:

1. Resolución de proveedores: cómo los flujos de autenticación se asignan a llamadas API
2. Jerarquía de configuración: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Sistema de herramientas + toolset: lo que el agente puede hacer, controlado por plataforma
4. Sistema de skills: memoria procedimental que el agente crea y evoluciona
5. Gateway + cron + profiles: ejecutar Hermes donde vives, no solo donde estás

Puntos clave

• La autenticación de proveedores tiene tres rutas, no una. Clave API en .env, OAuth mediante hermes model/hermes auth o endpoint personalizado en config.yaml. Elige la ruta que corresponda a tu proveedor, no la que te resulte familiar.
• Cambiar de proveedor es un solo comando. hermes model te guía de forma interactiva por todos los proveedores compatibles, incluidos los inicios de sesión OAuth, y /model provider:model cambia durante la sesión sin perder el historial.²
• Dos archivos son la superficie de configuración editable por el usuario. ~/.hermes/config.yaml contiene la configuración y ~/.hermes/.env contiene secretos. auth.json, SOUL.md, MEMORY.md y skills/ los administra Hermes directamente: puedes editar SOUL.md a mano, pero el resto lo modifica el propio agente.⁴
• Hermes es el sucesor de OpenClaw. Si estás migrando, hermes claw migrate importa automáticamente más de 30 categorías de estado.⁵
• La calidad del servicio depende de tu modelo auxiliar. La visión, el resumen web, la compresión y el vaciado de memoria usan un LLM auxiliar independiente. De forma predeterminada, es Gemini Flash mediante detección automática (OpenRouter → Nous → Codex); si ninguno está configurado, estas funciones se degradan silenciosamente hasta que dirijas las ranuras auxiliares a tu proveedor principal.⁴

Lo que cambia en la v0.14

La v0.14.0 trata menos de una función destacada y más de reducir la fricción de configuración mientras amplía los lugares donde Hermes puede ejecutarse.¹⁹ Los principales cambios operativos:

• La instalación y el inicio son más ligeros. pip install hermes-agent funciona desde PyPI, los adaptadores pesados se instalan bajo demanda en el primer uso y la ruta de inicio aplaza suficiente trabajo para reducir el arranque en frío en aproximadamente 19 segundos. (Desde entonces, la v0.19.0 ha dejado obsoletas las instalaciones con pip; consulta Instalación.)
• Las suscripciones pueden convertirse en endpoints API locales. hermes proxy convierte proveedores respaldados por OAuth, como Claude Pro, ChatGPT Pro y SuperGrok, en un endpoint local compatible con OpenAI para herramientas como Codex, Aider, Cline y Continue.
• El alcance del gateway se amplía. LINE y SimpleX Chat elevan el número de plataformas a 22, Microsoft Teams está conectado de extremo a extremo, el relleno del historial de Discord está activado de forma predeterminada y las solicitudes clarify de Telegram/Discord ahora usan botones nativos.
• La verificación en el momento de escribir mejora. Después de las ediciones, Hermes puede mostrar resúmenes por turno de las mutaciones de archivos y diagnósticos semánticos del servidor de lenguaje antes del siguiente turno, lo que lo acerca al trabajo de agentes basado en evidencia.
• Las herramientas de escritorio y multimedia se amplían. computer_use funciona mediante cua-driver para proveedores que no sean Anthropic, video_generate está unificado tras backends conectables y vision_analyze envía píxeles sin procesar a modelos que realmente pueden ver.

Cada sección a continuación se fundamenta en la documentación oficial en hermes-agent.nousresearch.com/docs y en el árbol de código fuente en github.com/NousResearch/hermes-agent. Cada afirmación factual tiene una nota al pie que apunta a la página oficial específica de la que proviene.

Elige tu ruta

Cómo funciona Hermes: el modelo mental

Hermes se estructura en torno a un único bucle de conversación que puede invocarse desde cualquier punto de entrada. Los puntos de entrada son la CLI (cli.py), el gateway de mensajería (gateway/run.py), el adaptador ACP para la integración con editores, el ejecutor por lotes y un servidor API.³ Todos terminan llamando a AIAgent.run_conversation() en run_agent.py, que:

1. Construye el prompt del sistema a partir de SOUL.md, MEMORY.md, USER.md, skills, archivos de contexto y directrices para las herramientas mediante prompt_builder.py³
2. Resuelve el proveedor en tiempo de ejecución mediante runtime_provider.py; en este paso se eligen la autenticación, la URL base y el modo de API³
3. Llama al proveedor mediante uno de los tres modos de API: chat_completions, codex_responses o anthropic_messages³
4. Procesa las llamadas a herramientas que se devuelvan mediante model_tools.py y el registro central de herramientas (tools/registry.py)³
5. Repite el ciclo hasta que el modelo genera una respuesta final y, después, guarda la sesión en SQLite con FTS5³

Comprender este bucle es importante porque cada función —personalidades, memoria, skills, compresión y fallback— se conecta con una de estas etapas. Cuando leas una clave de configuración y te preguntes qué hace, la respuesta suele ser: «es un control de la etapa 1, 2, 3 o 4 del bucle anterior».

Núcleo independiente de la plataforma. Una sola clase AIAgent sirve para la CLI, el gateway, ACP, el procesamiento por lotes y el servidor API. Las diferencias entre plataformas residen en el punto de entrada, no en el propio agente.³ Por eso los mismos comandos slash funcionan tanto en la terminal como en Telegram: se procesan desde un COMMAND_REGISTRY compartido en hermes_cli/commands.py.⁶

La estructura de directorios es el sistema. Hermes almacena todo en ~/.hermes/ (o en $HERMES_HOME para los profiles que no sean el predeterminado):⁴

~/.hermes/
├── config.yaml        # Settings (model, terminal, TTS, compression, etc.)
├── .env               # API keys and secrets
├── auth.json          # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md            # Primary agent identity (slot #1 in system prompt)
├── memories/          # Persistent memory (MEMORY.md, USER.md)
├── skills/            # Bundled + agent-created + hub-installed skills
├── cron/              # Scheduled jobs
├── sessions/          # Gateway session state
└── logs/              # agent.log, gateway.log, errors.log (secrets auto-redacted)

Cada archivo anterior tiene una función específica; ninguno se solapa con los demás. Si buscas «dónde almacena Hermes X», la respuesta está en uno de ellos.

Novedades de v0.20.0 (la versión Herald)

Hermes Agent v0.20.0 (etiqueta v2026.8.3, 3 de agosto de 2026) es la versión actual con nuevas funciones; v0.20.1 (13 de agosto) y v0.20.2 (16 de agosto) son etiquetas de estabilización publicadas sobre ella, y v0.20.3 (etiqueta v2026.8.16.2, publicada el 17 de agosto) y v0.20.4 (etiqueta v2026.8.18, 18 de agosto) mantienen en marcha la serie de actualizaciones acumulativas con periodos que también incluyen funciones propias; consulta la subsección siguiente. El periodo desde v0.19.0 abarca aproximadamente 3.650 commits, 1.400 PRs fusionados y 1.200 issues cerrados, con la participación de más de 650 colaboradores.²⁴

Tres cambios invalidan las instrucciones que las versiones anteriores de esta guía te indicaban seguir. Léelos antes que cualquier otra cosa:

• Ahora se requiere Node 26. El instalador fija NODE_VERSION="26" y rechaza versiones anteriores con el mensaje «Node.js … is too old (Hermes requires Node >=26)». Los instaladores, heal y upgrade aplican este requisito. Ten en cuenta que la página de instalación del sitio de documentación todavía indica Node v22; el script de instalación y las notas de la versión son las fuentes más recientes y autorizadas.²⁴
• pip y Homebrew se retiraron, no solo quedaron obsoletos. Textualmente: «brew + pip/PyPI wheel channels retired (shell installer / Docker / Nix are the supported channels)». Si aún utilizas una instalación mediante pip o brew, ese canal ya no recibe nuevas versiones.²⁴
• El límite predeterminado de iteraciones para llamar a herramientas pasó de 90 a 500. Las ejecuciones autónomas largas dejaron de chocar con un límite artificial, y todos los umbrales de presión presupuestaria que aparecen más adelante se calculan a partir del nuevo máximo. read_file también utiliza ahora 2.000 líneas de forma predeterminada en lugar de 500.²⁴

El resto de la versión:

• Voz conversacional. TTS en streaming con interrupción por voz y palabras de activación procesadas en el dispositivo.²⁴
• A2A v1.0. Un plugin de protocolo entre agentes que resuelve la solicitud planteada hace tiempo en el issue #514.²⁴
• Webhooks salientes firmados. Antes, hermes webhook solo admitía tráfico entrante; v0.20.0 incorpora webhooks salientes de ciclo de vida firmados con HMAC para eventos de sesión, turno y herramientas.²⁴
• Citas fundamentadas. Un nuevo skill con un modo de verificación de datos.²⁴
• Oleada de funciones avanzadas para la CLI. !command ejecuta de inmediato un comando de shell sin consumir un turno del modelo; /init analiza el proyecto y crea o actualiza un AGENTS.md; /diff muestra los cambios preparados, todos los cambios o los cambios de la sesión desde cualquier interfaz; /context desglosa qué está ocupando la ventana de contexto; /focus ofrece una vista con menos contenido y permite recuperar las líneas ocultas; Ctrl+S guarda temporalmente un prompt a medio escribir. hermes import-agent migra una configuración de Claude Code o de la CLI de Codex con un solo comando.²⁴
• Novedades en la gestión de secretos. Una fuente de secretos basada en comandos auxiliares que puede combinarse con cualquier bóveda, rotación de tokens con un solo comando y errores de inicio que indican cómo actuar, una caché cifrada opcional de emergencia para Bitwarden, claves inyectadas desde la bóveda y delimitadas por el directorio principal de cada profile, y paridad de SecretRef ${env:VAR} entre config.yaml y la configuración de MCP. El modelo de autenticación de tres vías que se describe a continuación no ha cambiado.²⁴
• Inicio en caliente más rápido. El arranque en frío de hermes -w se redujo de unos 14 s a 1,8 s.²⁴
• El escritorio se convirtió en una plataforma. Artefactos con tarjetas versionadas y vista previa interactiva en un entorno aislado, un SDK de plugins con Kanban como plugin de escritorio inicial, un atajo de teclado global para entrada rápida, varias ventanas de interfaz gráfica, modo de backend remoto SSH e inicio de sesión nativo conforme a RFC 8252.²⁴

Las actualizaciones acumulativas v0.20.3 y v0.20.4 (17 y 18 de agosto)

Tras v0.20.0, el proyecto adoptó una cadencia de actualizaciones acumulativas etiquetadas y publicadas con gran frecuencia, y las dos más recientes incluyen más que estabilización. Ambas indican que «full curated release notes for this window will ship with v0.21.0», por lo que los siguientes resúmenes proceden de las descripciones de los periodos incluidas en las propias versiones, no de una lista seleccionada de funciones.²³

v0.20.3 (aproximadamente 250 commits y 125 PRs desde v0.20.2):

• Migración a SDK de MCP 2.x, compatible con el protocolo sin estado del 28 de julio de 2026. Hermes adopta la generación actual de SDK de MCP y se comunica mediante la revisión sin estado del protocolo.²³
• Bot Mode se distribuye como plugin incluido (hermes-bots) con el protocolo central para compañeros de equipo.²³
• Un plugin del proveedor CommandCode se incorpora al catálogo de proveedores.²³
• Contratos de ejecución de Cua Driver 0.20 para el uso de computadoras, además del refuerzo de la propiedad del entorno de ejecución de Python en subprocesos (aislamiento de PYTHONHOME/PYTHONPATH).²³
• Fiabilidad: autorreparación del planificador cron (recuperación de EMFILE, conciliación de asignaciones obsoletas y reactivación de tareas bloqueadas), correcciones para evitar la pérdida de datos al transferir sesiones, autorreparación de la conexión del escritorio con el gateway remoto y una oleada de adaptaciones del ecosistema (análisis de seguridad al instalar plugins, /worktree, conservación de ediciones manuales con /rollback y lectura de archivos UTF-16).²³

v0.20.4 (aproximadamente 146 commits y 74 PRs desde v0.20.3):

• La superficie de vidrio del escritorio: mejoras de vidrio mate y translucidez, con un selector de efecto escarchado y preselección para macOS.²³
• Una barra lateral con pestañas SESSIONS|BOTS, que permite ocultar o mostrar cada bot, además de correcciones para los chats grupales de Bot Mode (turnos prolongados de los miembros, representación de Markdown y enrutamiento entre computadoras).²³
• Análisis consultivo de nivel 1 de NVIDIA SkillEvaluator al instalar skills: las comprobaciones de licencias y seguridad se ejecutan cuando instalas un skill.²³
• Refuerzo del envío de contenido multimedia mediante cron (tiempo de espera configurable, archivos adjuntos en ejecuciones manuales y presentación de activaciones omitidas), correcciones de SessionDB para el hilo del bucle de eventos y la contención, información transparente de hermes update sobre ramas estacionadas y notificaciones nativas del sistema operativo para Kanban.²³

El proceso de actualización no ha cambiado: ejecuta hermes update desde una instalación existente o utiliza el instalador de shell para una instalación nueva.²³

Novedades de v0.19.0 (la versión Quicksilver)

Hermes Agent v0.19.0 (etiqueta v2026.7.20, 20 de julio de 2026) recibe su nombre por la velocidad propia del dios mensajero: la columna vertebral de la versión es la capacidad de respuesta pura, con una reducción de ~80 % en el tiempo hasta el primer token del primer turno en todas las plataformas. A su alrededor se incorporan la facturación desde la terminal, fuentes de secretos de gestores de contraseñas, aprobaciones inteligentes de forma predeterminada, subagentes observables y entrega de respuestas resistente a fallos. El periodo desde v0.18.0 es el más grande del proyecto hasta ahora: ~2.245 commits, ~1.065 PR fusionados, ~3.300 issues cerrados y más de 450 colaboradores de la comunidad.²⁵

• ~80 % más rápido hasta el primer token, en todas partes. El envío en frío→despacho bajó de ~4,3 s a ~0,9 s en CLI, gateway, TUI, escritorio y cron por igual: la detección de capacidades de Discord salió de la ruta crítica, la comprobación de Ollama se omite para proveedores conocidos que no son Ollama y se eliminó el trabajo bloqueante de la inicialización del agente. La latencia percibida recibió su propia mejora: los modelos de razonamiento ahora transmiten su razonamiento en vivo de forma predeterminada (display.show_reasoning está ACTIVADO), y el cuadro de respuesta se dibuja por token en lugar de por línea.²⁵
• Oleada de renderizado para escritorio y TUI. La aplicación de escritorio recibió una revisión de velocidad de ~20 PR: 14× menos CPU en el separador de Markdown en streaming mediante análisis léxico incremental por bloques, diferencias virtualizadas en el panel de revisión, cambio ágil de sesión en transcripciones grandes y sin más rerenderizados por token de la barra lateral ni de las filas de herramientas. La TUI ahora renderiza Markdown transmitido de forma incremental por bloque.²⁵
• Las instalaciones con pip y Homebrew están obsoletas. Ambas rutas se marcaron como instalaciones heredadas «no compatibles», con su eliminación prevista. Esa eliminación ya ocurrió en v0.20.0: los canales de brew y las wheels de pip/PyPI se retiraron; el instalador de shell, Docker y Nix quedan como los canales compatibles.²⁵²⁴
• Los secretos pueden provenir de tu gestor de contraseñas. Una nueva interfaz conectable SecretSource obtiene secretos de Bitwarden y 1Password (referencias op://) durante la carga, con varias bóvedas habilitadas al mismo tiempo, precedencia determinista, advertencias de conflicto y procedencia por variable: las claves de API ya no tienen que vivir en un .env de texto sin formato. Los proveedores de bóvedas futuros se incorporan como plugins.²⁵
• Las aprobaciones inteligentes ahora son la opción predeterminada. Cuando Hermes quiere ejecutar un comando marcado, un revisor independiente de LLM lo evalúa en vez de pedirte confirmación para cada uno, y cada veredicto cubre únicamente ese comando exacto. Las reglas de denegación definidas por el usuario bloquean los comandos coincidentes incluso en modo YOLO, /deny <reason> transmite el motivo de tu rechazo para que el agente corrija el rumbo, y la acción de aprobación pre_tool_call del plugin (restaurada con claves de reglas) escala una llamada a herramienta a una puerta de revisión humana.²⁵
• Facturación desde la terminal: /subscription y /topup. Gestiona tu plan de Nous Portal sin salir de la terminal: consulta tu plan y el saldo restante, previsualiza exactamente cuánto cuesta una mejora o cuándo entra en vigor una reducción, y aplícala con opción de deshacer. La aplicación de escritorio incorpora una pestaña equivalente de configuración de facturación.²⁵
• Observa el trabajo de los subagentes; nunca pierdas una respuesta terminada. Los despachos de delegate_task devuelven archivos de transcripción en vivo a los que puedes aplicar tail -f en cuanto se inician los subagentes: cada llamada a herramienta, resultado y respuesta transmitida, con un registro legible por humanos para cada agente hijo. Las finalizaciones de delegaciones en segundo plano son duraderas tras reinicios, y las respuestas finales del gateway se registran en un libro mayor de obligación de entrega en state.db y se reenvían durante el siguiente arranque si el gateway falla a mitad del envío. La opción de configuración max_async_children está obsoleta en favor de límites unificados de concurrencia de delegación.²⁵
• Un gateway, muchos profiles. Un único gateway multiplexado que comparte un token de bot puede enrutar guilds, canales o hilos específicos a distintos profiles, cada uno con configuración, skills, memoria y secretos totalmente aislados, mediante una anulación GATEWAY_MULTIPLEX_PROFILES. El índice de enrutamiento se trasladó a state.db; sessions.json ahora es un espejo heredado opcional.²⁵
• Oleada de proveedores y modelos. Fireworks AI llega como opción de primera clase (estimación de costos, puesto n.º 2 en el selector de proveedores), acompañado por DeepInfra y Upstage Solar. Los catálogos añaden GPT-5.6 (Sol/Terra/Luna + Pro, conectado de extremo a extremo), grok-4.5 (GA), kimi-k3 (kimi-k2.x retirado) y Claude Sonnet 5 totalmente conectado. Una marca enabled: false por proveedor y la configuración excluded_providers eliminan los proveedores sin usar de los selectores y la resolución de /model.²⁵
• El esfuerzo de razonamiento se convierte en un dial. Los nuevos niveles de esfuerzo max y ultra llegan a todas las superficies, con anulaciones por modelo en la configuración, esfuerzo por slot en los preajustes de MoA (los asesores razonan a fondo y el sintetizador se mantiene rápido), esfuerzo por tarea para modelos auxiliares y un /reasoning con alcance de sesión en CLI.²⁵
• Superficie de CLI y MCP. hermes sessions export escribe formatos Markdown, Quarto, HTML, solo-prompt y trazas de Hugging Face con una limpieza opcional --redact; /model --once proporciona una anulación de modelo para un turno; las invocaciones de slash-skill se apilan (/skill-a /skill-b do XYZ); --safe-mode facilita la solución de problemas; hermes config get/unset completan la gestión de configuración; hermes serve se convierte en un backend verdaderamente sin interfaz; y las herramientas de MCP adoptan la convención de nombres mcp__server__tool.²⁵

Si estás actualizando desde v0.18.x, dos cambios merecen atención antes que cualquier otro: una instalación con pip o Homebrew ahora advierte que es heredada y no compatible (migra al instalador de una línea), y max_async_children está obsoleto en favor de los límites unificados de concurrencia de delegación. Todo lo demás es adicional: las razones principales para actualizar son la reducción de ~80 % en la latencia del primer turno, las aprobaciones inteligentes y el libro mayor de entrega que hace que las respuestas terminadas sean resistentes a fallos.

Novedades de v0.18.0 (la versión Judgment)

Hermes Agent v0.18.0 (etiqueta v2026.7.1, 1 de julio de 2026) recibe su nombre por el juicio: el agente verifica su propio trabajo en lugar de afirmar que tuvo éxito, y ofrece razonamiento en conjunto que realmente puedes inspeccionar. También cierra toda la lista pendiente P0/P1: aproximadamente 692 elementos de máxima prioridad resueltos en doce días.²²

• Mixture-of-Agents como modelo de primera clase. MoA ahora se puede seleccionar como cualquier otro modelo en todas las interfaces, y el razonamiento en conjunto es visible: la salida completa de cada modelo de referencia se renderiza como su propio bloque etiquetado con transmisión de respuestas en vivo; puedes observar cómo razona el conjunto en lugar de recibir una respuesta combinada opaca.²²
• Contratos de finalización para /goal. El agente verifica su propio trabajo ejecutando las comprobaciones del proyecto antes de informar que un objetivo está completo, en lugar de simplemente afirmar que tuvo éxito: juicio aplicado a sí mismo.²²
• /learn: describe cualquier cosa y conviértela en un skill. Convierte un flujo de trabajo en un skill reutilizable describiéndolo; los skills generados cumplen automáticamente las convenciones de CONTRIBUTING.md del repositorio.²²
• Cronología de /journey. Un historial visual de la memoria y los skills a lo largo del tiempo, con edición, además de un gráfico de memoria en el escritorio.²²
• Distribución de subagentes en segundo plano. Delega varias tareas que se ejecutan simultáneamente sin bloquear la conversación: el único subagente en segundo plano de v0.17.0 se convierte en una flota.²²
• Projects de escritorio. Projects de programación de primera clase con un modelo de organización por proyecto/repositorio/carril.²²
• Gateway con escalado a cero. Los gateways pueden quedar inactivos cuando no se usan y coordinar drenajes para implementaciones sin interrupciones, algo significativo para quienes ejecutan Hermes como un servicio siempre activo.²²
• Compatibilidad con Google Vertex AI. Acceso a Gemini mediante cuentas de servicio de GCP con actualización automática del token OAuth2, que se suma al catálogo de proveedores.²²
• Comando de editor /prompt. Abre $EDITOR para redactar prompts de varias líneas, en lugar de luchar con la línea de entrada.²²

Si estás actualizando desde v0.17.x, nada de esto rompe CLI. Las razones principales para actualizar son los contratos de finalización (objetivos que se verifican a sí mismos), MoA de primera clase con conjuntos inspeccionables y /learn para capturar skills.

Novedades de v0.17.0 (la versión de alcance)

Hermes Agent v0.17.0 (tag v2026.6.19, 19 de junio de 2026) recibe su nombre por el alcance que ahora tiene el agente: nuevos canales de mensajería, nuevos proveedores de modelos y un control más profundo del escritorio y el dashboard. Es una versión aditiva sobre v0.16.x; la superficie de CLI no cambia.²¹

• Nuevos canales de mensajería. iMessage ahora funciona sin un relay de Mac mediante Photon Spectrum (código de dispositivo de OAuth, hermes photon login); WhatsApp Business Cloud API es un adaptador oficial de Meta que sustituye el requisito de un proceso bridge; SimpleX incorpora grupos, adjuntos nativos, agrupación de texto y aceptación automática; y Raft se incorpora como plugin de plataforma incluido, con un diseño de canal de activación basado en privacidad por contrato.²¹
• Nuevos modelos y proveedores. El catálogo agrega z-ai/glm-5.2 (1M de contexto), anthropic/claude-fable-5, laguna-m.1, nemotron-3-ultra y grok-composer-2.5-fast (el modelo de Cursor mediante xAI OAuth, 200k de contexto). El valor predeterminado de xAI pasó a grok-build-0.1, y los modelos adaptativos de Anthropic ahora siguen el contrato moderno de razonamiento (nunca envían un campo reasoning).²¹
• Escritorio y dashboard. Desktop incorpora subagentes en segundo plano con transmisión en vivo de “watch-windows” que muestra la actividad delegada (delegate_task(background=true)), un selector de modelos en Composer, atajos de teclado reasignables, notificaciones nativas del sistema operativo, borradores del compositor por hilo, temas de VS Code Marketplace e interfaz en japonés y chino tradicional. El dashboard añade un constructor completo de profiles (modelo/skills/MCPs sin editar config.yaml), un selector global de profiles, un Skills Hub rediseñado con análisis de seguridad, Automation Blueprints (plantillas parametrizadas para formulario, comando slash, conversación y documentación), y un inicio de sesión seguro que devuelve 401 detrás de la puerta de OAuth.²¹
• Skills y herramientas. image_generate ahora puede editar y transformar una imagen de origen, no solo crear una desde cero, en todos los proveedores de imágenes compatibles; la herramienta memory obtuvo un arreglo operations para realizar lotes atómicos de agregar/reemplazar/eliminar en una sola llamada; un nuevo skill simplify-code ejecuta en paralelo una revisión y limpieza con tres agentes, controlada por un nivel de riesgo de la valla de Chesterton; y un booleano write_approval sustituye al write_mode de tres estados.²¹
• Arquitectura. Los subagentes en segundo plano devuelven un handle de inmediato y reincorporan su resultado como un nuevo turno; un controlador de elicitation de MCP permite confirmar durante una llamada de herramienta, y las herramientas de MCP que se conectan tarde se exponen entre turnos (seguro para la caché); cron pasa a ser un CronScheduler conectable con un proveedor de cron administrado Chronos; y un nuevo Managed scope (/etc/hermes) permite a un administrador fijar configuración inmutable para el usuario, junto con un relay Gateway-Gateway para topologías de múltiples gateways.²¹
• Nuevos comandos. /version, /billing (facturación interactiva en terminal), hermes photon login (autenticación de iMessage) y hermes curator run --consolidate; la consolidación ahora es opcional, por lo que la curación rutinaria en segundo plano no consume tokens.²¹
• Seguridad. v0.17.0 corrige una omisión de la lista de bloqueo de escapes de shell, falla de forma segura cuando faltan módulos de aprobación y adaptadores de gateway con políticas propias, sanitiza el entorno de los subprocesos de scripts de trabajos cron, oculta secretos en volcados de depuración de solicitudes, analiza configuraciones stdio de MCP en busca de patrones de exfiltración y actualiza urllib3 y PyJWT para corregir CVE.²¹

Si actualizas desde v0.16.x, nada de esto rompe CLI; se trata de nuevos canales, modelos y superficies alrededor del mismo agente. Los adaptadores oficiales de iMessage sin relay y WhatsApp, además del Managed scope para administradores, son los motivos principales para actualizar.

Novedades de v0.16.0 (la versión de superficies)

Hermes Agent v0.16.0 (tag v2026.6.5, 5 de junio de 2026) recibe su nombre por las nuevas superficies que pone frente al agente centrado en CLI. La gran novedad es que Hermes ya no se limita a la terminal.²⁰

• Aplicación de escritorio nativa. Hermes Desktop es una nueva aplicación Electron para macOS, Linux y Windows con instalación en un clic y actualización automática dentro de la aplicación. Te ofrece una ventana de chat con transmisión en vivo, archivos mediante arrastrar y soltar, pegado de imágenes desde el portapapeles, una paleta Cmd+K, una lista de sesiones con archivo y búsqueda, y un selector de modelos en la barra de estado. Puede conectarse a un gateway remoto de Hermes mediante un WebSocket seguro, con autenticación a través de OAuth o nombre de usuario/contraseña, hosts remotos por profile y sesiones simultáneas de varios profiles vinculadas mediante referencias @session entre profiles. La interfaz de escritorio también incluye una traducción completa al chino simplificado (简体中文) mediante una capa i18n tipada (display.language; el inglés sigue siendo el valor predeterminado).²⁰
• Panel de administración en el navegador. El dashboard web local evolucionó de una vista de estado a un panel de administración completo: un catálogo de MCP con controles para activar o desactivar, administración de credenciales, creación de webhooks y hooks, configuración de memory, controles de gateway y una página System con comprobación antes de actualizar y Debug Share en un clic. Una nueva página Channels configura desde el navegador todas las plataformas de mensajería del gateway (Telegram, Discord, Slack y las demás). La autenticación ahora es conectable: inicio de sesión con nombre de usuario/contraseña, un proveedor OIDC genérico autohospedado, hermes dashboard register para un cliente OAuth autohospedado y rotación de sesiones mediante refresh token.²⁰
• Nuevos CLI y comandos slash. /undo [N] respalda los últimos N turnos del usuario con prefill y eliminación suave, y funciona en CLI, la TUI y todas las plataformas de mensajería. Llega una interfaz predeterminada configurable (cli frente a tui) con una anulación --cli; la TUI obtiene un comando /model unificado y una superposición de Sessions. hermes portal es un alias legible para humanos del flujo de incorporación de Nous Portal, con nuevas rutas de primera ejecución Quick Setup y Full Setup, además de dos diagnósticos: hermes prompt-size y hermes sessions optimize.²⁰
• Nuevos modelos y proveedores. El selector añade deepseek-v4-flash, MiniMax-M3 (1M de contexto, proveedores MiniMax nativos), qwen3.7-plus (Nous + OpenRouter) y gemini-3.5-flash (Gemini OAuth + clave API). Un proveedor xAI Grok de OAuth de primera clase se incorpora al lanzador de escritorio, el selector de modelos pasa a tener búsqueda difusa en todas las superficies, los proveedores de múltiples endpoints se agrupan en una sola fila y la actualización del catálogo pasa de diaria a cada hora.²⁰
• Skills más ligeros y divulgación progresiva. El conjunto de skills predeterminado eliminó skills redundantes y sin uso (Spotify pasó a un plugin nativo, Linear a hermes mcp install linear y se retiraron varias entradas obsoletas), movió más elementos a opcionales y agregó una puerta de relevancia en frontmatter environments: (kanban/docker/s6) que mantiene los skills específicos del contexto fuera del índice hasta que se solicitan. NVIDIA/skills ahora es una fuente predeterminada confiable de Skills Hub junto con OpenAI, Anthropic y HuggingFace. Las herramientas de MCP y plugins obtuvieron divulgación progresiva de herramientas por alcance, y se corrigió un error de MCP que informaba falsos éxitos de OAuth cuando no se obtenía ningún token.²⁰
• Seguridad. v0.16.0 fija Starlette con el parche (≥1.0.1) para CVE-2026-48710 (BadHost), mueve las comprobaciones de URL contra SSRF fuera del event loop en rutas asíncronas, elimina el token bearer de inferencia de Bedrock del entorno de subprocesos, añade bws_cache.json a la protección de lectura de seguridad de archivos, incorpora docker restart/stop/kill a la lista de patrones peligrosos y sanitiza unicode invisible en contenido de skills validado. La versión cerró 2 problemas P0 y 62 P1, 16 de ellos etiquetados como de seguridad.²⁰

Si actualizas desde v0.15.x, nada de esto implica un cambio incompatible en CLI en sí; son superficies y proveedores adicionales alrededor del mismo agente. La aplicación de escritorio y el panel de administración son el motivo para actualizar si quieres ejecutar Hermes para usuarios que no usan la terminal o administrar un gateway remoto desde un navegador.

Instalación

El instalador de una sola línea es la vía de instalación compatible. Se encarga de Python, uv, Node.js, ripgrep, ffmpeg, el clon del repositorio, el entorno virtual y el comando global hermes.⁷

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Las instalaciones mediante pip y Homebrew están obsoletas desde la v0.19.0. El paquete de PyPI que introdujo la v0.14.0 (pip install hermes-agent) y la fórmula de Homebrew ahora se identifican como instalaciones «heredadas no compatibles»; cada interfaz advierte (sin bloquear) cuando Hermes detecta una, y está prevista la eliminación de la publicación en PyPI/Homebrew. Si instalaste mediante pip o brew, migra al instalador anterior.²⁵

Funciona en Linux, macOS, WSL2 y Android/Termux (el instalador detecta automáticamente Termux y cambia a un paquete de Android probado).⁷ Windows nativo ahora es una plataforma de nivel 1, en lugar de la beta temprana con la que se lanzó la v0.14.0: instálalo con iex (irm https://hermes-agent.nousresearch.com/install.ps1). Hay una advertencia que la documentación deja explícita: la compatibilidad con macOS es solo para Apple Silicon; las Mac Intel no son compatibles.²⁴ Históricamente, la v0.14.0 añadió soporte nativo para Windows en beta temprana mediante un instalador de PowerShell, pero WSL2 sigue siendo la recomendación más segura para uso en producción hasta que la vía de Windows madure.¹⁹

Cuando termine:

source ~/.bashrc    # or ~/.zshrc
hermes              # Start chatting

El único requisito previo es git. El instalador aprovisiona automáticamente Python 3.11 mediante uv (sin necesidad de sudo), Node.js 26 (para la automatización del navegador y el puente de WhatsApp), ripgrep y ffmpeg. Node 26 es un requisito mínimo estricto desde la v0.20.0: el instalador rechaza cualquier versión anterior e instala una versión de Node administrada por Hermes.²⁴⁷

Verifica la instalación

hermes version      # Check version
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

hermes doctor te indica exactamente qué falta y cómo solucionarlo.⁷ hermes dump es el comando de diagnóstico que debes pegar en un issue de GitHub o en un hilo de Discord al pedir ayuda: es un resumen de texto sin formato de toda tu configuración, con los secretos ocultos.⁸

Instalación manual

Si necesitas control total —una versión personalizada de Python, extras específicos o integración con Nix/NixOS—, el flujo manual está documentado paso a paso en la guía de instalación upstream.⁷ Extras opcionales clave que puedes combinar con uv pip install -e ".[<extras>]":

El comando de instalación de Termux es diferente: usa pip con un archivo de restricciones, no uv pip:

python -m pip install -e ".[termux]" -c constraints-termux.txt

Esto se debe a que .[all] en Android incorpora faster-whisper mediante el extra voice, que depende de paquetes wheel de ctranslate2 que no se publican para Android.⁷

Autenticación y proveedores

Hermes admite aproximadamente 22 proveedores de primera clase, además de endpoints personalizados (v0.19.0 añade Fireworks AI, DeepInfra y Upstage Solar), y tres rutas de autenticación distintas. Aquí tienes toda la superficie de autenticación, organizada por ruta para que encuentres la que coincida con lo que tienes.

Las tres rutas de autenticación

Cada proveedor de Hermes encaja en uno de tres patrones de autenticación:

Ruta 1 — clave API en .env. Coloca tu clave en ~/.hermes/.env y Hermes la lee al iniciarse. Se usa con OpenRouter, AI Gateway, z.ai/GLM, Kimi/Moonshot, MiniMax (y MiniMax China), Alibaba Cloud/DashScope, Kilo Code, OpenCode Zen, OpenCode Go, DeepSeek, Hugging Face, Google/Gemini y la mayoría de los proveedores de terceros.² Desde v0.19.0, la clave ya no tiene que estar en un archivo de texto sin formato: una interfaz conectable SecretSource puede obtener secretos de Bitwarden o 1Password (referencias op://) durante la carga, con varias bóvedas activadas simultáneamente, precedencia determinista, advertencias de conflicto y procedencia por variable; .env sigue siendo la alternativa de respaldo. (Esto es distinto del token de arranque de Bitwarden Secrets Manager de v0.15.0, que consolidaba las claves de proveedor detrás de un único token; SecretSource reemplaza el propio archivo de texto sin formato, y los futuros proveedores de bóvedas se incorporan como plugins.)²⁵

Ruta 2 — OAuth mediante hermes model o hermes auth. Inicia un flujo de código de dispositivo, abre un navegador, almacena las credenciales en ~/.hermes/auth.json (y puede importar credenciales existentes de herramientas como Claude Code o Codex CLI). Se usa con Nous Portal, OpenAI Codex (cuenta de ChatGPT), GitHub Copilot y Anthropic (Claude Pro/Max).²

Ruta 3 — endpoint personalizado en config.yaml. Para cualquier API compatible con OpenAI: Ollama, vLLM, SGLang, llama.cpp, LM Studio, proxy LiteLLM, Together AI, Groq, Azure OpenAI o tu propio servidor autoalojado. Se configura una vez mediante hermes model → Custom endpoint y luego se conserva en config.yaml.²

La matriz completa de proveedores

Esta es la lista completa de proveedores de primera clase, con el flujo de configuración exacto para cada uno.²

Desde v0.19.0 también puedes depurar los proveedores que no usas: una marca enabled: false por proveedor y una clave de configuración excluded_providers los eliminan de los selectores de /model y de la resolución de proveedores integrada.²⁵

Anthropic: tres métodos de autenticación

Anthropic tiene su propia sección porque Hermes admite tres rutas distintas hacia Claude, y elegir la adecuada importa. Según la documentación upstream:²

# Method 1: API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Method 2: OAuth through hermes model (preferred)
# Uses Claude Code's credential store when available
hermes model

# Method 3: Manual setup-token (fallback/legacy)
export ANTHROPIC_TOKEN=***
hermes chat --provider anthropic

# Auto-detect Claude Code credentials
hermes chat --provider anthropic   # reads Claude Code files automatically

Cuando eliges Anthropic OAuth mediante hermes model, Hermes prefiere el propio almacén de credenciales de Claude Code en lugar de copiar el token a ~/.hermes/.env. Así, las credenciales actualizables de Claude siguen siendo actualizables.² Si ya usas Claude Code en la misma computadora, esta es la ruta más limpia.

Para fijar Anthropic permanentemente en config.yaml:

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

--provider claude y --provider claude-code también funcionan como abreviaturas de --provider anthropic.²

GitHub Copilot: dos modos

Copilot es compatible con dos modos: API de Copilot directo (recomendado) y Copilot ACP (que inicia el CLI local de Copilot como subproceso).²

# Direct Copilot API
hermes chat --provider copilot --model gpt-5.4

# Copilot ACP (requires the Copilot CLI in PATH + an existing copilot login)
hermes chat --provider copilot-acp --model copilot-acp

La autenticación se comprueba en este orden, según la documentación upstream:² 1. Variable de entorno COPILOT_GITHUB_TOKEN 2. Variable de entorno GH_TOKEN 3. Variable de entorno GITHUB_TOKEN 4. Alternativa mediante CLI gh auth token 5. Inicio de sesión con código de dispositivo OAuth mediante hermes model

El tipo de token importa. El API de Copilot no admite Personal Access Tokens clásicos (ghp_*). Los tipos compatibles son tokens OAuth (gho_*), PAT de granularidad fina (github_pat_* con permiso Copilot Requests) y tokens de la App GitHub (ghu_*). Si tu gh auth token devuelve un token ghp_*, usa hermes model para autenticarte mediante OAuth.²

Proveedores de IA chinos (soporte de primera clase)

Hermes tiene soporte integrado para z.ai/GLM, Kimi/Moonshot, MiniMax (endpoints globales y de China) y Alibaba Cloud con ID de proveedor dedicados.²

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5                 # Requires: GLM_API_KEY

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding   # Requires: KIMI_API_KEY

# MiniMax (global)
hermes chat --provider minimax --model MiniMax-M2.7          # Requires: MINIMAX_API_KEY

# MiniMax (China)
hermes chat --provider minimax-cn --model MiniMax-M2.7       # Requires: MINIMAX_CN_API_KEY

# Alibaba Cloud / DashScope (Qwen)
hermes chat --provider alibaba --model qwen3.5-plus          # Requires: DASHSCOPE_API_KEY

Puedes reemplazar las URL base con las variables de entorno GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL o DASHSCOPE_BASE_URL.²

Z.AI detecta automáticamente el endpoint. Al usar el proveedor z.ai/GLM, Hermes prueba varios endpoints (global, China y variantes de código) para encontrar uno que acepte tu clave API. El endpoint funcional se almacena automáticamente en caché; la mayoría de los usuarios no necesitan GLM_BASE_URL.²

xAI (Grok) habilita automáticamente el almacenamiento en caché de prompts. Cuando la URL base contiene x.ai, Hermes envía el encabezado x-grok-conv-id con cada solicitud para dirigirla al mismo servidor durante una sesión de conversación, reutilizando prompts de sistema e historial almacenados en caché.² Es automático; no requiere configuración.

El comando hermes auth

hermes auth es el comando de gestión de credenciales para pools y credenciales OAuth.⁶

hermes auth                              # Interactive wizard
hermes auth list                         # Show all credential pools
hermes auth list openrouter              # Show one provider's pool
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth
hermes auth remove openrouter 2          # Remove by index
hermes auth reset openrouter             # Clear cooldowns

Los pools de credenciales te permiten rotar varias claves API o tokens OAuth para el mismo proveedor; son útiles para distribuir límites de tasa entre varias claves sin cambiar código.⁶ Los comandos heredados hermes login / hermes logout se eliminaron; usa hermes auth en su lugar.⁶

Endpoints personalizados y autoalojados

Hermes funciona con cualquier endpoint API compatible con OpenAI. Si un servidor implementa /v1/chat/completions, puedes dirigir Hermes hacia él.²

Configuración interactiva (recomendada):

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

config.yaml manual:

model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

Ambos enfoques se conservan en config.yaml, que es la única fuente de verdad para el modelo principal, el proveedor y la URL base.² Las variables de entorno heredadas OPENAI_BASE_URL y LLM_MODEL ya no se leen para la configuración del modelo principal; usa hermes model o edita config.yaml directamente.² (OPENAI_BASE_URL + OPENAI_API_KEY todavía se respetan como alternativa para la ruta de enrutamiento auxiliar provider: "main", así que no las elimines a ciegas si las usas allí.)⁴

Cambiar de endpoint personalizado durante una sesión:

/model custom:qwen-2.5             # Custom endpoint with explicit model
/model custom                      # Auto-detect the model from the endpoint
/model custom:local:qwen-2.5       # Named custom provider "local"
/model custom:work:llama3          # Named custom provider "work"
/model openrouter:claude-sonnet-4  # Back to a cloud provider

/model custom (sin nada más, sin nombre de modelo) consulta el API /v1/models de tu endpoint y selecciona automáticamente el modelo si hay exactamente uno cargado; es útil para servidores locales que ejecutan un solo modelo.²

Servidores LLM locales (plantillas de configuración)

La documentación upstream tiene guías completas de configuración para Ollama, vLLM, SGLang, llama.cpp y LM Studio. Aquí están los comandos clave que realmente ejecutarás. Cada uno está diseñado para producir un endpoint funcional al que Hermes pueda dirigirse.²

Ollama — la ruta local más sencilla, sin configuración:

ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # Raise from 4k default
hermes model   # Custom endpoint → http://localhost:11434/v1 → qwen2.5-coder:32b

Advertencia crítica de Ollama: Ollama usa por defecto longitudes de contexto muy bajas (4.096 tokens con menos de 24 GB de VRAM). Debes aumentarla mediante OLLAMA_CONTEXT_LENGTH o un Modelfile: el API compatible con OpenAI no acepta la longitud de contexto del cliente, por lo que Hermes no puede establecerla por ti.² Para uso con agentes, configúrala al menos entre 16k y 32k.

vLLM — servicio GPU de alto rendimiento:

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

Las llamadas a herramientas requieren --enable-auto-tool-choice y --tool-call-parser <name>. Analizadores compatibles: hermes (Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic. Sin estas opciones, las llamadas a herramientas regresarán como texto sin formato.²

SGLang — servicio rápido con RadixAttention para reutilización de caché KV:

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

Advertencia de SGLang: El valor predeterminado de max_tokens es 128. Configura --default-max-tokens en el servidor o model.max_tokens en config.yaml si las respuestas se cortan.²

llama.cpp / llama-server — CPU y Metal de Apple Silicon:

./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

--jinja es obligatorio para las llamadas a herramientas. Sin él, llama-server ignora por completo el parámetro tools y el modelo intenta llamar herramientas escribiendo JSON en el texto de su respuesta, algo que Hermes no puede interpretar como llamadas a herramientas reales.²

LM Studio — aplicación de escritorio con GUI:

Inicia el servidor desde la aplicación LM Studio (pestaña Developer → Start Server), o mediante CLI: lms server start (inicia en el puerto 1234) y lms load qwen2.5-coder --context-length 32768.² Luego dirige hermes model a http://localhost:1234/v1.

Advertencia crítica de LM Studio: LM Studio lee la longitud de contexto de los metadatos del modelo, pero muchos modelos GGUF informan valores predeterminados de 2048 o 4096. Configura siempre la longitud de contexto explícitamente en los ajustes del modelo de LM Studio: haz clic en el icono de engranaje junto al selector de modelos, establece “Context Length” en al menos 16384 (preferiblemente 32768) y vuelve a cargar el modelo.²

Proveedores personalizados con nombre

Si trabajas con varios endpoints personalizados (un servidor de desarrollo local y un servidor GPU remoto, por ejemplo), defínelos como proveedores personalizados con nombre en config.yaml:²

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions      # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages    # for Anthropic-compatible proxies

Luego cambia entre ellos durante la sesión con la sintaxis triple:

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4

También puedes seleccionar proveedores personalizados con nombre desde el menú interactivo hermes model.²

Arquitectura de proveedores conectables (v0.13.0+)

v0.13.0 incluye un ABC ProviderProfile además de un directorio plugins/model-providers/ para que los proveedores de inferencia de terceros se incorporen sin modificaciones al núcleo.¹⁸ Si un proveedor utiliza un modo API compatible con OpenAI, Anthropic o Codex, puedes implementar una subclase de ProviderProfile que declare la ruta de autenticación, la URL base, el catálogo de modelos y los encabezados de caché; Hermes la resuelve mediante la misma ruta runtime_provider.py que usan los proveedores integrados. Este es el cambio arquitectónico detrás de la expansión de proveedores de v0.13.0: en lugar de editar el código central para añadir un proveedor, distribuyes un plugin.

Proxy local compatible con OpenAI (v0.14.0+)

hermes proxy expone un endpoint local compatible con OpenAI respaldado por el proveedor OAuth en el que Hermes ya inició sesión: Claude Pro, ChatGPT Pro, SuperGrok u otro proveedor compatible configurado.¹⁹ Esto significa que las herramientas que esperan un API estilo OpenAI, incluidos Codex CLI, Aider, Cline, Continue o scripts personalizados, pueden reutilizar tu autenticación de Hermes respaldada por suscripción sin una clave API independiente. Trata el proxy como infraestructura local de desarrollo: asígnale un enlace de forma intencional, no lo expongas ampliamente y ten presentes los términos específicos del proveedor.

Detección de longitud de contexto

Según la documentación upstream, se confunden constantemente dos configuraciones:²

• context_length — la ventana de contexto total (presupuesto combinado de tokens de entrada + salida; por ejemplo, 1.000.000 para Claude Opus 4.7 o 200.000 para Sonnet 4.6). Hermes usa esto para decidir cuándo comprimir el historial.
• model.max_tokens — el límite de salida (máximo de tokens que el modelo puede generar en una sola respuesta). No está relacionado con la longitud del historial.

Configura context_length cuando la detección automática se equivoque en el tamaño de la ventana:

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072      # tokens

Hermes usa una cadena de resolución de múltiples fuentes para detectar las ventanas de contexto: anulación de configuración → proveedor personalizado por modelo → caché persistente → endpoint /models → Anthropic /v1/models → API de OpenRouter → Nous Portal → models.dev (registro mantenido por la comunidad con más de 3800 modelos) → valores predeterminados de respaldo (128K).² El sistema reconoce el proveedor, por lo que el mismo modelo puede tener límites de contexto diferentes según quién lo sirva (por ejemplo, claude-opus-4.6 tiene 1M con Anthropic directo, pero 128K con GitHub Copilot).²

Enrutamiento inteligente de modelos: rotación y respaldo de proveedores

Hermes no te fija a un modelo en un proveedor. El enrutamiento inteligente de modelos es el conjunto de mecanismos que decide qué proveedor y modelo atiende realmente una solicitud determinada: los pools de credenciales distribuyen la carga entre claves, un respaldo configurado toma el control cuando falla el principal y las ranuras auxiliares de abajo dirigen las tareas secundarias a modelos más económicos independientemente de tu modelo principal.²⁶ Configura estos tres elementos juntos: son la diferencia entre un agente que se detiene por un límite de tasa y uno que sigue trabajando.

Pools de credenciales. Cuando tienes varias claves API para el mismo proveedor, configura una estrategia de rotación mediante hermes auth. Así distribuyes los límites de tasa entre varias claves.⁶

Modelo de respaldo. Configura un provider:model de respaldo al que Hermes cambia automáticamente cuando falla tu modelo principal (límites de tasa, errores de servidor, fallas de autenticación):²

fallback_model:
  provider: openrouter            # required
  model: anthropic/claude-sonnet-4  # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name

El respaldo cambia el modelo y el proveedor durante la sesión sin perder tu conversación. Se activa como máximo una vez por sesión.² Proveedores compatibles para respaldo: openrouter, nous, openai-codex, copilot, copilot-acp, anthropic, huggingface, zai, kimi-coding, minimax, minimax-cn, deepseek, ai-gateway, opencode-zen, opencode-go, kilocode, alibaba, custom.²

Modelos auxiliares

Hermes usa modelos ligeros “auxiliares” para tareas secundarias: análisis de imágenes, resumen de páginas web, análisis de capturas de pantalla del navegador, clasificación de aprobación de comandos peligrosos, compresión de contexto, resumen de búsquedas de sesión, coincidencia de skills, despacho de herramientas MCP y vaciado de memoria.⁴ De forma predeterminada, estos usan Gemini Flash mediante detección automática (OpenRouter → Nous → Codex).

Puedes configurar qué modelo y proveedor usa cada tarea auxiliar. Cada ranura auxiliar utiliza los mismos tres controles: provider, model, base_url.⁴

auxiliary:
  vision:
    provider: "auto"                # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                       # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""                    # Custom OpenAI-compatible endpoint
    api_key: ""                     # Falls back to OPENAI_API_KEY
    timeout: 30
    download_timeout: 30
  web_extract:
    provider: "auto"
    model: ""
    timeout: 360
  approval:
    provider: "auto"
    model: ""
    timeout: 30
  compression:
    timeout: 120
  session_search: { provider: "auto", model: "", timeout: 30 }
  skills_hub:    { provider: "auto", model: "", timeout: 30 }
  mcp:           { provider: "auto", model: "", timeout: 30 }
  flush_memories:{ provider: "auto", model: "", timeout: 30 }

La opción de proveedor "main" significa “usar cualquier proveedor que use mi agente principal”; es válida solo dentro de las configuraciones auxiliary:, compression: y fallback_model:. No es válida para tu configuración de nivel superior model.provider. Si usas un endpoint personalizado compatible con OpenAI como modelo principal, establece provider: custom en la sección model:.⁴

Por qué importa: si solo configuraste Anthropic OAuth (sin clave de OpenRouter), tu visión, resumen web y compresión se degradarán o fallarán porque la cadena auxiliar predeterminada intenta usar primero OpenRouter. Añade una OPENROUTER_API_KEY para las tareas auxiliares o vuelve a configurar cada ranura auxiliar para usar tu proveedor principal:

auxiliary:
  vision:
    provider: "main"
  web_extract:
    provider: "main"

Esta es la advertencia más común de “mis funciones no funcionan de forma silenciosa” para los nuevos usuarios de Hermes.

Sistema de configuración

Hermes tiene un sistema de configuración por capas. Entender la precedencia es esencial, porque las capas superiores anulan las inferiores y una de ellas es un registro global de proveedores que no puedes ver en config.yaml.

Diseño de los archivos de configuración

Según la documentación upstream, estos son los archivos que conforman una configuración de Hermes:⁴

~/.hermes/
├── config.yaml       # All settings (model, terminal, TTS, compression, memory, toolsets, ...)
├── .env              # Secrets (API keys, bot tokens, passwords)
├── auth.json         # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md           # Primary agent identity (slot #1 in system prompt)
├── memories/         # Persistent memory (MEMORY.md, USER.md)
├── skills/           # Bundled + agent-created + hub-installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Gateway session state
└── logs/             # agent.log, gateway.log, errors.log (secrets auto-redacted)

config.yaml frente a .env: cuando ambos están configurados, config.yaml prevalece para los ajustes que no son secretos.⁴ La regla es: - Secretos (claves API, tokens de bots, contraseñas) → .env - Todo lo demás (modelo, backend de terminal, ajustes de compresión, límites de memoria, toolsets) → config.yaml

Puedes hacer referencia a secretos desde config.yaml mediante interpolación al estilo shell:⁴

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}
  delegation:
    api_key: ${DELEGATION_KEY}

Administración de la configuración

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config get KEY        # Print a single value (v0.19.0+)
hermes config unset KEY      # Remove a key so the default applies again (v0.19.0+)
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

Ejemplos:⁴

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

hermes config check y hermes config migrate son los comandos que debes ejecutar después de cada hermes update: detectan opciones de configuración recién añadidas que tu archivo aún no tiene.⁶

Precedencia de configuración

Hermes carga la configuración desde varias fuentes. Cuando varias fuentes establecen el mismo valor, prevalece la fuente de mayor prioridad:⁴

1. Argumentos de CLI — hermes chat --model anthropic/claude-sonnet-4 (anulación por invocación)
2. Variables de entorno — se aplican al iniciar el proceso
3. config.yaml — el archivo principal de ajustes
4. .env — solo secretos
5. Valores predeterminados integrados — se aplican cuando nada más establece un valor

Las flags de CLI siempre prevalecen para esa única invocación. config.yaml es la fuente de verdad a largo plazo.

Localización (v0.13.0+)

v0.13.0 añadió 7 idiomas para CLI y los mensajes del gateway: chino (simplificado), japonés, alemán, español, francés, ucraniano y turco.¹⁸ v0.14.0 localiza todos los comandos del gateway y el panel web, añade 8 idiomas más y eleva el total a 16.¹⁹ Actualmente, la documentación está localizada solo en zh-Hans. El idioma se resuelve a partir de las variables de entorno LC_ALL / LANG o de una clave explícita locale: en config.yaml. El inglés sigue siendo el valor predeterminado y la fuente de verdad para cualquier cadena que una traducción aún no cubra.

Profiles: múltiples instancias aisladas de Hermes

Los profiles te proporcionan varias instancias aisladas de Hermes, cada una con su propia configuración, sesiones, skills, memoria y PID del gateway. Así puedes ejecutar “Hermes de trabajo” y “Hermes personal” en paralelo sin que ninguno vea el estado del otro.⁶

hermes profile list
hermes profile create work --clone                  # Clone from current profile
hermes profile use work                             # Set sticky default
hermes profile alias work --name h-work             # Create wrapper script
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"    # One-off without switching

Cada profile obtiene su propio HERMES_HOME (~/.hermes-<name>/ de forma predeterminada), por lo que varios profiles pueden ejecutar el gateway de forma simultánea sin interferir entre sí.⁶³

Comandos de CLI

Esta sección es la referencia práctica de los comandos de nivel superior de CLI. Para consultar la referencia autorizada derivada del código, consulta la Referencia de comandos de CLI.⁶

Opciones globales

hermes [global-options] <command> [subcommand/options]

Comandos de nivel superior

hermes chat — El punto de entrada principal

hermes sin argumentos te lleva al chat interactivo. hermes chat es la forma explícita con opciones:⁶

hermes chat -q "Summarize the latest PRs"           # One-shot, non-interactive
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills          # Enable specific toolsets
hermes chat --quiet -q "Return only JSON"           # Programmatic mode
hermes chat --worktree -q "Review repo and open a PR"

Opciones clave:

hermes setup — Asistente completo

Ejecuta el asistente de configuración completo o salta directamente a una sección:⁶

hermes setup                 # Full wizard
hermes setup model           # Provider and model only
hermes setup terminal        # Terminal backend only
hermes setup gateway         # Messaging platforms only
hermes setup tools           # Tool enable/disable per platform
hermes setup agent           # Agent behavior only
hermes setup --non-interactive
hermes setup --reset         # Reset config to defaults before setup

hermes logs — Consulta estructurada de logs

hermes logs es más potente que usar tail -f en los archivos de log porque permite filtrar simultáneamente por nivel, ID de sesión y rango de tiempo.⁶

hermes logs                          # Last 50 lines of agent.log
hermes logs -f                       # Follow in real time
hermes logs gateway -n 100           # Last 100 lines of gateway.log
hermes logs --level WARNING --since 1h   # Warnings from the last hour
hermes logs --session abc123         # Filter by session ID substring
hermes logs errors --since 30m -f    # Follow errors.log from 30m ago
hermes logs list                     # List all log files with sizes

Los archivos de log se encuentran en ~/.hermes/logs/:⁶ - agent.log — toda la actividad del agente (llamadas a API, envío de tools, ciclo de vida de sesiones, INFO+) - errors.log — solo advertencias y errores (un subconjunto filtrado de agent.log) - gateway.log — actividad del gateway de mensajería (conexiones de plataformas, envío, webhooks)

La rotación es automática mediante RotatingFileHandler de Python: busca agent.log.1, agent.log.2, etc.⁶

hermes doctor — Diagnósticos

hermes doctor [--fix] es el primer comando que debes ejecutar cuando algo no funciona. Comprueba la validez de la configuración, la presencia de dependencias, la disponibilidad de claves de API, el estado de los servicios y puede intentar reparaciones automáticas con --fix.⁶

Para compartir diagnósticos con otra persona, usa hermes dump: genera un resumen compacto de texto sin formato con las claves de API censuradas, listo para pegar en un issue de GitHub o un hilo de Discord.⁶

Comandos con barra

Los comandos con barra se ejecutan dentro de una sesión de chat activa (CLI o una plataforma de mensajería). Se envían desde un COMMAND_REGISTRY compartido en hermes_cli/commands.py, por lo que la mayoría de los comandos funcionan de forma idéntica en todas las superficies.⁹

Control de sesión

Configuración y modelo

El comando /model es la herramienta principal para cambiar de proveedor a mitad de sesión:⁹

/model                              # Show current model and options
/model claude-sonnet-4              # Switch model (auto-detect provider)
/model zai:glm-5                    # Switch provider:model
/model custom:qwen-2.5              # Use model on custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Named custom provider
/model openrouter:anthropic/claude-sonnet-4   # Back to cloud

v0.19.0 agrega /model --once —una anulación de modelo para un turno que vuelve automáticamente a tu modelo anterior después de la respuesta.²⁵

Herramientas, Skills e información

Comandos con barra de Skills dinámicos

Cada skill instalado se expone automáticamente como un comando con barra:⁹

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/excalidraw       # Just the skill name loads it and lets the agent ask what you need

Desde v0.19.0, las invocaciones de slash-skill se acumulan: /skill-a /skill-b do XYZ carga ambos skills en orden en un solo turno, con autocompletado y texto fantasma para los nombres encadenados.²⁵

También puedes definir comandos rápidos en config.yaml que asignan un nombre corto a un prompt más largo:⁹

quick_commands:
  review: "Review my latest git diff and suggest improvements"
  deploy: "Run the deployment script at scripts/deploy.sh and verify the output"
  morning: "Check my calendar, unread emails, and summarize today's priorities"

Luego escribe /review, /deploy o /morning en CLI.

Coincidencia por prefijo

Los comandos admiten coincidencia por prefijo: al escribir /h se resuelve como /help, y /mod se resuelve como /model. Cuando un prefijo es ambiguo, gana el primer registro según el orden del registro. Los nombres completos de los comandos y los alias registrados siempre tienen prioridad sobre las coincidencias por prefijo.⁹

Comandos específicos de mensajería

Algunos comandos solo funcionan en plataformas de mensajería (Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant):⁹

• /status — muestra información de la sesión
• /sethome (alias /set-home) — marca el chat actual como inicio de la plataforma
• /approve [session|always] — aprueba un comando peligroso pendiente
• /deny [reason] — rechaza un comando peligroso pendiente. Desde v0.19.0, /deny <reason> transmite tu motivo de rechazo al agente para que corrija el rumbo en lugar de reintentar a ciegas²⁵
• /update — actualiza Hermes Agent a la versión más reciente
• /commands [page] — explora todos los comandos y skills (paginados)

Y algunos son exclusivos de CLI: /skin, /tools, /toolsets, /browser, /config, /cron, /skills, /platforms, /paste, /statusbar, /plugins.⁹

Herramientas y Toolsets

Hermes incluye un amplio registro de herramientas integradas que cubre búsqueda web, automatización de navegador, ejecución de terminal, edición de archivos, memoria, delegación, entrenamiento de RL, entrega de mensajes, integración con Home Assistant y más.¹⁰ Las herramientas se organizan en toolsets lógicos que pueden activarse o desactivarse para cada plataforma.

Categorías generales

Los nombres de toolsets comunes incluyen web, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant y rl.¹⁰

Gestión de herramientas

hermes chat --toolsets "web,terminal"       # Use specific toolsets
hermes tools                                # Interactive per-platform tool config
hermes tools --summary                      # Print enabled-tools summary

Las herramientas también pueden activarse o desactivarse durante una sesión mediante /tools disable <name> y /tools enable <name>, lo que reinicia la sesión para que el nuevo conjunto de herramientas surta efecto.⁹

Backends de terminal

La herramienta de terminal puede ejecutar comandos en seis entornos distintos:¹⁰

Cambia de backend con hermes config set terminal.backend <name> o en config.yaml:

terminal:
  backend: docker      # or: local, ssh, singularity, modal, daytona
  cwd: "."             # Working directory
  timeout: 180         # Command timeout in seconds

Backend SSH (recomendado para la seguridad: el agente no puede modificar su propio código):¹⁰

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Backend Docker:

terminal:
  backend: docker
  docker_image: python:3.11-slim

Recursos del contenedor (se aplican a docker, singularity, modal y daytona):¹⁰

terminal:
  container_cpu: 1
  container_memory: 5120          # MB (default 5GB)
  container_disk: 51200           # MB (default 50GB)
  container_persistent: true      # Persist filesystem across sessions

Con container_persistent: true, los paquetes instalados, archivos y la configuración se conservan entre sesiones.¹⁰

Todos los backends de contenedor se ejecutan con refuerzo de seguridad: sistema de archivos raíz de solo lectura (Docker), todas las capacidades de Linux se eliminan salvo DAC_OVERRIDE, CHOWN y FOWNER, sin escalamiento de privilegios, límites de PID (256 procesos), aislamiento completo de espacios de nombres y espacio de trabajo persistente mediante volúmenes.¹⁰

Procesos en segundo plano

La herramienta de terminal admite ejecución en segundo plano con administración explícita de procesos:¹⁰

terminal(command="pytest -v tests/", background=true)
# Returns: {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                            # Show all running processes
process(action="poll", session_id="proc_abc123")  # Check status
process(action="wait", session_id="proc_abc123")  # Block until done
process(action="log", session_id="proc_abc123")   # Full output
process(action="kill", session_id="proc_abc123")  # Terminate
process(action="write", session_id="proc_abc123", data="y")  # Send input

El modo PTY (pty=true) habilita herramientas interactivas de CLI como Codex y Claude Code.¹⁰

Sudo

Si un comando necesita sudo, Hermes solicita tu contraseña (almacenada en caché durante la sesión). También puedes establecer SUDO_PASSWORD en ~/.hermes/.env.¹⁰

Kanban multiagente (v0.13.0+)

v0.13.0 convierte la colaboración multiagente en una primitiva de primera clase: un tablero Kanban duradero que rastrea tareas, estado e identidad de los workers entre agentes y reinicios.¹⁸ El tablero es lo que hace que un enjambre de workers de Hermes realmente termine el trabajo, en lugar de quedarse estancado en transferencias fallidas.

El tablero Kanban se combina naturalmente con /goal (bucle Ralph de objetivo bloqueado) para el lado del objetivo y con la herramienta existente delegate_task para la semántica de generación. El resultado es un patrón de enjambre donde cada agente comparte una única fuente de verdad sobre qué hacer después, quién lo está haciendo y qué está bloqueado.

¿Qué es un enjambre de Hermes?

Un enjambre consiste en varios workers de Hermes que se ejecutan en paralelo contra un tablero Kanban compartido. No es un subsistema independiente que debas activar: es lo que el tablero hace posible. El tablero proporciona lo único que los agentes paralelos no pueden proporcionarse por sí mismos: una respuesta única y autorizada a ¿qué debería retomar después y alguien ya está trabajando en ello?

v0.15.0 promovió esto de patrón a topología compatible, añadiendo una topología de enjambre para la coordinación de workers en paralelo, descomposición automática de un objetivo de alto nivel en subtareas, anulaciones de modelo por tarea, tareas programadas y gestión de worktrees para que los workers en paralelo no entren en conflicto dentro del mismo checkout.²⁸

La forma práctica: dale un objetivo al enjambre, deja que la descomposición automática lo divida en tareas del tablero y permite que los workers las reclamen, ejecuten y devuelvan resultados. El presupuesto de reintentos es por tarea (max_retries), por lo que una subtarea frágil no consume la tolerancia de toda la ejecución. Como el tablero es duradero, un enjambre sobrevive a los reinicios: los workers vuelven a conectarse y reanudan el trabajo con el mismo estado.

Un enjambre es tan bueno como su descomposición. El tablero coordina a los workers; no convierte un objetivo mal dividido en uno bueno. Las tareas que comparten estado oculto seguirán entrando en conflicto, tengan worktrees o no.

Sistema de Skills

Los skills son documentos de conocimiento bajo demanda que el agente puede cargar cuando los necesita. Siguen un patrón de divulgación progresiva para minimizar el uso de tokens y son compatibles con el estándar abierto de agentskills.io.¹¹

Todos los skills se encuentran en ~/.hermes/skills/ — el directorio principal y fuente de referencia. En una instalación nueva, los skills incluidos se copian desde el repositorio. Los skills instalados desde el Hub y los creados por el agente también se almacenan aquí.¹¹

Divulgación progresiva

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata                 (varies)
Level 2: skill_view(name, path)  → Specific reference file                 (varies)

El agente solo carga el contenido completo del skill cuando realmente lo necesita.¹¹

Formato de SKILL.md

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]      # Optional — restrict to OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]     # Conditional activation
    requires_toolsets: [terminal]    # Conditional activation
    config:                          # Config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

Activación condicional

Los skills pueden mostrarse u ocultarse según las herramientas que estén disponibles. Esto es especialmente útil para los skills de respaldo — alternativas gratuitas o locales que solo deberían aparecer cuando una herramienta prémium no está disponible:¹¹

Ejemplo: el skill integrado duckduckgo-search usa fallback_for_toolsets: [web]. Cuando tienes configurada FIRECRAWL_API_KEY, el toolset web está disponible y el agente usa web_search — el skill de DuckDuckGo permanece oculto. Sin la clave de API, el skill de DuckDuckGo aparece automáticamente como respaldo.¹¹

Skills gestionados por el agente

El agente puede crear, actualizar y eliminar sus propios skills mediante la herramienta skill_manage. Esta es la memoria procedimental del agente: cuando resuelve un flujo de trabajo no trivial, guarda el enfoque como un skill para reutilizarlo en el futuro.¹¹

Cuándo crea skills el agente:¹¹ - Después de completar correctamente una tarea compleja (más de 5 llamadas a herramientas) - Cuando encontró errores o callejones sin salida y halló el camino que funciona - Cuando el usuario corrigió su enfoque - Cuando descubrió un flujo de trabajo no trivial

Acciones:¹¹

Skill Hub

Explora, busca, instala y administra skills desde registros en línea:⁶¹¹

hermes skills browse                          # Browse all hub skills
hermes skills browse --source official        # Browse official optional skills
hermes skills search kubernetes               # Search all sources
hermes skills search react --source skills-sh # Search skills.sh directory
hermes skills inspect openai/skills/k8s       # Preview before installing
hermes skills install openai/skills/k8s       # Install with security scan
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check                           # Check for upstream updates
hermes skills update                          # Reinstall changed hub skills
hermes skills audit                           # Re-scan installed hub skills
hermes skills uninstall k8s
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo       # Add custom GitHub source

Fuentes integradas del hub:¹¹

Taps predeterminados de GitHub (explorables sin configuración): openai/skills, anthropics/skills, huggingface/skills, NVIDIA/skills, garrytan/gstack. La fuente claude-marketplace se eliminó en v0.20.0; browse-sh la reemplazó en la lista de fuentes.¹¹²⁴

Análisis de seguridad

Todos los skills instalados desde el hub pasan por un escáner de seguridad que verifica la exfiltración de datos, la inyección de prompts, los comandos destructivos, las señales de la cadena de suministro y otras amenazas.¹¹

Niveles de confianza:¹¹

--force puede anular los bloqueos de política no peligrosos para los skills de la comunidad. No anula un veredicto de análisis dangerous.¹¹

Directorios de skills externos

Puedes indicar a Hermes directorios de skills adicionales que se analizan junto con el local:¹¹

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

Las rutas admiten expansión de ~ y sustitución de variables de entorno ${VAR}. Los directorios externos son de solo lectura — cuando el agente crea o edita un skill, siempre escribe en ~/.hermes/skills/. La precedencia local gana si existe un nombre de skill en ambos lugares.¹¹

Memoria persistente

Hermes cuenta con memoria acotada y curada que persiste entre sesiones. La memoria del agente se compone de dos archivos, ambos almacenados en ~/.hermes/memories/:¹²

Ambos se insertan en el system prompt como una instantánea congelada al iniciar la sesión. El agente gestiona su propia memoria mediante la herramienta memory: add, replace o remove.¹²

Patrón de instantánea congelada: la inserción en el system prompt se captura una sola vez al inicio de la sesión y nunca cambia durante ella. Es intencional: preserva la caché de prefijo de LLM para mejorar el rendimiento. Los cambios realizados durante una sesión se guardan en disco de inmediato, pero no aparecen en el system prompt hasta la siguiente sesión.¹²

Qué guardar

Guarda esto (el agente lo hace de forma proactiva):¹² - Preferencias del usuario: “Prefiero TypeScript en lugar de JavaScript” → user - Datos del entorno: “Este servidor ejecuta Debian 12 con PostgreSQL 16” → memory - Correcciones: “No uses sudo para los comandos de Docker, el usuario está en el grupo docker” → memory - Convenciones: “El proyecto usa tabulaciones, líneas de 120 caracteres y docstrings estilo Google” → memory - Trabajo completado: “La base de datos se migró de MySQL a PostgreSQL el 2026-01-15” → memory

Omite esto:¹² - Información trivial u obvia - Datos fáciles de descubrir de nuevo - Volcados de datos sin procesar (demasiado grandes para la memoria) - Información efímera específica de la sesión - Información que ya está en archivos de contexto

Búsqueda de sesiones

Además de MEMORY.md y USER.md, el agente puede buscar en sus conversaciones anteriores mediante la herramienta session_search. Todas las sesiones de CLI y mensajería se almacenan en SQLite (~/.hermes/state.db) con búsqueda de texto completo FTS5. Las consultas devuelven conversaciones anteriores relevantes con resúmenes de Gemini Flash.¹²

Proveedores de memoria externos

Para disponer de memoria persistente más profunda que MEMORY.md y USER.md, Hermes incluye ocho plugins de proveedores de memoria externos: Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover y Supermemory.¹²

Los proveedores externos se ejecutan junto con la memoria integrada (nunca la reemplazan) y añaden capacidades como grafos de conocimiento, búsqueda semántica, extracción automática de datos y modelado de usuarios entre sesiones:⁶¹²

hermes memory setup         # Pick a provider and configure it
hermes memory status        # Check what's active
hermes memory off           # Disable external provider (built-in only)

Solo puede haber un proveedor externo activo a la vez. La memoria integrada siempre está activa.⁶

Reanudación automática de sesiones (v0.13.0+)

La v0.13.0 permite sobrevivir a interrupciones a mitad de la ejecución del agente. El gateway reanuda automáticamente las sesiones interrumpidas después de reiniciarse; los reinicios mediante /update preservan el estado de la sesión durante la actualización; y las recargas de archivos fuente durante el desarrollo mantienen activa la sesión en lugar de forzar una nueva.¹⁸ En la práctica, el trabajo prolongado del gateway y los trabajos impulsados por cron ya no restablecen su ventana de contexto cuando se reinicia el proceso.

Checkpoints v2 (v0.13.0+)

La persistencia de estado se reescribe en la v0.13.0 como un diseño de almacenamiento único con poda real, límites de seguridad para el disco y sin repositorios sombra huérfanos.¹⁸ El sistema de checkpoints anterior acumulaba estado en disco entre profiles de larga duración; el almacenamiento v2 establece un límite estricto para el espacio local de checkpoints y elimina la contabilidad duplicada que provocaba ese crecimiento. No se requiere ningún cambio de configuración visible para el usuario; la siguiente escritura de checkpoint utilizará la ruta v2.

Personalidad y SOUL.md

SOUL.md es la identidad principal de una instancia de Hermes. Ocupa la posición n.º 1 en el system prompt y reemplaza la identidad predeterminada codificada.¹³

Hermes crea automáticamente un SOUL.md predeterminado en ~/.hermes/SOUL.md (o $HERMES_HOME/SOUL.md para profiles personalizados). Los archivos existentes del usuario nunca se sobrescriben. Hermes solo carga SOUL.md desde HERMES_HOME: no busca en el directorio de trabajo actual. Esto hace que la personalidad sea predecible entre proyectos.¹³

Qué debe incluir SOUL.md

Úsalo para pautas duraderas de voz y personalidad:¹³ - tono - estilo de comunicación - nivel de franqueza - estilo de interacción predeterminado - qué evitar desde el punto de vista estilístico - cómo debe manejar Hermes la incertidumbre, el desacuerdo y la ambigüedad

Úsalo menos para:¹³ - instrucciones puntuales de un proyecto - rutas de archivos - convenciones del repositorio - detalles temporales del flujo de trabajo

Eso pertenece a AGENTS.md, no a SOUL.md.

SOUL.md frente a AGENTS.md

Esta es la distinción más importante en la gestión de identidad de Hermes:¹³

SOUL.md: identidad, tono, estilo, valores predeterminados de comunicación y comportamiento a nivel de personalidad.

AGENTS.md: arquitectura del proyecto, convenciones de programación, preferencias de herramientas, flujos de trabajo específicos del repositorio, comandos, puertos, rutas y notas de implementación.

Una regla útil: si debe acompañarte a todas partes, pertenece a SOUL.md. Si pertenece a un proyecto, pertenece a AGENTS.md.¹³

Personalidades integradas

Hermes incluye personalidades integradas a las que puedes cambiar con /personality:¹³

Personalidades personalizadas en config.yaml:¹³

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

Luego cambia con /personality codereviewer.

SOUL.md frente a /personality

SOUL.md es la voz base. /personality es una superposición a nivel de sesión.¹³ Mantén un SOUL.md predeterminado pragmático y usa /personality teacher para una conversación de tutoría o /personality creative para una lluvia de ideas.

Nous Tool Gateway (v0.10.0+)

Desde Hermes Agent v0.10.0 (2026-04-16), los suscriptores de pago de Nous Portal obtienen acceso administrado a un conjunto seleccionado de herramientas mediante sus credenciales existentes de Portal, sin claves API adicionales que gestionar.³⁰ El propio CLI de Hermes sigue teniendo licencia MIT y siendo completamente de código abierto. Lo que cambió es que tu autenticación de Portal ahora desbloquea más que la inferencia de modelos.

Qué incluye el gateway

Cómo funciona

El gateway es opcional para cada herramienta mediante un nuevo campo de configuración use_gateway. Si tienes credenciales de Portal en hermes auth y habilitas el gateway para una herramienta, las llamadas de esa herramienta se enrutan a través de Portal. De lo contrario, se usa tu clave API directa (si existe).

# config.yaml — per-tool gateway opt-in
tools:
  web_search:
    provider: firecrawl
    use_gateway: true          # route via Nous Portal subscription
  image_generation:
    provider: fal
    use_gateway: true

Precedencia en tiempo de ejecución: cuando el gateway está disponible y una herramienta tiene use_gateway: true, Hermes prefiere el gateway incluso si también tienes configurada una clave API directa. Esto importa para la facturación: las llamadas al gateway consumen tu suscripción de Portal, no el saldo de tu clave API directa.

Habilitar el gateway

hermes model                      # select Nous Portal (OAuth flow)
hermes tools                      # per-platform tool picker integrates gateway tools
hermes status                     # confirms gateway/subscription detection

La suscripción se detecta automáticamente a partir de las credenciales de Portal OAuth que ya tienes en hermes auth; no hay un paso de inicio de sesión independiente. Desde v0.19.0, también puedes administrar la suscripción desde una sesión: /subscription muestra tu plan y la asignación restante, previsualiza exactamente cuánto cuesta una mejora o cuándo entra en vigor una reducción de plan, y aplica el cambio con avisos de cambios programados y una opción para deshacer; /topup agrega crédito. La aplicación de escritorio cuenta con una pestaña equivalente de configuración de facturación.²⁵

Precios y acceso

Los precios y nombres de los niveles se publican en la página de precios de Nous Portal (https://portal.nousresearch.com/pricing). Esta guía no enumera los niveles porque son responsabilidad del producto Portal, no del CLI de Hermes, y cambian independientemente de las versiones de Hermes. Regístrate en https://portal.nousresearch.com/ y consulta la página de precios para conocer los niveles actuales.

Aviso de desuso

• La variable de entorno HERMES_ENABLE_NOUS_MANAGED_TOOLS se eliminó en v0.10.0. Las herramientas administradas ahora se habilitan mediante el campo de configuración use_gateway por herramienta y dependen del estado de tu suscripción de Portal.³⁰

Contexto: lo que esta versión no es

El CLI de Hermes Agent no está restringido por una suscripción. El proyecto sigue teniendo licencia MIT; todas las funciones principales (CLI, skills, memoria, messaging gateway, cron, MCP, panel local, BYOK para todos los proveedores) funcionan de extremo a extremo sin pagar a nadie. v0.10.0 añade una vía práctica para quienes ya pagan por Nous Portal; no elimina nada de la opción gratuita.

Messaging Gateway

Hermes puede ejecutarse como un proceso de gateway de larga duración que se conecta a 28 plataformas de mensajería desde un único proceso de gateway: Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin (WeChat), BlueBubbles (iMessage), QQBot, Microsoft Teams, Tencent Yuanbao, Google Chat, LINE, SimpleX Chat y un adaptador Webhook genérico.^329171819 v0.9.0 añadió iMessage mediante BlueBubbles (registro automático de webhook, asistente de configuración y resistencia ante fallos) y compatibilidad nativa con WeChat mediante iLink Bot API con modo de callback de WeCom para aplicaciones empresariales.¹⁶ v0.11.0 añadió QQBot.²⁹ v0.12.0 añadió Microsoft Teams y Tencent Yuanbao.¹⁷ v0.13.0 añadió Google Chat como la vigésima plataforma, aprovechando la misma arquitectura de adaptadores conectables; IRC y Microsoft Teams también se migraron al nuevo patrón de adaptadores con hooks genéricos de plugins env_enablement_fn / cron_deliver_env_var.¹⁸ v0.14.0 añade LINE y SimpleX Chat y completa la pila de Microsoft Teams de extremo a extremo con autenticación de Graph, receptor de webhook, tiempo de ejecución del pipeline y entrega saliente.¹⁹ v0.17.0 (19 de junio de 2026) añade iMessage sin relay mediante Photon Spectrum (autenticación de dispositivo OAuth con hermes photon login, sin necesidad de relay de Mac/BlueBubbles), el adaptador oficial de WhatsApp Business Cloud API (que reemplaza el requisito de un proceso puente), grupos y adjuntos nativos de SimpleX, y Raft como plugin de plataforma incluido.²¹

Configuración

hermes gateway setup                # Interactive platform configuration
hermes gateway install              # Install as user service (systemd/launchd)
hermes gateway start                # Start the installed service
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes gateway run                  # Run in foreground (debugging)

La configuración interactiva te guía para conectar cada plataforma: tokens API, IDs de bots, asignaciones de canales y listas de permitidos.⁶

Cómo fluyen los mensajes

Según la documentación de arquitectura upstream:³

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

Todas las plataformas de mensajería usan el mismo ciclo de conversación AIAgent que el CLI. Por eso los comandos slash funcionan de forma idéntica en ambos lugares y un trabajo cron programado en Telegram puede entregar su resultado a Discord: la diferencia entre plataformas está únicamente en el borde.³

v0.19.0 añade enrutamiento de mensajes basado en profiles y entrega duradera. Un único gateway multiplexado que comparte un token de bot puede enrutar guilds, canales o hilos específicos a distintos profiles, cada uno con configuración, skills, memoria y secretos completamente aislados, mediante una anulación de GATEWAY_MULTIPLEX_PROFILES; además, una serie de mejoras de robustez impide que un profile mal configurado derribe todo el gateway. Internamente, el índice de enrutamiento se trasladó a state.db (sessions.json ahora es un espejo heredado opcional), y las respuestas finales se registran en un libro mayor duradero de obligaciones de entrega alrededor del envío de la plataforma: una respuesta terminada que coincide con un fallo del gateway se reentrega en el siguiente inicio en lugar de perderse silenciosamente.²⁵

Autorización y vinculación de usuarios

hermes pairing list                    # Show pending and approved users
hermes pairing approve <platform> <code>
hermes pairing revoke <platform> <user-id>
hermes pairing clear-pending

Los códigos de vinculación evitan que desconocidos al azar hablen con tu gateway. Un usuario envía un código de vinculación desde su plataforma de mensajería; lo apruebas con hermes pairing approve; a partir de entonces queda autorizado.⁶

Tareas programadas (Cron)

Hermes cuenta con un sistema cron de primera clase en el que los trabajos son tareas de agentes, no comandos de shell. Cada trabajo programado se ejecuta mediante un AIAgent nuevo con el prompt configurado, skills adjuntos opcionales, y entrega resultados a cualquier plataforma:³⁶

hermes cron list
hermes cron create --prompt "Check HN for AI news and summarize" --schedule "0 9 * * *" --deliver telegram
hermes cron edit <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron run <id>         # Trigger now on the next tick
hermes cron remove <id>
hermes cron status           # Check if scheduler is running
hermes cron tick             # Run due jobs once and exit

O crea uno de forma conversacional dentro de un chat de mensajería:

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

El agente configurará el trabajo cron mediante sus herramientas. Los trabajos persisten en JSON y sobreviven a los reinicios.³

Integración de MCP

Hermes admite Model Context Protocol tanto como cliente como servidor:⁶

Como cliente: conecta Hermes a servidores externos de MCP para ampliar su superficie de herramientas:

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection

O manualmente en config.yaml:¹⁴

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Desde v0.19.0, las herramientas de MCP se exponen al modelo siguiendo la convención de nombres mcp__server__tool: cada nombre de herramienta incluye el nombre de su servidor, por lo que dos servidores que expongan la misma herramienta ya no entran en conflicto; además, las notificaciones de registro del servidor MCP aparecen en agent.log.²⁵

Como servidor: expón conversaciones de Hermes a otros agentes:

hermes mcp serve
hermes mcp serve -v    # Verbose

Compresión de contexto

Hermes comprime automáticamente las conversaciones largas para mantenerse dentro de la ventana de contexto de tu modelo. El resumidor de compresión es una llamada LLM independiente; puedes dirigirla a cualquier proveedor o endpoint.⁴

compression:
  enabled: true
  threshold: 0.50                           # Compress at this % of context limit
  target_ratio: 0.20                        # Fraction to preserve as recent tail
  protect_last_n: 20                        # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"                  # "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                    # Custom OpenAI-compatible endpoint

Opciones de proveedor:⁴

summary_model debe admitir una longitud de contexto al menos tan grande como la de tu modelo principal, ya que recibe toda la sección intermedia de la conversación para comprimirla.⁴

Advertencias de presión de presupuesto

Cuando el agente trabaja en una tarea compleja con muchas llamadas a herramientas, puede agotar su presupuesto de iteraciones (predeterminado: 500 turnos desde la v0.20.0, antes 90) sin darse cuenta. La presión de presupuesto advierte automáticamente al modelo:⁴

Tiempos de espera de streaming

La conexión de streaming de LLM tiene dos capas de tiempo de espera que se ajustan automáticamente para proveedores locales (localhost, IP de LAN):⁴

El tiempo de espera de lectura del socket se eleva a 30 minutos para endpoints locales porque los LLM locales pueden tardar minutos en el prefill de contextos grandes antes de producir el primer token.⁴

Panel web local (v0.9.0+)

Un panel basado en navegador para administrar tu Hermes Agent localmente. Configura ajustes, supervisa sesiones, explora skills y administra tu gateway sin tocar archivos de configuración ni la terminal.¹⁶ Inícialo con hermes dashboard. Es la ruta de incorporación más sencilla para usuarios nuevos que prefieren una GUI.

Supervisión de procesos en segundo plano (v0.9.0+)

watch_patterns te permite configurar patrones para supervisar la salida de procesos en segundo plano y recibir notificaciones en tiempo real cuando coincidan.¹⁶ Supervisa errores, espera eventos específicos (“listening on port”) o vigila registros de compilación, todo sin hacer polling. Combinado con notify_on_complete de la v0.8.0 (que notifica al completarse una tarea en segundo plano), Hermes ahora cuenta con una capa completa de observabilidad de procesos en segundo plano.¹⁵

Context engine intercambiable (v0.9.0+)

La administración del contexto ahora es un componente intercambiable mediante hermes plugins. Sustituye context engines personalizados que controlan lo que ve el agente en cada turno: filtrado, resumen o inyección de contexto específica del dominio.¹⁶ Esto desacopla la estrategia de contexto del bucle principal del agente, lo que permite personalizar el contexto por proyecto o dominio.

Respaldo y restauración (v0.9.0+)

hermes backup crea un archivo completo de tu configuración, sesiones, skills y memoria. hermes import restaura desde un archivo de respaldo.¹⁶ Úsalo para migrar entre computadoras, crear instantáneas antes de cambios importantes o compartir una configuración confiable con tus compañeros de equipo.

Compatibilidad con Termux / Android (v0.9.0+)

Hermes se ejecuta de forma nativa en Android mediante Termux. Las rutas de instalación adaptadas, las optimizaciones de TUI para pantallas móviles, la compatibilidad con backend de voz y el comando /image funcionan en el dispositivo.¹⁶

Refuerzo de seguridad (v0.13.0+)

La v0.13.0 cerró 8 problemas de seguridad P0 y cambió un valor predeterminado a favor del usuario.¹⁸ La v0.14.0 continúa con otros 12 cierres P0 y 50 P1, incluidos el refuerzo contra fuerza bruta de sudo / sudo-stdin, correcciones para omitir comandos peligrosos, sanitización de errores de herramientas antes de reinyectarlos al modelo, autenticación de API para plugins del panel, cobertura SSRF de skills-hub y análisis de avisos de cadena de suministro durante la instalación.¹⁹

Si mantienes una implementación de Hermes, trata la v0.13.0 y la v0.14.0 como actualizaciones relevantes para la seguridad, no solo como lanzamientos de funciones. La v0.13.0 cierra la omisión entre guilds de Discord y dos ventanas TOCTOU; la v0.14.0 añade otra ronda de refuerzo para el manejo de sudo, la reinyección de errores de herramientas, los API de plugins, SSRF de skills-hub y avisos de dependencias.

Arquitectura para profesionales

Esta sección es para quienes quieren entender qué ocurre bajo el capó para poder depurarlo, ampliarlo o razonar sobre el rendimiento. Es una síntesis de la documentación de arquitectura upstream.³

Puntos de entrada → AIAgent

Cada punto de entrada en Hermes termina llamando a AIAgent.run_conversation():

┌──────────────────────────────────────────────────────────────────┐
│                        Entry Points                              │
│                                                                  │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)  │
│  Batch Runner    API Server                  Python Library     │
└──────────┬──────────────┬───────────────────────┬────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                       │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │ Prompt      │  │ Provider     │  │ Tool         │             │
│  │ Builder     │  │ Resolution   │  │ Dispatch     │             │
│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘             │
│         │                │                 │                    │
│  ┌──────┴───────┐ ┌──────┴───────┐  ┌──────┴───────┐             │
│  │ Compression  │ │ 3 API Modes  │  │ Tool Registry│             │
│  │ & Caching    │ │ chat_compl   │  │ 47 tools     │             │
│  │              │ │ codex_resp   │  │ 20 toolsets  │             │
│  │              │ │ anthropic    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

Diagrama adaptado de la documentación de arquitectura upstream.³

«47 tools / 20 toolsets» frente a «28 tools» en tu banner. El conteo de «47 tools» es el registro total de tools del repositorio upstream: cada tool cuyo código fuente incluye Hermes, en todos los toolsets. Tu CLI en ejecución mostrará un número menor en su banner de inicio (la instalación con la que verifiqué esta guía informa 28 tools / 89 skills). No es un error. Muchos toolsets son opcionales y deben habilitarse explícitamente en config.yaml, bajo toolsets:: adaptadores de plataformas de mensajería, automatización de navegador, herramientas de scraping más pesadas, etc. El total del registro es «lo que está disponible»; el número del banner es «lo que está habilitado en tu profile actual». Consulta qué toolsets están activos con hermes tools --list y habilita o deshabilita toolsets individuales con el bloque toolsets: en ~/.hermes/config.yaml (o con /tools list / /tools enable <name> / /tools disable <name> dentro de una sesión en ejecución; eliminar un tool provoca un reinicio de sesión para que el agente reconstruya su manifiesto de tools).

Los tres modos API

Hermes abstrae las diferencias entre providers en tres modos API, seleccionados automáticamente durante la ejecución:³

El resolvedor runtime_provider.py asigna tuplas de (provider, model) a (api_mode, api_key, base_url) para más de 18 providers, y gestiona flujos de OAuth, pools de credenciales y resolución de alias.³

Flujo de datos en una sesión de CLI

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

De la página de arquitectura upstream.³

Orden de ensamblaje del prompt

La pila de prompts incluye:¹³

1. SOUL.md (identidad del agente, o alternativa integrada si no está disponible)
2. Guía de comportamiento adaptada a tools
3. Contexto de memoria/usuario (MEMORY.md, USER.md)
4. Guía de skills
5. Archivos de contexto (AGENTS.md, .cursorrules)
6. Marca de tiempo
7. Indicaciones de formato específicas de la plataforma
8. Capas opcionales sobre el system prompt, como /personality

SOUL.md es la base: todo lo demás se construye sobre ella.¹³

Almacenamiento de sesiones

Almacenamiento de sesiones basado en SQLite con búsqueda de texto completo FTS5. Las sesiones tienen seguimiento de linaje (relación padre/hijo entre compresiones), aislamiento por plataforma y escrituras atómicas con gestión de contención.³

Sistema de plugins

Tres fuentes de descubrimiento: ~/.hermes/plugins/ (usuario), .hermes/plugins/ (proyecto) y puntos de entrada de pip. Los plugins registran tools, hooks y comandos de CLI mediante un contexto API. Los providers de memoria son un tipo especializado de plugin bajo plugins/memory/.³

hermes plugins                       # Interactive enable/disable UI
hermes plugins install <repo>        # Install from Git URL or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list

Principios de diseño

De la página de arquitectura upstream:³

Migración desde OpenClaw

Hermes Agent es el sucesor de OpenClaw. Si estás migrando desde una instalación existente de OpenClaw:⁶⁵

hermes claw migrate --dry-run                    # Preview what would be migrated
hermes claw migrate --preset full                # Full migration including API keys
hermes claw migrate --preset user-data --overwrite   # User data only, no secrets
hermes claw migrate --source /custom/path        # Non-default OpenClaw location

hermes claw migrate lee de ~/.openclaw de forma predeterminada (también detecta automáticamente los directorios heredados ~/.clawdbot y ~/.moldbot) y escribe en ~/.hermes.⁶

Importado directamente (más de 30 categorías): SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills de 4 directorios de origen, modelo predeterminado, providers personalizados, servidores MCP, tokens y listas de permitidos de plataformas de mensajería (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), valores predeterminados del agente (esfuerzo de razonamiento, compresión, demora humana, zona horaria, sandbox), políticas de reinicio de sesión, reglas de aprobación, configuración de TTS, ajustes del navegador, ajustes de tools, tiempo de espera de exec, lista de permitidos de comandos, configuración de gateway y claves API de 3 fuentes.⁶

Archivado para revisión manual: trabajos cron, plugins, hooks/webhooks, backend de memoria (QMD), configuración del registro de skills, UI/identidad, registro, configuración multiagente, enlaces de canales, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

La resolución de claves API verifica tres fuentes en orden de prioridad: valores de configuración → ~/.openclaw/.env → auth-profiles.json.⁶

Solución de problemas

“No inference provider configured. Run ‘hermes model’ to choose a provider and model”

El primer error que aparece en toda instalación nueva: Hermes aún no tiene un proveedor resuelto. Significa exactamente lo que dice: ninguna de las tres rutas de autenticación ha generado un proveedor utilizable. Ejecuta:

hermes model

El selector interactivo recorre todos los proveedores compatibles, incluidos los flujos de código de dispositivo de OAuth (Nous Portal, GitHub Copilot, Anthropic, OpenAI Codex) y endpoints personalizados para servidores autoalojados. Si esperabas que ya hubiera un proveedor configurado, hermes doctor muestra qué credenciales puede ver Hermes realmente; las causas habituales son una clave de API configurada en el lugar incorrecto (debe estar en .env o configurarse mediante hermes config set, no en el perfil de tu shell), una credencial de OAuth vencida en ~/.hermes/auth.json, o un endpoint personalizado de config.yaml que perdió su base_url. Las rutas de autenticación se explican en profundidad en Autenticación y proveedores.²⁷

“Clave de API no configurada”

Ejecuta hermes model para configurar el proveedor de forma interactiva, o hermes config set OPENROUTER_API_KEY your_key. El comando hermes doctor te indicará exactamente qué claves faltan.⁷

“Context limit: 2048 tokens” al iniciar (modelos locales)

Hermes detecta automáticamente la longitud de contexto desde el endpoint /v1/models de tu servidor, pero muchos servidores locales informan valores predeterminados bajos. Configúrala explícitamente en config.yaml:²

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

Las llamadas a herramientas aparecen como texto en lugar de ejecutarse

Tu servidor no tiene habilitada la llamada a herramientas, o el modelo no la admite a través de la implementación del servidor.²

Las respuestas se cortan a mitad de la oración

Hay dos causas posibles:²

1. Límite de salida bajo (max_tokens) en el servidor: SGLang usa de forma predeterminada 128 tokens por respuesta. Configura --default-max-tokens en el servidor o model.max_tokens en config.yaml.
2. Agotamiento del contexto: el modelo llenó su ventana de contexto. Aumenta model.context_length o habilita la compresión de contexto en Hermes.

“Connection refused” desde WSL2 hacia un servidor de modelos alojado en Windows

WSL2 usa un adaptador de red virtual con su propia subred: localhost dentro de WSL2 se refiere a la máquina virtual Linux, no al host de Windows. Tienes dos opciones:²

Red en espejo (Windows 11 22H2+): edita %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

Después ejecuta wsl --shutdown y reinicia. Ahora localhost funciona bidireccionalmente.

Alternativa con la IP del host (Windows anteriores): obtén la IP del host de Windows desde WSL2 y úsala en lugar de localhost:

ip route show | grep -i default | awk '{ print $3 }'
# Use that IP as the base_url host

También necesitas que el servidor de modelos se vincule a 0.0.0.0, no a 127.0.0.1: configura OLLAMA_HOST=0.0.0.0 para Ollama, agrega --host 0.0.0.0 para llama-server/SGLang o habilita “Serve on Network” en LM Studio.²

¿Dónde está todo?

hermes status y hermes dump son tus aliados aquí. hermes logs list muestra todos los archivos de registro con sus tamaños. hermes config path imprime la ubicación del archivo de configuración. hermes config env-path imprime la ubicación de .env.⁶

Preguntas frecuentes

¿Cuál es la diferencia entre Hermes Agent y Claude Code?

Claude Code es el CLI oficial de Anthropic, limitado a los modelos de Anthropic. Hermes Agent es un framework de agentes de código abierto de Nous Research que funciona con cualquier proveedor compatible con OpenAI: Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Hugging Face, Google o tu propio endpoint autoalojado.¹² Hermes también incluye un gateway de mensajería para Telegram/Discord/Slack/WhatsApp/Signal que Claude Code no tiene.

¿Puedo usar Hermes con una clave de API de Anthropic?

Sí. Hay tres formas:²

1. Configura ANTHROPIC_API_KEY en ~/.hermes/.env y ejecuta hermes chat --provider anthropic --model claude-sonnet-4-6
2. Ejecuta hermes model y selecciona Anthropic: Hermes usará el almacén de credenciales de Claude Code cuando esté disponible
3. Configura un ANTHROPIC_TOKEN manual (token de configuración o token de OAuth) como alternativa

La opción 2 es preferible si ya usas Claude Code en la misma computadora: mantiene actualizables las credenciales actualizables de Claude.

¿Cómo cambio de proveedor sin perder mi conversación?

Usa /model provider:model dentro de una sesión. El historial de conversación, la memoria y las skills se conservan:⁹

/model zai:glm-5
/model openrouter:anthropic/claude-sonnet-4
/model custom:local:qwen-2.5

Configuré Anthropic, pero vision/web/compression no funcionan

Estás usando la alternativa de modelo auxiliar. La visión, el resumen web, la compresión y otras tareas secundarias usan un LLM auxiliar independiente; de forma predeterminada, Gemini Flash mediante detección automática (OpenRouter → Nous → Codex). Si ninguno de ellos está configurado y solo tienes Anthropic configurado, estas funciones se degradan silenciosamente.⁴

Solución: agrega una OPENROUTER_API_KEY para tareas auxiliares o reconfigura las ranuras auxiliares para usar tu proveedor principal. Ten en cuenta que la compresión de contexto vive en su propio bloque superior compression: y recibe summary_provider, no auxiliary.compression.provider: la ranura auxiliary.compression solo expone un timeout. Solución completa:

auxiliary:
  vision:      { provider: "main" }
  web_extract: { provider: "main" }

compression:
  summary_provider: "main"

¿Cuál es la diferencia entre SOUL.md y AGENTS.md?

SOUL.md es la identidad de tu agente: tono, estilo y valores predeterminados de comunicación. Se encuentra en ~/.hermes/SOUL.md y te acompaña a todas partes. AGENTS.md es específico del proyecto: arquitectura, convenciones, comandos y rutas, y se encuentra en el directorio de tu proyecto.¹³ Si debe acompañarte a todas partes, usa SOUL.md. Si pertenece a un proyecto, usa AGENTS.md.

¿Cómo ejecuto varias instancias de Hermes en paralelo?

Con profiles. Cada profile obtiene su propio HERMES_HOME, configuración, memoria, sesiones y PID de gateway:⁶

hermes profile create work --clone
hermes profile use work                 # Sticky default
hermes -p work chat -q "..."            # One-off without switching
hermes profile alias work --name h-work # Wrapper script

¿Hermes admite LLMs locales?

Sí, mediante la ruta de endpoint personalizado. Hermes funciona con cualquier servidor compatible con OpenAI: Ollama, vLLM, SGLang, llama.cpp/llama-server, LM Studio, LocalAI, Jan o el tuyo propio.² Consulta Endpoints personalizados y autoalojados para conocer la configuración de cada servidor.

¿Por qué mi banner de inicio muestra menos herramientas de las que la guía dice que tiene Hermes?

La guía cita 47 herramientas / 20 toolsets del registro de arquitectura upstream: es el total completo de herramientas cuyo código fuente Hermes incluye en todos los toolsets. Tu instalación en ejecución muestra un número menor en el banner (la instalación de referencia usada para esta guía informa 28 herramientas) porque Hermes solo habilita el conjunto predeterminado de toolsets al iniciar. Muchos toolsets son opcionales: los adaptadores del gateway de mensajería, la automatización del navegador, las pilas de scraping más exigentes y varias integraciones especializadas deben incluirse explícitamente en toolsets: de ~/.hermes/config.yaml antes de cargarse. Total del registro = “lo que está disponible si lo habilitas”. Total del banner = “lo que realmente cargó tu profile actual”. Usa hermes tools --list para ver qué toolsets están activos y cuáles están disponibles, pero deshabilitados. Activa o desactiva toolsets individuales en tiempo de ejecución con /tools enable <name> y /tools disable <name> (deshabilitarlos provoca un reinicio de sesión para que el agente reconstruya su manifiesto de herramientas con la nueva forma).

¿Cómo gestiona Hermes la alternativa de modelo cuando falla mi proveedor principal?

Configura un bloque fallback_model en config.yaml:²

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

Cuando el principal falla (límite de tasa, error del servidor o fallo de autenticación), Hermes cambia a la alternativa a mitad de sesión sin perder el historial de conversación. Se activa como máximo una vez por sesión.

¿El agente puede mejorar sus propias skills con el tiempo?

Sí: esa es la parte de “automejora” de Hermes Agent. El agente puede crear, actualizar y eliminar skills mediante la herramienta skill_manage. Cuando resuelve un flujo de trabajo no trivial, guarda el enfoque como una skill para reutilizarlo en el futuro.¹¹ El agente crea skills después de tareas complejas (más de 5 llamadas a herramientas), cuando encuentra errores y descubre la ruta que funciona, cuando corriges su enfoque o cuando descubre un flujo de trabajo no trivial.

¿Existe una integración con IDE?

Sí: Hermes puede ejecutarse como un servidor ACP (Agent Client Protocol) para VS Code, Zed y JetBrains:⁶

pip install -e '.[acp]'
hermes acp

Registro de cambios

Referencias