Удалённый доступ через Telegram¶

Koda CLI умеет работать через Telegram-бота. Вы можете отправлять запросы, получать ответы AI и управлять сессиями прямо из мессенджера — с телефона, планшета или любого устройства, где есть Telegram.

Удалённый доступ живёт, только пока запущен процесс CLI с этим токеном бота. Это полноценный способ работы: бот сам регистрирует команды, привязывает владельца, создаёт и сохраняет сессии.

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

• CLI подключается к Telegram Bot API и опрашивает обновления (getUpdates).
• Каждый чат или тема в Telegram соответствует отдельной удалённой сессии CLI.
• Сессии и их история сохраняются между запусками для конкретного бота и проекта.
• Ответы приходят в реальном времени: статус и текст обновляются по мере работы агента.

Требования¶

• Koda CLI запущен в интерактивном режиме.
• Создан Telegram-бот через @BotFather, получен его токен.
• В CLI настроен токен бота (см. ниже).
• Выполнена привязка владельца.

Настройка¶

Проще всего задать токен и включить доступ одной командой:

/telegram setup <bot-token>

Токен сохраняется в пользовательских настройках, а доступ включается автоматически.

Токен из переменной окружения¶

Токен можно задать через переменную окружения KODA_TELEGRAM_BOT_TOKEN (например, в env/.env проекта). В этом случае токен не сохраняется в настройках.

Токен в настройках проекта¶

Чтобы токен хранился в настройках проекта, используйте флаг --project:

/telegram setup --project <bot-token>

При смене токена текущая привязка владельца сбрасывается — владельца нужно привязать заново.

Привязка владельца¶

После настройки токена выполните команду:

/telegram link

CLI запросит данные бота у Telegram Bot API и покажет:

• QR-код со ссылкой привязки;
• текстовую ссылку вида https://t.me/<bot>?start=<nonce>;
• запасной код для команды /bind <code> в боте.

Ссылка и код действуют ограниченное время (по умолчанию около 10 минут).

Чтобы привязать аккаунт:

1. Откройте ссылку в Telegram (или отсканируйте QR).
2. Нажмите Start в чате с ботом.
3. Либо отправьте боту /bind <code>.

После привязки CLI сохраняет данные владельца: Telegram ID, username и отображаемое имя.

Если владелец уже привязан, замените его через /telegram relink, а отвязать владельца можно командой /telegram unlink (в CLI) или /unlink (в боте).

Команды CLI¶

Команда /telegram без аргументов открывает мастер настройки, если токен бота или владелец ещё не заданы. Если всё настроено, она показывает текущий статус.

Что показывает /telegram status¶

• включён ли доступ;
• состояние токена: задан ли он, источник (settings или KODA_TELEGRAM_BOT_TOKEN), маскированное значение;
• привязан ли владелец и к кому;
• режим работы (один владелец);
• заметка, что сессии сохраняются между запусками для этого проекта и бота.

Создание сессий из Telegram¶

Чат с ботом привязывается к удалённой сессии автоматически при первом сообщении. Чтобы создать или выбрать сессию явно, используйте:

/new [label]

Сессии и их истории сохраняются локально в ~/.kodacli/telegram-remote/sessions/.

Файл хранилища привязан к паре «токен бота + проект». При следующем запуске CLI с тем же токеном и в том же проекте сессии восстанавливаются.

Команды бота¶

Бот показывает меню команд в Telegram, когда доступ активен.

Команда /start <code> подтверждает ссылку привязки, созданную в CLI.

Отправка запросов¶

Просто отправьте боту текстовое сообщение — оно станет запросом агента. Фото тоже поддерживаются: отправьте изображение с подписью, и подпись станет запросом, а фото — контекстом. Если подписи нет, используется стандартный запрос «Проанализируйте изображение».

Роль субагента можно запустить явно: начните сообщение меткой @agent:<имя> — например, @agent:reviewer проверь диф. Роль запустится до обращения к модели, а остальной текст сообщения станет её задачей.

Ответы приходят в реальном времени:

• статус обработки обновляется в сообщении (queued, running, ожидает подтверждения и т.д.);
• длинные ответы разбиваются на части до 4096 символов (лимит Telegram).

Если сессия уже занята, новые запросы попадают в очередь (максимум 3), отменить её можно командой /cancelqueue.

Подтверждение действий¶

Когда инструменту нужно подтверждение, бот показывает сообщение с деталями запроса и кнопками:

• Разрешить — разрешить один раз;
• Всегда — разрешить на всю сессию;
• Отклонить — отменить действие.

У каждой кнопки есть одноразовый токен, поэтому просроченные или повторные нажатия игнорируются. Пока выполнение ожидает подтверждения, бот показывает статус «ожидает подтверждения».

Уведомления о локальных запросах¶

Когда запрос отправляется из самого CLI (не из Telegram), бот может уведомить владельца о ходе работы. Это настраивается параметром notifyOn:

Значение по умолчанию — confirmation.

Ограничения¶

• Один бот — один владелец.
• Сессии живут только пока запущен CLI с этим токеном и в этом проекте.
• Поддерживаются только текстовые сообщения и фото; другие типы сообщений отклоняются.
• Длина одного сообщения ограничена 4096 символами.
• Если текущая модель не поддерживает изображения, фото не обработается — переключите модель через /model.
• Один и тот же токен не может использоваться двумя CLI одновременно: лок-файл блокирует повторный запуск.

Безопасность и данные¶

• Токен бота можно задать через переменную окружения KODA_TELEGRAM_BOT_TOKEN, чтобы не хранить его в настройках.
• В статусе токен маскируется, а в логах скрывается (redact).
• Сессии и их история хранятся локально, права на файлы — 0600.
• Лок токена предотвращает одновременное использование одного бота двумя процессами.

Устранение проблем¶