# Мост в Telegram — управление агентом с телефона

← [Документация](../README.md)

> **Отвечает на вопросы:** как подключить телеграм-бота к VibeIDE, как управлять агентом с телефона, как настроить телеграм / telegram bot, почему бот молчит, как отправлять голосовые сообщения агенту, что делать если Telegram заблокирован.
>
> Мануал «как начать». Что мост умеет — в [functional.md](../functional.md); почему устроен именно так — в разделе «Решения» ниже.

Мост даёт поставить агенту задачу из Telegram, видеть, что прогон идёт, и получить ответ, когда вы не за компьютером. Бот у вас **свой**, нашего сервера в цепочке нет: IDE сама ходит в `api.telegram.org`.

---

## 1. Создать бота (одна минута)

1. Откройте [@BotFather](https://t.me/BotFather) в Telegram.
2. Отправьте `/newbot`, дайте имя и username (username обязан оканчиваться на `bot`).
3. BotFather пришлёт **токен** вида `123456789:AAG...`. Это полный доступ к боту — обращайтесь с ним как с паролем.

## 2. Вставить токен и включить мост

**Настройки VibeIDE → Функции → Мост в Telegram.** Там же всё остальное: тумблер, код привязки, прокси и список разрешённых чатов.

Вставьте токен в поле **«Токен бота»**. Оно скрытого ввода, а само значение обратно не показывается — только отметка, что токен сохранён: скриншот этого экрана не должен отдавать управление ботом. Хранится токен в системном хранилище секретов ОС, **не** в `settings.json` (тот синхронизируется между машинами). Чтобы удалить — очистите поле.

Затем включите тумблер **«Включить мост»**. Мост подхватывает новый токен сразу, перезапуск не нужен.

> Тот же токен можно ввести из палитры команд — «VibeIDE: Токен Telegram-бота».

Если Telegram у вас заблокирован — заполните **«Прокси для api.telegram.org»** (`socks5://127.0.0.1:1080`, `http://…`; авторизация прямо в URL). Это **отдельный** адрес от прокси провайдеров моделей: Telegram и API моделей блокируются в разных местах, и один выход не обязан подходить обоим.

## 4. Привязать свой чат

Возьмите **код привязки** в настройках моста и отправьте боту:

```
/start ваш-код
```

В IDE появится вопрос «Разрешить этому чату управлять агентом?» — подтвердите.

**Пока вы не подтвердили, бот не выполняет ничего.** Разрешение даёт чату право запускать инструменты на вашем компьютере, поэтому защита двухслойная:

- **сообщение без верного кода игнорируется молча** — имя бота публично, и без кода незнакомец мог бы бесконечно дёргать вас окном подтверждения. Неверный код неотличим от отсутствия кода: иначе бот стал бы оракулом для подбора;
- **групповые чаты не привязываются даже с верным кодом** — там доступ достался бы составу участников, а он меняется без вашего ведома;
- **повторный запрос от одного чата — не чаще раза в 10 минут.**

Отозвать доступ — кнопка «Отозвать» в настройках. Сменить код — «Новый код» там же.

---

## Команды

| Команда | Что делает |
|---|---|
| просто текст | Поставить задачу агенту — основной режим |
| `/projects` | Какие окна VibeIDE открыты |
| `/use <проект>` | В какое окно слать команды (хватает части имени) |
| `/status` | Какой проект отвечает и идут ли прогоны |
| `/stop` | Остановить текущий прогон |
| `/menu` | Пульт: те же команды кнопками |
| `/digest` | Что агенты сделали за сутки: упавшие — поимённо, успешные — числом |
| `/help` | Список команд |
| `/cc <задача>` | Отдать задачу Claude Code (через его SDK) — см. [telegramClaudeCode.md](telegramClaudeCode.md) |
| `/acp <задача>` | Отдать задачу внешнему агенту по ACP — тому, кого объявляет `.vibe/agents.json` |
| `/acp_agents` | Кого можно позвать в этой папке |
| `/acp_use <id>` | Выбрать агента реестра, если их несколько |
| `/acp_stop` | Прервать ход внешнего агента |

Пока прогон идёт, бот **редактирует одно сообщение** с временем работы и текущим инструментом, а не шлёт поток новых. Когда прогон закончится, придёт ответ агента; при ошибке — её текст.

Кнопка делает ровно то, что написано на ней, и идёт тем же путём, что набранное сообщение: пульт — сокращение, а не расширение прав. `/projects` заодно рисует кнопку на каждый открытый проект, чтобы не набирать `/use <имя>` с телефонной клавиатуры.

## Внешний агент с телефона (`/acp`)

`/acp` отдаёт задачу не встроенному агенту и не Claude Code через SDK, а **внешнему агенту по ACP** — процессу, который объявлен в `.vibe/agents.json` рабочей папки (формат: [agentsSpec.md](agentsSpec.md)). Если агент в реестре один, он берётся сам; если несколько — выберите `/acp_use <id>`.

Отличие от `/cc` не в удобстве, а в воротах: агент по ACP **спрашивает разрешение перед каждой правкой**, и вопрос приходит в чат с диффом «было → стало» — до того, как файл изменён. VibeIDE успевает снять по этим файлам чекпоинт, поэтому чужую правку можно откатить так же, как свою.

- Ход показывается **одним редактируемым сообщением**: текст приезжает мелкими кусками, и слать их по отдельности значило бы упереться в ограничение частоты Telegram.
- В конце приходит итог: чем кончился ход и **сколько токенов и денег** он стоил.
- Сессия живёт: следующая `/acp` продолжает ту же работу, а не начинает с нуля. `/acp_stop` прерывает ход.
- Очередь разрешений **одна на телефон и на вкладку «Внешние агенты»**. Ответили в IDE — карточка в чате гаснет надписью «Решено в IDE»; ответили с телефона — исчезает вопрос во вкладке. Поздний тап не может разрешить то, к чему агент уже перешёл.
- Кнопки те же три. «Разрешить» выбирает **разовое** согласие из вариантов, предложенных агентом (не «разрешать всегда»); «Отклонить» отвечает отменой, а не чужим вариантом отказа; «Поправить» отклоняет и ждёт следующим сообщением, что сделать вместо этого.
- Ждать ответа мост будет **сколько угодно** — таймера здесь нет намеренно, как и у `/cc`.

Если реестра в папке нет, `/acp` так и скажет: звать некого, а формат файла описан в спеке — её можно отдать модели и попросить собрать `.vibe/agents.json` за компьютером.

## Подтверждения кнопками

Прогон, упершийся в запрос разрешения, присылает его в чат: сверху — что именно будет сделано (инструмент и параметры: команда, путь, запрос), под ним три кнопки.

| Кнопка | Что происходит |
|---|---|
| ✅ Разрешить | Действие выполняется, прогон продолжается |
| ⛔️ Отклонить | Вызов отклонён, агент получает отказ и решает сам, что дальше |
| ✏️ Поправить | Вызов отклонён, и бот ждёт ваше сообщение — оно уйдёт в **тот же тред**, поэтому объяснять задачу заново не нужно: достаточно сказать, что сделать вместо этого |

Молчание — **отказ**: если за пять минут никто не ответил, запрос закрывается сам. Ответ, данный в IDE, гасит кнопки в чате: иначе тап через полчаса одобрил бы совсем другое действие.

Что показывать в чате, решает настройка `vibeide.telegram.approvals`:

| Значение | Когда выбирать |
|---|---|
| `all` (по умолчанию) | Любой запрос подтверждения виден на телефоне |
| `dangerous` | Только команды терминала и MCP-инструменты; правки файлов ждут в IDE |
| `off` | Подтверждать только в IDE |

Настройка **ничего не одобряет сама**: незеркалированный запрос не выполняется автоматически, он просто ждёт вас за компьютером. Автоодобрение инструментов — отдельные настройки IDE, и включать его надо осознанно.

---

## Решения (почему так, а не иначе)

- **Свой бот у каждого, без нашего сервера.** IDE стоит на личной машине без публичного адреса, поэтому webhook невозможен и используется long polling — а он не требует посредника вовсе. Общий бот экономил бы один поход к BotFather, но пропускал бы вашу переписку и куски кода через чужую инфраструктуру.
- **Опрос живёт в главном процессе приложения.** Он один на все окна: два параллельных `getUpdates` по одному боту Telegram отвергает с `409 Conflict`, и мост замолкает без внятной причины.
- **Чат должен быть привязан явно.** Без этого любой, кто узнал имя бота, получает выполнение инструментов на вашей машине.
- **Молчание — это отказ.** Запрос подтверждения, оставшийся без ответа, по таймауту считается отклонённым: телефон мог лежать в кармане.
- **Ответы отправляются в HTML-режиме Telegram, а не MarkdownV2.** MarkdownV2 требует экранировать десяток знаков препинания, которых полно в любом ответе модели; один незаэкранированный символ в сгенерированном коде — и Telegram отвергает сообщение целиком, то есть ответ теряется, а не просто выглядит хуже.

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

Наговорите задачу голосом — бот расшифрует её **локально** и выполнит как обычный текст. Наружу уходит только скачивание самого файла из Telegram.

Порядок такой: бот присылает `🎧 «расшифровка»`, и лишь потом запускает её как задачу — распознавание не идеально, и лучше видеть, что именно услышал агент, чем гадать, почему он сделал не то.

**Что для этого нужно:** ffmpeg и офлайн-модель распознавания. Оба компонента **общие** с разбором видео (`/watch`) и диктовкой в чате — если вы ими пользовались, качать нечего. Состояние видно в настройках моста, блок «Голосовые сообщения»:

| Что написано | Что делать |
|---|---|
| «Готово» | ничего, отправляйте голосовое |
| «Нужно скачать ~N МБ» | ничего — скачается само при первом голосовом; кнопка «Скачать сейчас» просто делает это заранее |
| «Скачивается…» | подождать |
| «На этой платформе недоступно» | распознавания для вашей ОС/архитектуры нет; пишите текстом |

Язык берётся из той же настройки, что и диктовка в IDE (`accessibility.voice.speechLanguage`), — микрофон и голосовое не могут распознаться на разных языках.

Первое голосовое при отсутствующих компонентах не молчит: бот сразу пишет, сколько качает, — минута тишины читалась бы как поломка.

## Чего мост пока не умеет

- **Скриншот превью в чат.** Заведено, не реализовано.

## Один бот — одно приложение

Telegram отдаёт сообщение **одному** получателю. Если на компьютере запущены два VibeIDE (например, установленный и dev-сборка), бота обслуживает тот, кто занял его первым; второй молчал бы, ничем не отличаясь от «мне просто никто не пишет».

Поэтому владение заявляется файлом `~/.vibe/telegram-bot.lock`. Второй экземпляр мост не запускает и пишет в статус, какой процесс держит бота, — закройте лишнее окно или выключите мост в нём. Если приложение упало, лок протухает сам примерно за две минуты и следующий запуск забирает бота без ручной уборки.

## Если не работает

| Симптом | Причина и что делать |
|---|---|
| «Мост включён, но токен не задан» | Выполните «VibeIDE: Токен Telegram-бота» |
| «нет ответа от api.telegram.org (таймаут)» | Telegram недоступен напрямую — заполните `vibeide.telegram.proxy.url` |
| «этот бот уже опрашивается другим приложением» | Тот же токен используется где-то ещё (второй компьютер, старый скрипт) либо у бота настроен webhook |
| Бот молчит на сообщения | Чат не привязан: отправьте `/start <код привязки>` (код — в настройках) и подтвердите вопрос в IDE. Сообщение без кода игнорируется молча — это защита, а не поломка |
| «Provider "…" not recognized» в ответе | Выбранная модель принадлежит конфиг-провайдеру, а `providers.json` в этом проекте нет. Мост тут ни при чём — он доставил ошибку прогона; выберите доступную модель |
| «Нет открытых окон VibeIDE» | Мост исполняет команды в окне IDE — откройте проект |

Связанное: [vibeEnvironment.md](vibeEnvironment.md) — про папку `.vibe`, [providersSpec.md](providersSpec.md) — формат провайдеров.