Hermes Agent: la referencia para profesionales (2026)

TL;DR: Hermes Agent es un agente de AI open-source que se mejora a sí mismo, creado por Nous Research. Funciona como CLI y como gateway de mensajería multiplataforma, almacena una identidad duradera y memoria persistente en disco, agrega skills que mejoran con el uso y trabaja con cualquier proveedor LLM compatible con OpenAI: Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok o tu propio endpoint autoalojado.¹²¹⁹ A partir de v0.14.0 (16 de mayo de 2026), Hermes agrega SuperGrok OAuth con contexto de 1M en grok-4.3, un proxy local compatible con OpenAI para proveedores OAuth (hermes proxy), x_search como función de primera clase, soporte de instalación desde PyPI, instalación diferida de dependencias, 22 plataformas de mensajería con LINE y SimpleX Chat, /handoff, diagnósticos semánticos LSP después de escrituras, video_generate unificado, computer_use mediante cua-driver para proveedores que no son Anthropic, beta nativa para Windows y el cierre de 12 P0 / 50 P1.¹⁹ La parte más difícil para la mayoría de los usuarios nuevos es la autenticación del proveedor: Hermes admite ~20 proveedores de primera clase más 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 de qué proveedor se resuelva.

Hermes Agent funciona como un runtime completo de agente, no como una envoltura de chat. Lee tu sistema de archivos, ejecuta comandos en backends con sandbox, extrae contenido de la web, lanza subagentes, ejecuta trabajos cron programados, habla con Telegram/Discord/Slack/WhatsApp/Signal/Email desde un único proceso gateway y crea sus propias skills a partir de la experiencia.¹ El CLI es una interfaz 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 desde plataformas de mensajería a través del mismo bucle de conversación.³

La diferencia entre un uso casual y experto de Hermes se reduce a cinco sistemas. Domínalos y Hermes se convierte 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 tool + toolset: qué puede hacer el agente, limitado por plataforma
4. Sistema de skills: memoria procedural 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 con OAuth, y /model provider:model cambia a mitad de 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 los secretos. auth.json, SOUL.md, MEMORY.md y skills/ los administra Hermes directamente; puedes editar SOUL.md a mano, pero el agente toca el resto por su cuenta.⁴
• 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 volcado de memoria usan un LLM auxiliar separado. De forma predeterminada, es Gemini Flash mediante autodetección (OpenRouter → Nous → Codex); si ninguno de esos está configurado, estas funciones se degradan silenciosamente hasta que apuntes los espacios auxiliares a tu proveedor principal.⁴

Qué cambia en v0.14

v0.14.0 no se trata tanto de una sola función destacada, sino de reducir la fricción de configuración y ampliar los lugares donde Hermes puede ejecutarse.¹⁹ Los principales cambios operativos son:

• La instalación y el inicio son más ligeros. pip install hermes-agent funciona desde PyPI, los adaptadores pesados se instalan de forma diferida en el primer uso, y la ruta de arranque posterga suficiente trabajo como para reducir el inicio en frío por unos 19 segundos.
• 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 expande. LINE y SimpleX Chat elevan el conteo de plataformas a 22, Microsoft Teams está conectado de extremo a extremo, el backfill del historial de Discord está activado de forma predeterminada, y los prompts clarify de Telegram/Discord ahora usan botones nativos.
• La verificación al escribir mejora. Después de editar, Hermes puede mostrar resúmenes de mutaciones de archivos por turno y diagnósticos semánticos del servidor de lenguaje antes del siguiente turno, lo que lo acerca más al trabajo de agentes basado en evidencia.
• Las herramientas de escritorio y medios se amplían. computer_use funciona mediante cua-driver para proveedores que no son Anthropic, video_generate se unifica detrás de backends conectables, y vision_analyze envía píxeles sin procesar a modelos que realmente pueden ver.

Cada sección a continuación se basa en la documentación upstream 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 upstream específica de donde proviene.

Elige tu ruta

Cómo funciona Hermes: el modelo mental

Hermes está estructurado en torno a un único bucle de conversación que cualquier punto de entrada puede invocar. Los puntos de entrada son la CLI (cli.py), el gateway de mensajería (gateway/run.py), el adaptador ACP para 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 orientación de herramientas mediante prompt_builder.py³
2. Resuelve el proveedor en tiempo de ejecución mediante runtime_provider.py: este es el paso que elige tu autenticación, URL base y modo API³
3. Llama al proveedor usando uno de tres modos API: chat_completions, codex_responses o anthropic_messages³
4. Despacha cualquier llamada de herramienta devuelta mediante model_tools.py y el registro central de herramientas (tools/registry.py)³
5. Repite el ciclo hasta que el modelo produce una respuesta final y luego persiste la sesión en SQLite con FTS5³

Entender este bucle importa porque cada función —personalidades, memoria, skills, compresión, fallback— se conecta a una de estas etapas. Cuando lees una clave de configuración y te preguntas qué hace, la respuesta suele ser: “es un control sobre la etapa 1, 2, 3 o 4 del bucle anterior”.

Núcleo independiente de la plataforma. Una sola clase AIAgent sirve a CLI, gateway, ACP, lotes y servidor API. Las diferencias de plataforma viven en el punto de entrada, no en el agente en sí.³ Por eso los mismos comandos slash funcionan en la terminal y en Telegram: se despachan desde un COMMAND_REGISTRY compartido en hermes_cli/commands.py.⁶

La estructura de directorios es el sistema. Hermes almacena todo bajo ~/.hermes/ (o $HERMES_HOME para profiles no predeterminados):⁴

~/.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 un rol específico; ninguno se superpone. Si estás buscando “dónde almacena Hermes X”, está en uno de estos lugares.

Qué hay de nuevo en v0.18.0 (The Judgment Release)

Hermes Agent v0.18.0 (tag v2026.7.1, 1 de julio de 2026) recibe su nombre por el juicio: el agente verifica su propio trabajo en vez de afirmar que tuvo éxito, y ofrece razonamiento en conjunto que realmente puedes inspeccionar. También cierra todo el backlog P0/P1: alrededor de 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 muestra como su propio bloque etiquetado con transmisión en vivo de la respuesta; puedes ver pensar al conjunto en vez 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 afirmar que tuvo éxito: juicio aplicado a sí mismo.²²
• /learn: describe cualquier cosa y conviértela en una skill. Convierte un flujo de trabajo en una skill reutilizable describiéndolo; las skills generadas cumplen automáticamente con las convenciones de CONTRIBUTING.md del repo.²²
• Línea de tiempo /journey. Un historial visual de memoria y skills a lo largo del tiempo, con edición, además de un grafo de memoria en escritorio.²²
• Distribución a subagentes en segundo plano. Delega varias tareas que se ejecutan de forma concurrente sin bloquear la conversación: el único subagente en segundo plano de v0.17.0 se convierte en una flota.²²
• Desktop Projects. Projects de codificación de primera clase con un modelo de organización por proyecto/repo/lane.²²
• Gateway con scale-to-zero. Los gateways pueden quedar inactivos cuando no se usan y coordinar drenajes para despliegues sin interrupciones, algo importante para cualquiera que ejecute Hermes como servicio siempre activo.²²
• Soporte para Google Vertex AI. Acceso a Gemini mediante cuentas de servicio de GCP con actualización automática de token OAuth2, sumándose al catálogo de proveedores.²²
• Comando de editor /prompt. Abre $EDITOR para redactar prompts de varias líneas en lugar de pelear con la línea de entrada.²²

Si estás actualizando desde v0.17.x, nada de esto rompe la 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.

Qué hay de nuevo en v0.17.0 (The Reach Release)

Hermes Agent v0.17.0 (tag v2026.6.19, 19 de junio de 2026) recibe su nombre por lo lejos que ahora llega el agente: nuevos canales de mensajería, nuevos proveedores de modelos y control más profundo en escritorio y dashboard. Es aditivo sobre v0.16.x; la superficie CLI no cambia.²¹

• Nuevos canales de mensajería. iMessage ahora funciona sin un relay en Mac mediante Photon Spectrum (OAuth con código de dispositivo, hermes photon login); la API de WhatsApp Business Cloud es un adaptador oficial de Meta que reemplaza el requisito de un proceso bridge; SimpleX incorpora grupos, archivos adjuntos nativos, agrupación de texto y aceptación automática; y Raft se suma 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 (contexto de 1M), anthropic/claude-fable-5, laguna-m.1, nemotron-3-ultra y grok-composer-2.5-fast (el modelo de Cursor mediante OAuth de xAI, contexto de 200k). El valor predeterminado de xAI pasó a grok-build-0.1, y los modelos adaptativos Anthropic ahora siguen el contrato moderno de thinking (nunca envían un campo reasoning).²¹
• Escritorio y dashboard. El escritorio agrega subagentes en segundo plano con transmisión en vivo en “watch-windows” de la actividad delegada (delegate_task(background=true)), un selector de modelo Composer, atajos de teclado reasignables, notificaciones nativas del sistema operativo, borradores de Composer por hilo, temas de VS Code Marketplace e interfaz en japonés y chino tradicional. El dashboard agrega un constructor completo de profiles (modelo/skills/MCPs sin editar config.yaml), un selector global de profile, un Skills Hub rediseñado con escaneo de seguridad, Automation Blueprints (plantillas parametrizadas para formulario, comando slash, conversación y docs) y un inicio de sesión seguro que devuelve 401 detrás de la puerta OAuth.²¹
• Skills y herramientas. image_generate ahora puede editar y transformar una imagen fuente, no solo crear una desde cero, en todos los proveedores de imágenes compatibles; la herramienta memory incorporó un arreglo operations para agregar/reemplazar/eliminar en lotes atómicos con una sola llamada; una nueva skill simplify-code ejecuta una revisión y limpieza paralela con tres agentes, controlada por un nivel de riesgo tipo Chesterton’s-Fence; y un booleano write_approval reemplaza el write_mode de tres estados.²¹
• Arquitectura. Los subagentes en segundo plano devuelven un handle de inmediato y reingresan su resultado como un nuevo turno; un manejador de elicitación MCP permite confirmación a mitad de una llamada de herramienta, y las herramientas MCP que se conectan tarde quedan expuestas entre turnos (seguro para caché); cron se convierte en un CronScheduler conectable con un proveedor de cron administrado Chronos; y un nuevo Managed scope (/etc/hermes) permite que un administrador fije configuración inmutable para el usuario, junto con un relay Gateway-Gateway para topologías con 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, así que la curación rutinaria en segundo plano cuesta cero tokens.²¹
• Seguridad. v0.17.0 cierra una omisión de denylist por escape de shell, falla de forma cerrada cuando faltan módulos de aprobación y adaptadores de gateway de política propia, sanitiza el entorno para subprocesos de scripts de trabajos cron, redacta secretos en volcados de depuración de solicitudes, revisa configuraciones stdio de MCP en busca de patrones de exfiltración y actualiza urllib3 y PyJWT para resolver CVEs.²¹

Si estás actualizando desde v0.16.x, nada de esto rompe la CLI; son nuevos canales, modelos y superficies alrededor del mismo agente. iMessage sin relay, los adaptadores oficiales de WhatsApp y el Managed scope para administradores son las razones principales para actualizar.

Novedades en v0.16.0 (The Surface Release)

Hermes Agent v0.16.0 (etiqueta v2026.6.5, 5 de junio de 2026) recibe su nombre por las nuevas superficies que pone delante del agente centrado en CLI. La noticia principal es que Hermes ya no funciona solo en la terminal.²⁰

• App de escritorio nativa. Hermes Desktop es una nueva app de Electron para macOS, Linux y Windows, con instalación en un clic y autoactualización dentro de la app. Te da una ventana de chat en streaming, archivos con 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 modelo en la barra de estado. Puede conectarse a un gateway Hermes remoto mediante un WebSocket seguro, con autenticación por OAuth o usuario/contraseña, hosts remotos por profile y sesiones multiprofile concurrentes vinculadas por referencias @session entre profiles. La UI de escritorio también incluye una traducción completa al chino simplificado (简体中文) mediante una capa i18n tipada (display.language; English sigue siendo el valor predeterminado).²⁰
• Panel de administración en el navegador. El dashboard web local pasó de ser una vista de estado a un panel de administración completo: un catálogo de MCP con interruptores para activar/desactivar, gestión de credenciales, creación de webhooks y hooks, configuración de memoria, controles de gateway y una página System con verificación antes de actualizar y Debug Share en un clic. Una nueva página Channels configura desde el navegador cada plataforma de mensajería del gateway (Telegram, Discord, Slack y las demás). La autenticación ahora es conectable: inicio de sesión con usuario/contraseña, un proveedor OIDC genérico autohospedado, hermes dashboard register para un cliente OAuth autohospedado y rotación de sesiones con refresh-token.²⁰
• Nuevos CLI y slash commands. /undo [N] respalda los últimos N turnos del usuario con prefill y eliminación suave, y funciona en CLI, la TUI y las plataformas de mensajería. Llega una interfaz predeterminada configurable (cli vs tui) con una anulación --cli; la TUI suma un comando /model unificado y una superposición Sessions. hermes portal es un alias legible para humanos del flujo de incorporación de Nous Portal, con nuevas rutas de primer uso Quick Setup vs Full Setup, y llegan dos diagnósticos: hermes prompt-size y hermes sessions optimize.²⁰
• Nuevos modelos y proveedores. El selector agrega deepseek-v4-flash, MiniMax-M3 (contexto de 1M, proveedores MiniMax nativos), qwen3.7-plus (Nous + OpenRouter) y gemini-3.5-flash (clave Gemini OAuth + API). Se suma un proveedor xAI Grok OAuth de primera clase al lanzador de escritorio, el selector de modelos pasó a tener búsqueda difusa en todas las superficies, los proveedores multi-endpoint se agrupan bajo una sola fila y la actualización del catálogo pasó de diaria a horaria.²⁰
• Skills más ligeras y divulgación progresiva. El conjunto predeterminado de skill eliminó skills redundantes y muertas (Spotify pasó a un plugin nativo, Linear a hermes mcp install linear y se quitaron varias entradas obsoletas), movió más elementos a opcionales y agregó una puerta de relevancia en frontmatter environments: (kanban/docker/s6) que mantiene las skills específicas de contexto fuera del índice hasta que se soliciten. NVIDIA/skills ahora es una fuente predeterminada de confianza de Skills Hub junto con OpenAI, Anthropic y HuggingFace. Las herramientas de MCP y plugin obtuvieron divulgación progresiva (con alcance) de herramientas, y se corrigió un bug de MCP que reportaba éxito falso de OAuth cuando no se obtenía ningún token.²⁰
• Seguridad. v0.16.0 fija Starlette parcheado (≥1.0.1) para CVE-2026-48710 (BadHost), mueve las verificaciones de URL SSRF fuera del event loop en rutas async, elimina el token bearer de inferencia de Bedrock del env de subprocess, agrega bws_cache.json al guard de lectura segura de archivos, añade docker restart/stop/kill a la lista de patrones peligrosos y sanea Unicode invisible en contenido de skill validado. La versión cerró 2 problemas P0 y 62 P1, 16 de ellos etiquetados como seguridad.²⁰

Si estás actualizando desde v0.15.x, nada de esto es un breaking change para el CLI en sí; son superficies y proveedores adicionales alrededor del mismo agente. La app de escritorio y el panel de administración son la razón 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 sigue siendo la ruta guiada para la mayoría de los usuarios. Gestiona Python, uv, Node.js, ripgrep, ffmpeg, la clonación del repo, el entorno virtual y el comando global hermes.⁷ v0.14.0 también incluye un paquete real en PyPI, así que pip install hermes-agent ahora es una instalación directa viable cuando ya controlas el entorno Python.¹⁹

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

pip install hermes-agent
hermes

Funciona en Linux, macOS, WSL2 y Android/Termux (el instalador detecta Termux automáticamente y cambia a un paquete Android probado).⁷ v0.14.0 agrega 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 ruta de Windows madure.¹⁹

Cuando termine:

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

El único prerrequisito es git. El instalador aprovisiona automáticamente Python 3.11 mediante uv (sin sudo), Node.js v22 (para automatización del navegador y el puente de WhatsApp), ripgrep y ffmpeg.⁷

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 dice exactamente qué falta y cómo arreglarlo.⁷ hermes dump es el comando de diagnóstico que debes pegar en un issue de GitHub o en un hilo de Discord cuando pidas ayuda: es un resumen en texto plano de toda tu configuración, con los secretos redactados.⁸

Instalación manual

Si necesitas control total —versión personalizada de Python, extras específicos, 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 constraints, no uv pip:

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

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

Autenticación y Providers

Hermes admite ~19 providers de primera clase, además de endpoints personalizados, y tres rutas de autenticación distintas. Esta es toda la superficie de autenticación, organizada por ruta para que puedas encontrar la que coincide con lo que tienes.

Las tres rutas de autenticación

Cada provider en 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 iniciar. La usan 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 providers de terceros.²

Ruta 2 — OAuth mediante hermes model o hermes auth. Inicia un flujo de código de dispositivo, abre un navegador, guarda las credenciales en ~/.hermes/auth.json (y puede importar credenciales existentes de herramientas como Claude Code o Codex CLI). La usan 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 providers

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

Anthropic: tres métodos de autenticación

Anthropic tiene su propia sección porque Hermes admite tres rutas distintas hacia Claude, y elegir la correcta 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 OAuth de Anthropic mediante hermes model, Hermes prefiere el almacén de credenciales propio de Claude Code en lugar de copiar el token en ~/.hermes/.env. Así, las credenciales renovables de Claude siguen siendo renovables.² Si ya usas Claude Code en la misma máquina, esta es la ruta más limpia.

Para fijar Anthropic de forma permanente 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 en dos modos: API directo de Copilot (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 verifica 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. Fallback de 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 admitidos son tokens OAuth (gho_*), PATs de alcance fino (github_pat_* con permiso Copilot Requests) y tokens de GitHub App (ghu_*). Si tu gh auth token devuelve un token ghp_*, usa hermes model para autenticarte mediante OAuth en su lugar.²

Providers de AI chinos (soporte de primera clase)

Hermes incluye soporte integrado para z.ai/GLM, Kimi/Moonshot, MiniMax (endpoints globales + China) y Alibaba Cloud con IDs de provider 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

Las URL base se pueden sobrescribir con las variables de entorno GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL o DASHSCOPE_BASE_URL.²

Z.AI autodetecta el endpoint. Al usar el provider z.ai/GLM, Hermes prueba varios endpoints (globales, China y variantes de coding) para encontrar uno que acepte tu clave API. El endpoint funcional se guarda en caché automáticamente; la mayoría de los usuarios no necesita GLM_BASE_URL.²

xAI (Grok) activa automáticamente el almacenamiento en caché de prompts. Cuando la URL base contiene x.ai, Hermes envía el encabezado x-grok-conv-id en cada solicitud para enrutarla al mismo servidor dentro de una sesión de conversación, reutilizando prompts del sistema e historial 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 sirven para rotar varias claves API o tokens OAuth para el mismo provider; 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 apuntar 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 guardan en config.yaml, que es la única fuente de verdad para el modelo principal, el provider 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 aún se respetan como fallback para la ruta auxiliar provider: "main", así que no las borres a ciegas si las usas ahí).⁴

Cambiar endpoints personalizados a mitad de 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 autoselecciona el modelo si hay exactamente uno cargado; resulta útil para servidores locales que ejecutan un solo modelo.²

Servidores locales LLM (plantillas de configuración)

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

Ollama — la ruta local más fácil, 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

Detalle crítico de Ollama: Ollama usa de forma predeterminada longitudes de contexto muy bajas (4.096 tokens con menos de 24GB de VRAM). Debes aumentarla mediante OLLAMA_CONTEXT_LENGTH o un Modelfile; el API compatible con OpenAI no acepta la longitud de contexto desde el cliente, así que Hermes no puede configurarla por ti.² Para uso con agentes, configura al menos 16k–32k.

vLLM — serving 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>. Parsers admitidos: hermes (Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic. Sin estas flags, las llamadas a herramientas volverán como texto plano.²

SGLang — serving rápido con RadixAttention para reutilizar la 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

Detalle de SGLang: El max_tokens predeterminado 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 Apple Silicon Metal:

./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 llamadas a herramientas. Sin esa opción, llama-server ignora por completo el parámetro tools y el modelo intenta llamar herramientas escribiendo JSON en el texto de su respuesta, lo que Hermes no puede interpretar como llamadas reales a herramientas.²

LM Studio — aplicación de escritorio con GUI:

Inicia el servidor desde la app 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 apunta hermes model a http://localhost:1234/v1.

Detalle crítico de LM Studio: LM Studio lee la longitud de contexto desde los metadatos del modelo, pero muchos modelos GGUF reportan valores predeterminados de 2048 o 4096. Configura siempre la longitud de contexto explícitamente en la configuración del modelo de LM Studio: haz clic en el ícono de engranaje junto al selector de modelo, configura “Context Length” al menos en 16384 (preferiblemente 32768) y vuelve a cargar el modelo.²

Providers personalizados con nombre

Si trabajas con varios endpoints personalizados (por ejemplo, un servidor local de desarrollo y un servidor GPU remoto), defínelos como providers 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 a mitad de 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 providers personalizados con nombre desde el menú interactivo de hermes model.²

Arquitectura de providers conectable (v0.13.0+)

v0.13.0 incluye una ABC ProviderProfile y un directorio plugins/model-providers/ para que providers de inferencia de terceros puedan integrarse sin modificar el núcleo.¹⁸ Si un provider habla en 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 providers integrados. Este es el cambio arquitectónico detrás de la expansión de providers en v0.13.0: en lugar de editar el código central para agregar un provider, publicas un plugin.

Proxy local compatible con OpenAI (v0.14.0+)

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

Detección de longitud de contexto

Dos configuraciones se confunden constantemente, según la documentación upstream:²

• 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 (tokens máximos que el modelo puede generar en una sola respuesta). No está relacionado con la longitud del historial.

Configura context_length cuando la autodetección se equivoque con 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 con varias fuentes para detectar ventanas de contexto: override de configuración → modelo por provider personalizado → caché persistente → endpoint /models → /v1/models de Anthropic → API de OpenRouter → Nous Portal → models.dev (registro mantenido por la comunidad para más de 3800 modelos) → valores predeterminados de fallback (128K).² El sistema reconoce el provider, así que el mismo modelo puede tener límites de contexto distintos según quién lo sirva (por ejemplo, claude-opus-4.6 tiene 1M en Anthropic directo, pero 128K en GitHub Copilot).²

Rotación y fallback de providers

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

Modelo de fallback. Configura un provider:model de respaldo al que Hermes cambie automáticamente cuando tu modelo principal falle (límites de tasa, errores del 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 fallback cambia el modelo y el provider a mitad de sesión sin perder la conversación. Se activa como máximo una vez por sesión.² Providers admitidos para fallback: 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 “auxiliares” ligeros para tareas secundarias: análisis de imágenes, resumen de páginas web, análisis de capturas del navegador, clasificación de aprobación de comandos peligrosos, compresión de contexto, resumen de búsqueda de sesiones, coincidencia de skills, despacho de herramientas MCP y volcado de memoria.⁴ De forma predeterminada, estos usan Gemini Flash mediante autodetección (OpenRouter → Nous → Codex).

Puedes configurar qué modelo y provider usa cada tarea auxiliar. Cada ranura auxiliar usa 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 provider "main" significa “usa el provider que usa mi agente principal”; es válida solo dentro de las configuraciones auxiliary:, compression: y fallback_model:. No es válida para tu configuración superior model.provider. Si usas un endpoint personalizado compatible con OpenAI como modelo principal, configura provider: custom en tu sección model:.⁴

Por qué importa: si solo configuraste OAuth de Anthropic (sin clave de OpenRouter), visión, resumen web y compresión se degradarán o fallarán porque la cadena de fallback auxiliar predeterminada intenta OpenRouter primero. Agrega una OPENROUTER_API_KEY para tareas auxiliares o reconfigura cada ranura auxiliar para usar tu provider principal:

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

Este es el detalle más común detrás de “mis funciones no trabajan y no sé por qué” para usuarios nuevos 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 a las inferiores, y una de esas capas es un registro global de proveedores que no puedes ver en config.yaml.

Estructura de archivos de configuración

Según la documentación upstream, estos son los archivos que componen 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 vs .env: cuando ambos están definidos, config.yaml tiene prioridad para la configuración que no es secreta.⁴ La regla es: - Secretos (claves API, tokens de bots, contraseñas) → .env - Todo lo demás (modelo, backend de terminal, configuración de compresión, límites de memoria, toolsets) → config.yaml

Los secretos pueden referenciarse desde config.yaml mediante interpolación estilo shell:⁴

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

Gestionar 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 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 agregadas que tu archivo todavía no tiene.⁶

Precedencia de configuración

Hermes carga la configuración desde varias fuentes. Cuando varias fuentes definen el mismo valor, gana la fuente con mayor prioridad:⁴

1. Argumentos de CLI — hermes chat --model anthropic/claude-sonnet-4 (anulación por invocación)
2. Variables de entorno — aplicadas al iniciar el proceso
3. config.yaml — el archivo principal de configuración
4. .env — solo secretos
5. Valores predeterminados integrados — aplicados cuando ninguna otra fuente define un valor

Las flags de CLI siempre tienen prioridad para esa invocación específica. config.yaml es la fuente de verdad a largo plazo.

Localización (v0.13.0+)

v0.13.0 agregó 7 locales para mensajes de CLI y gateway: chino (simplificado), japonés, alemán, español, francés, ucraniano y turco.¹⁸ v0.14.0 localiza todos los comandos de gateway y el panel web, agrega 8 locales más y lleva el total a 16.¹⁹ Actualmente, la documentación solo está localizada en zh-Hans. El locale 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 todavía no haya cubierto.

Profiles: varias instancias aisladas de Hermes

Los profiles te dan varias instancias aisladas de Hermes, cada una con su propia configuración, sesiones, skills, memoria y PID de gateway. Así puedes ejecutar un “Hermes de trabajo” y un “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 al mismo tiempo sin interferir entre sí.⁶³

Comandos de CLI

Esta sección es la referencia práctica para 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 completo de configuración o salta 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 tail -f sobre 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, despacho de herramientas, ciclo de vida de sesiones, INFO+) - errors.log: solo advertencias y errores (un subconjunto filtrado de agent.log) - gateway.log: actividad del messaging gateway (conexiones de plataforma, despacho, webhooks)

La rotación es automática mediante el 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 falla. Comprueba la validez de la configuración, la presencia de dependencias, la disponibilidad de claves de API, el estado de servicios y puede intentar reparaciones automáticas con --fix.⁶

Para compartir diagnósticos con otra persona, usa hermes dump: produce un resumen compacto en texto plano con claves de API redactadas, listo para pegar en un issue de GitHub o en un hilo de Discord.⁶

Comandos slash

Los comandos slash se ejecutan dentro de una sesión de chat activa (CLI o plataforma de mensajería). Se despachan desde un COMMAND_REGISTRY compartido en hermes_cli/commands.py, por eso la mayoría de los comandos funcionan igual 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

Herramientas, Skills e información

Comandos slash dinámicos de Skills

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

/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

También puedes definir comandos rápidos en config.yaml que asignan un alias 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; /mod se resuelve como /model. Cuando un prefijo es ambiguo, gana el primer registro según el orden del registry. Los nombres completos de 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 home de la plataforma
• /approve [session|always] — aprueba un comando peligroso pendiente
• /deny — rechaza un comando peligroso pendiente
• /update — actualiza Hermes Agent a la versión más reciente
• /commands [page] — explora todos los comandos y skills (paginado)

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 integrado de herramientas que cubre búsqueda web, automatización del navegador, ejecución en terminal, edición de archivos, memoria, delegación, entrenamiento 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 por plataforma.

Categorías de alto nivel

Los nombres comunes de toolsets 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 con /tools disable <name> y /tools enable <name>, lo que restablece la sesión para que el nuevo conjunto de herramientas entre en vigor.⁹

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 por 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 (aplica a docker, singularity, modal, 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 configuración persisten entre sesiones.¹⁰

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

Procesos en segundo plano

La herramienta de terminal admite ejecución en segundo plano con gestió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 CLI como Codex y Claude Code.¹⁰

Sudo

Si un comando necesita sudo, Hermes te pide la contraseña (almacenada en caché durante la sesión). También puedes configurar 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 trabajadores entre agentes y entre reinicios.¹⁸ El tablero es lo que hace que un enjambre de trabajadores de Hermes realmente termine el trabajo en lugar de quedarse bloqueado por traspasos muertos.

El tablero Kanban se combina de forma natural con /goal (bucle Ralph de objetivo bloqueado) para el lado del objetivo y con la herramienta existente delegate_task para la semántica de spawn. 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á atascado.

Sistema de Skills

Las 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 agentskills.io.¹¹

Todas las skills viven en ~/.hermes/skills/: el directorio principal y la fuente de verdad. En una instalación nueva, las skills incluidas se copian desde el repo. Las skills instaladas desde el Hub y las creadas por el agente también van 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 de la 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

Las skills pueden mostrarse u ocultarse según las herramientas disponibles. Esto es especialmente útil para skills de fallback: alternativas gratuitas o locales que solo deberían aparecer cuando una herramienta premium no está disponible:¹¹

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

Skills administradas por el agente

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

Cuándo crea skills el agente:¹¹ - Después de completar correctamente una tarea compleja (5+ llamadas a herramientas) - Cuando encontró errores o caminos sin salida y dio con la ruta que funcionaba - Cuando el usuario corrigió su enfoque - Cuando descubrió un flujo de trabajo no trivial

Acciones:¹¹

Hub de skills

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 de hub integradas:¹¹

Taps predeterminados de GitHub (explorables sin configuración): openai/skills, anthropics/skills, VoltAgent/awesome-agent-skills, garrytan/gstack.¹¹

Escaneo de seguridad

Todas las skills instaladas desde el hub pasan por un escáner de seguridad que revisa exfiltración de datos, prompt injection, comandos destructivos, señales de supply chain y otras amenazas.¹¹

Niveles de confianza:¹¹

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

Directorios externos de skills

Puedes apuntar Hermes a directorios de skills adicionales que se escanean 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 una skill, siempre escribe en ~/.hermes/skills/. La precedencia local gana si existe un nombre de skill en ambos lugares.¹¹

Memoria persistente

Hermes tiene una memoria acotada y curada que persiste entre sesiones. Dos archivos componen la memoria del agente, ambos almacenados en ~/.hermes/memories/:¹²

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

Patrón de instantánea congelada: la inyección del system prompt se captura una sola vez al inicio de la sesión y nunca cambia a mitad de sesión. Esto 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 comandos de Docker; el usuario está en el grupo docker” → memory - Convenciones: “El proyecto usa tabs, ancho de línea de 120 caracteres y docstrings estilo Google” → memory - Trabajo completado: “Se migró la base de datos de MySQL a PostgreSQL el 15 de enero de 2026” → memory

Omite esto:¹² - Información trivial u obvia - Datos fáciles de redescubrir - Volcados de datos sin procesar (demasiado grandes para la memoria) - 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 pasadas con 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 pasadas relevantes con resumen de Gemini Flash.¹²

Proveedores externos de memoria

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

Los proveedores externos se ejecutan junto con la memoria integrada (nunca la reemplazan) y agregan capacidades como grafos de conocimiento, búsqueda semántica, extracción automática de hechos y modelado de usuario 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 estar activo un proveedor externo a la vez. La memoria integrada siempre está activa.⁶

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

v0.13.0 hace que una interrupción a mitad del agente sea recuperable. El gateway reanuda automáticamente las sesiones interrumpidas después de un reinicio; los reinicios por /update preservan el estado de la sesión durante la actualización; las recargas de archivos fuente durante el desarrollo mantienen viva la sesión activa en lugar de forzar una nueva.¹⁸ Efecto práctico: el trabajo prolongado del gateway y las tareas impulsadas por cron ya no reinician su ventana de contexto cuando el proceso se reinicia.

Checkpoints v2 (v0.13.0+)

La persistencia de estado se reescribió en v0.13.0 como un diseño de almacén único con poda real, límites de seguridad en disco y sin repos sombra huérfanos.¹⁸ El sistema anterior de checkpoint acumulaba estado en disco en profiles de larga duración; el almacén v2 impone un techo estricto al almacenamiento local de checkpoints y elimina la contabilidad duplicada que causaba ese crecimiento. No se requiere ningún cambio de configuración visible para el usuario; la próxima escritura de checkpoint usa la ruta v2.

Personalidad y SOUL.md

SOUL.md es la identidad principal de una instancia de Hermes. Ocupa el espacio #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é corresponde en SOUL.md

Úsalo para guía duradera de voz y personalidad:¹³ - tono - estilo de comunicación - nivel de franqueza - estilo de interacción predeterminado - qué evitar estilísticamente - cómo debe manejar Hermes la incertidumbre, el desacuerdo y la ambigüedad

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

Eso corresponde en AGENTS.md, no en SOUL.md.

SOUL.md vs 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, comportamiento a nivel de personalidad.

AGENTS.md: arquitectura del proyecto, convenciones de código, preferencias de herramientas, flujos de trabajo específicos del repo, comandos, puertos, rutas, notas de despliegue.

Una regla útil: si debe acompañarte a todas partes, va en SOUL.md. Si pertenece a un proyecto, va en 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 vs /personality

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

Nous Tool Gateway (v0.10.0+)

A partir de Hermes Agent v0.10.0 (16 de abril de 2026), los suscriptores pagos de Nous Portal obtienen acceso administrado a un conjunto curado de herramientas mediante sus credenciales existentes de Portal, sin claves de API adicionales que gestionar.²⁶ El CLI de Hermes en sí sigue con licencia MIT y es completamente open source. Lo que cambió es que tu autenticación de Portal ahora desbloquea más que inferencia de modelos.

Qué incluye el gateway

Cómo funciona

El gateway es opt-in por 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 directa de API (si está presente).

# 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 directa de API. Esto importa para la facturación: las llamadas del gateway consumen tu suscripción de Portal, no el saldo de tu clave directa de API.

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

No existe un comando separado hermes subscribe ni hermes login --portal. La suscripción se detecta automáticamente a partir de las credenciales de OAuth de Portal que ya tienes en hermes auth.

Precios y acceso

Los precios y nombres de 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 de forma independiente a los lanzamientos de Hermes. Regístrate en https://portal.nousresearch.com/ y consulta la página de precios para ver los niveles actuales.

Aviso de obsolescencia

• 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 se restringen según el estado de tu suscripción de Portal.²⁶

Marco: lo que esta versión no es

El CLI de Hermes Agent no está bloqueado detrás de una suscripción. El proyecto sigue con licencia MIT; todas las funciones principales (CLI, skills, memoria, messaging gateway, cron, MCP, dashboard local, BYOK para cada proveedor) funcionan de principio a fin sin pagarle a nadie. v0.10.0 agrega una ruta conveniente para usuarios que ya pagan Nous Portal; no elimina nada de la ruta gratuita.

Messaging Gateway

Hermes puede ejecutarse como un proceso gateway de larga duración que se conecta a 22 plataformas de mensajería desde un solo proceso 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.^325171819 v0.9.0 agregó iMessage mediante BlueBubbles (registro automático de webhook, asistente de configuración, resiliencia ante fallos) y soporte nativo para WeChat mediante iLink Bot API, con modo de callback de WeCom para apps empresariales.¹⁶ v0.11.0 agregó QQBot.²⁵ v0.12.0 agregó Microsoft Teams y Tencent Yuanbao.¹⁷ v0.13.0 agregó Google Chat como la plataforma número 20, usando la misma arquitectura de adaptadores conectables; IRC y Microsoft Teams también se migraron al nuevo patrón de adaptadores con hooks de plugin genéricos env_enablement_fn / cron_deliver_env_var.¹⁸ v0.14.0 agrega LINE y SimpleX Chat y completa el stack de Microsoft Teams de extremo a extremo con autenticación Graph, listener de webhook, runtime de pipeline y entrega saliente.¹⁹ v0.17.0 (19 de junio de 2026) agrega iMessage sin relay mediante Photon Spectrum (OAuth con hermes photon login; no se requiere relay de Mac/BlueBubbles), el adaptador oficial de WhatsApp Business Cloud API (que reemplaza el requisito de un proceso bridge), grupos de SimpleX y adjuntos nativos, 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 bot, 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 pasan por el mismo bucle de conversación AIAgent que CLI. Por eso los comandos slash funcionan igual en ambos lugares y por eso un cron job programado en Telegram puede entregar su salida en Discord: la diferencia entre plataformas está solo en el borde.³

Autorización y emparejamiento 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 emparejamiento evitan que desconocidos al azar hablen con tu gateway. Un usuario envía un código de emparejamiento desde su plataforma de mensajería; lo apruebas con hermes pairing approve; desde ese momento queda autorizado.⁶

Tareas programadas (Cron)

Hermes tiene un sistema cron de primera clase donde los jobs son tareas de agente, no comandos de shell. Cada job programado se ejecuta mediante un AIAgent nuevo con el prompt configurado, skills adjuntas 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 cron job mediante sus herramientas. Los jobs persisten en JSON y sobreviven a los reinicios.³

Integración con MCP

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

Como cliente: conecta Hermes a servidores MCP externos 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"

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 separada; puedes apuntarlo 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: 90 turnos) sin darse cuenta. La presión de presupuesto advierte automáticamente al modelo:⁴

Timeouts de streaming

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

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

Dashboard web local (v0.9.0+)

Un dashboard basado en navegador para administrar tu Hermes Agent localmente. Configura opciones, monitorea 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 onboarding más sencilla para usuarios nuevos que prefieren una GUI.

Monitoreo de procesos en segundo plano (v0.9.0+)

watch_patterns te permite definir patrones para monitorear la salida de procesos en segundo plano y recibir notificaciones en tiempo real cuando coincidan.¹⁶ Monitorea errores, espera eventos específicos (“listening on port”) o revisa logs de compilación, todo sin hacer polling. Combinado con notify_on_complete de v0.8.0 (que notifica cuando termina una tarea en segundo plano), Hermes ahora tiene una capa completa de observabilidad para procesos en segundo plano.¹⁵

Context engine conectable (v0.9.0+)

La gestión de contexto ahora es un slot conectable 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 central del agente, lo que permite personalizar el contexto por proyecto o por dominio.

Backup 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 backup.¹⁶ Úsalo para migrar entre máquinas, crear snapshots antes de cambios importantes o compartir una configuración validada 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, el soporte de backend de voz y el comando /image funcionan en el dispositivo.¹⁶

Refuerzo de seguridad (v0.13.0+)

v0.13.0 cerró 8 problemas de seguridad P0 y cambió un valor predeterminado a favor del usuario.¹⁸ v0.14.0 continúa con otros 12 cierres P0 y 50 P1, incluidos el refuerzo contra fuerza bruta de sudo / sudo-stdin, correcciones de evasión de comandos peligrosos, sanitización de errores de herramientas antes de reinyectarlos en el modelo, auth de dashboard plugin API, cobertura SSRF de skills-hub y escaneo de avisos de supply-chain durante la instalación.¹⁹

Si mantienes un despliegue de Hermes, trata v0.13.0 y v0.14.0 como actualizaciones relevantes para la seguridad, no solo como lanzamientos de funciones. v0.13.0 cierra la evasión cross-guild de Discord y dos ventanas TOCTOU; v0.14.0 agrega otra pasada de refuerzo en el manejo de sudo, la reinyección de errores de herramientas, los APIs de plugins, SSRF de skills-hub y avisos de dependencias.

Arquitectura para practicantes

Esta sección es para quienes quieren entender qué ocurre bajo el capó para poder depurarlo, extenderlo 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 herramientas del repositorio upstream: todas las herramientas para las que Hermes incluye código fuente, en todos los toolsets. Tu CLI real en ejecución mostrará un número menor en su banner de inicio (la instalación con la que verifiqué esta guía reporta 28 tools / 89 skills). No es un bug. Muchos toolsets son opt-in y deben habilitarse explícitamente en config.yaml dentro de 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”. Revisa qué toolsets están activos con hermes tools --list y habilita o deshabilita toolsets individuales con el bloque toolsets: en ~/.hermes/config.yaml (o /tools list / /tools enable <name> / /tools disable <name> dentro de una sesión en ejecución; quitar una herramienta provoca un reinicio de sesión para que el agente reconstruya su manifiesto de herramientas).

Los tres modos API

Hermes abstrae las diferencias entre proveedores en tres modos API, seleccionados automáticamente en tiempo de ejecución:³

El resolver runtime_provider.py mapea tuplas (provider, model) a (api_mode, api_key, base_url) para más de 18 proveedores, y maneja flujos OAuth, pools de credenciales y resolución de alias.³

Flujo de datos a través de una sesión 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 de prompts

La pila de prompts incluye:¹³

1. SOUL.md (identidad del agente, o fallback integrado si no está disponible)
2. Guía de comportamiento consciente de herramientas
3. Memoria/contexto de usuario (MEMORY.md, USER.md)
4. Guía de skills
5. Archivos de contexto (AGENTS.md, .cursorrules)
6. Marca de tiempo
7. Pistas de formato específicas de la plataforma
8. Overlays opcionales de system-prompt como /personality

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

Almacenamiento de sesiones

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

Sistema de plugins

Tres fuentes de descubrimiento: ~/.hermes/plugins/ (usuario), .hermes/plugins/ (proyecto) y entry points de pip. Los plugins registran herramientas, hooks y comandos de CLI mediante un contexto API. Los proveedores de memoria son un tipo especializado de plugin dentro de 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 desde ~/.openclaw por defecto (también detecta automáticamente 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 fuente, modelo predeterminado, proveedores personalizados, servidores MCP, tokens y allowlists de plataformas de mensajería (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), valores predeterminados del agente (reasoning effort, compresión, human delay, zona horaria, sandbox), políticas de reinicio de sesión, reglas de aprobación, configuración de TTS, configuración del navegador, configuración de herramientas, exec timeout, command allowlist, configuración de gateway y claves API de 3 fuentes.⁶

Archivado para revisión manual: cron jobs, plugins, hooks/webhooks, backend de memoria (QMD), configuración del registro de skills, UI/identidad, logging, configuración multi-agente, vinculaciones de canales, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

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

Solución de problemas

“Clave API no configurada”

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

“Límite de contexto: 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 reportan valores predeterminados bajos. Configúralo 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 habilitadas las llamadas a herramientas, o el modelo no las admite a través de la implementación del servidor.²

Las respuestas se cortan a mitad de una oración

Hay dos causas posibles:²

1. Límite bajo de salida (max_tokens) en el servidor: SGLang usa 128 tokens por respuesta de forma predeterminada. Configura --default-max-tokens en el servidor o define 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 apunta a la VM de Linux, no al host de Windows. Hay dos opciones:²

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

[wsl2]
networkingMode=mirrored

Luego ejecuta wsl --shutdown y reinicia. Ahora localhost funciona en ambas direcciones.

Alternativa con IP del host (versiones anteriores de Windows): 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 open-source 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 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 manualmente un ANTHROPIC_TOKEN (token setup-token o token OAuth) como alternativa

La opción 2 es la recomendada si ya usas Claude Code en la misma máquina, porque mantiene actualizables las credenciales Claude que pueden renovarse.

¿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 llegando al fallback del modelo auxiliar. Vision, la síntesis web, la compresión y otras tareas secundarias usan un LLM auxiliar separado: de forma predeterminada, Gemini Flash mediante detección automática (OpenRouter → Nous → Codex). Si ninguno de esos está configurado y solo tienes Anthropic listo, estas funciones se degradan de forma silenciosa.⁴

Corrección: agrega una OPENROUTER_API_KEY para tareas auxiliares, o reconfigura los slots auxiliares para usar tu proveedor principal. Ten en cuenta que la compresión de contexto vive en su propio bloque de nivel superior compression: y usa summary_provider, no auxiliary.compression.provider; el slot auxiliary.compression solo expone un timeout. Correcció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. Vive en ~/.hermes/SOUL.md y te acompaña a todas partes. AGENTS.md es específico del proyecto: arquitectura, convenciones, comandos y rutas, y vive en el directorio de tu proyecto.¹³ Si debe seguirte a todas partes, va en SOUL.md. Si pertenece a un proyecto, va en 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 ver la configuración por 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: ese es el conteo completo de herramientas para las que Hermes incluye código fuente 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 reporta 28 herramientas) porque Hermes solo habilita el conjunto predeterminado de toolsets al iniciar. Muchos toolsets son opcionales: los adaptadores de gateway de mensajería, la automatización de navegador, los stacks de scraping más pesados y varias integraciones especializadas deben listarse explícitamente bajo toolsets: en ~/.hermes/config.yaml antes de cargarse. Total del registro = “lo que está disponible si lo habilitas”. Total del banner = “lo que tu profile actual cargó realmente”. 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> (deshabilitar uno activa un reinicio de sesión para que el agente reconstruya su manifiesto de herramientas con la nueva forma).

¿Cómo maneja Hermes el fallback 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 falla el principal (límite de tasa, error del servidor, falla de autenticación), Hermes cambia al fallback 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 “self-improving” de Hermes Agent. El agente puede crear, actualizar y eliminar skills mediante la herramienta skill_manage. Cuando descubre 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 (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.

¿Hay integración con IDE?

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

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

Registro de cambios

Referencias