# Telegram для ChatGPT

Личный Telegram как плагин ChatGPT. Модель читает навыки, пишет JavaScript/TypeScript и исполняет его через один MCP-инструмент с полным SDK mtcute. Можно читать папки и переписку, готовить черновики и выполнять порученные действия. Проект рассчитан на один Telegram-аккаунт и одного владельца на установку.

После развёртывания откройте страницу сервера, введите API ID/API Hash с [my.telegram.org/apps](https://my.telegram.org/apps), номер телефона и код Telegram. Если включена 2FA, форма попросит облачный пароль. Код и пароль не сохраняются. Сессия шифруется ключом вашей установки.

## Быстрый запуск на сервере

**Покупать домен и регистрировать аккаунт для адреса не нужно.** Передайте агенту ссылку на этот репозиторий и SSH-доступ к серверу:

> Разверни https://github.com/pyro17ai/telegram-sdk-plugin на моём сервере. Выполни AGENTS.md и docs/deploy-server.md: установи зависимости, получи бесплатный постоянный адрес и проверь HTTPS с OAuth. Верни персональную ссылку для входа и инструкцию добавления плагина в веб-версию ChatGPT. Telegram-реквизиты я введу сам на странице.

Агент выполнит настройку. Вам останется открыть персональную ссылку, войти в Telegram и добавить плагин в ChatGPT.

Для самостоятельного запуска нужны Git и Docker с Compose на сервере с публичным IPv4. Node.js на сервер устанавливать не нужно. Входящие TCP-порты 80 и 443 должны быть доступны:

```bash
git clone https://github.com/pyro17ai/telegram-sdk-plugin.git && cd telegram-sdk-plugin
bash scripts/deploy.sh
```

Установщик определит публичный IP и создаст адрес вида `https://telegram.<IP-через-дефисы>.sslip.io`. Бесплатный DNS уже направляет его на сервер; Caddy получает и продлевает HTTPS-сертификат. Адрес сохраняется после перезапуска, пока не меняется IP сервера. Аккаунты в Cloudflare или сервисе туннелей не нужны.

После проверки HTTPS установщик напечатает **персональную ссылку владельца**. Она сразу открывает форму Telegram. Сохраните её в менеджере паролей и не публикуйте: ссылка содержит ключ доступа. Браузер убирает ключ из адресной строки при входе. Файл `.env` создаётся с правами 600 и исключён из Git. Повторный `bash scripts/deploy.sh` сохраняет адрес и ключи.

Откройте персональную ссылку и пройдите вход в Telegram. На готовой странице нажмите **Скачать плагин**. Прикрепите `Telegram.zip` в ChatGPT с установленным Plugin Creator и отправьте:

> @Plugin Creator создай и установи мне приватный плагин Telegram из этого ZIP. Сохрани оба навыка и подключение MCP. Пройди OAuth-подключение.

Во время OAuth откроется ваша панель: в том же браузере вход владельца уже сохранён, остаётся нажать **Подключить**. Client ID и Client Secret вручную создавать не требуется. Затем проверьте: `@Telegram покажи мои папки`. [Подробности подключения и ограничения аккаунтов](docs/chatgpt.md).

Если IP не определился автоматически, агент укажет его через `bash scripts/deploy.sh --ip ПУБЛИЧНЫЙ_IP`. Собственный домен остаётся необязательным вариантом: `bash scripts/deploy.sh --domain telegram.example.com`. Эти параметры нужны только для первой установки. [Проверка сети и восстановление установки](docs/deploy-server.md).

## ChatGPT Sites

Установите Sites и Plugin Creator, затем дайте агенту эту инструкцию:

> Разверни для меня https://github.com/pyro17ai/telegram-sdk-plugin как новый приватный ChatGPT Site. Выполни docs/deploy-sites.md. Создай новую установку с собственным ключом шифрования и привяжи оба навыка к каноническому плагину Sites. Telegram-реквизиты я введу сам через страницу после публикации. Существующие сайты не изменяй.

Агент создаст личный Site и плагин. После публикации откройте страницу, войдите в Telegram и установите плагин из **Plugins → Personal → Created by you**. [Полная инструкция для агента](docs/deploy-sites.md). Публичного терминального CLI Sites этот проект не предполагает.

## Устройство и границы

Один код работает в Node.js и Cloudflare Workers на Sites. Произвольный JavaScript/TypeScript исполняется в QuickJS WASM. `withTelegram` предоставляет SDK; `tg.call` даёт доступ к низкоуровневому MTProto. Оболочка ОС и установка произвольных npm-пакетов в исполняемом коде не поддерживаются. Обычный запуск ограничен 45 секундами, вывод ограничен 240 КБ, файл через `files.write` ограничен 1 000 000 символов. Большие выборки разбивайте на несколько запусков.

Объёмные зашифрованные данные хранятся в R2 на Sites или в каталоге данных на сервере. D1/SQLite хранит указатели и атомарные блокировки. Кеш SDK не упирается в предел строки D1. `request_id` предотвращает повторное выполнение одного запроса; при неопределённом результате используйте тот же ID.

Серверный MCP использует OAuth с PKCE и одноразовыми кодами. На Sites доступ проверяет платформа и серверное ограничение по владельцу. Доступ ChatGPT к вашему плагину даёт возможность действовать от вашего имени в Telegram: разрешайте его только своему аккаунту. Автоматизации и расписания задавайте в ChatGPT отдельно; этот проект не добавляет собственный планировщик.

## Разработка и проверка

```bash
npm ci
npm run build:server
npm test
npm run scan
```

Для разработки нужен Node.js 24. Для локальной проверки: `node scripts/configure.mjs --domain http://localhost:3000`, затем `npm start`. Внешний ChatGPT не подключится к localhost: ему нужен публичный HTTPS-адрес, который серверный установщик создаёт без покупки домена.

Работающий локальный сервер проверяется командой `node --env-file=.env scripts/smoke-server.mjs http://localhost:3000`. Она проходит вход владельца и OAuth, затем исполняет TypeScript через MCP без обращения к Telegram. GitHub Actions повторяет эту проверку внутри собранного Docker-контейнера.

Тесты проверяют OAuth целиком, запрет поддельной личности, CSRF, идемпотентность и сохранение больших данных. Вход Telegram с кодом и 2FA проверяется с подменой ответа SDK; автоматические тесты не отправляют реальные коды и не подключают чужие аккаунты. Последняя проверка не заменяет вход владельца после развёртывания.

[Обновление и резервное копирование](docs/operations.md) · [Безопасность и проверка секретов](SECURITY.md) · [Лицензия MIT](LICENSE)