Archivo de configuración de Hermes Agent
Una vez completada la instalación, toda la configuración y los datos se guardan en~/.hermes/la siguiente ubicación:
~/.hermes/ ├── config.yaml # 主配置文件（模型、工具、终端后端等） ├── .env # API 密钥和 Secret（不提交到版本库） ├── auth.json # OAuth 凭据（Nous Portal 等） ├── SOUL.md # Agent 人格设定文件 ├── memories/ # 持久记忆（MEMORY.md、USER.md） ├── skills/ # 技能文件（Agent 自动创建和管理） ├── cron/ # 定时任务配置 ├── sessions/ # 网关会话记录 └── logs/ # 日志（API 密钥自动脱敏）
Principios importantes：
- Secrets (claves API, tokens, contraseñas)→ Guárdalos en
.env - Configuración normal (modelos, herramientas, backend de terminal, etc.)→ Guárdala en
config.yaml - Usa el
hermes config set KEY VALUEcomando: se enrutará automáticamente al archivo correcto.
Seleccionar el proveedor de modelos
Ejecuta el siguiente comando para entrar en la selección interactiva:
hermes model
Ruta recomendada: Nous Portal (lo más sencillo)
Una suscripción cubre más de 300 modelos + Tool Gateway (búsqueda web, generación de imágenes, TTS, navegador en la nube), sin necesidad de solicitar varias API Key por separado:
hermes setup
Tras ejecutarlo, inicia sesión mediante OAuth y la configuración del proveedor y la activación de la puerta de enlace de herramientas (Tool Gateway) se completan automáticamente.
Resumen de proveedores comunes
| Proveedor | Características | Método de configuración |
|---|---|---|
| Nous Portal | Por suscripción, más de 300 modelos, Tool Gateway | hermes setup --portalInicio de sesión OAuth |
| Anthropic | Serie Claude, la suscripción Max permite OAuth | ANTHROPIC_API_KEYo OAuth |
| OpenAI Codex | ChatGPT OAuth, modelos Codex | hermes model→ OAuth con código de dispositivo |
| OpenRouter | Enrutamiento de múltiples proveedores, más de 200 modelos | OPENROUTER_API_KEY |
| xAI Grok OAuth | Suscripción a SuperGrok / Premium+, sin necesidad de API Key | hermes model → xAI Grok OAuth |
| GitHub Copilot | Suscripción a Copilot (GPT, Claude, Gemini) | hermes model → OAuth |
| Google AI Studio | Serie Gemini | GOOGLE_API_KEY |
| DeepSeek | Serie DeepSeek | DEEPSEEK_API_KEY |
| Modelo local (Ollama) | Totalmente local, sin costo | Configurar una URL Base personalizada |
Requisitos de la ventana de contexto del modeloHermes requiere que el modelo soporte al menos64,000 tokensde contexto. Al usar un modelo local, asegúrate de que los parámetros de inicio establezcan un tamaño de contexto suficiente (por ejemplo,
--ctx-size 65536）。
Cambiar de proveedor
Puedes cambiar en cualquier momento sin modificar ningún código:
hermes model
Tres modos de Setup
Al ejecutar por primera vezhermes setup, se te pedirá elegir un modo de inicialización:
Modo 1: Quick Setup (Nous Portal)
Inicio de sesión OAuth gratuito, configura automáticamente el modelo + Tool Gateway (búsqueda web, generación de imágenes, TTS, navegador).Recomendado para nuevos usuarios.
Modo 2: Full Setup
Configura manualmente uno por uno el proveedor, los conjuntos de herramientas, las plataformas de mensajería, etc. Adecuado para usuarios con necesidades específicas y que tienen su propia API Key.
Modo 3: Blank Slate (punto de partida en blanco)
Solo mantiene el conjunto mínimo de ejecución (proveedor, herramientas de archivos, herramientas de terminal); todo lo demás está desactivado. Adecuado para usuarios avanzados que necesitan controlar con precisión los límites de las capacidades del Agent. El modo en blanco escribe la configuración explícitamente para evitar quehermes updateposteriormente se activen automáticamente nuevas funciones.
Iniciar la primera conversación
Una vez completada la configuración, inicia Hermes:
hermes # 经典 CLI 模式 hermes --tui # 现代 TUI 模式（推荐，支持鼠标、弹窗等）
Al iniciar, se mostrará un banner de bienvenida con información sobre el modelo actual, las herramientas disponibles y las habilidades cargadas.
Verificar que todo funciona correctamente
Prueba con un prompt simple pero específico:
Revisa mi directorio actual, dime qué archivos contiene e identifica el archivo principal de entrada del proyecto.
Indicadores de éxito：
- El banner muestra correctamente el modelo/proveedor que elegiste
- El Agent responde correctamente, sin mensajes de error
- Puede invocar herramientas cuando es necesario (terminal, lectura de archivos, etc.)
- La conversación puede durar más de una ronda
Verificar la recuperación de la sesión
Confirma que la continuidad entre sesiones funciona correctamente:
Revisa mi directorio actual, dime qué archivos contiene e identifica el archivo principal de entrada del proyecto.
Operaciones básicas de la interfaz TUI
Ejecutahermes --tuiAl entrar en el modo TUI moderno, las operaciones comunes son:
| Operación | Atajo de teclado |
|---|---|
| Enviar mensaje | Enter |
| Salto de línea en entrada multilínea | Alt+EnteroCtrl+J |
| Interrumpir la tarea actual del Agent | Después de introducir directamente un nuevo mensajeEnter |
| Interrupción forzada | Ctrl+C |
| Ver todos los comandos | Introduce/Activar el autocompletado |
Comandos de barra diagonal (slash) principales
| Comando | Función |
|---|---|
/help |
Muestra todos los comandos disponibles |
/tools |
Lista las herramientas actualmente habilitadas |
/model |
Cambiar de modelo en tiempo de ejecución |
/memory |
Ver y gestionar la memoria del Agent |
/skills |
Ver y gestionar habilidades |
/save |
Guardar la conversación actual |
/new |
Iniciar una nueva sesión (conservando la configuración actual) |
/verbose |
Cambiar el nivel de detalle de la salida de las llamadas a herramientas |
/voice on |
Habilitar el modo de entrada por voz |
Configuración del backend de ejecución de terminal
Hermes admite seis entornos de ejecución de terminal, que determinan dónde se ejecutan los comandos Shell del Agent:
| Backend | Dónde se ejecuta el comando | Nivel de aislamiento | Caso de uso |
|---|---|---|---|
local(por defecto) |
Ejecución directa en la máquina local | Ninguno | Desarrollo, uso personal |
docker |
Dentro de un contenedor Docker | Aislamiento total | Sandbox de seguridad, CI/CD |
ssh |
Servidor remoto | Límite de red | Desarrollo remoto, máquinas de alto rendimiento |
modal |
Sandbox en la nube de Modal | Total (VM en la nube) | Computación en la nube temporal, evaluaciones |
daytona |
Espacio de trabajo Daytona | Total (contenedor en la nube) | Entorno de desarrollo en la nube gestionado |
singularity |
Contenedor Singularity | Aislamiento de espacios de nombres | Clústeres HPC, máquinas compartidas |
Cambiar al backend de Docker (recomendado para producción)
hermes config set terminal.backend docker
o edita directamente~/.hermes/config.yaml：
terminal: backend: docker docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
Nota de seguridad:El backend por defecto
localotorga al Agent los mismos permisos del sistema de archivos que tú. Si deseas limitar el alcance de las operaciones del Agent, cambia aldockerbackend; es la forma más sencilla y eficaz.
Gestión de conjuntos de herramientas (toolkits)
Hermes agrupa más de 70 herramientas integradas en 28 conjuntos de herramientas, que se pueden habilitar o desactivar según sea necesario:
hermes tools # 打开可视化工具集管理界面（curses UI）
Principales conjuntos de herramientas
| Conjunto de herramientas | Capacidades incluidas |
|---|---|
filesystem |
Lectura/escritura de archivos, operaciones de directorios |
terminal |
Ejecución de comandos Shell |
web |
Búsqueda web, extracción de contenido |
browser |
Automatización completa del navegador (requiere Playwright) |
code |
Ejecución de código (execute_codeherramienta) |
vision |
Análisis de imágenes |
audio |
Conversión de voz a texto, TTS |
memory |
Herramientas de gestión de memoria |
skills |
Herramientas de gestión de habilidades |
mcp |
Conjunto de herramientas del servidor MCP (dinámico) |
Desactivar un conjunto de herramientas: el conjunto de herramientas desaparece por completo del prompt del sistema, no solo se desactiva; de esta forma se ahorran tokens y se evita que el Agent utilice herramientas que no debe.
Comandos comunes de gestión de configuración
# 查看当前完整配置 hermes config # 用编辑器打开 config.yaml hermes config edit # 设置单个配置值（自动路由到正确文件） hermes config set model anthropic/claude-sonnet-4-6 hermes config set terminal.backend docker hermes config set OPENROUTER_API_KEY sk-or-... # 自动存入 .env # 检查是否有新版本引入的配置项未填写 hermes config check # 交互式补全缺失配置 hermes config migrate # 诊断所有配置问题 hermes doctor # 更新到最新版本 hermes update
Solución de problemas comunes
Problema 1:hermes: command not found
# 刷新 Shell 配置 source ~/.bashrc # o source ~/.zshrc # 如果仍然找不到，检查 PATH echo $PATH # 确保 ~/.local/bin 在其中 export PATH="$HOME/.local/bin:$PATH"
Problema 2:API key not set/ El modelo no responde
# 重新配置提供商 hermes model # 或直接设置 API Key hermes config set OPENROUTER_API_KEY sk-or-...
Problema 3: Respuesta vacía o caracteres corruptos (mojibake)
Puede ser un error de autenticación del proveedor o de selección del modelo:
# 重新选择模型 hermes model # 全面诊断 hermes doctor
Problema 4: Error por ventana de contexto insuficiente
Hermes requiere que el modelo admita al menos 64K tokens de contexto. Cambie a un modelo que admita un contexto más amplio, o aumente el parámetro de contexto al usar un modelo local (por ejemplo, Ollama:OLLAMA_NUM_CTX=65536）。
Problema 5:hermes --continueNo se encuentra la sesión anterior
# 查看所有会话 hermes sessions list # 确认当前 Profile hermes profile list
Kit de herramientas universal de recuperación
Si encuentra cualquier problema extraño, ejecute en el siguiente orden:
hermes doctor # 1. 诊断 hermes model # 2. 检查模型配置 hermes setup # 3. 重新向导配置 hermes sessions list # 4. 查看会话状态 hermes --continue # 5. 尝试恢复会话 hermes gateway status # 6. 检查网关状态（如已启用）
Vista previa de configuración avanzada
Después de completar la instalación básica, las siguientes funciones se pueden activar según sea necesario (se detallan en los capítulos siguientes):
Integrar plataformas de mensajería
hermes gateway setup # 交互式配置 Telegram、Discord、Slack 等 hermes gateway # 启动消息网关
Habilitar el modo de voz
# 安装语音依赖 cd ~/.hermes/hermes-agent uv pip install -e ".[voice]" # 在 CLI 中启用 /voice on # 按 Ctrl+B 开始录音
Integrar servidores MCP
En~/.hermes/config.yamlagregar en:
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
hermes mcp # 交互式管理 MCP 服务器
Integración con editores (ACP)
hermes acp # 启动编辑器 Agent 模式（VS Code / Zed / JetBrains）
Referencia rápida de comandos
| Comando | Descripción |
|---|---|
hermes |
Iniciar conversación CLI |
hermes --tui |
Iniciar conversación TUI (recomendado) |
hermes desktop |
Iniciar aplicación de escritorio |
hermes model |
Seleccionar/cambiar proveedor y modelo de LLM |
hermes setup |
Asistente de configuración completo |
hermes setup --portal |
Configuración rápida de Nous Portal |
hermes tools |
Configurar conjunto de herramientas |
hermes doctor |
Diagnosticar problemas de configuración |
hermes update |
Actualizar a la última versión |
hermes gateway |
Iniciar puerta de enlace de mensajes |
hermes gateway setup |
Configurar plataforma de mensajería |
hermes --continue |
Restaurar sesión reciente |
hermes config set KEY VAL |
Establecer elementos de configuración |
hermes sessions list |
Ver historial de sesiones |
hermes profile list |
Ver perfil del agente |