Файл конфигурации Hermes Agent

После установки вся конфигурация и данные хранятся в~/.hermes/Ниже:

~/.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 密钥自动脱敏）

Важные принципы：

• Секреты (ключи API, токены, пароли)→ Хранить.env
• Общая конфигурация (модели, инструменты, терминальные бэкенды и т. д.)→ Хранитьconfig.yaml
• Использованиеhermes config set KEY VALUEКоманды автоматически направляются в нужный файл

Выберите поставщика модели

Выполните следующую команду, чтобы перейти к интерактивному выбору:

hermes model

Рекомендуемый путь: Nous Portal (самый простой)

Одна подписка охватывает 300+ моделей + Tool Gateway (веб-поиск, генерация изображений, TTS, облачный браузер), не нужно отдельно запрашивать несколько ключей API:

hermes setup

После выполнения войдите через OAuth, а настройка провайдера и активация Tool Gateway выполняются автоматически.

Обзор распространённых провайдеров

Требования к контекстному окну модели: Hermes требует, чтобы модель поддерживала как минимум64,000 tokensконтекста. При использовании локальных моделей убедитесь, что в параметрах запуска задан достаточный размер контекста (например,--ctx-size 65536）。

Сменить провайдера

Вы можете переключиться в любое время, не изменяя код:

hermes model

Три режима настройки

Первый запускhermes setupВ этот момент вам будет предложено выбрать режим инициализации:

Режим 1: Быстрая настройка (Nous Portal)

Бесплатный вход через OAuth, автоматически настраивает модели + Tool Gateway (веб-поиск, генерация изображений, TTS, браузер).Рекомендуется для новых пользователей.

Режим 2: Полная настройка

Вручную настраивайте провайдеров, наборы инструментов, платформы обмена сообщениями и т. д. по одному. Подходит для пользователей с четкими требованиями и собственными API-ключами.

Режим 3: Чистый лист (Пустая отправная точка)

Оставьте только минимальный набор времени выполнения (провайдеры, файловые инструменты, терминальные инструменты), всё остальное отключено. Подходит для продвинутых пользователей, которым нужен точный контроль над границами возможностей агента. Пустой режим явно записывает конфигурацию, чтобы предотвратитьhermes updateавтоматическое включение новых функций впоследствии.

Начните первый разговор

После завершения настройки запустите Hermes:

hermes          # 经典 CLI 模式
hermes --tui    # 现代 TUI 模式（推荐，支持鼠标、弹窗等）

После запуска отобразится приветственный баннер с текущей моделью, доступными инструментами и загруженными навыками.

Убедитесь, что всё работает нормально

Проверьте с помощью простого, но конкретного запроса:

Check my current directory, tell me what files are in it, and identify the main project entry file.

Индикатор успеха：

• Баннер правильно отображает выбранную вами модель/провайдера
• Агент отвечает нормально, без сообщений об ошибках
• Может вызывать инструменты при необходимости (терминал, чтение файлов и т. д.)
• Беседы могут продолжаться более одного хода

Проверить восстановление сеанса

Подтвердить, что непрерывность между сеансами работает корректно:

Check my current directory, tell me what files are in it, and identify the main project entry file.

Базовые операции в интерфейсе TUI

Запуститеhermes --tuiПосле входа в современный режим TUI, обычные операции:

Основные слеш-команды

Конфигурация бэкенда выполнения терминала

Hermes поддерживает шесть сред выполнения терминала, определяющих, где выполняются Shell-команды Agent:

Переключиться на бэкенд Docker (рекомендуется для продакшена)

hermes config set terminal.backend docker

Или отредактируйте напрямую~/.hermes/config.yaml：

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"

Инструкции по безопасности: По умолчаниюlocalБэкенд даёт Агенту те же права доступа к файловой системе, что и у вас. Если вы хотите ограничить область операций Агента, переключитесь наdockerБэкенд — это самый простой и эффективный способ.

Управление наборами инструментов

Hermes группирует 70+ встроенных инструментов в 28 наборов инструментов, которые можно включать или отключать по мере необходимости:

hermes tools    # 打开可视化工具集管理界面（curses UI）

Основные наборы инструментов

Отключить определённый набор инструментов: Этот набор инструментов полностью исчезает из системного промпта, а не просто отключается — это экономит токены и не позволяет Агенту неправильно использовать инструменты, которые ему не следует использовать.

Общие команды управления конфигурацией

# 查看当前完整配置
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

Распространённые проблемы

Вопрос 1:hermes: command not found

# 刷新 Shell 配置
source ~/.bashrc   # или  source ~/.zshrc

# 如果仍然找不到，检查 PATH
echo $PATH
# 确保 ~/.local/bin 在其中
export PATH="$HOME/.local/bin:$PATH"

Вопрос 2:API key not set/ Модель не отвечает

# 重新配置提供商
hermes model

# 或直接设置 API Key
hermes config set OPENROUTER_API_KEY sk-or-...

Проблема 3: Пустые или искажённые ответы

Это может быть связано с неправильной аутентификацией у провайдера или выбором модели:

# 重新选择模型
hermes model

# 全面诊断
hermes doctor

Проблема 4: Ошибка недостаточного контекстного окна

Hermes требует, чтобы модель поддерживала контекст не менее 64K токенов. Переключитесь на модель с большим контекстом или увеличьте параметр контекста при использовании локальных моделей (например, Ollama:OLLAMA_NUM_CTX=65536）。

Вопрос 5:hermes --continueНе удаётся найти старые беседы

# 查看所有会话
hermes sessions list

# 确认当前 Profile
hermes profile list

Универсальный набор инструментов для восстановления

Если вы столкнетесь с какими-либо странными проблемами, выполните следующие шаги по порядку:

hermes doctor           # 1. 诊断
hermes model            # 2. 检查模型配置
hermes setup            # 3. 重新向导配置
hermes sessions list    # 4. 查看会话状态
hermes --continue       # 5. 尝试恢复会话
hermes gateway status   # 6. 检查网关状态（如已启用）

Предварительный просмотр расширенной конфигурации

После завершения базовой установки следующие функции можно включить по мере необходимости (подробно описано в последующих главах):

Подключение к платформе обмена сообщениями

hermes gateway setup    # 交互式配置 Telegram、Discord、Slack 等
hermes gateway          # 启动消息网关

Включение голосового режима

# 安装语音依赖
cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"

# 在 CLI 中启用
/voice on
# 按 Ctrl+B 开始录音

Подключение MCP-серверов

В~/.hermes/config.yamlДобавить в:

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

hermes mcp    # 交互式管理 MCP 服务器

Интеграция с редактором (ACP)

hermes acp    # 启动编辑器 Agent 模式（VS Code / Zed / JetBrains）

Краткий справочник команд