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