Удалённый доступ через Telegram¶
Koda Desktop умеет работать через Telegram-бота: вы отправляете запрос из мессенджера, а агент выполняет его в выбранном проекте на вашем компьютере. Это удобно, когда вы не за рабочим местом, но хотите запустить задачу, узнать статус или разрешить действие агента.
Общая настройка с CLI
Бот, токен и привязанный владелец — общие для Koda Desktop и Koda CLI. Один и тот же бот обслуживает и терминальные, и настольные сессии; подробности о CLI-режиме — на странице удалённого доступа через Telegram.
Вкладка «Telegram» в настройках¶
Откройте Настройки и перейдите на вкладку Telegram. Все параметры вкладки собраны на странице настроек Telegram.
Включение доступа¶
- Создайте бота через @BotFather и скопируйте его токен.
- Включите переключатель Включить Telegram-доступ.
- Введите токен бота в поле Токен бота.
- Дождитесь статуса Ждёт привязку аккаунта.
Если токен задан переменной окружения KODA_TELEGRAM_BOT_TOKEN, поле ввода не требуется — приложение использует её значение.
Привязка владельца¶
К одному боту привязывается только один Telegram-пользователь — владелец. Сообщения от всех остальных пользователей бот игнорирует.
Когда приложение ждёт привязку, оно показывает:
- QR-код — отсканируйте его камерой телефона;
- ссылку — откройте её в Telegram;
- код — отправьте боту сообщение вида
/bind <код>.
Ссылка и код действуют ограниченное время. Если привязка не успела пройти, обновите данные на вкладке — приложение покажет новые.
После привязки владелец сохраняется в общих настройках, и повторная привязка не требуется. Сменить владельца можно, запустив привязку заново.
Статусы подключения¶
На вкладке отображается текущее состояние бота:
| Статус | Что означает |
|---|---|
| Выключено | Переключатель доступа выключен |
| Нужен токен бота | Доступ включён, но токен ещё не задан |
| Токен не принят | Telegram отклонил токен — проверьте его значение |
| Токен занят другим процессом | Этот же токен уже использует запущенный Koda CLI — остановите его |
| Подключение... | Приложение проверяет токен и запускает бота |
| Ждёт привязку аккаунта | Бот работает, осталось привязать владельца |
| Подключено | Бот готов принимать сообщения от владельца |
| Выполняет запрос | Агент обрабатывает запрос из Telegram |
| Ошибка подключения | Сетевая проблема или отказ API — попробуйте переподключиться |
Один токен — один процесс
Desktop и запущенный CLI не могут работать с одним ботом одновременно: кто первый взял блокировку, тот и обслуживает сообщения. Если статус показывает, что токен занят, завершите сессию CLI или используйте другой бот.
Уведомления в Telegram¶
Настройка Уведомления определяет, какие события из Desktop-чатов приходят владельцу в личные сообщения:
- Не присылать — бот отвечает только на ваши сообщения.
- Когда чат закончил задачу — одно сообщение по завершении каждого чата.
- Когда нужно подтверждение и по завершении — уведомление, когда агент ждёт вашего решения, и по завершении задачи.
Эти уведомления не зависят от переключателя Системные уведомления — они приходят в Telegram независимо от настроек ОС.
Чаты из Telegram в приложении¶
Каждый диалог в Telegram отображается в боковой панели Koda Desktop как обычный чат с соответствующей пометкой. История сохраняется локально, как и у обычных чатов, — вы можете открыть её в приложении и продолжить работу уже оттуда.
Безопасность¶
- Токен бота не попадает в интерфейс, логи, телеметрию и отчёты об ошибках — в них он отображается замаскированным.
- Управлять агентом может только привязанный владелец.
- Кнопки подтверждения в Telegram передают только короткие одноразовые идентификаторы, без данных сессии.