2026: самое полное руководство по установке и настройке Hermes Agent — пошаговый tutorial с практическим кейсом от нуля до запуска

2. Где большинство руководств обрываются

1. Потолок: «запуск прошёл успешно». Приветственный баннер в терминале не означает, что модель доступна, файловые инструменты работают или gateway принимает сообщения. Hermes по-настоящему пригоден к использованию только после проверки окружения, связи с моделью, границ прав, отслеживаемых логов и приёмки низкорискового кейса.
2. Скрытая цена: ключи и пути разбросаны. API Key живёт только в заметках; config.yaml и .env противоречат друг другу; рабочая область указывает на весь домашний каталог — одна ошибка может перезаписать SSH-ключи или production-репозиторий.
3. Стабильность и аудит: установил и забыл, где лежат логи. При сбое слепая переустановка стирает единственные подсказки в ~/.hermes/logs/errors.log; без бэкапа нельзя откатить конфигурацию после обновления.

3. Подготовка перед установкой: чек-лист Mac и окружения

Цель: не обнаружить проблемы с сетью, Git или диском на полпути установки. Критерий прохождения: все пункты ниже отмечены до запуска install-скрипта.

• Система: macOS 12+ (Intel или Apple Silicon; на Apple Silicon больше вариантов локального inference, но облачные модели следуют документации каждого провайдера).
• Git: у официального git-установщика единственный жёсткий пререквизит — Git (git --version ≥ 2.30 рекомендуется). Без Git установите Xcode Command Line Tools или brew install git.
• Сеть: нужен доступ к GitHub raw (скрипт установки) и API выбранного LLM-провайдера; в корпоративной сети заранее настройте HTTPS_PROXY.
• Диск: официальная установка тянет Python 3.11, Node.js v22, ripgrep, ffmpeg и репозиторий — зарезервируйте ≥ 2 ГБ (с кэшем Skills ближе к 1,5–3 ГБ; сверяйтесь с актуальной документацией).
• Права: per-user установка не требует sudo; если когда-то ставили от root, данные могут лежать в /root/.hermes, а не по путям ниже.
• Бэкап: если уже есть ~/.hermes, сначала выполните cp -a ~/.hermes ~/.hermes.bak-$(date +%F).
• Тестовый каталог: создайте изолированную рабочую область (далее используем ~/hermes-lab). Не направляйте первый кейс на ~/Documents, production git-репозитории или каталоги с секретами.

# Быстрая самопроверка перед установкой (скопируйте и выполните)
git --version
sw_vers
df -h ~
mkdir -p ~/hermes-lab/{inbox,outbox,archive}
echo "Hermes lab sample: Q2 planning notes." > ~/hermes-lab/inbox/sample.txt

При сбое проверьте: ошибки Git → CLT/Homebrew; мало места → очистите Downloads или используйте другой том; таймаут сети → смените сеть или прокси — не переустанавливайте три раза подряд, не понимая причину.

4. Официальная установка Hermes Agent

Цель: использовать поддерживаемый установщик Nous Research, чтобы Python, Node и CLI настроились автоматически. Источник: официальная документация Installation (перед публикацией перепроверьте номера версий и новые флаги).

4.1 Рекомендуется: git-установка одной строкой (следует main)

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

Установщик автоматически настраивает uv, Python 3.11, Node.js v22, ripgrep, ffmpeg, клонирует репозиторий, создаёт venv и добавляет hermes в PATH. Типичная per-user структура:

• Код: ~/.hermes/hermes-agent/
• Данные и конфиг: ~/.hermes/ (переопределяется через HERMES_HOME)
• CLI: ~/.local/bin/hermes

4.2 Альтернатива: pip install (нужен Python 3.11+ заранее)

pip install hermes-agent
hermes postinstall   # опционально: Node, browser, ripgrep, ffmpeg + setup

PyPI следует тегированным релизам; для bleeding edge предпочтите git-скрипт выше. Поведение hermes update различается по способу установки — доверяйте выводу hermes doctor.

4.3 Три обязательных шага после установки

source ~/.zshrc          # или откройте новое окно терминала
hermes version           # зафиксируйте версию для будущей диагностики
hermes doctor            # авто-диагностика; добавьте --fix для попытки исправления

Критерий прохождения: which hermes указывает на ~/.local/bin/hermes; hermes doctor без блокирующих FAIL. При сбое проверьте: последние 20 строк лога установки → PATH → не вызываете ли вы hermes из репозитория системным Python (используйте launcher venv).

Не делайте: не удаляйте ~/.hermes и не переустанавливайте сразу при ошибке — сохраните вывод терминала и hermes doctor, иначе нельзя отличить сетевую проблему от проблемы прав.

5. Настройка моделей и API Key

Цель: дать Hermes доступ к выбранному LLM-провайдеру. Критерий прохождения: неинтерактивный smoke-тест возвращает осмысленный ответ; hermes auth list или .env содержит запись, а ключ не остался в истории shell открытым текстом.

5.1 Интерактивная настройка (рекомендуется при первом запуске)

hermes setup          # полный мастер: модели, инструменты, gateway и т.д.
# или по шагам:
hermes model          # выбор провайдера и модели по умолчанию
hermes tools          # включение наборов инструментов по необходимости

5.2 Переменные окружения и конфигурационные файлы

Основной конфиг обычно лежит в ~/.hermes/config.yaml; секреты — в ~/.hermes/.env (уточните через hermes config path и hermes config env-path). Пример (имена переменных следуют актуальной документации провайдера — не копируйте устаревшие имена):

# Пример: OpenRouter (замените на свой ключ; никогда не коммитьте в git)
hermes config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# или редактируйте .env напрямую (chmod 600 ~/.hermes/.env)
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.hermes/.env

Граница ответственности: цены моделей, лимиты API, доступность по регионам и политики конфиденциальности меняются у провайдеров — перед production прочитайте их актуальные условия. Эта статья не привязывает вас к одному имени модели.

6. Рабочая область, права и логи

Цель: после установки сделать операции отслеживаемыми, ограниченными и с возможностью отката. Принцип: минимальные привилегии — сначала разрешите только тестовый каталог, затем постепенно открывайте реальные проекты.

• Рабочая область: укажите ~/hermes-lab в config.yaml или сессии; добавьте туда AGENTS.md с описанием разрешённых инструментов и границ (см. официальную документацию Context Files).
• Права macOS: терминальные/файловые инструменты могут запросить Full Disk Access — при первой приёмке выдавайте только то, что нужно тестовому каталогу, а не доступ ко всему диску.
• Каталог логов: по умолчанию ~/.hermes/logs/ (agent.log, errors.log, gateway.log). Просмотр: hermes logs list, hermes logs errors --since 30m.
• Гигиена секретов: chmod 600 ~/.hermes/.env; не кладите zip-бэкапы в синхронизируемые папки; не давайте Agent читать ~/.ssh, платёжные данные или production kubeconfig.
• Фоновый запуск (опционально): для Telegram/Discord gateway используйте hermes gateway setup и hermes gateway install; долгосрочная эксплуатация описана в нашем руководстве по долгосрочному обслуживанию Hermes Agent.

Критерий прохождения: после указания Agent «читать/писать только ~/hermes-lab» попытки выйти за пределы тестовых путей отклоняются или фиксируются в логах для аудита.

7. Первая приёмка: runbook из 7 шагов

Эти семь шагов переводят вас от «настройка завершена» к «готов к работе» — выполняйте по порядку и сохраняйте скриншоты или фрагменты логов.

1. Диагностика: hermes doctor --fix → нет неразрешённых FAIL.
2. Ping модели: hermes chat -q "Reply with exactly: HERMES_OK" → ответ содержит HERMES_OK.
3. Чтение файла: попросите Agent прочитать ~/hermes-lab/inbox/sample.txt и повторить первое предложение.
4. Запись файла: запишите ~/hermes-lab/outbox/ping.txt → видно через cat.
5. Логи: hermes logs errors --since 10m → нет новых ERROR (или известные безвредные задокументированы).
6. Закрытие терминала: закройте окно, откройте новое, повторите шаг 2 → исключает PATH, действующий только в текущей сессии.
7. Опциональная перезагрузка: перезагрузите Mac и повторите шаг 2 (если gateway установлен, добавьте hermes gateway status).

Ориентиры (личная приёмка, не официальный SLA): smoke-ответ < 60 с; 0 необъяснимых ERROR в errors.log за 10 минут; после тестовой записи ls -la ~/hermes-lab/outbox показывает новый файл.

8. Первый практический кейс: резюме + задачи + выходной файл с откатом

Сценарий: прочитать тестовый текст в каталоге, сгенерировать резюме и три задачи, записать Markdown-файл и сохранить копию для отката. Кейс покрывает результат установки (CLI), результат настройки (модель) и реальный workflow (чтение → рассуждение → запись → логи).

# 1. Подготовка входных данных (пропустите, если раздел 3 уже создал файл)
cat > ~/hermes-lab/inbox/weekly-notes.txt <<'EOF'
This week: finished draft Hermes install documentation.
Follow-ups: configure OpenRouter budget alerts; evaluate Telegram gateway next week.
Risk: never commit API keys to git.
EOF

# 2. Интерактивная сессия (или одна составная инструкция)
hermes
# В сессии отправьте (пример промпта):
# "Use only the ~/hermes-lab directory. Read inbox/weekly-notes.txt,
#   write a summary under 150 words plus 3 todos in English,
#   save to outbox/summary-and-todos.md,
#   and copy the original file to archive/weekly-notes.bak"

# 3. Неинтерактивная проверка
ls -la ~/hermes-lab/outbox/summary-and-todos.md
ls -la ~/hermes-lab/archive/
hermes logs agent -n 30 --since 15m

Критерии прохождения:

• summary-and-todos.md содержит резюме и три задачи, согласованные с исходным файлом.
• В archive/ лежит бэкап, который можно сравнить через diff.
• В логах видны соответствующие вызовы инструментов; биллинг/дашборд провайдера отражает этот запуск (помогает проверить стоимость).

Откат: rm ~/hermes-lab/outbox/summary-and-todos.md && cp ~/hermes-lab/archive/weekly-notes.bak ~/hermes-lab/inbox/weekly-notes.txt. При сбое проверьте: модель обрезала файл → permission denied в outbox → ошибки инструментов в errors.log.

9. Диагностика: послойно, без слепой переустановки

Чек-лист фактов перед публикацией (для редакторов): URL официального install.sh, минимальная macOS, имена каталогов по умолчанию, подкоманды CLI, имена env-переменных провайдеров, пути логов — обновите документ перед публикацией при любых изменениях. Читателям достаточно запомнить: при ошибке запустите hermes doctor, затем прочитайте errors.log, и только потом думайте о переустановке.

10. Следующие шаги: от тестового каталога к реальным workflow

После успешной приёмки расширяйтесь в этом порядке — не переходите сразу к production-репозиториям или платёжным системам:

1. Добавьте один реальный side-project каталог в allowlist; по-прежнему блокируйте ~/.ssh и глобальное чтение/запись *.
2. Включите hermes cron для ежедневных низкорисковых задач (например, инвентаризация Downloads — всё ещё в рамках тестовых каталогов).
3. Настройте один messaging gateway (Telegram/Discord) с pairing mode для блокировки незнакомцев (см. официальную документацию Security).
4. Установите еженедельный ритм hermes backup --quick, затем прочитайте руководство по долгосрочному обслуживанию для drill-ов обновления и отката.