Respuesta rápida
Hermes Agent se puede autoalojar en un servidor doméstico si quieres un agente de IA que pueda conectarse a un proveedor de modelos, usar herramientas y comunicarse mediante una pasarela de mensajería, como Telegram. Para la mayoría de los principiantes, lo más difícil no es solo ejecutar la aplicación, sino entender dónde tiene lugar cada acción: en el servidor host, dentro del contenedor, en el entorno de la aplicación o a través de una plataforma de mensajería.
Una configuración autoalojada segura debería responder seis preguntas antes de solucionar cualquier problema:
- ¿Estoy trabajando en el host o dentro del contenedor?
- ¿Dónde se guardan la configuración de la aplicación, los registros, las descargas y los datos del entorno de ejecución?
- ¿Qué usuario es propietario de los archivos y ejecuta la aplicación?
- ¿Puede la aplicación conectarse al proveedor del modelo y a la API de mensajería?
- ¿Están protegidas las claves de API, los tokens de bots y las listas de permitidos?
- ¿Cómo confirmo que el agente sigue funcionando después de reiniciar?
Si mantienes claros estos límites, será mucho más fácil entender, verificar y solucionar problemas de la configuración de Hermes Agent.
¿Qué es Hermes Agent en la configuración de un servidor doméstico autoalojado?
Hermes Agent es un flujo de trabajo de agente de IA autoalojado que puede conectarse a un proveedor de modelos, usar herramientas e interactuar a través de la terminal o de canales de mensajería. En un servidor doméstico, suele situarse entre el modelo de IA, el entorno del servidor y una interfaz de comunicación, como un panel web o una pasarela de bots.
Lo importante es que un agente autoalojado no es solo un chatbot. Según su configuración, puede interactuar con archivos, herramientas de terminal, API de modelos, plataformas de mensajería y datos del entorno de ejecución. Por eso es importante delimitar las rutas, los permisos y el acceso.
Qué hace Hermes Agent para la interacción con IA y la mensajería
Hermes Agent se puede configurar para conectarse a un proveedor de modelos, iniciar conversaciones, usar herramientas y conectar pasarelas de mensajería. El flujo de inicio rápido de Hermes Agent explica que los usuarios pueden instalar Hermes, configurar un proveedor de modelos, iniciar una primera conversación, usar herramientas de terminal y, más adelante, conectar plataformas de mensajería mediante una pasarela.
Para quien usa un servidor doméstico, esto significa que Hermes puede convertirse en un asistente de IA persistente que se ejecuta en un dispositivo bajo tu control. También puede añadir nuevas capas de configuración: credenciales del modelo, entorno de ejecución de la aplicación, ajustes de la pasarela y permisos de acceso.
Cuándo basta con configurar la interfaz web
Por lo general, basta con configurar la interfaz web cuando la aplicación ofrece directamente en el panel todos los ajustes necesarios. Esta es la opción más segura para la mayoría de los usuarios, porque evita acceder a la terminal del contenedor, salvo que falte algo o no funcione.
Un enfoque centrado primero en la interfaz web es adecuado cuando:
- la aplicación se instala correctamente;
- el proveedor del modelo se puede configurar desde la interfaz;
- se puede conectar la pasarela de mensajería sin acceder al shell;
- el panel muestra el estado con claridad;
- los registros no muestran errores de permisos ni de red.
Si el panel de control ofrece la opción que necesitas, úsala primero. La configuración de la terminal del contenedor debe considerarse una alternativa o una opción avanzada, no el primer paso predeterminado para todos los usuarios.
Cuándo necesitas configurar la terminal del contenedor
Es posible que necesites configurar la terminal del contenedor cuando el panel de control no ofrezca una opción necesaria, cuando la aplicación requiera ejecutar un asistente de configuración dentro del contenedor o cuando, para resolver un problema, necesites acceder a los registros, al entorno de ejecución o a comandos específicos de la aplicación.
Aquí es donde muchos usuarios se confunden. Un comando ejecutado en la shell del host puede no afectar a la aplicación dentro del contenedor. Puede que un archivo visible dentro del contenedor no exista en la misma ruta del host. Un error de permisos puede deberse al usuario con el que se ejecuta la aplicación, no al proveedor del modelo ni al token del bot.
Antes de usar la terminal del contenedor, confirma exactamente en qué shell estás y con qué usuario estás trabajando.
Qué necesitas antes de empezar
Para configurar un agente autoalojado se necesita algo más que un servidor en funcionamiento. Necesitas una ruta de red operativa, acceso al modelo, credenciales de mensajería y permisos suficientes para gestionar la aplicación sin modificar por accidente los archivos equivocados.
Un servidor doméstico con acceso a internet
El servidor doméstico debe poder acceder a internet si piensas usar un proveedor de modelos en la nube o una API de mensajería. Si usas un punto de conexión de un modelo local, el servidor igualmente debe poder acceder a ese punto de conexión a través de la red local o de la red de contenedores.
El acceso a la red es importante porque puede parecer que un agente está instalado correctamente y aun así no responder. Por ejemplo, la conexión con el proveedor del modelo, la pasarela de mensajería y el panel de control pueden depender de rutas de red distintas.
Empieza por confirmar que:
- el servidor tiene una conexión LAN estable;
- el servidor puede acceder al punto de conexión o proveedor del modelo;
- el servidor puede acceder a la API de mensajería;
- el puerto del panel de control es accesible desde el navegador;
- ninguna regla del cortafuegos bloquea la pasarela.
Un proveedor de modelos o un punto de conexión de un modelo local
Hermes necesita una conexión con un modelo para generar respuestas útiles. Puede ser un proveedor en la nube, una clave de API o un punto de conexión compatible con OpenAI. Algunos usuarios pueden conectarse a un servicio de modelo local si su hardware y su conjunto de modelos lo permiten.
El detalle importante de la configuración es que la configuración del modelo es independiente de la configuración de mensajería. Un bot puede estar conectado correctamente aunque el proveedor del modelo sea incorrecto, y el proveedor del modelo puede funcionar aunque falle la pasarela del bot.
Organiza la URL base del modelo, la clave de API, el nombre del modelo y la configuración del contexto antes de empezar la configuración.
Una cuenta de mensajería y el token de un bot
Si quieres comunicarte con el agente a través de Telegram u otra plataforma de mensajería, necesitas una cuenta de mensajería y las credenciales de un bot o una pasarela. En el caso de Telegram, normalmente tendrás que crear un bot y guardar su token.
Un token de bot debe tratarse como una contraseña. Telegram explica que cada bot recibe un token único que se utiliza para autorizar solicitudes a Bot API, y que las solicitudes incluyen el token en la ruta de API según el modelo de autorización de tokens de bots de Telegram.
No pegues un token de bot en chats públicos, capturas de pantalla, registros, incidencias de GitHub ni documentos compartidos. Si el token queda expuesto, vuelve a generarlo mediante el procedimiento oficial de la plataforma de mensajería.
Dirección IP del host, acceso de inicio de sesión y permisos del contenedor
Necesitas la dirección IP del host para acceder al panel del servidor o conectarte por SSH. También necesitas credenciales de inicio de sesión que te permitan administrar la aplicación de forma segura.
En las configuraciones basadas en contenedores, los permisos suelen estar organizados en capas:
| Capa de permisos | Qué controla | Error habitual | Comprobación segura |
|---|---|---|---|
| Usuario del host / cuenta SSH | Acceso al sistema de archivos del servidor doméstico, a los comandos de Docker y al panel del servidor. | Dar por sentado que los permisos del host se aplican automáticamente dentro del contenedor. | Confirma con qué cuenta has iniciado sesión y qué acciones puede realizar en el servidor. |
| Usuario del contenedor | El usuario que ejecuta el proceso de la aplicación y escribe sus archivos dentro del contenedor. | Ejecutar la configuración como root cuando la aplicación normalmente se ejecuta con un usuario sin privilegios de root. | Comprueba cuál es el usuario previsto del contenedor antes de crear o modificar datos de la aplicación. |
| Carpeta del host montada | La carpeta del host o el volumen de Docker expuesto al contenedor. | Modificar una carpeta del host que no está montada en la ruta que lee la aplicación. | Verifica la ruta de origen en el host y la ruta de destino en el contenedor. |
| Ruta de ejecución de la aplicación | Dónde se guardan la configuración, los registros, las descargas, las sesiones y los datos temporales. | Modificar archivos en la capa equivocada o perder la configuración tras reiniciar. | Confirma que la ruta persista tras reiniciar y que el usuario de la aplicación pueda escribir en ella. |
No des por sentado que root siempre es la respuesta adecuada. Usar root en el momento equivocado puede crear archivos propiedad de root que el usuario de la aplicación no podrá modificar después.
Ruta del host vs. ruta del contenedor vs. ruta de datos de la aplicación
Este es el concepto más importante de este artículo. Muchos problemas al configurar Hermes Agent se deben a confundir las rutas del host, las del contenedor, las rutas de datos de la aplicación, los registros, las descargas y los volúmenes montados.
Usa El mapa de control del contenedor de Agent antes de ejecutar comandos o depurarlos.
| Capa | Pregunta que hay que responder | Señal de validación | Fallo habitual |
|---|---|---|---|
| Sistema host | ¿Se puede acceder al servidor, al panel, a la sesión SSH y al administrador de contenedores? | Se abre el panel o la sesión SSH, y el contenedor aparece en ejecución. | La aplicación parece estar instalada, pero no se puede acceder al servidor ni al contenedor. |
| Entorno de ejecución del contenedor | ¿Estoy dentro del contenedor correcto y usando el usuario esperado? | El shell, el directorio de trabajo y el usuario coinciden con la ruta de configuración de la aplicación. | Los comandos se ejecutan en el shell del host y no afectan a la aplicación dentro del contenedor. |
| Ruta de datos de la aplicación | ¿Dónde se guardan la configuración, los registros, las descargas y los archivos de tiempo de ejecución? | La configuración y los registros persisten tras reiniciar, y el usuario de la aplicación puede escribir en ellos. | La configuración desaparece después de reiniciar o la aplicación muestra errores de acceso denegado. |
| Ruta de red | ¿El contenedor puede conectarse al proveedor del modelo, al punto de conexión local y a la API de mensajería? | Las comprobaciones del proveedor, las llamadas a la puerta de enlace y el acceso al panel funcionan desde la capa prevista. | El modelo o el bot falla aunque parezca que la aplicación se instaló correctamente. |
| Credenciales y acceso | ¿Las claves de API, los tokens del bot y los usuarios de la lista de permitidos están configurados de forma segura? | Los mensajes de prueba privados funcionan y los registros no muestran errores de token ni de acceso. | El token del bot no es válido, se ha expuesto o el ID de usuario permitido es incorrecto. |
| Validación del reinicio | ¿La configuración sigue funcionando después de reiniciar la puerta de enlace o el servicio? | El bot responde, el panel funciona correctamente y los registros no muestran problemas tras reiniciar. | La configuración anterior sigue activa o los nuevos ajustes no se conservan. |
Qué puede ver el sistema host
El sistema host es el sistema operativo real del servidor doméstico. Puede ver las carpetas del host, los contenedores de Docker, las interfaces de red, los dispositivos de almacenamiento y los servicios del sistema.
Si una aplicación se ejecuta en Docker, es posible que el host no vea la ruta interna de la aplicación de la misma forma que el contenedor. En su lugar, el host puede ver un volumen de Docker, una carpeta montada mediante bind o metadatos del contenedor.
Por eso, una ruta como /opt/data o /app/config puede no significar lo mismo en el host y dentro del contenedor.
Qué puede ver el contenedor
Un contenedor ve su propio sistema de archivos. También puede ver las carpetas del host que se hayan montado en el contenedor. La ruta del contenedor es la ruta desde el punto de vista de la aplicación.
Docker explica que un montaje bind monta un archivo o directorio de la máquina host en un contenedor, mientras que un volumen de Docker se crea en el directorio de almacenamiento de Docker en el host y Docker lo administra mediante el modelo de almacenamiento de los montajes bind de Docker.
Esta distinción importa porque un contenedor solo puede acceder a las rutas del host que se montan en él. Si la aplicación no encuentra un archivo, puede que el archivo exista en el host, pero no esté montado en la ruta esperada del contenedor.
Dónde suelen estar la configuración de la aplicación y los datos de ejecución
La configuración de la aplicación, los registros, las descargas y los datos de ejecución pueden estar en distintas ubicaciones, según cómo se haya empaquetado la aplicación. Algunos datos pueden estar dentro del contenedor, otros en un volumen de Docker y otros montados desde el host.
En un agente autoalojado, los tipos de datos habituales incluyen:
- configuración del proveedor de modelos;
- configuración de la puerta de enlace;
- token del bot o configuración de mensajería;
- registros y estado de la sesión;
- descargas temporales;
- resultados de herramientas;
- datos de ejecución específicos de la aplicación.
La pregunta importante no es solo «¿dónde está el archivo?», sino «¿qué capa es la propietaria de este archivo y qué usuario puede modificarlo?»

Por qué la confusión con las rutas provoca problemas de permisos y datos
La confusión con las rutas causa dos problemas habituales. En primer lugar, los usuarios editan un archivo en el host, pero el contenedor lee otro archivo desde su propia ruta. En segundo lugar, los usuarios ejecutan la configuración como root y crean archivos que el usuario de la aplicación no puede modificar más adelante.
Los montajes de enlace también pueden ocultar archivos existentes del contenedor si se monta una carpeta del host sobre un directorio del contenedor que no está vacío. En ese caso, puede parecer que faltan archivos aunque solo estén ocultos por el montaje.
Antes de solucionar un problema con los datos de una aplicación, comprueba la capa de ejecución, las rutas montadas, el propietario de los archivos y el usuario del contenedor.
Cómo configurar paso a paso un agente autoalojado
La configuración de un agente autoalojado debería avanzar desde las comprobaciones de bajo riesgo hasta la configuración y, luego, la validación. No empieces por cambiar permisos ni reiniciar servicios hasta saber qué capa está fallando.
Paso 1: Instala o abre la aplicación desde el panel de tu servidor
Empieza con el método de instalación o inicio de aplicaciones más sencillo que admita tu servidor doméstico. Si el servidor ofrece un panel de aplicaciones, úsalo para confirmar que Hermes Agent está instalado, visible y en ejecución.
En esta etapa, no entres en el contenedor a menos que la aplicación lo requiera. Primero confirma el estado en el panel, la versión de la aplicación si se muestra y si hay una página de configuración disponible.
Si la aplicación no se inicia, consulta los registros antes de cambiar los archivos de configuración.
Paso 2: Confirma la IP del host y el acceso a la red
Confirma la dirección IP del host y asegúrate de que tu navegador o terminal pueda acceder al servidor. Según la configuración, se puede usar la misma IP para acceder al panel, por SSH o a la puerta de enlace local.
Luego confirma que haya acceso a la red externa. Un bot de mensajería no responderá si el contenedor no puede comunicarse con la API de mensajería, y un proveedor de modelos fallará si el servidor no puede comunicarse con el punto de conexión del modelo.
Esta comprobación ayuda a distinguir entre «falló la configuración de la aplicación» y «falló el acceso a la red».
Paso 3: Entra en el contenedor con el usuario correcto
Si es necesario configurar el terminal del contenedor, entra en él con el usuario previsto por la aplicación. Esto es importante porque los archivos creados por el usuario incorrecto pueden provocar errores de permisos más adelante.
No trates el shell del host y el shell del contenedor como si fueran el mismo entorno. Es posible que un comando que funciona en el host no esté disponible dentro del contenedor, y que una ruta de archivo dentro del contenedor no exista en el host.
Antes de ejecutar comandos de configuración, confirma lo siguiente:
- Estás dentro del contenedor correcto.
- Estás usando el usuario previsto del contenedor.
- Estás en el directorio de trabajo previsto.
- El comando requerido de la aplicación está disponible.
- Sabes cómo salir del contenedor y volver a entrar.
Paso 4: Activa el entorno de la aplicación antes de ejecutar comandos de configuración
Algunas aplicaciones autoalojadas usan un entorno virtual o una configuración de shell específica para la aplicación. Si el entorno no está activado, es posible que no se encuentre el comando de la aplicación o que se ejecute con dependencias incorrectas.
Este paso no es un mero trámite. Garantiza que el asistente de configuración, el comando de la pasarela y el comando de configuración del modelo se ejecuten en el mismo contexto de ejecución que la aplicación.
Si un comando falla de forma inesperada, comprueba que estés en el contenedor correcto y que el entorno de la aplicación esté activo antes de reinstalar nada.
Paso 5: Conecta un proveedor de modelos o un servicio de modelo local
Configura el proveedor del modelo, el endpoint personalizado o el servicio de modelo local. Asegúrate de que la URL base, la clave API, el nombre del modelo y los ajustes relacionados con el contexto sean compatibles con el proveedor que utilizas.
Si falla la configuración del modelo, comprueba lo siguiente en este orden:
- ¿La clave API es correcta?
- ¿Se puede acceder a la URL base desde el contenedor?
- ¿El endpoint admite el nombre del modelo?
- ¿La aplicación necesita un modelo con contexto largo?
- ¿Hay problemas de red o DNS dentro del contenedor?
Evita confundir los errores del modelo con los de mensajería. Que un bot de Telegram no responda y que falle un proveedor de modelos solo están relacionados porque el agente necesita ambos para completar el flujo de trabajo.
Paso 6: Configura la pasarela de mensajería
La pasarela de mensajería conecta el entorno de ejecución del agente con una plataforma de mensajería. En el caso de Telegram, normalmente se necesita un token de bot y una identidad de usuario autorizada.
Una buena configuración de la pasarela debe definir quién puede enviar mensajes al agente, qué token de bot se usa y si el bot está pensado para chats privados, grupales o ambos.
Nunca des por sentado que un bot de mensajería es una interfaz pública. Un agente autoalojado puede tener acceso a herramientas, datos locales o acciones que no deberían estar disponibles para todos los usuarios que puedan acceder al bot.
Paso 7: Reinicia la pasarela y aplica la nueva configuración
Después de cambiar el modelo o la pasarela de mensajería, puede que haya que reiniciar la pasarela para que se aplique la nueva configuración. El comportamiento del reinicio es importante porque la configuración puede parecer completa, pero seguir usando los ajustes antiguos.
Después del reinicio, valida desde el lado del usuario y desde el lado del servidor. Envía un mensaje de prueba, comprueba el estado en el panel e inspecciona los registros para detectar errores de permisos, tokens o red.
Si la reconfiguración no se mantiene después del reinicio, vuelve a revisar la ruta de datos y los límites de permisos.

Permisos, tokens y control de acceso
Los agentes autoalojados combinan los permisos del entorno de ejecución local con credenciales externas. Esto significa que una configuración puede funcionar técnicamente y aun así ser insegura si los tokens, las listas de permitidos o los límites entre usuarios no son correctos.
Por qué es importante el usuario del contenedor
El usuario del contenedor determina qué archivos puede leer y escribir la aplicación dentro del contenedor. Si los comandos de configuración se ejecutan como root y luego la aplicación se ejecuta como un usuario sin privilegios de root, es posible que la aplicación no pueda acceder a sus datos.
Esto suele aparecer como un error de permisos dentro de la ruta de datos de la aplicación. La solución no siempre es seguir usando root. En muchos casos, es mejor restablecer la propiedad correcta y ejecutar la aplicación como el usuario previsto.
Usa root solo cuando sea necesario para un paso específico de recuperación y evita crear como root archivos habituales de la aplicación.
Por qué deben protegerse las claves de API y los tokens de bot
Las claves de API y los tokens de bot son credenciales. Una clave de API de modelo puede dar acceso a un proveedor de modelos. Un token de bot puede autorizar solicitudes en nombre del bot.
No incluyas estos valores en repositorios públicos, capturas de pantalla, registros compartidos ni mensajes de soporte. Al solucionar problemas, oculta los tokens antes de compartir cualquier configuración o registro.
Si se ha expuesto un token, rótalo en lugar de confiar en que nadie lo usará.
Cómo controla el acceso privado la lista de usuarios permitidos
Una lista de usuarios permitidos limita quiénes pueden interactuar con el agente a través de una pasarela de mensajería. Esto es importante porque es posible que más personas de las esperadas puedan acceder a un bot de mensajería.
Para los chats privados con IA, usa la lista de usuarios permitidos más reducida que sea razonable. Confirma que el ID del usuario autorizado sea correcto y que los mensajes de prueba provengan de esa cuenta.
Si varias personas necesitan acceso, añádelas de forma intencionada en lugar de dejar el bot abierto.
Por qué los bots de mensajería no deben tratarse como interfaces públicas
Un bot de mensajería puede parecer una interfaz de chat normal, pero detrás puede haber un agente autoalojado con acceso a modelos, herramientas, sesiones y permisos de ejecución locales.
Eso lo hace diferente de un simple bot de notificaciones. Debe tener reglas de acceso claras, tokens protegidos y una ruta de red controlada.
En los chats de grupo, actúa con cautela. Los permisos del grupo, el modo de privacidad y el estado de administrador del bot pueden cambiar qué mensajes puede ver o responder.
Problemas habituales de configuración y cómo solucionarlos
La mayoría de los problemas de configuración se pueden atribuir a una de seis capas: entorno de ejecución, ruta de datos, permisos, pasarela, secreto o validación.
Errores de permisos en la ruta de datos de la aplicación
Un error de permisos suele significar que el usuario actual de la aplicación no puede leer o escribir un archivo o una carpeta necesarios. Esto puede ocurrir cuando un comando de configuración anterior creó archivos como usuario root o cuando una carpeta montada tiene un propietario incorrecto.
Comprueba primero lo siguiente:
- ¿Estás dentro del contenedor o en el host?
- ¿Qué usuario está ejecutando la aplicación?
- ¿Quién es el propietario de la carpeta de datos de la aplicación?
- ¿La ruta de datos de la aplicación está montada desde el host?
- ¿Se ejecutó anteriormente un comando de configuración como usuario root?
No cambies los permisos de forma recursiva en carpetas amplias, a menos que entiendas cuál es el destino. Corrige únicamente la ruta específica más pequeña que sea necesaria.
El bot no responde después de la configuración
Un bot puede dejar de responder aunque el propio Hermes Agent esté en funcionamiento. El problema puede deberse al token, a la lista de usuarios permitidos, a la pasarela de mensajería, al acceso a la red o a los permisos del grupo.
Comprueba en este orden:
- Confirma que el token del bot sea correcto.
- Confirma que el ID de usuario esté autorizado.
- Confirma que se haya reiniciado la pasarela después de la configuración.
- Confirma que el contenedor pueda conectarse a la API de mensajería.
- Comprueba los registros de la aplicación en busca de errores de token, red o permisos.
- Prueba el chat privado antes de diagnosticar los problemas del chat grupal.
La prueba del chat privado suele ser más sencilla que la del chat grupal, porque los permisos de grupo añaden variables adicionales.
La configuración del proveedor del modelo es incorrecta
Si el bot de mensajería responde, pero fallan las respuestas del modelo, puede que el problema esté en el proveedor del modelo. Comprueba la URL base, la clave de API, el nombre del modelo y la compatibilidad del punto de conexión.
Si usas puntos de conexión de modelos locales, comprueba también que el servicio del modelo esté en ejecución y sea accesible desde el contenedor. Puede que un servicio accesible desde el host no lo sea desde el contenedor si la configuración de red es diferente.
Mantén la solución de problemas del proveedor separada de la de mensajería. Así evitarás modificar el bot cuando el problema real esté en la conexión con el modelo.
El contenedor no puede conectarse a la API de mensajería
Si el contenedor no puede conectarse a la API de mensajería, la puerta de enlace no podrá recibir ni enviar mensajes correctamente. Esto puede deberse a problemas de DNS, reglas del firewall, ajustes del proxy o falta de acceso a internet saliente.
Comprueba si el host tiene acceso a internet y si el contenedor tiene acceso a internet. No siempre son lo mismo.
Si el servidor doméstico usa una VPN, un proxy o una red restringida, confirma que el contenedor pueda realizar solicitudes HTTPS salientes.
Los permisos del chat grupal o el modo de privacidad impiden responder
El comportamiento del chat grupal es más complejo que el del chat privado. Puede que un bot responda en privado, pero no en un grupo porque no puede ver el mensaje, no tiene los permisos adecuados o le afectan los ajustes de privacidad.
Empieza validando el chat privado. Después, prueba el chat grupal por separado.
Para usarlo en grupos, comprueba si hay que mencionar directamente al bot, si necesita permisos de administrador y si su configuración de privacidad le permite recibir los mensajes necesarios.
Cómo comprobar si Hermes Agent funciona
La configuración no está completa solo porque la instalación haya terminado. Está completa cuando el modelo, la puerta de enlace, los permisos, el panel, los registros y el proceso de reconfiguración superan las comprobaciones básicas.
El asistente de configuración se completa sin errores
El asistente de configuración debería completarse sin errores por falta de comandos, errores del proveedor ni errores de permisos. Si falla, identifica qué capa falló antes de volver a intentarlo.
Un error del asistente de configuración suele pertenecer a una de estas categorías:
- credenciales del proveedor del modelo;
- entorno de ejecución;
- permisos del contenedor;
- falta un comando de la aplicación;
- acceso a la red;
- configuración de la puerta de enlace.
Usa esa categoría para decidir cuál es la siguiente comprobación.
El bot de mensajería responde a un mensaje de prueba privado
La validación más sencilla de la mensajería consiste en enviar un mensaje de prueba privado. Envía un mensaje básico y confirma que el bot responda.
Si el chat privado funciona, es probable que el token, la lista de permitidos, la puerta de enlace y la conexión con el modelo estén configurados correctamente. Si el chat grupal sigue fallando, céntrate en los permisos del grupo y la configuración de privacidad en lugar de reinstalar la aplicación.
El chat privado debería ser tu primera prueba de mensajería satisfactoria.
El panel muestra que el agente está en funcionamiento
El panel debería indicar que el agente o la pasarela está en funcionamiento, según el sistema. El estado del panel es útil porque ofrece una vista desde el servidor, en lugar de depender únicamente de la aplicación de mensajería.
Si el panel muestra un estado detenido o no saludable, consulta los registros antes de cambiar los tokens o los ajustes del modelo.
El estado del panel y la respuesta del bot deben coincidir. Si uno funciona y el otro falla, la diferencia indica qué capa está fallando.
Los registros no muestran errores de permisos ni de red
Los registros no deberían mostrar repetidamente errores de permiso denegado, token no válido, proveedor inaccesible, fallo de la pasarela o tiempo de espera de la red.
Usa los registros para determinar el siguiente paso. Un error de permisos apunta a la propiedad de los archivos o al usuario del contenedor. Un error de red apunta a la accesibilidad de la API. Un error de token apunta a la configuración de las credenciales.
Evita corregir todas las capas a la vez. Cambia una variable, reinicia si es necesario y vuelve a probar.
La reconfiguración funciona después de reiniciar
Una configuración duradera debe mantenerse tras reiniciar o volver a configurar. Después de cambiar los ajustes del modelo o de la pasarela, reinicia el servicio o la pasarela necesarios y confirma que los nuevos ajustes sigan aplicándose.
Si la configuración desaparece después de reiniciar, comprueba dónde se almacena y si la ruta de datos de la aplicación es persistente.
Aquí es donde resulta práctico conocer las rutas del host, las rutas del contenedor y los volúmenes montados.
Cómo funciona esto en un entorno real de servidor doméstico
En un entorno real de servidor doméstico, el modelo general de configuración no cambia: confirma la capa de ejecución, comprueba las rutas de datos, protege las credenciales, configura el acceso a la pasarela y valida el estado mediante los registros y el panel.
Una guía de configuración específica para el dispositivo puede indicar entonces la ruta exacta de los comandos. Por ejemplo, el flujo de configuración de Hermes Agent en ZimaOS explica cómo configurar Hermes Agent, incluida la configuración del proveedor de modelos, la vinculación de un bot de Telegram, el acceso al contenedor de Hermes como usuario de la aplicación, la activación del entorno de la aplicación, la ejecución de comandos de configuración, la comprobación del estado en el panel y la solución de errores de permisos o de respuesta del bot.
Para los usuarios que ejecutan aplicaciones autoalojadas, pasarelas de mensajería y flujos de trabajo ligeros con agentes en un servidor compacto siempre encendido, servidor doméstico con IA ZimaBoard 2 encaja en el tipo de entorno donde es necesario comprender en conjunto las aplicaciones de Docker, el acceso al terminal, los servicios locales y las rutas de datos específicas de cada aplicación. No es la única forma de alojar un agente, pero es un ejemplo pertinente del tipo de flujo de trabajo en un servidor doméstico que describe este artículo.
La lección clave es aplicable en cualquier entorno: no memorices una sola orden de configuración. Entiende en qué capa estás trabajando y cómo validar el resultado.
Preguntas frecuentes
¿Puedo configurar Hermes Agent únicamente desde un panel web?
En muchos casos, un panel web puede bastar para la configuración básica, sobre todo si permite configurar modelos y la pasarela. Configurar desde la terminal del contenedor resulta necesario cuando el panel no ofrece una opción requerida o cuando la resolución de problemas exige comandos de la aplicación. Si es posible, empieza con la WebUI y usa la terminal del contenedor solo cuando la configuración lo requiera.
¿Por qué tengo que acceder al contenedor en lugar de usar la terminal del host?
Algunos comandos de la aplicación solo están disponibles dentro del contenedor, porque ahí se encuentran el entorno de ejecución y las dependencias de la aplicación. Si ejecutas el mismo comando en el host, puede fallar o afectar al entorno equivocado. Acceder al contenedor con el usuario correcto ayuda a garantizar que los cambios de configuración se apliquen a la propia aplicación.
¿Cuál es la diferencia entre los datos del host y los datos de la aplicación del contenedor?
Los datos del host se almacenan en el sistema de archivos del servidor doméstico. Los datos de la aplicación del contenedor pueden estar dentro del contenedor, en un volumen administrado por Docker o en una carpeta del host montada en el contenedor. Que una carpeta tenga la misma ruta visible no significa necesariamente que sea la misma en las capas del host y del contenedor, así que verifica los montajes y las ubicaciones de los datos de la aplicación antes de editar archivos.
¿Por qué Hermes Agent muestra un error de permisos?
Un error de permisos suele significar que el usuario de la aplicación no puede leer ni escribir un archivo o una carpeta necesarios. Esto puede ocurrir si los archivos se crearon como root, si una carpeta montada tiene un propietario incorrecto o si el contenedor se ejecuta con un usuario distinto del esperado. Comprueba la capa de ejecución, el usuario del contenedor, la ruta de datos de la aplicación y la propiedad de los archivos antes de cambiar los permisos de forma generalizada.
¿Por qué no responde mi bot de Telegram?
Es posible que un bot de Telegram no responda porque el token es incorrecto, el ID de usuario no está autorizado, no se reinició la pasarela, el contenedor no puede conectarse a la API de Telegram o los permisos del chat grupal bloquean el mensaje. Primero prueba en un chat privado, ya que así se eliminan muchas variables relacionadas con los grupos. Luego revisa los registros para detectar errores de token, red o permisos.
¿Debería exponer Hermes Agent directamente a Internet?
La exposición pública directa no suele ser la opción predeterminada más recomendable para un agente alojado por cuenta propia. Un bot de mensajería o una pasarela pueden conectarse a herramientas, al acceso a modelos y posiblemente a acciones de ejecución locales, por lo que conviene restringir el acceso. Usa métodos de acceso privado, credenciales robustas, listas de permitidos y permisos limitados antes de considerar una configuración de acceso público.
Soporte y consejos
Más para leer

Qué comprobar antes de cargar un modelo de la comunidad en Transformers
Usa la actualización del entorno aislado de Jinja para Transformers para revisar la procedencia del modelo, las plantillas de chat, el código remoto, los...

Ejecuta Mirage localmente: OCR y detección de objetos a partir de una sola imagen
Prueba el pequeño modelo de visión local de Cactus Compute, valida el OCR y la extracción de objetos con datos reales y comprende las...

Cómo programar un agente de programación en Open WebUI en un servidor doméstico
Configura una automatización de agente de programación solo para informes en Open WebUI, selecciona su terminal y espacio de trabajo, y verifica los permisos,...



