Настройка Telegram

VibeOS интегрируется с Telegram как полнофункциональный диалоговый бот. После подключения вы можете общаться со своим агентом с любого устройства, отправлять голосовые заметки, которые автоматически расшифровываются, получать результаты запланированных задач и использовать агента в групповых чатах. Интеграция построена на python-telegram-bot и поддерживает текст, голос, изображения и вложения файлов.

Шаг 1. Создайте бота через BotFather

Каждому боту Telegram требуется токен API, выданный @BotFather, официальным инструментом управления ботами Telegram.

Откройте Telegram и найдите @BotFather или посетите t.me/BotFather.
Отправьте /newbot.
Выберите отображаемое имя (например, «VibeOS») — это может быть что угодно.
Выберите имя пользователя — оно должно быть уникальным и заканчиваться на bot (например, my_vibeos_bot).
BotFather отвечает вашим токеном API. Это выглядит так:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

предупреждение

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

Шаг 2. Настройте своего бота (необязательно)

Эти команды BotFather улучшают взаимодействие с пользователем. Отправьте сообщение @BotFather и используйте:

Команда	Цель
`/setdescription`	Вопрос «Что может этот бот?» текст, отображаемый перед тем, как пользователь начинает общение
`/setabouttext`	Краткий текст на странице профиля бота
`/setuserpic`	Загрузите аватарку для своего бота
`/setcommands`	Определить командное меню (кнопка `/` в чате)
`/setprivacy`	Контролируйте, видит ли бот все групповые сообщения (см. Шаг 3)

подсказка

Для /setcommands полезный стартовый набор:

help - Show help information
new - Start a new conversation
sethome - Set this chat as the home channel

Индикатор состояния Online/Offline (дополнительно)

Боты Telegram не имеют реальной точки присутствия в сети/offline — эта зеленая точка Функция учетной записи пользователя, а не то, что бот API предоставляет ботам. Ближайший поверхность – это краткое описание бота (строка под его именем в профиль бота).

Включите status_indicator, а VibeOS устанавливает для этого краткого описания значение В сети. когда шлюз подключается и находится в режиме Offline при чистом завершении работы:

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        # Optional custom strings (defaults: "Online" / "Offline"):
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

Примечания:

Краткое описание является глобальным для бота (видно всем пользователям), а не за чат. Пользователи видят его на странице профиля бота, а не как живой значок внутри. открытый чат.
Только чистое отключение шлюза (/stop, disconnect) пишет "Не в сети". Тяжелый сбой оставляет последний известный статус — неотъемлемое ограничение текстовый индикатор профиля.
По умолчанию отключено, поскольку изменяет глобальный профиль бота.

Приоритет и ограничение меню команд (необязательно)

VibeOS автоматически регистрирует свое командное меню при запуске шлюза Telegram. Меню создается на основе центрального реестра косых команд плюс подходящих команд плагина /skill, а затем ограничивается, чтобы Telegram надежно принимал полезную нагрузку. Ограничение по умолчанию составляет 60 команд — этого достаточно, чтобы все встроенные команды, а также команды общих навыков были видимыми.

Если у вас есть локальные или подключаемые команды, которые должны оставаться видимыми в средстве выбора Telegram /, установите их приоритет в ~/.vibeos/config.yaml:

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command

priority_mode управляет тем, как ваш список объединяется со встроенным списком приоритетов VibeOS:

prepend: сначала поместите свои команды, затем VibeOS по умолчанию.
append: сначала оставьте настройки VibeOS по умолчанию, а затем ваши команды.
replace: используйте только свой список для приоритетного заказа.

Telegram допускает до 100 BotCommands, но при загрузке больших команд может возникнуть сбой. VibeOS по умолчанию имеет значение 60 для надежности и фиксирует настроенные значения на 1..100; используйте /commands для получения полного списка команд.

Шаг 3: Режим конфиденциальности (критичен для групп)

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

При включенном режиме конфиденциальности ваш бот может видеть только:

Сообщения, начинающиеся с команды /.
Отвечает непосредственно на собственные сообщения бота.
Служебные сообщения (присоединение участников к /leaves, закрепленные сообщения и т. д.)
Сообщения в каналах, где бот является админом

В режиме конфиденциальности OFF бот получает каждое сообщение в группе.

Как отключить режим конфиденциальности

Сообщение @BotFather
Отправьте /mybots.
Выберите своего бота
Откройте Настройки бота → Конфиденциальность группы → Выключить.

предупреждение

Вы должны удалить и повторно добавить бота в любую группу после изменения настроек конфиденциальности. Telegram кэширует состояние конфиденциальности, когда бот присоединяется к группе, и оно не будет обновляться до тех пор, пока бот не будет удален и повторно добавлен.

подсказка

Альтернатива отключению режима конфиденциальности: назначьте бота администратором группы. Боты-администраторы всегда получают все сообщения независимо от настроек конфиденциальности, и это позволяет избежать необходимости переключать глобальный режим конфиденциальности.

Наблюдайте за групповым общением без автоответа

Для группового поведения OpenClaw/Yuanbao-style настройте Telegram так, чтобы бот мог видеть обычные групповые сообщения, но отвечал только при прямом запуске:

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

Если этот режим включен, неупомянутые групповые сообщения из чатов /topics, явно включенных в разрешенный список, добавляются к общей расшифровке сеанса чата /topic в качестве наблюдаемого контекста, но они не отправляют агента. allowed_chats шлюзы, на которые отвечает бот; group_allowed_chats авторизует общий групповой сеанс, используемый для наблюдаемого контекста, поэтому используйте те же идентификаторы чата для этого режима. Более позднее упоминание @botname, ответ боту или настроенный шаблон упоминания в том же чате из разрешенного списка /topic могут использовать этот наблюдаемый контекст. Сработавшее сообщение также помечается тегом [nickname|user_id] и получает подсказку безопасности для каждого хода, поэтому модель обрабатывает предыдущие наблюдаемые строки как контекст, а не как инструкции, адресованные боту.

Эквивалентная переменная среды:

TELEGRAM_ALLOWED_CHATS=-1001234567890
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true

Для этого Telegram должен доставлять обычные групповые сообщения на шлюз, поэтому отключите режим конфиденциальности BotFather или назначьте бота администратором группы, как описано выше.

Шаг 4. Найдите свой идентификатор пользователя

VibeOS использует числовые идентификаторы пользователей Telegram для управления доступом. Ваш идентификатор пользователя не ваше имя пользователя — это номер типа 123456789.

Метод 1 (рекомендуется): Сообщение @userinfobot — он мгновенно отвечает с вашим идентификатором пользователя.

Способ 2: Сообщение @get_id_bot — еще один надежный вариант.

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

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

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

vibeos gateway setup

При появлении запроса выберите Telegram. Мастер запрашивает токен вашего бота и разрешенные идентификаторы пользователей, а затем записывает для вас конфигурацию.

Вариант Б: Настройка вручную

Добавьте следующее в ~/.vibeos/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users

Запуск шлюза

vibeos gateway

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

Отправка сгенерированных файлов с терминалов, поддерживаемых Docker

Если серверная часть вашего терминала — docker, имейте в виду, что вложения Telegram отправлено процессом шлюза, а не изнутри контейнера. Это означает, что конечный путь MEDIA:/... должен быть доступен для чтения на хосте, где находится шлюз. бег.

Распространенная ошибка:

— агент записывает файл внутри Docker в /workspace/report.txt

модель излучает MEDIA:/workspace/report.txt
Доставка Telegram не удалась, поскольку /workspace/report.txt существует только внутри контейнер, а не на хосте

Рекомендуемый шаблон:

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/.vibeos/cache/documents:/output"

Тогда:

записывать файлы внутри Docker в /output/...
укажите путь host-visible в MEDIA:, например: MEDIA:/home/user/.vibeos/cache/documents/report.txt

Если у вас уже есть раздел docker_volumes:, добавьте новое монтирование в тот же раздел. список. Дублированные ключи YAML автоматически переопределяют предыдущие.

Поддерживаемые расширения файлов `MEDIA:`

Шлюз извлекает теги MEDIA:/path/to/file из ответов агента и отправляет указанный файл в виде вложения, встроенного в платформу. Поддерживаемые расширения на всех платформах шлюзов:

Категория	Расширения
Изображения	`png`, `jpg`, `jpeg`, `gif`, `webp`, `bmp`, `tiff`, `svg`
Аудио	`mp3`, `wav`, `ogg`, `m4a`, `opus`, `flac`, `aac`
Видео	`mp4`, `mov`, `webm`, `mkv`, `avi`
Документы	`pdf`, `txt`, `md`, `csv`, `json`, `xml`, `html`, `yaml`, `yml`, `log`
Офис	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`
Архивы	`zip`, `rar`, `7z`, `tar`, `gz`, `bz2`
Книги/пакеты	`epub`, `apk`, `ipa`

Все, что есть в этом списке, доставляется в виде встроенного вложения на платформах, которые это поддерживают (Telegram, Discord, Signal, Slack, WhatsApp, Feishu, Matrix и т. д.); на платформах без встроенной поддержки используется ссылка или текстовый индикатор. Категории, выделенные жирным шрифтом, были добавлены в последних нескольких выпусках — если вместо этого вы полагались на модель с надписью here is the file: /path/to/report.docx, замените ее на MEDIA:/path/to/report.docx для встроенной доставки.

Режим вебхука

По умолчанию VibeOS подключается к Telegram с помощью длинного опроса — шлюз отправляет исходящие запросы к серверам Telegram для получения новых обновлений. Это хорошо работает для локальных и постоянно действующих развертываний.

Для облачных развертываний (Fly.io, Railway, Render и т. д.) режим веб-перехватчика является более экономичным. Эти платформы могут автоматически пробуждать приостановленные компьютеры при входящем трафике HTTP, но не при исходящих соединениях. Поскольку опрос является исходящим, бот-опрос никогда не может спать. Режим Webhook меняет направление: Telegram отправляет обновления в HTTPS URL вашего бота, обеспечивая развертывание в режиме сна во время простоя.

	Опрос (по умолчанию)	Вебхук
Направление	Шлюз → Telegram (исходящий)	Telegram → Шлюз (входящий)
Лучшее для	Локальные, постоянно работающие серверы	Облачные платформы с автоматическим пробуждением
Настройка	Никаких дополнительных настроек	Набор `TELEGRAM_WEBHOOK_URL`
Стоимость простоя	Машина должна продолжать работать	Машина может спать между сообщениями

Конфигурация

Добавьте следующее в ~/.vibeos/.env:

TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"  # required
# TELEGRAM_WEBHOOK_PORT=8443        # optional, default 8443

Переменная	Требуется	Описание
`TELEGRAM_WEBHOOK_URL`	Да	Публичный HTTPS URL, куда Telegram будет отправлять обновления. Путь URL извлекается автоматически (например, `/telegram` из примера выше).
`TELEGRAM_WEBHOOK_SECRET`	Да (если установлен `TELEGRAM_WEBHOOK_URL`)	Секретный токен, который Telegram повторяет в каждом запросе веб-перехватчика на проверку. Без него шлюз отказывается запускаться — см. `GHSA-3vpc-7q5r-276h`. Сгенерируйте с помощью `openssl rand -hex 32`.
`TELEGRAM_WEBHOOK_PORT`	Нет	Локальный порт, который прослушивает сервер веб-перехватчиков (по умолчанию: `8443`).

Если установлен TELEGRAM_WEBHOOK_URL, шлюз запускает сервер веб-перехватчиков HTTP вместо опроса. Если этот параметр не установлен, используется режим опроса — поведение не меняется по сравнению с предыдущими версиями.

Пример облачного развертывания (Fly.io)

Добавьте переменные env в секреты вашего приложения Fly.io:

fly secrets set TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
fly secrets set TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)

Откройте порт веб-перехватчика на вашем fly.toml:

[[services]]
  internal_port = 8443
  protocol = "tcp"

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

Развертывание:

fly deploy

В журнале шлюза должно быть указано: [telegram] Connected to Telegram (webhook mode).

Поддержка прокси

Если API Telegram заблокирован или вам необходимо маршрутизировать трафик через прокси, установите специальный прокси Telegram URL. Это имеет приоритет над общими переменными окружения HTTPS_PROXY/HTTP_PROXY.

Вариант 1: config.yaml (рекомендуется)

telegram:
  proxy_url: "socks5://127.0.0.1:1080"

Вариант 2: переменная среды

TELEGRAM_PROXY=socks5://127.0.0.1:1080

Поддерживаемые схемы: http://, https://, socks5://.

Прокси применяется как к основному соединению Telegram, так и к резервному IP-транспорту. Если прокси-сервер для Telegram не установлен, шлюз переключается на HTTPS_PROXY / HTTP_PROXY / ALL_PROXY (или автоматическое определение системного прокси-сервера macOS).

Домашний канал

Используйте команду /sethome в любом чате Telegram (DM или группе), чтобы назначить его домашним каналом. Запланированные задачи (задания cron) доставляют свои результаты в этот канал.

Вы также можете установить его вручную в ~/.vibeos/.env:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"

подсказка

Идентификаторы групповых чатов представляют собой отрицательные числа (например, -1001234567890). Ваш личный идентификатор чата DM совпадает с вашим идентификатором пользователя.

Доставки Cron в тематическом режиме

Если у вас в личном кабинете бота включен тематический режим, сообщения cron, доставленные в корневой чат, попадают в системное лобби — ответ там не открывает сеанс, и вы видите уведомление «основной чат зарезервирован для системных команд». Создайте специальную тему на форуме (например, Cron) и установите:

TELEGRAM_CRON_THREAD_ID=<topic_thread_id>

TELEGRAM_CRON_THREAD_ID переопределяет TELEGRAM_HOME_CHANNEL_THREAD_ID только для поставок cron. Ответы в этой теме продолжают существующий сеанс темы.

Голосовые сообщения

Входящий голос (преобразование речи в текст)

Голосовые сообщения, которые вы отправляете в Telegram, автоматически расшифровываются настроенным провайдером VibeOS VibeOS и вставляются в разговор в виде текста.

local использует faster-whisper на машине под управлением VibeOS — ключ API не требуется.
groq использует Groq Whisper и требует GROQ_API_KEY.
openai использует OpenAI Whisper и требует VOICE_TOOLS_OPENAI_KEY

Пропуск STT: передать необработанный аудиофайл агенту

Если вы предпочитаете, чтобы агент сам обрабатывал аудио — для ведения дневника, специального инструмента транскрипции или просто для архивирования записи — установите stt.enabled: false в ~/.vibeos/config.yaml:

stt:
  enabled: false

При отключенном STT шлюз по-прежнему загружает вложение voice/audio в аудиокэш VibeOS, но не расшифровывает его. Агент получает сообщение с маркером типа:

[The user sent a voice message: /home/<user>/.vibeos/cache/audio/<hash>.ogg]

Затем ваши инструменты или навыки смогут напрямую прочитать этот путь (например, передать его в локальный конвейер диаризации, в более богатую модель транскрипции или загрузить в долгосрочное хранилище). Расширение файла соответствует исходному формату, поставляемому Telegram (.ogg для голосовых заметок, .mp3/.m4a/etc. для аудио вложений).

Это естественным образом сочетается с разделом local Bot API server ниже, который увеличивает потолок getFile Telegram в 20 МБ до 2 ГБ — это полезно, когда записи, которые вы хотите обработать, длиннее пары минут.

Исходящая голосовая связь (преобразование текста в речь)

Когда агент генерирует звук через TTS, он доставляется в виде встроенных в Telegram голосовых пузырей — круглых, доступных для встроенного воспроизведения.

OpenAI и ElevenLabs самостоятельно создают Opus — дополнительная настройка не требуется.
Edge TTS (бесплатный поставщик по умолчанию) выводит MP3 и требует ffmpeg для преобразования в Opus:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

Без ffmpeg звук Edge TTS отправляется как обычный аудиофайл (все еще воспроизводимый, но вместо голосового пузыря используется прямоугольный проигрыватель).

Настройте провайдера TTS в вашем config.yaml под ключом tts.provider.

Большие файлы (>20 МБ) через локальный сервер Bot API

Публичный бот Telegram API ограничивает загрузку getFile 20 МБ, поэтому любая голосовая заметка, аудиофайл, видео или документ большего размера молча отклоняется VibeOS с ответом «слишком большой». Документированный способ обойти эту проблему — запустить локальный демон telegram-bot-api — то же самое серверное программное обеспечение, которое использует Telegram, но работающее в вашей сети. Локальный сервер повышает максимальный размер файла до 2 ГБ, а VibeOS автоматически поднимает свой внутренний предел, когда видит настроенный специальный base_url.

Это разблокирует такие рабочие процессы, как:

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

Шаг 1. Получите учетные данные Telegram API

Локальный сервер напрямую взаимодействует со слоем MTProto Telegram (а не с общедоступным ботом API), поэтому ему необходимы учетные данные MTProto:

Посетите my.telegram.org/apps и войдите в свою учетную запись Telegram.
Создайте новое приложение (подойдет любое имя и краткое описание).
Скопируйте api_id и api_hash — оба обязательны.

Шаг 2. Запустите сервер Telegram-bot-api

Самый простой путь — образ Docker aiogram/telegram-bot-api, поддерживаемый сообществом. Минимальный docker-compose.yaml (используйте режим --local, чтобы включить более высокие пределы):

services:
  tg-bot-api:
    image: aiogram/telegram-bot-api:latest
    container_name: tg-bot-api
    restart: unless-stopped
    ports:
      - "127.0.0.1:8081:8081"   # bind to loopback only; see security note
    environment:
      TELEGRAM_API_ID: "12345"           # your api_id from Step 1
      TELEGRAM_API_HASH: "abcdef..."     # your api_hash from Step 1
      TELEGRAM_LOCAL: "1"                # enable --local mode (raises 20MB → 2GB)
    volumes:
      - ./tg-bot-api-data:/var/lib/telegram-bot-api

Поднимите это:

docker compose up -d tg-bot-api
docker logs --tail 20 tg-bot-api

безопасности

Локальный сервер бота API принимает ваш токен бота по пути URL (например, /bot<TOKEN>/getMe) без без дополнительной аутентификации. Любой, кто может получить доступ к порту, может полностью контролировать вашего бота — читать каждое сообщение, которое он видит, отправлять сообщения как есть и т. д. Привяжите контейнер к 127.0.0.1 и /or, используя обратный прокси-сервер в частной сети. Никогда не предоставляйте порт 8081 общедоступному Интернету.

Шаг 3: Выходим из паблика бота API (однократно)

Бот может быть активен только на одном сервере Bot API одновременно. Если ваш бот уже работал с api.telegram.org (что почти наверняка и было), вы должны явно выйти из него, прежде чем локальный сервер его примет:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/logOut"
# expected response: {"ok":true,"result":true}

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

Убедитесь, что локальный сервер может общаться с Telegram от имени бота:

curl "http://127.0.0.1:8081/bot<YOUR_BOT_TOKEN>/getMe"
# expected response: {"ok":true,"result":{"id":...,"is_bot":true,...}}

Шаг 4. Наведите VibeOS на локальный сервер.

Добавьте URL-адреса под platforms.telegram.extra в ~/.vibeos/config.yaml:

platforms:
  telegram:
    extra:
      base_url: "http://127.0.0.1:8081/bot"
      base_file_url: "http://127.0.0.1:8081/file/bot"
      local_mode: true        # see Step 5 below — only set this if the bot's data
                              # directory is readable by the VibeOS process

Используйте platforms.telegram.extra, а не telegram.extra.

На данный момент в конфиг платформы глубоко встроена только форма platforms.<name>.extra. Ключи, помещенные непосредственно под блок telegram.extra верхнего уровня, удаляются автоматически.

Если установлен base_url, VibeOS:

Создает клиент python-telegram-bot на локальном сервере.
Автоматически снимает ограничение размера внутреннего документа /audio с 20 МБ → 2 ГБ.
Сообщает об активном лимите в сообщении об ошибке «слишком большой» (Maximum: 2048 MB.), чтобы было очевидно, в каком режиме вы находитесь.

Перезапустите шлюз и найдите строку журнала подтверждения:

vibeos gateway restart
grep -E "Using custom Telegram base_url|Using Telegram local_mode" ~/.vibeos/logs/gateway.log | tail

Шаг 5: `local_mode` — доступ к файлу на диске

Локальный сервер имеет два способа доставки файлов:

Без --local (по умолчанию): файлы передаются через HTTP по адресу /file/bot<TOKEN>/<path>, так же, как общедоступный бот API. Потолок в 20 МБ остается в силе. Полезно только для исправления сети (например, когда api.telegram.org` недоступен, но вы можете разместить его самостоятельно); это не то, что вам нужно для увеличения размера.
При использовании --local (устанавливается с помощью TELEGRAM_LOCAL=1 выше): файлы записываются в файловую систему сервера, а ответ getFile возвращает абсолютный путь вместо HTTP URL. Потолок в 20 МБ снят. Затем VibeOS должен прочитать байты с диска, а не через HTTP.

Чтобы путь чтения с диска работал, установите local_mode: true в конфигурации выше и убедитесь, что процесс VibeOS может прочитать путь, возвращаемый сервером. Два сценария:

Одна и та же машина — Telegram-bot-api и VibeOS работают на одном хосте. Привяжите том данных к каталогу, который VibeOS может читать (например, /var/lib/telegram-bot-api), и убедитесь, что права собственности на файл совпадают. Контейнер передает привилегии своему внутреннему пользователю telegram-bot-api (uid зависит от образа); Самое простое решение — добавить user: "<UID>:<GID>" в службу создания, чтобы файлы принадлежали uid, который VibeOS уже запускает.
Разные машины — бот-сервер работает на одном хосте (например, NAS, отдельная виртуальная машина), а VibeOS — на другом. Каталог данных сервера должен быть доступен машине VibeOS по тому же абсолютному пути, о котором сообщает сервер (обычно /var/lib/telegram-bot-api). NFS хорошо подходит для этого; CIFS/SMB с переназначением монтирования uid= более удобен, если вы не хотите иметь дело с несоответствиями uid на уровне файловой системы.

Если local_mode: true установлен, но VibeOS не может stat вернуть путь к файлу (разрешения или неправильное монтирование), python-telegram-bot автоматически возвращается к HTTP getFile против локального сервера, который в режиме --local отвечает 404 Not Found. Симптом проявляется в gateway.log как:

[Telegram] Failed to cache voice: Not Found
telegram.error.InvalidToken: Not Found

Если вы это видите, то шап-лифт работает, а файлообменник - нет. Проверьте ls -la /var/lib/telegram-bot-api/<TOKEN>/voice/ на хосте VibeOS в качестве пользователя, от имени которого работает шлюз, и убедитесь, что один файл поддерживает cat без ошибки разрешения.

Шаг 6: Проверьте это

Отправьте боту голосовую заметку или аудиофайл размером более 20 МБ. Храните журнал шлюза:

tail -f ~/.vibeos/logs/gateway.log | grep -iE "telegram|cache"

Вы должны увидеть строку [Telegram] Cached user voice at /home/<user>/.vibeos/cache/audio/... и нет «слишком большого» отклонения. В сочетании с stt.enabled: false (см. выше) путь к исходному аудиофайлу затем попадает во входящее сообщение агента для последующей обработки.

Использование группового чата

VibeOS работает в групповых чатах Telegram с некоторыми соображениями:

Режим конфиденциальности определяет, какие сообщения может видеть бот (см. Шаг 3)
TELEGRAM_ALLOWED_USERS по-прежнему применяется — только авторизованные пользователи могут запускать бота, даже в группах.
Вы можете запретить боту отвечать на обычный групповой чат с помощью telegram.require_mention: true.
При использовании telegram.require_mention: true групповые сообщения принимаются, если они:
- отвечает на одно из сообщений бота
- @botusername упоминает
- /command@botusername (командная форма меню бота Telegram, включающая имя бота)
- соответствует одному из настроенных вами слов пробуждения регулярного выражения в telegram.mention_patterns.
В группах с несколькими ботами VibeOS telegram.exclusive_bot_mentions сохраняет детерминированную маршрутизацию. Когда в сообщении явно упоминается одно или несколько имен пользователей ботов Telegram, его обрабатывают только упомянутые профили ботов; другие боты VibeOS игнорируют его до запуска ответа и резервного слова пробуждения. Это включено по умолчанию.
Используйте telegram.ignored_threads, чтобы VibeOS молчал в определенных темах форума Telegram, даже если в противном случае группа разрешала бы бесплатные ответы или ответы, вызванные упоминаниями.
Если telegram.require_mention не установлен или имеет значение false, VibeOS сохраняет предыдущее поведение открытой группы и отвечает на обычные групповые сообщения, которые он может видеть.

Несколько ботов VibeOS в одной группе

Если вы запускаете несколько профилей VibeOS в одной группе Telegram, создайте один токен бота Telegram для каждого профиля и запустите один шлюз для каждого профиля. Не используйте повторно один и тот же токен бота в нескольких работающих шлюзах; Telegram отклонит параллельный опрос для одного и того же токена.

Рекомендуемая конфигурация группы:

telegram:
  require_mention: true
  exclusive_bot_mentions: true
  mention_patterns: []

При такой настройке групповое сообщение типа @research_bot @ops_bot summarize this обрабатывается только research_bot и ops_bot. Другие боты VibeOS в группе хранят молчание, даже если сообщение является ответом на одно из их предыдущих сообщений или иным образом соответствует общему слову пробуждения.

Установите exclusive_bot_mentions: false только для устаревших групп, где явные упоминания не должны переопределять триггеры ответа и пробуждающего слова.

Чтобы работать с несколькими профилями, запустите команду шлюза один раз для каждого профиля. Например:

# default profile
vibeos gateway start
vibeos gateway status
vibeos gateway stop

# named profiles
vibeos -p research gateway start
vibeos -p research gateway status
vibeos -p research gateway stop

Для небольшого фиксированного парка используйте цикл оболочки или сценарий, который вызывает vibeos gateway <action> для профиля по умолчанию и vibeos -p <profile> gateway <action> для каждого именованного профиля. Это более надежно, чем предположение, что одна команда уровня процесса контролирует каждый именованный профиль в каждом диспетчере служб.

Устранение неполадок: работает в личных сообщениях, но не в группах.

Если бот отвечает в приватном чате, но молчит в группе, проверьте эти ворота по порядку:

Доставка Telegram: отключите режим конфиденциальности BotFather, продвигайте бота администратора или упомяните бота напрямую. VibeOS не может отвечать на групповые сообщения что Telegram никогда не доставляет боту.
Присоединитесь снова после изменения конфиденциальности: удалите бота из группы и добавьте его. снова после изменения настроек конфиденциальности BotFather. Telegram может сохранить старый поведение доставки для существующих участников.
Авторизация VibeOS: убедитесь, что отправитель указан в TELEGRAM_ALLOWED_USERS или TELEGRAM_GROUP_ALLOWED_USERS, или разрешите групповой чат с TELEGRAM_GROUP_ALLOWED_CHATS.
Упоминание фильтров: если установлен telegram.require_mention: true, это нормально. групповой чат игнорируется, если сообщение не является slash-командой, ответьте на бот, упоминание @botusername или настроенное совпадение mention_patterns.
Маршрутизация нескольких ботов: если в группе несколько ботов, убедитесь, что каждый из них Профиль VibeOS использует уникальный токен бота и сохраняет exclusive_bot_mentions. включено, если только вы намеренно не хотите использовать устаревшее поведение общего триггера.

Отрицательные идентификаторы чата являются нормальным явлением для групп и супергрупп Telegram. Если вы используете авторизацию на уровне чата, поместите эти идентификаторы в TELEGRAM_GROUP_ALLOWED_CHATS, а не список разрешенных пользователей-отправителей.

Пример настройки группового триггера

Добавьте это в ~/.vibeos/config.yaml:

telegram:
  require_mention: true
  exclusive_bot_mentions: true
  mention_patterns:
    - "^\\s*chompy\\b"
  ignored_threads:
    - 31
    - "42"

В этом примере разрешены все обычные прямые триггеры, а также сообщения, начинающиеся с chompy, даже если они не используют @mention. Сообщения в темах Telegram 31 и 42 всегда игнорируются до запуска проверок упоминаний и свободного ответа.

Примечания к `mention_patterns`

— В шаблонах используются регулярные выражения Python.

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

Темы приватного чата (бот API 9.4)

Telegram Bot API 9.4 (февраль 2026 г.) представил Темы приватного чата — боты могут создавать темы в стиле форума непосредственно в чатах DM один на один, супергруппа не требуется. Это позволяет вам запускать несколько изолированных рабочих пространств в существующем DM с помощью VibeOS.

Вариант использования

Если вы работаете над несколькими долгосрочными проектами, темы сохраняют свой контекст отдельно:

Тема «Веб-сайт» — работа над вашим производственным веб-сервисом.
Тема «Исследование» — обзор литературы и исследование статей.
Тема «Общее» — разные задания и быстрые вопросы.

Каждая тема имеет свой собственный сеанс разговора, историю и контекст — полностью изолированный от других.

Конфигурация

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

Прежде чем добавлять темы в конфиг, пользователю необходимо включить режим тем в чате с ботом в Директ:

Откройте приватный чат с ботом VibeOS в Telegram.
Нажмите на имя бота вверху, чтобы открыть информацию о чате.
Включите Темы (переключатель, позволяющий превратить чат в форум).

Без этого VibeOS будет регистрировать The chat is not a forum при запуске и пропускать создание темы. Это настройка на стороне клиента Telegram — бот не может включить ее программно.

Добавьте темы под platforms.telegram.extra.dm_topics в ~/.vibeos/config.yaml:

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789        # Your Telegram user ID
        topics:
        - name: General
          icon_color: 7322096
        - name: Website
          icon_color: 9367192
        - name: Research
          icon_color: 16766590
          skill: arxiv              # Auto-load a skill in this topic

Поля:

Поле	Требуется	Описание
`name`	Да	Отображаемое название темы
`icon_color`	Нет	Цветовой код значка Telegram (целое число)
`icon_custom_emoji_id`	Нет	Пользовательский идентификатор смайлика для значка темы
`skill`	Нет	Навык автозагрузки при новых сессиях в этой теме
`thread_id`	Нет	Заполняется автоматически после создания темы — не устанавливайте вручную

Как это работает

При запуске шлюза VibeOS вызывает createForumTopic для каждой темы, у которой еще нет thread_id.
thread_id автоматически сохраняется обратно в config.yaml — последующие перезапуски пропускают вызов API.
Каждой теме соответствует изолированный сеансовый ключ: agent:main:telegram:dm:{chat_id}:{thread_id}.
Сообщения в каждой теме имеют свою историю разговоров, очистку памяти и контекстное окно.

Обработка корневого DM

По умолчанию обрабатываются сообщения, отправленные в корневой DM (вне любой темы). нормально. Установите ignore_root_dm: true, чтобы превратить корневой DM в лобби — нормально сообщения молча игнорируются для пользователей, у которых настроены темы DM, в то время как системные команды (/start, /help, /status и т. д.) по-прежнему работают.

platforms:
  telegram:
    extra:
      ignore_root_dm: true
      dm_topics:
        - chat_id: 123456789
          topics:
            - name: General

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

Привязка навыков

Темы с полем skill автоматически загружают этот навык, когда в теме начинается новый сеанс. Это работает точно так же, как ввод /skill-name в начале разговора — содержимое навыка вводится в первое сообщение, а последующие сообщения видят его в истории разговора.

Например, в теме с skill: arxiv навык arxiv будет предварительно загружен при каждом сбросе сеанса (из-за тайм-аута простоя, ежедневного сброса или ручного /reset).

подсказка

Темы, созданные вне конфигурации (например, путем ручного вызова Telegram API), обнаруживаются автоматически при поступлении служебного сообщения forum_topic_created. Вы также можете добавлять темы в конфиг во время работы шлюза — они будут подхвачены при следующем промахе кеша.

Многосессионный режим DM (`/topic`)

Многосессионный DM в стиле ChatGPT — один бот, множество параллельных разговоров. В отличие от режима extra.dm_topics, курируемого оператором, описанного выше, этот режим управляется пользователем: нет конфигурации, нет заранее объявленных названий тем. Конечный пользователь включает его с помощью /topic, затем нажимает кнопку Telegram +, чтобы создать столько тем, сколько он хочет, каждая из которых представляет собой полностью независимый сеанс VibeOS.

`/topic` подкоманды

Форма	Контекст	Эффект
`/topic`	Корневой DM, еще не включен	Проверьте возможности BotFather, включите многосессионный режим, создайте закрепленную системную тему
`/topic`	Корневой DM, уже включен	Показать статус: несвязанные сеансы доступны для восстановления
`/topic`	Внутри темы	Показать привязку сеанса текущей темы
`/topic help`	Любой	Встроенное использование
`/topic off`	Корневой DM	Отключить многосессионный режим и очистить все привязки тем для этого чата
`/topic` <session-id>`	Внутри темы	Восстановить предыдущую сессию Telegram в текущей теме

Только авторизованные пользователи (список разрешенных через TELEGRAM_ALLOWED_USERS/конфигурацию аутентификации платформы) могут запускать /topic. Неавторизованный отправитель вместо активации получает отказ.

Темы DM против многосессионного режима DM

	`extra.dm_topics` (управляемый конфигурацией)	`/topic` (управляется пользователем)
Кто его активирует	Оператор, в `config.yaml`	Конечный пользователь, отправив `/topic`
Список тем	Фиксированный набор, объявленный в конфигурации	Пользователь свободно создает темы /deletes
Названия тем	Выбрано оператором	Выбирается пользователем; автоматически переименовано в соответствии с заголовком сеанса VibeOS
Поведение корневого DM	Обычный чат (лобби, если `ignore_root_dm: true`)	Становится системным лобби (некомандные сообщения отклоняются)
Основной вариант использования	Постоянные рабочие места с дополнительной привязкой навыков	Специальные параллельные сеансы
Настойчивость	`extra.dm_topics` в конфиге	`telegram_dm_topic_mode` + `telegram_dm_topic_bindings` Таблицы SQLite

Обе функции могут сосуществовать в одном боте — вы запускаете /topic из личного сообщения пользователя, а extra.dm_topics продолжает управлять объявленными оператором темами для других чатов.

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

В @BotFather откройте своего бота → Настройки бота → Настройки тем:

Включите Резьбовой режим (включает has_topics_enabled).
не отключать пользователей, создающих темы (оставив allows_users_to_create_topics включенным)

Когда пользователь впервые запускает /topic, VibeOS вызывает getMe для проверки обоих флагов. Если какой-либо из них отключен, VibeOS отправляет снимок экрана страницы настроек потоков BotFather и объясняет, что переключать — активация не происходит, пока не будут выполнены предварительные условия.

Порядок активации

Из корневого DM отправьте:

/topic

VibeOS будет:

Проверьте getMe().has_topics_enabled и allows_users_to_create_topics.
Если оба варианта верны, включите режим многосессионной темы для этого DM.
Создайте и закрепите тему Система для status/commands (максимально возможное).
Ответьте списком предыдущих несвязанных сеансов Telegram, которые пользователь может восстановить.

После активации корневой DM является лобби: обычные запросы отклоняются, указывая на Все сообщения. Системные команды (/status, /sessions, /usage, /help и т.д.) по-прежнему работают в корне.

Создание новой темы (поток конечного пользователя)

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

Каждая тема имеет свою собственную историю разговоров, состояние модели, выполнение инструмента и идентификатор сеанса. Ключ изоляции — agent:main:telegram:dm:{chat_id}:{thread_id} — идентичен изоляции тем DM на основе конфигурации.

Автоматическое переименование тем

Когда VibeOS генерирует заголовок сеанса для темы (через конвейер автоматического названия после первого обмена), сама тема Telegram переименовывается в соответствии с ним — например. «Новая тема» становится «Планом миграции базы данных». Переименование выполняется максимально эффективно: сбои регистрируются, но не прерывают сеанс.

Чтобы отключить это и сохранить имена тем, выбранных вручную, нетронутыми, установите:

gateway:
  platforms:
    telegram:
      extra:
        disable_topic_auto_rename: true

Когда этот флаг включен, VibeOS по-прежнему генерирует заголовок внутреннего сеанса (используется vibeos sessions, TUI и т. д.), но никогда не редактирует имя темы Telegram. Полезно, когда вы организуете темы вручную в многопоточном режиме BotFather и не хотите, чтобы каждый первый ответ перезаписывал заголовок.

`/new` внутри темы

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

Восстановление предыдущей сессии

Внутри темы отправьте:

/topic <session-id>

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

Целевая сессия должна принадлежать одному и тому же пользователю Telegram.
Целевой сеанс не должен быть привязан к другой теме.

VibeOS подтверждает заголовок сеанса и воспроизводит последнее сообщение помощника для контекста.

Чтобы узнать идентификаторы сеансов, отправьте /topic (без аргументов) в корневой DM — VibeOS перечисляет несвязанные сеансы Telegram пользователя.

`/topic` внутри темы (без аргументов)

Показывает привязку текущей темы: заголовок сеанса, идентификатор сеанса и подсказки для /new и создания другой темы.

Под капотом

Активация сохраняется до telegram_dm_topic_mode(chat_id, user_id, enabled, ...) в state.db.
Каждая привязка темы сохраняется на telegram_dm_topic_bindings(chat_id, thread_id, session_id, ...), а ON DELETE CASCADE на session_id — обрезка сеанса автоматически очищает привязку к теме.
Миграция SQLite в тематическом режиме осуществляется по согласию: она запускается при первом вызове /topic, а не при запуске шлюза. Пока пользователь не запустит /topic в этом профиле, state.db не изменится.
Каждое входящее сообщение DM ищет свою привязку (chat_id, thread_id). Если он присутствует, поиск направляет сообщение в связанный сеанс через SessionStore.switch_session(), чтобы сопоставление ключа сеанса с идентификатором сеанса оставалось согласованным на диске.
/new внутри темы перезаписывает строку привязки, чтобы указать на новый идентификатор сеанса, поэтому следующее сообщение остается в новом сеансе.
Темы, объявленные в extra.dm_topics, никогда не переименовываются автоматически — имя, выбранное оператором, сохраняется даже при включении многосессионного режима.
Установите extra.disable_topic_auto_rename: true, чтобы отключить автоматическое переименование для всех тем в чате (включая специальные темы, созданные в потоковом режиме).
Тема «Общие» (закрепленная вверху) в DM с поддержкой форума рассматривается как корневое лобби, независимо от того, доставляет ли Telegram свои сообщения с message_thread_id=1 или без thread_id.
Напоминания в корневом лобби ограничены одним сообщением за 30 секунд для каждого чата — пользователь, который забудет включен режим темы и введет десять запросов в корне, не получит десять ответов.
Скриншоты настройки BotFather ограничены одной отправкой за 5 минут на чат — повторные попытки /topic, пока настройки тем все еще отключены, не будут повторно загружать одно и то же изображение.
/background <prompt>`, запущенный внутри темы, возвращает результат обратно в ту же тему; фоновые сеансы не вызывают автоматическое переименование темы-владельца
Сам /topic закрыт проверкой авторизации пользователя бота — неавторизованные DM вместо активации получают отказ

Отключение многосессионного режима

Отправьте /topic off в корневой DM. VibeOS отключает строку, очищает привязки чата (thread_id → session_id), и корневой DM возвращается к обычному чату VibeOS. Существующие темы в Telegram не удаляются — они просто перестают быть независимыми сессиями. Повторно запустите /topic позже, чтобы снова включить его.

Если вам нужно выполнить очистку вручную (например, выполнить массовый сброс во многих чатах), удалите строки напрямую:

sqlite3 ~/.vibeos/state.db \
  "UPDATE telegram_dm_topic_mode SET enabled = 0 WHERE chat_id = '<your_chat_id>'; \
   DELETE FROM telegram_dm_topic_bindings WHERE chat_id = '<your_chat_id>';"

Понижение версии VibeOS

Если вы откатитесь на версию VibeOS, предшествующую /topic, эта функция просто перестанет работать — таблицы telegram_dm_topic_mode и telegram_dm_topic_bindings останутся в state.db, но будут игнорироваться более старым кодом. DM возвращаются к встроенной изоляции каждого потока (каждый message_thread_id по-прежнему получает свой собственный сеанс через build_session_key), поэтому ваши существующие темы Telegram продолжают работать как параллельные сеансы. Корневой DM больше не является лобби — сообщения оттуда поступают агенту, как раньше. Повторное обновление активирует многосессионный режим именно там, где он был.

Привязка навыков к теме группового форума

Супергруппы с включенным режимом тем (также называемые «темами форума») уже получают изоляцию сеансов для каждой темы — каждая thread_id сопоставляется со своим собственным разговором. Но вы можете захотеть автоматически загружать навык, когда сообщения приходят в определенную групповую тему, точно так же, как работает привязка навыков к теме DM.

Вариант использования

Супергруппа команды с темами форума для разных направлений работы:

Тема Инженерное дело → автоматически загружается навык software-development.
Тема исследования → автоматически загружается навык arxiv.
Общая тема → без навыков, универсальный помощник.

Конфигурация

Добавьте привязки темы под platforms.telegram.extra.group_topics в ~/.vibeos/config.yaml:

platforms:
  telegram:
    extra:
      group_topics:
      - chat_id: -1001234567890       # Supergroup ID
        topics:
        - name: Engineering
          thread_id: 5
          skill: software-development
        - name: Research
          thread_id: 12
          skill: arxiv
        - name: General
          thread_id: 1
          # No skill — general purpose

Поля:

Поле	Требуется	Описание
`chat_id`	Да	Числовой идентификатор супергруппы (отрицательное число, начинающееся с `-100`)
`name`	Нет	Читабельная метка темы (только для информации)
`thread_id`	Да	Идентификатор темы форума Telegram — виден в ссылках `t.me/c/<group_id>/`<thread_id>`
`skill`	Нет	Навык автозагрузки при новых сессиях в этой теме

Как это работает

Когда сообщение поступает в тему сопоставленной группы, VibeOS ищет chat_id и thread_id в конфигурации group_topics.
Если совпадающая запись имеет поле skill, этот навык автоматически загружается для сеанса — аналогично привязке навыка к теме DM.
Темы без ключа skill получают только изоляцию сеанса (существующее поведение без изменений).
Несопоставленные значения thread_id или значения chat_id проваливаются автоматически — ни ошибки, ни навыков.

Отличия от тем DM

	Темы DM	Темы группы
Конфигурационный ключ	`extra.dm_topics`	`extra.group_topics`
Создание темы	VibeOS создает темы через API, если `thread_id` отсутствует	Администратор создает темы в интерфейсе Telegram
`thread_id`	Автоматически заполняется после создания	Должен быть установлен вручную
`icon_color` / `icon_custom_emoji_id`	Поддерживается	Неприменимо (администратор контролирует внешний вид)
Привязка навыков	✓	✓
Изоляция сеанса	✓	✓ (уже встроено для тем форума)

подсказка

Чтобы найти thread_id темы, откройте тему в Telegram Web или Desktop и посмотрите на URL: https://t.me/c/1234567890/5 — последний номер (5) — это thread_id. chat_id для супергрупп — это идентификатор группы с префиксом -100 (например, группа 1234567890 становится -1001234567890).

Последние возможности бота API

Бот API 9.4 (февраль 2026 г.): Частные темы чата — боты могут создавать темы на форуме в чатах DM один на один через createForumTopic. VibeOS использует это для двух различных функций: курируемых оператором Темы частного чата (управляемый конфигурацией, фиксированный список тем) и управляемых пользователем Многосессионный режим DM (активируется /topic, неограниченное количество тем, создаваемых пользователями).
Политика конфиденциальности. Telegram теперь требует, чтобы у ботов была политика конфиденциальности. Установите его через BotFather с помощью /setprivacy_policy, иначе Telegram может автоматически сгенерировать заполнитель. Это особенно важно, если ваш бот общедоступен.
Бот API 9.5 (март 2026 г.): встроенная потоковая передача через sendMessageDraft. VibeOS поддерживает собственный потоковый проект Telegram API в качестве дополнительного транспорта для частных чатов. По умолчанию остается устаревший путь editMessageText, поскольку предварительный просмотр черновиков может заметно сворачиваться и повторно отображаться в некоторых клиентах Telegram.

Потоковый транспорт (`gateway.streaming.transport`)

Когда потоковая передача включена (gateway.streaming.enabled: true), VibeOS выбирает один из четырех видов транспорта:

Значение	Поведение
`auto` (по умолчанию)	Собственная трансляция черновиков в поддерживаемых чатах (в настоящее время в личных сообщениях Telegram); в противном случае устаревший путь на основе редактирования. Грамотно откатывается назад, если черновой кадр терпит неудачу.
`draft`	Принудительно использовать собственные черновики. Регистрирует переход на более раннюю версию и возвращается к редактированию, если чат не поддерживает черновики (например, groups/topics).
`edit`	Устаревший прогрессивный опрос `editMessageText` для каждого типа чата.
`off`	Полностью отключить потоковую передачу (только окончательный ответ, без прогрессивных обновлений).

В ~/.vibeos/config.yaml:

gateway:
  streaming:
    enabled: true
    transport: auto    # auto | draft | edit | off

То, что вы увидите в личных сообщениях с edit (по умолчанию) — шлюз отправляет обычное сообщение предварительного просмотра и постепенно обновляет его через editMessageText, избегая эффекта свертывания черновика Telegram /rollback.

Что вы увидите в личных сообщениях с auto или draft — Telegram показывает анимированный предварительный просмотр черновика, который обновляет токен за токеном. Когда ответ заканчивается, он доставляется как обычное сообщение, и предварительный просмотр черновика автоматически очищается на клиенте. Черновики не имеют идентификатора сообщения, поэтому окончательный ответ остается в вашей истории чата.

А как насчет групп, супергрупп, тем форума? Telegram ограничивает sendMessageDraft частными чатами (DM). Шлюз прозрачно возвращается к пути редактирования для всего остального — тот же UX, что и раньше.

Что, если черновик кадра завершится сбоем? Любой сбой (временная сетевая ошибка, отклонение на стороне сервера, установка более старой версии python-telegram-bot) возвращает этот ответ к пути, основанному на редактировании, для остальной части потока. Следующий ответ получает новую попытку.

Рендеринг: расширенные сообщения, таблицы и предварительный просмотр ссылок

Расширенные сообщения (бот API 10.1). Окончательные ответы, содержащие конструкции, устаревшие пути MarkdownV2 — таблицы, списки задач, сворачиваемый <details> и математические блоки — отправляются с помощью собственного Telegram [sendRichMessage](https://core.telegram.org/bots/api#sendrichmessage) с использованием **необработанной markdown** агента, поэтому они визуализируйте изначально без выравнивания на стороне клиента. Во время потоковой передачи окончательный ответ предоставляется путем **редактирования существующего предварительного просмотра на месте** с помощью параметра editMessageText rich_message— ни второго сообщения, ни удаления, поэтому в конце хода нет мерцания дублированной доставки. В личных сообщениях предварительный просмотр прямой трансляции также используетsendRichMessageDraft`, поэтому анимированный черновик соответствует окончательному расширенному сообщению. Обычные ответы (простая проза, жирный шрифт /italic, простые списки) остаются в пути MarkdownV2 для обеспечения одинакового размера шрифта и интервалов между клиентами.

Расширенный путь автоматически пропускается, когда содержимое превышает ограничение в 32 768 символов, а любое отклонение от Telegram (неподдерживаемая конечная точка в более старой версии python-telegram-bot, ошибка синтаксического анализатора, слишком большие блоки /columns) прозрачно возвращается к пути MarkdownV2 — ваше сообщение никогда не теряется. Ошибки Transient/network не пересылаются автоматически (без дублирования конечного сообщения).

Резервный вариант MarkdownV2. Если расширенный путь недоступен для сообщения, VibeOS преобразует markdown в MarkdownV2. Поскольку MarkdownV2 не имеет собственного синтаксиса таблиц, таблицы каналов нормализуются:

– Небольшие таблицы объединяются в маркеры групп строк — каждая строка становится читаемым маркированным списком под заголовками столбцов. Подходит для 2–4 столбцов и коротких ячеек. – Большие или более широкие таблицы возвращаются к огороженному блоку кода с выровненными столбцами, чтобы ничего не схлопывалось.

Расширенные сообщения доступны по согласию. По умолчанию остается устаревший путь MarkdownV2, поскольку текущие клиенты Telegram могут затруднить копирование расширенных сообщений Bot API в виде обычного текста, что особенно болезненно для фрагментов команд и мобильных передач. Включение встроенного рендеринга для таблиц/task списков/details/math:

gateway:
  platforms:
    telegram:
      extra:
        rich_messages: true
        rich_drafts: false

Этот параметр предназначен для совместимости с клиентским рендерингом /copy; VibeOS уже автоматически возвращается, когда Telegram отклоняет расширенный вызов API. rich_drafts управляет экспериментальным путем предварительного просмотра расширенного черновика во время потоковой передачи Telegram DM и остается отключенным по умолчанию, поскольку Telegram Desktop/macOS может визуально накладывать кадры расширенного черновика до тех пор, пока чат не будет перерисован. Если вам нужно только устаревшее поведение таблицы «всегда с блокировкой кода», сохраняя при этом расширенные сообщения, отключите нормализацию таблицы, установив telegram.pretty_tables: false в config.yaml (по умолчанию: true).

Предварительный просмотр ссылок. Telegram автоматически создает предварительный просмотр ссылок для URL-адресов в сообщениях ботов. Если вы предпочитаете их подавить (длинный вывод /tools, ответ агента, в котором упоминаются десять ссылок и т. д.):

gateway:
  platforms:
    telegram:
      extra:
        disable_link_previews: true

При включении VibeOS прикрепляет LinkPreviewOptions(is_disabled=True) Telegram к каждому исходящему сообщению и возвращается к устаревшему параметру disable_web_page_preview в более старых версиях python-telegram-bot.

Белый список групп

Группы Telegram и чаты на форумах имеют два ортогональных шлюза, которые вы можете настроить:

Идентификаторы пользователей отправителя (group_allow_from / TELEGRAM_GROUP_ALLOWED_USERS) — список разрешений на уровне отправителя, который применяется только к сообщениям группы /forum. Используйте это, если вы хотите, чтобы определенные пользователи могли вызывать бота в группах, не добавляя их в TELEGRAM_ALLOWED_USERS (что также предоставит им доступ к DM).
Идентификаторы чата (group_allowed_chats / TELEGRAM_GROUP_ALLOWED_CHATS) — белый список на уровне чата. С ботом может взаимодействовать любой участник этих групп/forums. Полезно для ботов Team/support, где членство в группе само по себе является сигналом доступа.

gateway:
  platforms:
    telegram:
      extra:
        # Global access (DMs + groups). Users here can always invoke the bot.
        allow_from:
          - "123456789"
        # Sender IDs allowed in groups/forums only. Does NOT grant DM access.
        group_allow_from:
          - "987654321"
        # Entire groups/forums — any member is authorized.
        group_allowed_chats:
          - "-1001234567890"

Эквивалентные переменные окружения:

TELEGRAM_ALLOWED_USERS="123456789"
TELEGRAM_GROUP_ALLOWED_USERS="987654321"
TELEGRAM_GROUP_ALLOWED_CHATS="-1001234567890"

Поведение:

TELEGRAM_ALLOWED_USERS охватывает все типы чатов (DM, группы, форумы).
TELEGRAM_GROUP_ALLOWED_USERS авторизует только перечисленных отправителей в группах. /forums. Они по-прежнему не могут отправлять сообщения боту, если они не указаны в TELEGRAM_ALLOWED_USERS.
Чат в TELEGRAM_GROUP_ALLOWED_CHATS авторизует каждого участника этого чата, независимо от отправителя.
Используйте * в любом из них, чтобы разрешить любому отправителю /chat..
Этот слой поверх существующих триггеров упоминания /pattern и поверх group_topics + ignored_threads.

Миграция с предыдущего PR #17686

До этого разделения TELEGRAM_GROUP_ALLOWED_USERS был единственной кнопкой, и пользователи помещали в нее идентификаторы чата. В целях обратной совместимости значения в форме идентификатора чата (начиная с -) в TELEGRAM_GROUP_ALLOWED_USERS по-прежнему учитываются как идентификаторы чата, а предупреждение об устаревании регистрируется один раз. Миграция:

# Old (still works, but deprecated)
TELEGRAM_GROUP_ALLOWED_USERS="-1001234567890"

# New
TELEGRAM_GROUP_ALLOWED_CHATS="-1001234567890"

Обход гостевого @mention (`guest_mode`)

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

Для более случайных настроек — групповых чатов друзей, в которых вы хотите, чтобы бот в основном молчал, но иногда был доступен при явном пинге — включите guest_mode:

gateway:
  platforms:
    telegram:
      extra:
        group_allowed_chats:
          - "-1001234567890"   # your main allowlisted group
        guest_mode: true       # non-allowlisted groups: allow on @mention only

Эквивалент конвертации:

TELEGRAM_GUEST_MODE=true

По умолчанию: false.

При использовании guest_mode: true сообщение из группы, не внесенной в белый список, обрабатывается только, если в нем явно @упоминается бот. Упоминание требуется на каждом шагу — для взаимодействия с гостями сеанс не привязан, поэтому бот никогда автоматически не подключается к ветке группы друзей, к которой он не подключен.

DM и группы из белого списка ведут себя точно так же, как и раньше.

Контроль доступа slash-команд

По умолчанию любой пользователь из allowlist может запускать любую slash-команду. Чтобы разделить на админов (полный набор slash-команд) и обычных пользователей (только явно разрешённые), добавьте allow_admin_from и user_allowed_commands в блок extra платформы:

gateway:
  platforms:
    telegram:
      extra:
        # Existing allowlists (unchanged)
        allow_from:
          - "123456789"     # admin
          - "555555555"     # regular user
          - "777777777"     # regular user

        # NEW — admins get all slash commands (built-in + plugin)
        allow_admin_from:
          - "123456789"

        # NEW — non-admin allowed users can only run these slash commands.
        # /help and /whoami are always allowed so users can see their access.
        user_allowed_commands:
          - status
          - model
          - history

        # Optional: separate admin/command lists for groups
        group_allow_admin_from:
          - "123456789"
        group_user_allowed_commands:
          - status

Поведение:

Пользователь, указанный в allow_admin_from для области (DM или группы), может запускать каждую зарегистрированную slash-команду — встроенные команды, зарегистрированные в плагине AND — через действующий реестр.
Пользователь в allow_from, но не в allow_admin_from, может запускать только команды, перечисленные в user_allowed_commands, а также всегда разрешенный уровень: /help и /whoami.
Обычный чат (сообщения без slash) не затрагивается. Пользователи, не являющиеся администраторами, по-прежнему могут нормально общаться с агентом, они просто не могут запускать произвольные команды.
Обратная совместимость: если allow_admin_from не установлен для области, для этой области отключается slash-команда. Существующие установки продолжают работать без изменений.
Статус администратора DM не подразумевает статус администратора группы. Каждая область имеет свой собственный список администраторов.
Если установлен только group_allow_admin_from, область DM остается в неограниченном режиме (обратной совместимости).

Используйте /whoami, чтобы увидеть активную область, ваш уровень (администратор/пользователь/неограниченный) и какие slash-команды вы можете запускать.

Интерактивный выбор моделей

Когда вы отправляете /model без аргументов в чат Telegram, VibeOS показывает интерактивную встроенную клавиатуру для переключения моделей:

Выбор провайдера — кнопки, показывающие каждого доступного провайдера с указанием количества моделей (например, «OpenAI (15)», «✓ Anthropic (12)» для текущего провайдера).
Выбор модели – постраничный список моделей с навигацией Предыдущая/Следующая, кнопкой Назад для возврата к поставщикам и Отмена.

Текущая модель и поставщик отображаются вверху. Вся навигация происходит путем редактирования одного и того же сообщения на месте (без беспорядка в чате).

подсказка

Если вы знаете точное название модели, введите /model <name> напрямую, чтобы пропустить сборщик. Вы также можете ввести /model <name> --global`, чтобы сохранить изменения между сеансами.

DNS-over-HTTPS Резервные IP-адреса

В некоторых сетях с ограниченным доступом api.telegram.org может разрешить недоступный IP-адрес. Адаптер Telegram включает в себя механизм резервного IP, который прозрачно повторяет соединения с альтернативными IP-адресами, сохраняя при этом правильное имя хоста TLS и SNI.

Как это работает

Если установлен TELEGRAM_FALLBACK_IPS, эти IP-адреса используются напрямую.
В противном случае адаптер автоматически запрашивает Google DNS и Cloudflare DNS через DNS-over-HTTPS (DoH), чтобы обнаружить альтернативные IP-адреса для api.telegram.org.
IP-адреса, возвращаемые DoH, которые отличаются от системного результата DNS, используются в качестве резервных.
Если DoH также заблокирован, в крайнем случае используется жестко закодированный начальный IP-адрес (149.154.167.220).
Как только резервный IP-адрес успешен, он становится «прикрепленным» — последующие запросы используют его напрямую, не повторяя сначала основной путь.

Конфигурация

# Explicit fallback IPs (comma-separated)
TELEGRAM_FALLBACK_IPS=149.154.167.220,149.154.167.221

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

platforms:
  telegram:
    extra:
      fallback_ips:
        - "149.154.167.220"

подсказка

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

Поддержка прокси

Если вашей сети требуется прокси-сервер HTTP для доступа в Интернет (обычно в корпоративных средах), адаптер Telegram автоматически считывает стандартные переменные среды прокси-сервера и маршрутизирует все соединения через прокси-сервер.

Поддерживаемые переменные

Адаптер проверяет эти переменные среды по порядку, используя первую установленную:

HTTPS_PROXY
HTTP_PROXY
ALL_PROXY
https_proxy / http_proxy / all_proxy (варианты в нижнем регистре)

Конфигурация

Установите прокси-сервер в своей среде перед запуском шлюза:

export HTTPS_PROXY=http://proxy.example.com:8080
vibeos gateway

Или добавьте его в ~/.vibeos/.env:

HTTPS_PROXY=http://proxy.example.com:8080

Прокси-сервер применяется как к основному транспорту, так и ко всем резервным IP-транспортам. Никакой дополнительной настройки VibeOS не требуется — если переменная среды установлена, она используется автоматически.

примечание

Здесь рассматривается пользовательский резервный транспортный уровень, который VibeOS использует для соединений Telegram. Стандартный клиент httpx, используемый где-то еще, уже изначально учитывает переменные окружения прокси.

Реакции на сообщения

Бот может добавлять эмодзи-реакции к сообщениям в качестве обратной связи по визуальной обработке:

👀 когда бот начнет обрабатывать ваше сообщение
✅ когда ответ доставлен успешно
❌ если при обработке произошла ошибка

Реакции отключены по умолчанию. Включите их в config.yaml:

telegram:
  reactions: true

Или через переменную среды:

TELEGRAM_REACTIONS=true

примечание

В отличие от Discord (где реакции суммируются), бот Telegram API заменяет все реакции бота за один вызов. Переход от 👀 к ✅/❌ происходит атомарно — вы не увидите оба сразу.

подсказка

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

Подсказки для каждого канала

Назначайте временные системные подсказки конкретным группам Telegram или темам форума. Приглашение вводится во время выполнения на каждом ходу и никогда не сохраняется в истории расшифровки, поэтому изменения вступают в силу немедленно.

telegram:
  channel_prompts:
    "-1001234567890": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "42":  |
      This topic is for creative writing feedback. Be warm and
      constructive.

Ключи — это идентификаторы чатов (groups/supergroups) или идентификаторы тем форума. Для групп форума подсказки на уровне темы переопределяют подсказки на уровне группы:

Сообщение в теме 42 внутри группы -1001234567890 → используется подсказка темы 42.
Сообщение в теме 99 (без явной записи) → возвращается к подсказке группы -1001234567890.
Сообщение в группе без записи → подсказка о канале не применяется.

Числовые ключи YAML автоматически преобразуются в строки.

Устранение неполадок

Проблема	Решение
Бот вообще не отвечает	Убедитесь, что `TELEGRAM_BOT_TOKEN` верен. Проверьте журналы `vibeos gateway` на наличие ошибок.
Бот отвечает «несанкционировано»	Ваш идентификатор пользователя не указан в `TELEGRAM_ALLOWED_USERS`. Проверьте еще раз с помощью @userinfobot.
Бот игнорирует групповые сообщения	Вероятно, режим конфиденциальности включен. Отключите его (Шаг 3) или сделайте бота администратором группы. Не забудьте удалить и повторно добавить бота после изменения конфиденциальности.
Голосовые сообщения не расшифрованы	Убедитесь, что STT доступен: установите `faster-whisper` для локальной транскрипции или установите `GROQ_API_KEY`/`VOICE_TOOLS_OPENAI_KEY` в `~/.vibeos/.env`.
Голосовые ответы — это файлы, а не пузырьки	Установите `ffmpeg` (необходим для преобразования Edge TTS Opus).
Токен бота отозван/invalid	Создайте новый токен через `/revoke`, затем `/newbot` или `/token` в BotFather. Обновите файл `.env`.
Вебхук не получает обновлений	Убедитесь, что `TELEGRAM_WEBHOOK_URL` общедоступен (проверьте с помощью `curl`). Убедитесь, что прокси-сервер вашей платформы /reverse направляет входящий трафик HTTPS из порта URL на локальный порт прослушивания, настроенный `TELEGRAM_WEBHOOK_PORT` (они не обязательно должны иметь одинаковый номер). Убедитесь, что SSL/TLS активен — Telegram отправляет сообщения только на URL-адреса HTTPS. Проверьте правила брандмауэра.

Утверждение исполнительного директора

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

⚠️ Эта команда потенциально опасна (рекурсивное удаление). Ответьте «да», чтобы одобрить.

Ответьте «да»/«да», чтобы одобрить, или «нет»/«н», чтобы отклонить.

Интерактивные подсказки (уточните)

Когда агент вызывает инструмент clarify — чтобы спросить, какой подход вы предпочитаете, получить обратную связь после выполнения задачи или проверить перед принятием нетривиального решения — Telegram отображает вопрос с помощью встроенных кнопок клавиатуры:

❓ Какой фреймворк мне следует использовать для дашборда?

[1. Next.js] [2. Ремикс] [3. Астро] [✏️ Другое (введите ответ)]

Нажмите кнопку, чтобы ответить, или нажмите Другое, чтобы ввести ответ в свободной форме (следующее отправленное вами сообщение станет ответом). Открытые вызовы clarify (без предустановленных вариантов) пропускают кнопки и просто записывают следующее сообщение.

Настройте таймаут ответа через agent.clarify_timeout в ~/.vibeos/config.yaml (по умолчанию 600 секунды). Если вы не ответите в течение тайм-аута, агент разблокируется с помощью дозорного сообщения и адаптируется, а не зависает.

Громкость push-уведомлений

Telegram отправляет push-уведомление о каждом сообщении, отправляемом ботом. При длительных оборотах агентов, сопровождающихся всплывающими сообщениями о ходе работы инструмента, потоковыми обновлениями и обратными вызовами состояния, это быстро становится шумным. Адаптер Telegram имеет два режима уведомлений:

Режим	Поведение
`important` (по умолчанию)	Звонят только окончательные ответы, подсказки об одобрении и подтверждения slash-команд. Ход работы инструмента, потоковые фрагменты и сообщения о состоянии доставляются с помощью `disable_notification=true`.
`all`	Каждое исходящее сообщение отправляет push-уведомление. Унаследованное поведение; подпишитесь, если вы действительно хотите получать информацию о каждом вызове инструмента.

Настройте в ~/.vibeos/config.yaml:

display:
  platforms:
    telegram:
      notifications: important   # or "all"

Переопределение Env (удобно для быстрого тестирования A/B):

VIBEOS_TELEGRAM_NOTIFICATIONS=all

Неизвестные значения регистрируют предупреждение и возвращаются к important.

Сообщения о состоянии отредактированы на месте

Адаптер Telegram маршрутизирует повторяющиеся обратные вызовы статуса агента (например, «Сжатие контекста…», «Вызов инструмента…») через send_or_update_status(), который сохраняет кэш {(chat_id, status_key) → message_id} и редактирует существующий пузырь при последующих выпусках вместо добавления каждый раз нового. Отдельные значения status_key получают свои собственные сообщения; отдельные чаты никогда не конфликтуют. Если редактирование не удалось (например, пользователь удалил сообщение или оно старше, чем Telegram позволяет редактировать), запись в кэше удаляется, а следующий выпуск публикует новое сообщение и повторно кэширует его идентификатор. Никакой настройки не требуется — это поведение Telegram по умолчанию. Другие адаптеры, которые не реализуют send_or_update_status, без изменений переходят на обычный send().

Закрепить входящее сообщение пользователя во время поворота агента

Когда пользователь отправляет сообщение, которое вызывает очередь агента, адаптер Telegram закрепляет это входящее сообщение на время очереди и открепляет его, когда ответ будет завершен — легкий визуальный индикатор того, что бот активно работает над сообщением, а не игнорирует его. Пин использует disable_notification=true, чтобы избежать дополнительных пингов. Никакой конфигурации не требуется.

Безопасность

предупреждение

Всегда устанавливайте TELEGRAM_ALLOWED_USERS, чтобы ограничить круг лиц, которые могут взаимодействовать с вашим ботом. Без него шлюз по умолчанию запрещает доступ всем пользователям в качестве меры безопасности.

Никогда не делитесь своим токеном бота публично. В случае взлома немедленно отмените его с помощью команды BotFather /revoke.

Более подробную информацию см. в Документации по безопасности. Вы также можете использовать DMpairing для более динамичного подхода к авторизации пользователей.

Шаг 1. Создайте бота через BotFather
Шаг 2. Настройте своего бота (необязательно)
- Индикатор состояния Online/Offline (дополнительно)
- Приоритет и ограничение меню команд (необязательно)
Шаг 3: Режим конфиденциальности (критичен для групп)
- Как отключить режим конфиденциальности
- Наблюдайте за групповым общением без автоответа
Шаг 4. Найдите свой идентификатор пользователя
Шаг 5: Настройте VibeOS
- Вариант A: Интерактивная настройка (рекомендуется)
- Вариант Б: Настройка вручную
- Запуск шлюза
Отправка сгенерированных файлов с терминалов, поддерживаемых Docker
- Поддерживаемые расширения файлов MEDIA:
Режим вебхука
- Конфигурация
- Пример облачного развертывания (Fly.io)
Поддержка прокси
Домашний канал
- Доставки Cron в тематическом режиме
Голосовые сообщения
- Входящий голос (преобразование речи в текст)
- Исходящая голосовая связь (преобразование текста в речь)
Большие файлы (>20 МБ) через локальный сервер Bot API
- Шаг 1. Получите учетные данные Telegram API
- Шаг 2. Запустите сервер Telegram-bot-api
- Шаг 3: Выходим из паблика бота API (однократно)
- Шаг 4. Наведите VibeOS на локальный сервер.
- Шаг 5: local_mode — доступ к файлу на диске
- Шаг 6: Проверьте это
Использование группового чата
- Несколько ботов VibeOS в одной группе
- Устранение неполадок: работает в личных сообщениях, но не в группах.
- Пример настройки группового триггера
- Примечания к mention_patterns
Темы приватного чата (бот API 9.4)
- Вариант использования
- Конфигурация
- Как это работает
- Обработка корневого DM
- Привязка навыков
Многосессионный режим DM (/topic)
- /topic подкоманды
- Темы DM против многосессионного режима DM
- Предварительные условия
- Порядок активации
- Создание новой темы (поток конечного пользователя)
- Автоматическое переименование тем
- /new внутри темы
- Восстановление предыдущей сессии
- /topic внутри темы (без аргументов)
- Под капотом
- Отключение многосессионного режима
- Понижение версии VibeOS
Привязка навыков к теме группового форума
- Вариант использования
- Конфигурация
- Как это работает
- Отличия от тем DM
Последние возможности бота API
- Потоковый транспорт (gateway.streaming.transport)
Рендеринг: расширенные сообщения, таблицы и предварительный просмотр ссылок
Белый список групп
- Миграция с предыдущего PR #17686
- Обход гостевого @mention (guest_mode)
Контроль доступа slash-команд
Интерактивный выбор моделей
DNS-over-HTTPS Резервные IP-адреса
- Как это работает
- Конфигурация
Поддержка прокси
- Поддерживаемые переменные
- Конфигурация
Реакции на сообщения
Подсказки для каждого канала
Устранение неполадок
Утверждение исполнительного директора
Интерактивные подсказки (уточните)
Громкость push-уведомлений
Сообщения о состоянии отредактированы на месте
Закрепить входящее сообщение пользователя во время поворота агента
Безопасность

Шаг 1. Создайте бота через BotFather​

Шаг 2. Настройте своего бота (необязательно)​

Индикатор состояния Online/Offline (дополнительно)​

Приоритет и ограничение меню команд (необязательно)​

Шаг 3: Режим конфиденциальности (критичен для групп)​

Как отключить режим конфиденциальности​

Наблюдайте за групповым общением без автоответа​

Шаг 4. Найдите свой идентификатор пользователя​

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

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

Вариант Б: Настройка вручную​

Запуск шлюза​

Отправка сгенерированных файлов с терминалов, поддерживаемых Docker​

Поддерживаемые расширения файлов MEDIA:​

Режим вебхука​

Конфигурация​

Пример облачного развертывания (Fly.io)​

Поддержка прокси​

Домашний канал​

Доставки Cron в тематическом режиме​

Голосовые сообщения​

Входящий голос (преобразование речи в текст)​

Пропуск STT: передать необработанный аудиофайл агенту​

Исходящая голосовая связь (преобразование текста в речь)​

Большие файлы (>20 МБ) через локальный сервер Bot API​

Шаг 1. Получите учетные данные Telegram API​

Шаг 2. Запустите сервер Telegram-bot-api​

Шаг 3: Выходим из паблика бота API (однократно)​

Шаг 4. Наведите VibeOS на локальный сервер.​

Шаг 5: local_mode — доступ к файлу на диске​

Шаг 6: Проверьте это​

Использование группового чата​

Несколько ботов VibeOS в одной группе​

Устранение неполадок: работает в личных сообщениях, но не в группах.​

Пример настройки группового триггера​

Примечания к mention_patterns​

Темы приватного чата (бот API 9.4)​

Вариант использования​

Конфигурация​

Как это работает​

Обработка корневого DM​

Привязка навыков​

Многосессионный режим DM (/topic)​

/topic подкоманды​

Темы DM против многосессионного режима DM​

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

Порядок активации​

Создание новой темы (поток конечного пользователя)​

Автоматическое переименование тем​

/new внутри темы​

Восстановление предыдущей сессии​

/topic внутри темы (без аргументов)​

Под капотом​

Отключение многосессионного режима​

Понижение версии VibeOS​

Привязка навыков к теме группового форума​

Вариант использования​

Конфигурация​

Как это работает​

Отличия от тем DM​

Последние возможности бота API​

Потоковый транспорт (gateway.streaming.transport)​

Рендеринг: расширенные сообщения, таблицы и предварительный просмотр ссылок​

Белый список групп​

Миграция с предыдущего PR #17686​

Обход гостевого @mention (guest_mode)​

Контроль доступа slash-команд​

Интерактивный выбор моделей​

DNS-over-HTTPS Резервные IP-адреса​

Как это работает​

Конфигурация​

Поддержка прокси​

Поддерживаемые переменные​

Конфигурация​

Реакции на сообщения​

Подсказки для каждого канала​

Устранение неполадок​

Утверждение исполнительного директора​

Интерактивные подсказки (уточните)​

Громкость push-уведомлений​

Шаг 1. Создайте бота через BotFather

Шаг 2. Настройте своего бота (необязательно)

Индикатор состояния Online/Offline (дополнительно)

Приоритет и ограничение меню команд (необязательно)

Шаг 3: Режим конфиденциальности (критичен для групп)

Как отключить режим конфиденциальности

Наблюдайте за групповым общением без автоответа

Шаг 4. Найдите свой идентификатор пользователя

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

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

Вариант Б: Настройка вручную

Запуск шлюза

Отправка сгенерированных файлов с терминалов, поддерживаемых Docker

Поддерживаемые расширения файлов `MEDIA:`

Режим вебхука

Конфигурация

Пример облачного развертывания (Fly.io)

Поддержка прокси

Домашний канал

Доставки Cron в тематическом режиме

Голосовые сообщения

Входящий голос (преобразование речи в текст)

Пропуск STT: передать необработанный аудиофайл агенту

Исходящая голосовая связь (преобразование текста в речь)

Большие файлы (>20 МБ) через локальный сервер Bot API

Шаг 1. Получите учетные данные Telegram API

Шаг 2. Запустите сервер Telegram-bot-api

Шаг 3: Выходим из паблика бота API (однократно)

Шаг 4. Наведите VibeOS на локальный сервер.

Шаг 5: `local_mode` — доступ к файлу на диске

Шаг 6: Проверьте это

Использование группового чата

Несколько ботов VibeOS в одной группе

Устранение неполадок: работает в личных сообщениях, но не в группах.

Пример настройки группового триггера

Примечания к `mention_patterns`

Темы приватного чата (бот API 9.4)

Вариант использования

Конфигурация

Как это работает

Обработка корневого DM

Привязка навыков

Многосессионный режим DM (`/topic`)

`/topic` подкоманды

Темы DM против многосессионного режима DM

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

Порядок активации

Создание новой темы (поток конечного пользователя)

Автоматическое переименование тем

`/new` внутри темы

Восстановление предыдущей сессии

`/topic` внутри темы (без аргументов)

Под капотом

Отключение многосессионного режима

Понижение версии VibeOS

Привязка навыков к теме группового форума

Вариант использования

Конфигурация

Как это работает

Отличия от тем DM

Последние возможности бота API

Потоковый транспорт (`gateway.streaming.transport`)

Рендеринг: расширенные сообщения, таблицы и предварительный просмотр ссылок

Белый список групп

Миграция с предыдущего PR #17686

Обход гостевого @mention (`guest_mode`)

Контроль доступа slash-команд

Интерактивный выбор моделей

DNS-over-HTTPS Резервные IP-адреса

Как это работает

Конфигурация

Поддержка прокси

Поддерживаемые переменные

Конфигурация

Реакции на сообщения

Подсказки для каждого канала

Устранение неполадок

Утверждение исполнительного директора

Интерактивные подсказки (уточните)

Громкость push-уведомлений