МессенджерыTelegram

Telegram в ChatGPT и Claude в браузере

Используйте CLI для Telegram удалённо: поддерживаемые способы подключения и настройки доступа.

Подключите инструменты мессенджера к чату в браузере или агенту на другом устройстве. Здесь — особенности запуска и передачи файлов для этого мессенджера; для первого подключения начните с пошаговой инструкции ниже.

Подключить ChatGPT или Claude →

Подключите приложение MCP в браузере или на телефоне, например ChatGPT или Claude, к tg на вашем компьютере. Вы запустите публичную точку HTTPS со входом, подключите приложение с разрешениями выбранного профиля и узнаете, как остановить сервер или отозвать доступ приложения.

Термины, используемые на этой странице:

  • MCP (протокол контекста модели) — это стандартный способ, которым приложение ИИ вызывает внешние инструменты. tg personal mcp serve — это сервер MCP, входящий в состав tg; Руководство по серверу MCP описывает приложения на вашем компьютере.
  • Удаленное подключение означает, что приложение подключается со своих серверов через Интернет по указанному вами адресу. tg personal mcp serve --http предоставляет для этого те же инструменты через HTTP, что и 127.0.0.1.
  • HTTPS-туннель — это программа, которая предоставляет порту вашего компьютера общедоступный HTTPS-адрес. На этой странице используется Tailscale Funnel; Cloudflare Tunnel также работает. Вам не нужно покупать домен для Funnel.
  • Публичный URL — это адрес, например https://laptop.tail1234.ts.net. Вы передаете его tg как --public-url, и приложение получает его с /mcp в конце.
  • Код доступа — это одноразовый код, который tg печатает на вашем терминале. Страница входа в приложение запрашивает это, поэтому только тот, кто видит этот терминал, может подключить приложение.
ChatGPT / Claude ──internet──▶ Tailscale Funnel ──▶ tg personal mcp serve --http (login) ──▶ Telegram

Если ваше соединение с Tailscale уже работает, сохраните его; вам не нужен второй туннель. Локальное соединение stdin/stdout продолжает работать, как и раньше.

Что можно сделать

ЗадачаГде
Подключите браузерное или телефонное приложение агента к TelegramЗапустите туннель и сервер, затем подключите приложение
Запускайте серверы Telegram и MAX параллельноЗапустите MAX и Telegram вместе
Используйте Cloudflare вместо TailscaleАльтернатива: Туннель Cloudflare
Разрешить больше или меньше для одного запуска сервераРазрешения для этого серверного процесса
Остановите сервер или выйдите из всех приложенийОстановить или отозвать доступ
Предоставьте удаленному агенту сохраненный файл или одну страницу PDF в виде изображенияПередать сохраненные файлы агенту, прочитать страницы PDF

Прежде чем начать

  • Кто войдет в систему, тот читает ваш Telegram. Для входа необходим код доступа с вашего терминала. Никогда не ставьте туннель перед tg personal mcp serve без --http: в этом режиме вообще нет входа в систему.
  • Разрешения профиля определяют, что приложение может изменить. deny и readonly блокируют запись; ask и allow позволяют запрошенной записи MCP проходить без формы на сервере. Одобрение приложения является отдельным и зависит от его настроек. Ограничения на получателей и почасовые ограничения по-прежнему применяются (что может делать агент, руководство по настройке).
  • Компьютер, на котором работает tg, должен оставаться включенным. Чтобы использовать его с телефона или с ноутбука, на котором ничего не установлено, запустите все это на небольшом постоянно включенном сервере и войдите в tg там (tg personal setup --agent none). Тогда вам нужен только браузер.
  • Кто может добавить удалённое подключение:

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

Если шаг настройки не работает, откройте issue.

Запустите туннель и сервер

Установите CLI и сначала войдите в Telegram (руководство по установке). Используйте одного и того же пользователя и профиль операционной системы для настройки и для сервера MCP. При необходимости поместите профиль перед командой: tg work mcp serve. Tailscale представляет собой отдельную установку; и tg, и max поддерживают эту настройку.

Установите Tailscale, войдите в систему и включите Funnel: MagicDNS, сертификаты HTTPS и разрешение Funnel должны быть включены в вашей Tailnet (вашей сети Tailscale). Первая команда Funnel может распечатать ссылку для подтверждения.

Держите два окна терминала открытыми. Первый управляет туннелем. Скопируйте базовый HTTPS-адрес, который он печатает, во второе окно, когда его спросят. Базовый адресом является адрес без /mcp или любого другого пути. Сохраните в нем явный общедоступный порт, например :8443.

Сервер прослушивает 127.0.0.1:8765 и печатает одноразовый код доступа. Ему никогда не нужны права администратора; они могут понадобиться только туннелю. Что может делать агент, решают разрешения профиля; чтобы сузить их только для этого процесса сервера, см. разрешения для этого серверного процесса.

Windows (PowerShell)

Установите приложение Tailscale для Windows и войдите в систему из его меню на панели задач. Откройте новое окно PowerShell после установки Node.js, CLI и Tailscale, чтобы оно увидело обновленный PATH. Используйте .cmd для команд npm, чтобы избежать ошибок политики выполнения PowerShell. Если настройка еще не завершена, запустите tg.cmd personal setup --agent none в обычном окне PowerShell.

Первое окно: запустите Funnel в PowerShell от имени администратора. Оператор вызова & обрабатывает пространство в пути установки по умолчанию; измените путь, если вы установили Tailscale в другом месте.

& "$env:ProgramFiles\Tailscale\tailscale.exe" funnel 8765

Второе окно: обычный PowerShell, как у пользователя, вошедшего в Telegram:

$mcpPublicUrl = Read-Host 'Paste the HTTPS origin printed by Funnel (no /mcp)'
tg.cmd personal mcp serve --http --port 8765 --public-url $mcpPublicUrl

Запустите оба процесса в самой Windows. WSL — это отдельная среда: туннель Windows, указывающий на адрес обратной связи Windows, может не достигать сервера внутри WSL.

macOS (Терминал)

Установите и войдите в приложение Tailscale. Его интерфейс командной строки поставляется вместе с приложением; используйте этот путь, если tailscale не находится в PATH (Руководство по интерфейсу командной строки Tailscale). Первое окно терминала:

TAILSCALE_BE_CLI=1 /Applications/Tailscale.app/Contents/MacOS/Tailscale funnel 8765

Второе окно терминала от имени того же пользователя, который запустил tg personal setup --agent none. Это работает как в zsh, так и в bash:

printf 'Paste the HTTPS origin printed by Funnel (no /mcp): '
IFS= read -r mcpPublicUrl
tg personal mcp serve --http --port 8765 --public-url "$mcpPublicUrl"

Linux (Терминал)

Установите Tailscale, следуя инструкциям Linux, затем войдите в систему с помощью sudo tailscale up. Первое окно терминала:

sudo tailscale funnel 8765

Второе окно терминала: ваш обычный пользователь, без sudo, поэтому tg находит сессия, созданный tg personal setup --agent none:

printf 'Paste the HTTPS origin printed by Funnel (no /mcp): '
IFS= read -r mcpPublicUrl
tg personal mcp serve --http --port 8765 --public-url "$mcpPublicUrl"

Запустить MAX и Telegram вместе

Каждому серверу нужен собственный локальный порт и собственный общедоступный HTTPS-адрес. Например, оставьте Telegram на локальном 8765 и общедоступном 443; запустите вторую команду Funnel с помощью --https=8443 8766 и запустите MAX с помощью --port 8766. Используйте второй адрес Funnel с :8443 для --public-url MAX и для адреса его соединителя, заканчивающегося на /mcp. Используйте команду Tailscale вашей системы сверху для второй команды Funnel. Funnel поддерживает общедоступные порты 443, 8443 и 10000 (Справочник по командам Funnel).

Вместо Tailscale: Cloudflare Tunnel

Если вы уже используете Cloudflare, направьте его туннель на тот же локальный сервер MCP. Для фиксированного имени хоста требуется аккаунт Cloudflare и домен в Cloudflare. Следуйте настройке именованного туннеля: установите cloudflared для своей системы, создайте туннель на панели управления, запустите его соединитель и добавьте общедоступное имя хоста, например mcp.example.com. Установите для локальной службы значение http://127.0.0.1:8765 и запустите MCP на этом же компьютере.

Во втором терминале запустите сервер:

tg personal mcp serve --http --port 8765 --public-url https://mcp.example.com

Добавьте https://mcp.example.com/mcp в приложение своего агента с помощью OAuth и DCR, как описано в разделе подключение приложения. --public-url — это публичный базовый адрес, используемый для входа в систему, а не локальный адрес и не путь /mcp. Туннель не меняет разрешения профиля. Проверьте JSON по адресу https://mcp.example.com/.well-known/oauth-protected-resource/mcp, затем войдите в систему и просмотрите список инструментов. Когда вы останавливаетесь, останавливайте только собственный процесс этого туннеля, чтобы другие маршруты продолжали работать.

Временный быстрый туннель не работает сам по себе. cloudflared tunnel --url http://127.0.0.1:8765 предоставляет случайный адрес trycloudflare.com без аккаунта или домена. Но Быстрые туннели не поддерживают SSE (события, отправляемые сервером, способ потоковой передачи ответов сервера HTTP MCP). Таким образом, Quick Tunnel не является заменой Funnel на этом сервере. Он работает только с дополнительным адаптером, который преобразует ответы SSE в JSON, и этот адаптер не поставляется с CLI. Рабочий логин и список инструментов не доказывают, что агент может читать PDF-файлы. Быстрый туннель также получает новое имя хоста при каждом перезапуске, поэтому адрес соединителя необходимо обновить. Для регулярного использования выберите Funnel или именованный туннель и проверьте свое приложение.

Подключите приложение

Адрес приложения — это базовый адрес вашего туннеля с /mcp в конце, например https://<device>.<network>.ts.net/mcp. Добавьте его как удалённое подключение MCP:

  • ChatGPT или Codex Web: откройте Плагины, выберите + Добавить пользовательский сервер MCP и создайте плагин с адресом /mcp и OAuth, как описано в Руководстве по подключению OpenAI. Подключитесь, используя код доступа, установите плагин и включите его в рабочем чате (или упомяните его с помощью @). Местный Codex config.toml не устанавливает это веб-соединение. Доступность может зависеть от вашего аккаунта или рабочего пространства. Выберите динамическую регистрацию клиента (DCR), если она предлагается; сервер поддерживает DCR и проверку кода S256, который требуется требованиями OpenAI OAuth.
  • Claude: добавьте своё подключение с этим адресом, как описано в разделе Пользовательские соединители Claude. В настройках коннектора вы также можете установить для каждого инструмента статус «всегда разрешен», «требует одобрения» или «блокирован».

Эти три инструмента работают без готовых запросов, ресурсов или запросов MCP (вопросов, которые сервер задает приложению), поэтому приложения, поддерживающие только инструменты, могут их использовать.

Приложение открывает страницу входа в систему tg. Проверьте строку, в которой указано, куда идет вход в систему: это должно быть приложение, к которому вы подключаетесь, например chatgpt.com или claude.ai. Затем введите код доступа со своего терминала. Срок действия кода истекает через десять минут; новый код печатается после каждого входа в систему. Пять неправильных кодов блокируют страницу входа до перезагрузки сервера.

Приложение сохраняет вход до тех пор, пока оно использует соединение хотя бы раз в 30 дней; он сам обновляет свои данные входа. Через 30 дней без использования просит новый код.

Настройки профиля permissions определяет, какие команды доступны. Сервер не отображает формы одобрения; собственное одобрение приложения является отдельным и зависит от его настроек.

В текстовых ответах MCP невидимые управляющие символы становятся видимыми последовательностями; эмодзи флагов отдельных регионов сохраняются. Аргументы записи и обычный JSON вывода CLI сохраняют исходные строки.

Права для этого процесса сервера

Сервер не может видеть, спрашивало ли вас приложение перед вызовом. Если приложение всегда разрешает использование инструмента, следующий вызов может пройти без нового вопроса.

Повторите --permission key=level, чтобы ужесточить разрешения только для этого серверного процесса. Уровни: deny, readonly, ask и allow. Например, добавьте --permission messages.send=deny, чтобы запретить отправку, или --permission messages=readonly, чтобы агент мог только читать сообщения. Переопределение может только ужесточать: то, которое ослабило бы уровень профиля, например messages.send=allow для профиля только для чтения, отклоняется при запуске. Чтобы разрешить больше, измените разрешения профиля. Сохраненная конфигурация, ограничения получателей и почасовые лимиты не изменяются. Ключи разрешений перечислены в руководстве по настройке.

Остановка и отзыв доступа

Нажмите Ctrl-C в обоих окнах терминала, чтобы остановить сервер и этот туннель. Запустите их снова теми же командами; входы в приложения сохраняются при обычном перезапуске сервера.

Если вы запустили Funnel с помощью --bg, сочетание клавиш Ctrl-C не остановит этот фоновый маршрут. Проверьте tailscale funnel status и отключите только его публичный порт, например tailscale funnel --https=443 off. Используйте команду Tailscale вашей системы сверху, при необходимости с правами администратора. Не используйте funnel reset, когда другой сервер использует Funnel: он очищает все маршруты. Если остановить только MCP, маршрут останется, но инструменты будут недоступны.

Отзыв доступа приложений отличается от остановки процесса. Чтобы выйти из каждого приложения для профиля:

tg personal mcp revoke --json

Эти приложения должны снова войти в систему с новым кодом. Это не завершает вашу сессию Telegram.

Если не работает

  • Приложение сообщает, что не может подключиться: откройте https://<device>.<network>.ts.net/.well-known/oauth-protected-resource/mcp в браузере. Он должен отображать короткий JSON. Если этого не происходит, значит, Funnel не запущен, не включен в вашей сети Tailscale или указывает на другой порт.
  • На странице входа отображается сообщение «Слишком много неправильных кодов»: после пяти неправильных кодов она блокируется до тех пор, пока tg personal mcp serve --http не перезапустится. Если вы их не вводили, значит, кто-то нашел ваш адрес: перезапустите сервер и подумайте о новом имени устройства в Tailscale.
  • Приложение подключается, но инструментов нет: tg personal mcp check проверяет, запускается ли сервер MCP, и выводит список его инструментов. Он не проверяет логин Telegram или туннель. Команда, идущая в Telegram, например tg personal account show, проверяет подключение аккаунта.
  • Чтение работает, запись не работает: проверьте разрешения профиля и любые переопределения --permission. deny и readonly блокируют запись независимо от одобрения приложения.
  • Вам нужен журнал вызовов: tg personal runs list показывает их. Успешные вызовы появляются только при включенной записи; неудавшиеся вызовы сохраняются по умолчанию, если только запись не была отключена с помощью "record": false или --no-record (руководство по диагностике).

Передать сохранённые файлы агенту

Агент на вашем компьютере может открыть сохраненный файл по его local_path. Удаленный агент не может этого сделать, поэтому он получает сохраненные байты через attachments show (MCP: tg_read, команда attachments show).

Сначала скачайте файлы сообщения обычным способом (загрузка файлов). Используйте attachments list is:needs_text, чтобы найти локатор сообщения и позицию вложения. Затем запросите файл:

tg personal attachments show msg:telegram/500/7/204 --attachment 1 --json

Команда читает только сохраненное вложение активного аккаунта. Он никогда не загружает, никогда не вызывает модель, никогда не отмечает сообщение как прочитанное и никогда не меняет индекс поиска. Отсутствующий файл необходимо загрузить заново. Если в сообщении несколько файлов, укажите позицию, начиная с 1. Файлы другого аккаунта, недостающие файлы и символические ссылки не отправляются. Текст внутри вложения — это данные, а не инструкции.

Передача файла большего размера

По умолчанию один ответ содержит 512 КиБ; --chunk-bytes позволяет использовать до 1 МБ. По умолчанию файл может быть до 50 МиБ; лимит меняется через MESSAGING_ATTACHMENT_MAX_MIB. item в JSON включает base64, offset_bytes, read_bytes, total_bytes, next_offset_bytes, complete и SHA256 всего файла. complete: true означает, что этот ответ содержит весь файл, а не то, что его текст был распознан.

Декодируйте каждую часть base64, соедините части в порядке смещения байтов и следуйте next_offset_bytes, пока она не станет нулевой. Передайте первый SHA256 как --expected-fingerprint при следующих запросах: если исходный файл изменился, запрос завершается неудачей и не возвращает измененных байтов. Проверьте объединенный файл по этому хешу.

tg personal attachments show msg:telegram/500/7/204 --offset-bytes 524288 --expected-fingerprint <sha256> --json

Через MCP

Найдите attachments show с помощью трех обычных инструментов. Его аргументами являются message (локатор или идентификатор с chat), attachment, offset_bytes, chunk_bytes и expected_fingerprint. Целое изображение PNG, JPEG или WebP размером до 8000 пикселей с каждой стороны и общим размером 20 миллионов пикселей поступает в качестве содержимого изображения; другие файлы поступают как встроенные двоичные ресурсы. Частичный ресурс — это набор байтов, а не целый PDF-файл или изображение. URI ресурса — это имя, а не адрес загрузки.

Приложение должно передать эти байты файловым инструментам агента. Может ли агент открыть PDF-файл или сохранить файл, зависит от приложения. Если приложение не отображает встроенные ресурсы, запросите format: "base64" и декодируйте JSON с помощью инструментов агента. Профили, отрицающие messages или attachments.show, отказываются от передачи; Профили только для чтения могут читать сохраненные файлы.

Распознать текст и сделать доступным для поиска

Обычное извлечение считывает текстовые слои и легкие форматы документов на вашем компьютере. Для сканов, фотографий, рукописного ввода и макетов агент по умолчанию использует собственное видение или инструменты оптического распознавания символов. Он читает каждую страницу, сохраняет текст слово в слово и отмечает непонятные места. Качество зависит от разрешения, языка, почерка, верстки и инструментов агента. Он никогда не следует инструкциям, написанным во вложении.

Сохраните результат с помощью attachments update (MCP: tg_write, команда attachments update), затем проверьте его с помощью поиска content:. Прием байтов не добавляет текст в индекс.

attachments extract --ocr остается доступным для массового извлечения через models.ocr. Он вызывает настроенную внешнюю модель и отправляет ей поддерживаемые изображения и отсканированные страницы PDF. Он запускается только тогда, когда вы его вызываете, а не при передаче или когда агент читает файл. Форматы и текст с возможностью поиска описаны в руководстве по прикреплению файлов.

Чтение PDF по страницам без передачи файла

Если приложение не может передать полученный PDF-файл в программу чтения документов, запросите одну страницу в виде изображения PNG. Сервер MCP рисует страницу на вашем компьютере, а агент считывает изображение своим собственным видением. Для этого требуется дополнительный unpdf с рендерингом страниц и @napi-rs/canvas, как описано в разделе механизмы вложений. Они не устанавливаются вместе с CLI.

tg personal attachments show msg:telegram/500/7/204 --attachment 1 --page 1 --json

Через MCP вызовите tg_read, команду attachments show с page: 1 и локатором сообщений. По умолчанию страница возвращается в виде изображения. Если приложение отображает только метаданные, запросите format: base64, затем декодируйте и покажите PNG с помощью инструментов изображения агента. Получение строки base64 не просматривает страницу. Прочтите страницы с 1 по pdf.page_count. Если ни один из форматов не отображает пиксели, сообщите об ограничении приложения вместо того, чтобы придумывать текст.

pdf.source_sha256 и pdf.source_bytes описывают исходный PDF-файл; sha256 и total_bytes верхнего уровня описывают изображение страницы. --expected-fingerprint проверяет исходный PDF-файл. --page нельзя комбинировать с --offset-bytes или --chunk-bytes. По умолчанию PDF-файлы могут быть до 50 МиБ без фиксированного ограничения числа страниц; PNG — до 4000 пикселей по каждой стороне и 8 МиБ на страницу. Все три значения настраиваются.

Изображение страницы не вызывает никакой внешней службы OCR и не индексирует текст. После просмотра каждой страницы агент вызывает attachments update и проверяет поиск content:. Сверяйте цифры и сложные раскладки с изображениями; качество зависит от исходного документа и инструментов агента.

Увеличить размер файла или PDF-превью

Задайте переменные на компьютере, где работает Telegram или его MCP-сервер:

ПеременнаяПо умолчаниюЧто ограничивает
MESSAGING_ATTACHMENT_MAX_MIB50Размер файла для извлечения текста и передачи сохранённого вложения
MESSAGING_PDF_PREVIEW_MAX_PIXELS4000Ширину и высоту PNG страницы PDF
MESSAGING_PDF_PREVIEW_MAX_MIB8Размер PNG одной страницы

Например, разрешить файлы до 250 МиБ и страницы до 8000 пикселей/16 МиБ:

export MESSAGING_ATTACHMENT_MAX_MIB=250
export MESSAGING_PDF_PREVIEW_MAX_PIXELS=8000
export MESSAGING_PDF_PREVIEW_MAX_MIB=16

В PowerShell: $env:MESSAGING_ATTACHMENT_MAX_MIB = "250"; остальные имена задаются так же. Значения — положительные целые числа. После изменения переменных запустите tg personal mcp config снова и замените запись сервера в приложении: она сохранит эти настройки. Уже запущенный сервер нужно перезапустить. Обычная передача остаётся частями до 1 МиБ; это отдельный лимит.

Увеличение требует больше памяти и времени. Рендер масштабирует страницу до четырёх раз в пределах выбранных размеров; большой потолок не заставляет каждую страницу занимать всю его ширину. Ответ MCP учитывает base64 и служебные поля, но приложение может иметь свой предел. Для большого ответа CLI JSON задайте --max-output-bytes 50000000; 0 явно выключает общий предел вывода. Лимиты внешнего OCR и распаковки офисных документов не меняются вместе с размером файла.