🏠 Главная › Документация › Гайды

Настройка командного Telegram-ассистента

Это руководство проведёт вас через настройку Telegram-бота на основе Hermes Agent, который могут использовать несколько членов команды. В итоге ваша команда получит общего AI-ассистента, которому можно писать для помощи с кодом, исследованиями, системным администрированием и многим другим — защищённого авторизацией по пользователям.

Что мы создаём

Telegram-бот, который:

Предварительные требования

Перед началом убедитесь, что у вас есть:

VPS за $5/мес. вполне достаточно для шлюза. Сам Hermes лёгкий — деньги тратятся на LLM API запросы, которые выполняются удалённо.

Шаг 1: Создание Telegram-бота

Каждый Telegram-бот начинается с @BotFather — официального бота Telegram для создания ботов.

  1. Откройте Telegram и найдите @BotFather, или перейдите по ссылке t.me/BotFather

  2. Отправьте /newbot — BotFather спросит вас два пункта:

  3. Отображаемое имя — то, что видят пользователи (например, Team Hermes Assistant)

  4. Имя пользователя — должно заканчиваться на bot (например, myteam_hermes_bot)

  5. Скопируйте токен бота — BotFather ответит примерно так: Use this token to access the HTTP API: 7123456789:***... Сохраните этот токен — он понадобится на следующем шаге.

  6. Установите описание (необязательно, но рекомендуется): /setdescription Выберите вашего бота, затем введите что-то вроде: Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.

  7. Установите команды бота (необязательно — даёт пользователям меню команд): /setcommands Выберите вашего бота, затем вставьте: new - Start a fresh conversation model - Show or change the AI model status - Show session info help - Show available commands stop - Stop the current task

Храните токен бота в секрете. Любой, у кого есть токен, может управлять ботом. Если он утёк, используйте `/revoke` в BotFather для создания нового.

Шаг 2: Настройка шлюза

У вас есть два варианта: интерактивный мастер настройки (рекомендуется) или ручная настройка.

hermes gateway setup

Этот мастер проведёт вас через всё с выбором с помощью стрелок. Выберите Telegram, вставьте токен бота и укажите ваш ID пользователя при запросе.

Вариант B: Ручная настройка

Добавьте эти строки в ~/.hermes/.env:

# Telegram bot token from BotFather
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

# Your Telegram user ID (numeric)
TELEGRAM_ALLOWED_USERS=123456789

Поиск вашего ID пользователя

Ваш ID пользователя Telegram — это числовое значение (не имя пользователя). Чтобы найти его:

  1. Напишите @userinfobot в Telegram

  2. Он мгновенно ответит вашим числовым ID пользователя

  3. Скопируйте этот номер в TELEGRAM_ALLOWED_USERS

ID пользователей Telegram — это постоянные числа, например 123456789. Они отличаются от вашего @username, который может меняться. Всегда используйте числовой ID для списков доступа.

Шаг 3: Запуск шлюза

Быстрая проверка

Сначала запустите шлюз в обычном режиме (foreground) чтобы убедиться, что всё работает:

hermes gateway

Вы должны увидеть примерно такой вывод:

[Gateway] Starting Hermes Gateway...
[Gateway] Telegram adapter connected
[Gateway] Cron scheduler started (tick every 60s)

Откройте Telegram, найдите вашего бота и отправьте ему сообщение. Если он ответит, всё работает. Нажмите Ctrl+C для остановки.

Продакшн: Установка как сервиса

Для постоянного развёртывания, переживающего перезагрузки:

hermes gateway install
sudo hermes gateway install --system   # Linux only: boot-time system service

Это создаёт фоновый сервис: пользовательский сервис systemd на Linux по умолчанию, сервис launchd на macOS или системный сервис Linux для загрузки, если указать --system.

# Linux — manage the default user service
hermes gateway start
hermes gateway stop
hermes gateway status

# View live logs
journalctl --user -u hermes-gateway -f

# Keep running after SSH logout
sudo loginctl enable-linger $USER

# Linux servers — explicit system-service commands
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

# macOS — manage the service
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log

tip macOS PATH Файл plist launchd захватывает ваш shell PATH при установке, поэтому подпроцессы шлюза могут находить инструменты вроде Node.js и ffmpeg. Если вы установите новые инструменты позже, повторно выполните hermes gateway install для обновления plist.

Проверка работы

hermes gateway status

Затем отправьте тестовое сообщение вашему боту в Telegram. Вы должны получить ответ в течение нескольких секунд.

Шаг 4: Настройка доступа команды

Теперь давайте дадим доступ вашим коллегам. Есть два подхода.

Подход A: Статический список доступа

Соберите ID пользователей Telegram каждого участника команды (пусть они напишут @userinfobot) и добавьте их списком через запятую:

# In ~/.hermes/.env
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555

Перезапустите шлюз после изменений:

hermes gateway stop && hermes gateway start

Привязка через ЛС более гибкая — вам не нужно собирать ID пользователей заранее. Вот как это работает:

  1. Коллега пишет боту в ЛС — так как его нет в списке доступа, бот отвечает одноразовым кодом привязки: 🔐 Pairing code: XKGH5N7P Send this code to the bot owner for approval.

  2. Коллега отправляет вам код (через любой канал — Slack, email, лично)

  3. Вы одобряете его на сервере: bash hermes pairing approve telegram XKGH5N7P

  4. Всё готово — бот немедленно начинает отвечать на их сообщения

Управление привязанными пользователями:

# See all pending and approved users
hermes pairing list

# Revoke someone's access
hermes pairing revoke telegram 987654321

# Clear expired pending codes
hermes pairing clear-pending
Привязка через ЛС идеальна для команд, потому что вам не нужно перезапускать шлюз при добавлении новых пользователей. Одобрения вступают в силу немедленно.

Вопросы безопасности

Шаг 5: Настройка бота

Установка домашнего канала

Домашний канал — это куда бот доставляет результаты задач cron и проактивные сообщения. Без него у запланированных задач нет места для отправки вывода.

Вариант 1: Используйте команду /sethome в любой группе или чате Telegram, где бот является участником.

Вариант 2: Установите вручную в ~/.hermes/.env:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

Чтобы найти ID канала, добавьте @userinfobot в группу — он сообщит ID чата группы.

Настройка отображения прогресса инструментов

Управляйте тем, сколько деталей бот показывает при использовании инструментов. В ~/.hermes/config.yaml:

display:
  tool_progress: new    # off | new | all | verbose
Режим Что вы видите
off Только чистые ответы — без активности инструментов
new Краткий статус для каждого нового вызова инструмента (рекомендуется для мессенджеров)
all Каждый вызов инструмента с деталями
verbose Полный вывод инструментов, включая результаты команд

Пользователи также могут менять это для каждой сессии командой /verbose в чате.

Настройка личности с помощью SOUL.md

Настройте стиль общения бота, редактируя ~/.hermes/SOUL.md:

Полное руководство: Использование SOUL.md с Hermes.

# Soul
You are a helpful team assistant. Be concise and technical.
Use code blocks for any code. Skip pleasantries — the team
values directness. When debugging, always ask for error logs
before guessing at solutions.

Добавление контекста проекта

Если ваша команда работает над конкретными проектами, создайте файлы контекста, чтобы бот знал ваш стек:

<!-- ~/.hermes/AGENTS.md -->
# Team Context

- We use Python 3.12 with FastAPI and SQLAlchemy

- Frontend is React with TypeScript

- CI/CD runs on GitHub Actions

- Production deploys to AWS ECS

- Always suggest writing tests for new code
Файлы контекста внедряются в системный промпт каждой сессии. Будьте кратки — каждый символ учитывается в вашем токен-бюджете.

Шаг 6: Настройка запланированных задач

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

Ежедневная сводка стендапа

Напишите боту в Telegram:

Every weekday at 9am, check the GitHub repository at
github.com/myorg/myproject for:

1. Pull requests opened/merged in the last 24 hours

2. Issues created or closed

3. Any CI/CD failures on the main branch
Format as a brief standup-style summary.

Агент автоматически создаёт задачу cron и доставляет результаты в чат, где вы задали запрос (или в домашний канал).

Проверка здоровья сервера

Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
and Docker container status with 'docker ps'. Report anything unusual —
partitions above 80%, containers that have restarted, or high memory usage.

Управление запланированными задачами

# From the CLI
hermes cron list          # View all scheduled jobs
hermes cron status        # Check if scheduler is running

# From Telegram chat
/cron list                # View jobs
/cron remove <job_id>     # Remove a job
Промпты задач cron запускаются в полностью свежих сессиях без памяти о предыдущих разговорах. Убедитесь, что каждый промпт содержит **весь** контекст, необходимый агенту — пути к файлам, URL, адреса серверов и чёткие инструкции.

Советы для продакшна

Использование Docker для безопасности

На общем командном боте используйте Docker в качестве терминального бэкенда, чтобы команды агента выполнялись в контейнере, а не на вашем хосте:

# In ~/.hermes/.env
TERMINAL_BACKEND=docker
TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20

Или в ~/.hermes/config.yaml:

terminal:
  backend: docker
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

Таким образом, даже если кто-то попросит бота выполнить что-то разрушительное, ваша хост-система будет защищена.

Мониторинг шлюза

# Check if the gateway is running
hermes gateway status

# Watch live logs (Linux)
journalctl --user -u hermes-gateway -f

# Watch live logs (macOS)
tail -f ~/.hermes/logs/gateway.log

Обновление Hermes

В Telegram отправьте /update боту — он загрузит последнюю версию и перезапустится. Или с сервера:

hermes update
hermes gateway stop && hermes gateway start

Расположение логов

Что Расположение
Логи шлюза journalctl --user -u hermes-gateway (Linux) или ~/.hermes/logs/gateway.log (macOS)
Вывод задач cron ~/.hermes/cron/output/{job_id}/{timestamp}.md
Определения задач cron ~/.hermes/cron/jobs.json
Данные привязки ~/.hermes/pairing/
История сессий ~/.hermes/sessions/

Дальнейшие шаги

У вас есть работающий командный Telegram-ассистент. Вот несколько следующих шагов:

Вопросы или проблемы? Откройте issue на GitHub — вклад приветствуется.