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

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

Что получится в итоге

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

Любой авторизованный участник может написать в личку — ревью кода, исследование, shell-команды, отладка
Работает на вашем сервере с полным доступом к инструментам — терминал, редактирование файлов, веб-поиск, выполнение кода
Сессии на пользователя — каждый получает собственный контекст разговора
Безопасен по умолчанию — только одобренные пользователи могут взаимодействовать, с двумя методами авторизации
Расписание задач — ежедневные стендапы, проверки здоровья системы и напоминания в командный канал

Требования

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

Hermes Agent установлен на сервере или VPS (не на ноутбуке — боту нужно работать постоянно). Следуйте инструкции по установке, если ещё не сделали.
Аккаунт Telegram для себя (владелец бота)
Настроенный LLM-провайдер — как минимум API-ключ OpenAI, Anthropic или другого поддерживаемого провайдера в ~/.hermes/.env

совет

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

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

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

Откройте Telegram и найдите @BotFather, или перейдите по t.me/BotFather
Отправьте /newbot — BotFather задаст два вопроса:
- Отображаемое имя — что видят пользователи (например, Team Hermes Assistant)
- Username — должен заканчиваться на bot (например, myteam_hermes_bot)
Скопируйте токен бота — BotFather ответит примерно так:
```
Use this token to access the HTTP API:
7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
```
Сохраните токен — он понадобится на следующем шаге.
Установите описание (опционально, но рекомендуется):
```
/setdescription
```
Выберите своего бота, затем введите что-то вроде:
```
Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.
```
Задайте команды бота (опционально — добавляет меню команд для пользователей):
```
/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: Настройте шлюз

Два варианта: интерактивный мастер настройки (рекомендуется) или ручная конфигурация.

Вариант A: Интерактивная настройка (рекомендуется)

hermes gateway setup

Мастер проведёт через всё с выбором стрелками. Выберите Telegram, вставьте токен бота и введите ваш user ID.

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

Добавьте в ~/.hermes/.env:

# Токен бота от BotFather
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

# Ваш Telegram user ID (числовой)
TELEGRAM_ALLOWED_USERS=123456789

Как узнать свой user ID

Telegram user ID — это числовое значение, не username. Чтобы его найти:

Напишите @userinfobot в Telegram
Он сразу ответит вашим числовым user ID
Скопируйте это число в TELEGRAM_ALLOWED_USERS

инфо

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

Шаг 3: Запустите шлюз

Быстрый тест

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

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: системный сервис при загрузке

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

# Linux — управление пользовательским сервисом
hermes gateway start
hermes gateway stop
hermes gateway status

# Просмотр логов в реальном времени
journalctl --user -u hermes-gateway -f

# Продолжать работу после разлогина по SSH
sudo loginctl enable-linger $USER

# Linux-серверы — явные команды системного сервиса
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

# macOS — управление сервисом
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log

совет

macOS PATH

Plist launchd захватывает ваш PATH из shell’а при установке, чтобы сабпроцессы шлюза находили инструменты вроде Node.js и ffmpeg. Если позже установите новые инструменты — перезапустите hermes gateway install для обновления plist.

Проверьте работу

hermes gateway status

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

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

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

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

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

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

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

hermes gateway stop && hermes gateway start

Подход B: Паринг через личку (рекомендуется для команд)

Паринг через ЛС гибче — не нужно заранее собирать user ID. Как это работает:

Коллега пишет боту — поскольку он не в списке доступа, бот отвечает одноразовым кодом паринга:
```
🔐 Pairing code: XKGH5N7P
Send this code to the bot owner for approval.
```
Коллега присылает вам код (через любой канал — Slack, почта, лично)

Вы одобряете на сервере:

hermes pairing approve telegram XKGH5N7P

Готово — бот сразу начинает отвечать на его сообщения

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

# Посмотреть всех ожидающих и одобренных
hermes pairing list

# Отозвать доступ
hermes pairing revoke telegram 987654321

# Очистить просроченные ожидающие коды
hermes pairing clear-pending

совет

Паринг через ЛС удобен для команд: не нужно перезапускать шлюз при добавлении новых пользователей. Одобрение вступает в силу мгновенно.

Соображения безопасности

Никогда не устанавливайте GATEWAY_ALLOW_ALL_USERS=true для бота с доступом к терминалу — любой, кто найдёт вашего бота, сможет выполнять команды на вашем сервере
Коды паринга действуют 1 час и используют криптографическую случайность
Защита от брутфорса: 1 запрос от пользователя раз в 10 минут, максимум 3 ожидающих кода на платформу
После 5 неудачных попыток одобрения платформа входит в блокировку на 1 час
Все данные паринга хранятся с правами chmod 0600

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

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

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

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

Вариант 2: Задайте вручную в ~/.hermes/.env:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

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

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

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

display:
  tool_progress: new    # off | new | all | verbose

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

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

Задайте личность через SOUL.md

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

Полное руководство — в Use SOUL.md with 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.

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

# Через CLI
hermes cron list          # Список всех задач
hermes cron status        # Проверить работу планировщика

# Из чата Telegram
/cron list                # Список задач
/cron remove <job_id>     # Удалить задачу

внимание

Промпты cron-задач выполняются в полностью свежих сессиях без памяти о предыдущих разговорах. Убедитесь, что каждый промпт содержит весь необходимый контекст — пути к файлам, URL, адреса серверов и чёткие инструкции.

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

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

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

# В ~/.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

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

Мониторьте шлюз

# Проверить, что шлюз работает
hermes gateway status

# Следить за логами в реальном времени (Linux)
journalctl --user -u hermes-gateway -f

# Следить за логами в реальном времени (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-ассистент готов к работе. Следующие шаги:

Руководство по безопасности — авторизация, изоляция контейнеров, одобрение команд
Шлюз сообщений — полный справочник по архитектуре шлюза, управлению сессиями и чат-командам
Настройка Telegram — детали платформы, включая голосовые сообщения и TTS
Запланированные задачи — продвинутое планирование cron с вариантами доставки и cron-выражениями
Файлы контекста — AGENTS.md, SOUL.md и .cursorrules для знаний о проекте
Личность — встроенные пресеты личности и собственные определения персонажа
Добавьте другие платформы — тот же шлюз может одновременно работать с Discord, Slack и WhatsApp

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