🏠 Главная › guides › team telegram assistant

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

В этом руководстве описаны изменения бота Telegram на базе агента «Гермес», который может использовать несколько сотрудников команды. В результате вы получаете команду общего ИИ-ассистента, который может писать для помощи с кодом, исследованиями, администрированием систем и многим другим — с записью по авторизации пользователя.

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

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

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

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

Шаг 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:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp... Сохраните этот токен — он понадобится на следующем шаге.

  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: Настройка шлюза

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

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

hermes gateway setup

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

Вариант Б: Ручная обработка

Добавьте эти строки в ~/.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. Он мгновенно возвращает ваш числовой идентификатор пользователя.
  3. Скопируйте это число в TELEGRAM_ALLOWED_USERS:::информация Идентификатор пользователя Telegram — это, например, постоянные числа, 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 only: boot-time system service

Это создаёт фоновую службу: пользовательскую 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
Файл launchd plist захватывает вашу оболочку PATH во время установки, чтобы дочерние процессы шлюза можно было использовать с помощью таких инструментов, как Node.js и ffmpeg. Если вы позже установите новые инструменты, повторно запустите `hermesgatewayinstall`, чтобы обновить plist.</div>
### Проверка работы
```bash
hermes gateway status

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

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

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

Подход A: Статический список разрешённых

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

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

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

hermes gateway stop && hermes gateway start

Подход Б: Привязка через личные сообщения (рекомендации для команды)

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

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

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

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

  4. Он в системе — бот сразу начинает появляться на его сообщениях.

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

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

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

# Очистить просроченные ожидающие коды
hermes pairing clear-pending
```:::совет
Привязка через личное сообщение идеальна для команды, потому что вам не нужно перезапускать шлюз при добавлении новых пользователей. Одобрение внесено в силу немедленно.</div>
### Вопросы безопасности

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

---

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

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

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

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

**Вариант 2:** Настроить вручную в `~/.hermes/.env`:
```bash
TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

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

Инструменты настройки, отображающие прогресс

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

display:
  tool_progress: new    # 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
```:::информация
Файлы контекста внедряются в систему каждой сессии запроса. Делайте их краткими — каждый символ учитывается в вашем токене-бюджете.</div>
---

## Шаг 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.

### Управление запланированными задачами
```bash
# From the CLI
hermes cron list          # Просмотр всех запланированных задач
hermes cron status        # Проверка, запущен ли планировщик

# From Telegram chat
/cron list                # Просмотр задач
/cron remove <job_id>     # Удаление задачи
```:::предупреждение
Задачи cron выполняются в совершенно новых сеансах без памяти о предыдущих разговорах. Убедитесь, что каждое приглашение содержит **весь** контекст, выбранный агент — путь к файлам, URL-адресам, адресам серверов и четкие инструкции.</div>
---

## Советы для продуктивной работы

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

В общем командном боте используйте Docker в качестве серверного терминала, чтобы агент команды выполнялся в контейнере, а не на хосте:
```bash
# 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

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

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

# Проверить, запущен ли шлюз
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-ассистент. Вот несколько следующих шагов:

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