Перейти к основному содержимому

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

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

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

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

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

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

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

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

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

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

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

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

  2. Отправьте /newbot — BotFather задаст два вопроса:

    • Отображаемое имя — то, что видят пользователи (например, Team VibeOS Assistant)
    • Имя пользователя — должно заканчиваться на bot (например, myteam_vibeos_bot)

  3. Скопируйте токен бота — BotFather ответит примерно так:

    Use this token to access the HTTP API:
    7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

    Сохраните этот токен — он понадобится на следующем шаге.

  4. Установите описание (необязательно, но рекомендуется):

    /setdescription

    Выберите своего бота, затем введите что-то вроде:

    Командный AI-ассистент на базе VibeOS. Пишите в личку для помощи с кодом, исследованиями, отладкой и многим другим.

  5. Установите команды бота (необязательно — даёт пользователям меню команд):

    /setcommands

    Выберите своего бота, затем вставьте:

    new - Начать новый разговор
    model - Показать или сменить AI-модель
    status - Показать информацию о сессии
    help - Показать доступные команды
    stop - Остановить текущую задачу
предупреждение

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

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

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

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

vibeos gateway setup

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

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

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

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

# Ваш Telegram ID пользователя (числовой)
TELEGRAM_ALLOWED_USERS=123456789

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

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

  1. Напишите @userinfobot в Telegram
  2. Он мгновенно отвечает вашим числовым ID пользователя
  3. Скопируйте это число в TELEGRAM_ALLOWED_USERS
к сведению

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

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

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

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

vibeos gateway

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

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

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

Продакшн: Установка как службы​

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

vibeos gateway install
sudo vibeos gateway install --system   # Только Linux: системная служба автозагрузки

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

# Linux — управление пользовательской службой по умолчанию
vibeos gateway start
vibeos gateway stop
vibeos gateway status

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

# Оставаться запущенным после выхода из SSH
sudo loginctl enable-linger $USER

# Linux-серверы — явные команды системной службы
sudo vibeos gateway start --system
sudo vibeos gateway status --system
journalctl -u vibeos-gateway -f
# macOS — управление службой
vibeos gateway start
vibeos gateway stop
tail -f ~/.vibeos/logs/gateway.log
macOS PATH

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

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

vibeos gateway status

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

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

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

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

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

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

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

vibeos gateway stop && vibeos gateway start

Подход B: Привязка через личные сообщения (рекомендуется для команд)​

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

  1. Коллега пишет боту в личку — так как его нет в списке разрешений, бот отвечает одноразовым кодом привязки:

    🔐 Код привязки: XKGH5N7P
    Отправьте этот код владельцу бота для одобрения.

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

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

    vibeos pairing approve telegram XKGH5N7P

  4. Всё готово — бот сразу начинает отвечать на его сообщения

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

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

# Отзыв доступа у кого-либо
vibeos pairing revoke telegram 987654321

# Очистка истёкших ожидающих кодов
vibeos pairing clear-pending
подсказка

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

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

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

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

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

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

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

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

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Обновления команды"

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

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

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

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

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

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

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

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

# Душа
Вы — полезный командный ассистент. Будьте кратки и техничны.
Используйте блоки кода для любого кода. Опустите любезности — команда
ценит прямоту. При отладке всегда спрашивайте логи ошибок
прежде чем гадать на решениях.

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

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

<!-- ~/.vibeos/AGENTS.md -->
# Контекст команды
- Мы используем Python 3.12 с FastAPI и SQLAlchemy
- Фронтенд — React с TypeScript
- CI/CD работает на GitHub Actions
- Продакшн развёртывается на AWS ECS
- Всегда предлагайте писать тесты для нового кода
к сведению

Файлы контекста внедряются в системный промпт каждой сессии. Держите их краткими — каждый символ учитывается в вашем токенном бюджете.

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

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

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

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

Каждый будний день в 9 утра проверяй GitHub-репозиторий
github.com/myorg/myproject на:
1. Pull request'ы, открытые/слитые за последние 24 часа
2. Созданные или закрытые issues
3. Любые сбои CI/CD в основной ветке
Оформи в виде краткой сводки в стиле стендапа.

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

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

Каждые 6 часов проверяй использование диска с 'df -h', память с 'free -h'
и статус Docker-контейнеров с 'docker ps'. Сообщай о любых аномалиях —
разделах выше 80%, контейнерах, которые перезапускались, или высоком
использовании памяти.

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

# Из CLI
vibeos cron list          # Просмотр всех запланированных задач
vibeos cron status        # Проверка, запущен ли планировщик

# Из чата Telegram
/cron list                # Просмотр задач
/cron remove <job_id>     # Удаление задачи
предупреждение

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

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

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

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

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

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

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

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

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

# Проверка, запущен ли шлюз
vibeos gateway status

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

# Просмотр логов в реальном времени (macOS)
tail -f ~/.vibeos/logs/gateway.log

Обновление VibeOS​

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

vibeos update
vibeos gateway stop && vibeos gateway start

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

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

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

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

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

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