Что такое AcpGram и какую задачу он решает
AcpGram - открытый Telegram-шлюз на чистом Node.js 24 без единой npm-зависимости. Он запускает консольных кодинг-агентов как подпроцессы и позволяет управлять ими из чата: Claude Code, OpenAI Codex, Gemini CLI и Antigravity CLI работают через один интерфейс, а сама работа идёт на вашей машине, не в облаке проекта (исходный разбор).
Задача знакома каждому, кто гонял агента по SSH. Агент живёт в терминале на машине, которая стоит дома или в стойке, а вы в этот момент в метро или на встрече. Проверить, дошёл ли он до тестов, поправить ушедшую не туда правку, остановить зациклившийся цикл - всё это требует терминала. AcpGram делает Telegram пультом: сообщение в чат превращается в задачу для подпроцесса, а прогресс возвращается в тот же чат.
Чем AcpGram не является: это не новый кодинг-агент и не облачный сервис с чужой моделью. Движки, API-ключи, подписки и файлы проекта остаются вашими, шлюз только маршрутизирует запросы и показывает, что происходит. Проект работает на Windows, Linux и macOS, код открыт и распространяется под лицензией MIT.
Кому AcpGram реально нужен, а кому хватит терминала
Польза появляется там, где агент и человек физически разделены.
- Сервер отдельно от вас: задача запущена на домашней машине или рабочем хосте, а вы проверяете прогресс и одобряете критический шаг со смартфона.
- Несколько человек на один проект: нужен контролируемый доступ с разными правами вместо общего SSH-ключа, который есть у всех.
- Долгие прогоны: рефакторинг на десятки файлов, сборка, прогон тестов, за которыми не хочется сидеть у экрана.
- Возврат к сессиям: диалог с агентом можно поднять снова, а не начинать с нуля.
Терминала достаточно, если вы работаете за одним ноутбуком, а агент запускается в том же окне. Если вы не готовы отдавать управление серверным агентом в мессенджер, а сервера под агента нет вовсе, шлюз добавит только лишний слой.
Архитектура: Agent Client Protocol как единый язык для четырёх агентов
В основе AcpGram лежит Agent Client Protocol (ACP): протокол взаимодействия на базе JSON-RPC поверх стандартных потоков ввода-вывода, stdin и stdout. Шлюз запускает агент как подпроцесс и обменивается с ним структурированными сообщениями, а не парсит вывод терминала регулярками. Разница принципиальная: агент сам сообщает, что читает файл, что запускает команду, а что просит разрешение, и шлюзу не нужно угадывать смысл по тексту.
Gemini CLI и Antigravity CLI поддерживают ACP «из коробки», для Claude Code и OpenAI Codex написаны специальные лёгкие ACP-мосты (там же). Отсюда единый интерфейс: переключение проектов, сессий и выдача разрешений устроены одинаково для всех движков. Не нужно переучиваться под синтаксис каждого CLI, логика работы в чате одна.
Важное уточнение про «без npm-зависимостей». Это про сам шлюз, а не про агентов. У Claude Code, Codex, Gemini CLI и Antigravity свои требования к среде, свои способы авторизации и свои API-ключи, и настраивать их придётся отдельно. AcpGram не подменяет движок и не переписывает его промпты, он даёт канал управления.
С MCP это не конфликтует. ACP отвечает за диалог клиента с агентом, а инструменты внутри агента подключаются по Model Context Protocol, и настройка MCP-серверов остаётся за вами: разбор MCP как интерфейса агента.
Нативная поддержка ACP против мостов: что это значит на практике
Нативная поддержка означает, что CLI сам умеет говорить на ACP. Мост - отдельная прослойка между шлюзом и агентом, которая переводит ACP в то, что понимает конкретный CLI. Цепочка удлиняется на один процесс, и то, насколько полно мост передаёт возможности движка, зависит от его реализации.
В первичном материале нет данных, какие именно функции Claude Code или Codex теряются или меняются при работе через мост. Поэтому обещать полный паритет с Gemini CLI нельзя. Проверять стоит на своих сценариях: правки в нескольких файлах за один шаг, запуск тестов, длинная задача с десятком последовательных действий. Что вообще умеет Claude Code в терминале, мы разбирали отдельно: гайд по Claude Code.
Как это выглядит в Telegram: стриминг, /stop и финальный отчёт
Отправляете задачу в чат, и дальше ответы агента, его «мысли», список выполняемых шагов (чтение файлов, запуск команд, поиск, правки) и затраченное время обновляются в реальном времени прямо в черновике сообщения Telegram. Это не поток отдельных сообщений, а одно живое сообщение, которое переписывается по мере работы.
Зациклился - есть кнопка остановки /stop. По окончании приходит структурированный отчёт с заголовками, списками, таблицами и подсветкой кода. Под ним прячется сворачиваемый лог шагов, а в футере показывается служебная информация: движок, модель, уровень рассуждений, токены, реальная стоимость (для Claude Code) и время выполнения (описание работы).
Типовой цикл удалённой работы выглядит так.
- Ставите задачу в чат: агент стартует как подпроцесс на сервере, в нужной директории проекта.
- Смотрите прогресс в черновике, не дожидаясь финала: видно, какие файлы читаются и какие команды запускаются.
- Отвечаете на запрос подтверждения, если агент упёрся в правку файла или shell-команду.
- Нажимаете /stop, если действия ушли не туда, вместо того чтобы ждать конца.
- Разбираете результат по финальному отчёту, при необходимости возвращаетесь к диалогу командой /sessions.
| Поле футера | Что показывает |
|---|---|
| Движок | Кто выполнял задачу: Claude Code, Codex, Gemini CLI или Antigravity |
| Модель и уровень рассуждений | Какая модель отвечала и в каком режиме |
| Токены | Расход за конкретную задачу |
| Стоимость | Реальная стоимость, отображается для Claude Code |
| Время выполнения | Сколько заняла задача целиком |
Зачем нужен сворачиваемый лог шагов
Типичная проблема ботов с агентами в Telegram - стена технических сообщений, в которой теряется результат. Здесь лог спрятан под отчётом и раскрывается по необходимости: в обычном режиме виден итог, при разборе ошибки - вся цепочка действий агента. Футер со стоимостью и токенами добавляет второй уровень контроля: видно, во что обошлась задача, а не только то, что она сделана. Для Claude Code это реальные деньги, и разница между «поправить один файл» и «прогнать рефакторинг» становится заметной сразу.
Стоимость по остальным движкам в отчёте не указывается, и это стоит учитывать при планировании расходов: у Gemini CLI, Antigravity и Codex свой способ тарификации.
Разрешения и права: как не дать агенту лишнего
Интерактивные разрешения (Permissions) работают так: агент запрашивает подтверждение на правку файлов и запуск shell-команд, а пользователь одобряет или отклоняет действие прямо из чата. Это главный предохранитель всей схемы. Команда, пришедшая из мессенджера, выполняется на сервере с доступом к вашим файлам, и точка подтверждения отделяет «агент подумал» от «агент сделал».
Оговорка по деталям: в первичном материале раздел о разрешениях обрывается на полуслове. Не описано, как именно формулируется запрос, можно ли задать правило «одобрять всё внутри этой папки» и сколько живёт выданное подтверждение. Эти вещи проверяйте в документации проекта, а не по обзорам.
Уровни доступа Read/Normal/Full/Admin: как выбрать политику для команды
Многопользовательский режим строится на инвайтах и четырёх уровнях доступа. Публичной ссылки на бота быть не должно: доступ выдаётся приглашением, а права различаются. Состав прав на каждом уровне задаётся настройками шлюза, в первичном материале он не раскрыт, поэтому таблица ниже - рабочая логика такой схемы, а не точная спецификация.
| Уровень | Смысл | Когда выдавать |
|---|---|---|
| Read | Наблюдение за ходом работы без вмешательства | Тому, кому нужно видеть прогресс, но не нужно ничего запускать |
| Normal | Рабочий режим с подтверждением опасных действий | Разработчику на повседневных задачах |
| Full | Широкие права на правки и команды | Тому, кто отвечает за проект и понимает последствия |
| Admin | Управление шлюзом, пользователями и инвайтами | Одному-двум людям, не всей команде |
Принцип простой: минимально достаточный уровень. Новому человеку - Read или Normal, Full выдаётся под конкретную задачу, Admin не размножается. Аудит сессий ведётся в SQLite через встроенный модуль node:sqlite, поэтому инцидент можно разобрать постфактум: кто запускал, что подтверждал. Внешней СУБД для этого не требуется.
Детали этой части (инвайты, уровни, аудит в SQLite, команда /sessions) взяты из описания проекта: в первичном материале они не разобраны, конкретные команды и поля таблиц смотрите в репозитории. Кто хочет хранить состояние работ между чатами, моделями и агентами вне шлюза, может посмотреть на подход Later Bender.
Развёртывание: одна команда, системная служба или Docker
Установка заявлена одной командой на Windows, Linux и macOS. Дальше есть два пути: оставить шлюз в фоне как системную службу или упаковать в контейнер. Служба на Windows регистрируется через NSSM, на Linux как systemd --user, на macOS через launchd - во всех трёх случаях шлюз поднимается сам и переживает перезагрузку.
Общий порядок такой: поставить Node.js 24 как среду выполнения, подготовить токен Telegram-бота, настроить авторизацию нужных агентов и их API-ключи, затем выполнить установку и, при желании, зарегистрировать службу. Точный синтаксис команд, флагов и параметров смотрите в README проекта: в первичном материале их нет, а угадывать синтаксис установщика бессмысленно.
Отсутствие npm-зависимостей заметно упрощает этот шаг. Нет node_modules, который нужно пересобирать после обновления Node.js, нет транзитивных пакетов с известными уязвимостями, нет расхождений между машинами разработчика и сервера. Поверхность атаки у такого шлюза меньше, чем у проекта на сотне зависимостей.
Docker и изоляция директории проектов
Docker-вариант решает другую задачу: в контейнер монтируется только папка проектов, остальная файловая система хоста агенту недоступна. Если агент ошибётся с путём или выполнит лишнюю команду, ущерб ограничен смонтированным каталогом.
Две границы дополняют друг друга. Docker - грубая, но надёжная рамка на уровне файловой системы, Permissions - точечный контроль внутри сессии, когда вы подтверждаете или отклоняете конкретное действие. Для домашнего сервера хватает разрешений. Для машины, где лежат чужие проекты или рабочие секреты, контейнер с одним примонтированным каталогом разумнее.
Способы развёртывания (NSSM, systemd --user, launchd, Docker) и лицензия MIT приведены по описанию проекта. В первичном материале они не разобраны, поэтому имена служб, параметры монтирования и поведение установщика проверяйте в документации проекта перед тем, как ставить на боевую машину.
Ограничения подхода: что стоит взвесить до установки
Привязка к Telegram - первое, что нужно принять осознанно. Мессенджер становится и точкой отказа, и каналом управления сервером: недоступность Telegram или блокировка аккаунта означает потерю пульта. К аккаунту и боту стоит отнестись как к административному инструменту, а не как к личному чату.
Нужны API-ключи агентов. Claude Code, Codex, Gemini CLI и Antigravity требуют своей авторизации, и расходы идут на стороне провайдеров моделей. В футере отчёта стоимость видна только для Claude Code, по остальным движкам бюджет придётся считать отдельно.
Уровни доступа и разрешения - обязательный шаг, а не галочка в настройках. Если оставить всех на Full и включить автоматическое одобрение всего, шлюз превращается в удалённый shell с правами вашего пользователя.
Скорость. Для мелкой правки в одном файле терминал быстрее: команда, Enter, готово. Чат выигрывает на длинных задачах и на работе вне рабочего места, а не на наборе коротких команд.
И последнее: шлюз не решает проблемы автономности самого агента. Изоляция контекста, память в файлах, автопроверки и откат остаются задачей харнеса, а не Telegram-обёртки. Критерии выбора такого харнеса мы разбирали в материале о харнесе для многодневных задач кодинга.
Кому AcpGram не подойдёт
- Тем, кто работает за одним устройством и не выносит агента на отдельный сервер: лишний слой без выгоды.
- Тем, кому критична работа без внешнего мессенджера: политика безопасности может запрещать управление инфраструктурой через Telegram.
- Тем, кто не готов управлять ключами, инвайтами и правами: без этого шлюз опаснее прямого SSH.
- Тем, кому нужен только быстрый локальный цикл правок: терминал или интеграция агента в IDE закрывают это проще.
Итог: когда AcpGram оправдан
AcpGram оправдан в четырёх случаях.
- Нужен единый интерфейс к четырём разным агентам через ACP, без переучивания под каждый CLI.
- Нужен прозрачный прогресс и финальный отчёт со служебной информацией, включая стоимость задачи для Claude Code.
- Нужен контроль: разрешения на правки и shell-команды, уровни доступа, инвайты и аудит сессий.
- Нужна простая установка на Windows, Linux или macOS без npm-зависимостей, с опцией системной службы или Docker.
Ключи, модели и файлы проекта остаются на вашей стороне, код открыт под лицензией MIT, а Telegram выполняет роль пульта, а не хранилища. Следующий шаг: развернуть шлюз на тестовой машине, выдать себе уровень Normal, поставить одну небольшую задачу и посмотреть, как выглядит стриминг и отчёт именно на вашем движке. После этого станет понятно, где мост ведёт себя иначе нативного ACP, и стоит ли отдавать шлюзу более широкие права.