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

Установка CLI и MCP-сервера Telegram

Установите tg, зарегистрируйте его приложение Telegram, войдите по QR-коду и подключите ИИ-агента — с его помощью или вручную.

На этой странице вы подключите аккаунт Telegram к ИИ-агенту на своём компьютере. После этого агента можно просить читать чаты, искать сообщения и готовить ответы. Понадобится около пяти минут и телефон, на котором вы уже вошли в Telegram.

Шаги

  1. Установите tg. tg — небольшая программа, которая даёт агенту доступ к вашему аккаунту Telegram. Агент может установить её сам, или вы сделаете это вручную.
  2. Войдите в Telegram. Вы дважды подтверждаете вход на телефоне: сначала кодом, который регистрирует tg в Telegram, затем сканированием QR-кода. Так компьютер становится новым устройством вашего аккаунта.
  3. Подключите агента. Агент получает инструкции, чтобы пользоваться tg.
  4. Проверьте, что всё работает. Агент показывает ваш аккаунт и несколько чатов.

Если какой-то шаг не получается, загляните в вопросы и ответы.

1. Установите tg

Установить можно двумя способами. Результат одинаковый.

С помощью агента

Подойдёт агент, который умеет запускать программы на этом компьютере, например Claude Code, Codex, Cursor или Gemini CLI. Если вы пользуетесь только чатом с агентом в браузере или на телефоне, откройте подключение из веба или с телефона.

Скопируйте этот запрос в чат с агентом. Он поможет установить инструмент и войти в аккаунт на вашем компьютере.

Запрос
Помоги подключить мой аккаунт Telegram к моему ИИ-агенту на этом компьютере.
Следуй https://wirecat.dev/ru/docs/tg/installation: проверь нужные программы и помоги с установкой.
Покажи мне шаги входа, чтобы я сам подтвердил доступ к аккаунту.
Подключи инструкции инструмента к моему агенту. В конце покажи мой аккаунт и несколько чатов. Ничего не отправляй.

Агент проведёт вас по шагам:

  1. Проверит компьютер. Для tg нужен Node.js 22.19 или новее. Если его нет, агент объяснит, как его установить.
  2. Установит tg. Ваш аккаунт на этом шаге не затрагивается.
  3. Запустит вход. Агент запускает tg personal setup в окне терминала. Вы подтверждаете вход на телефоне, как описано в разделе Войдите в Telegram. Если агент не может показать вам это окно, он вставит QR-код в чат текстом: см. агент не может показать мне терминал.
  4. Подключит себя к tg. Агент устанавливает себе инструкции tg.
  5. Покажет результат. Вы увидите имя аккаунта и несколько чатов. Агент ничего не отправляет.

Вход вы подтверждаете сами, на телефоне. Не вставляйте коды и пароли в чат с агентом.

Вручную в терминале

Откройте «Терминал» в macOS или Linux либо PowerShell в Windows.

  1. Установите Node.js 22.19 или новее (22.x или 24+) либо Bun. См. Node.js, npm и поиск команды.

  2. Установите tg:

    npm install -g @wirecat/tg-cli && tg skill install --for all

    npm может сообщить о заблокированных сценариях установки. Вторая команда явно устанавливает инструкции агента. Прочитайте предупреждения менеджера пакетов и проверьте версию на следующем шаге. В Windows откройте новый терминал, если команда tg не найдена.

    В Windows можно установить одной командой. Она ставит tg, добавляет его в PATH (папки, в которых терминал ищет команды) и подключает все поддерживаемые агенты:

    & ([scriptblock]::Create((Invoke-RestMethod 'https://wirecat.dev/install.ps1'))) -Tool tg -Agent all
  3. Проверьте установку:

    tg --version

    Появится номер версии. Если терминал пишет, что команда не найдена, см. tg не находится после установки.

  4. Запустите вход:

    tg personal setup

    Дальше — следующий шаг.

2. Войдите в Telegram

Вход добавляет компьютер как новое устройство вашего аккаунта Telegram — как Telegram Desktop. Это устройство видно в Telegram на телефоне, и его можно удалить в любой момент. Вход не скачивает историю чатов.

Вход показывает tg personal setup. Его запускает агент или вы сами.

personal — имя этого входа на компьютере, оно называется профилем. Подойдёт любое имя. Следующие команды начинаются с того же имени, например tg personal doctor.

Telegram просит два подтверждения. Сначала tg регистрирует для вашего аккаунта собственное приложение Telegram — два значения, App api_id и App api_hash: они обозначают программу, но сами по себе не дают доступа к сообщениям. Затем вы сканируете QR-код, и tg входит в аккаунт.

  1. Когда настройка попросит номер телефона, введите его с кодом страны, например +7… . Это первое подтверждение нужно, чтобы tg подготовил данные подключения, которые Telegram требует для вашего аккаунта.

  2. Откройте Telegram на телефоне и найдите служебное сообщение Telegram с кодом для my.telegram.org. Этот код приходит в Telegram, а не по SMS. Введите его в запросе настройки. tg получит уже созданные данные подключения или создаст их за вас — писать программу не нужно.

    Сообщение Telegram с кодом для входа на my.telegram.org

  3. Затем дождитесь QR-кода для входа в аккаунт на экране компьютера. Это два отдельных подтверждения: предыдущий код нужен для настройки подключения, а QR-код — для входа tg в ваш аккаунт.

  4. В Telegram на телефоне откройте «Настройки» → «Устройства» и выберите «Привязать настольное устройство» или «Добавить устройство» (Add Device). Разрешите доступ к камере, если приложение попросит, и наведите сканер на QR-код, который настройка показала на компьютере. Используйте сканер внутри Telegram, а не обычное приложение камеры. Не нашли? Смотрите шаги для iOS и Android.

    Telegram: Настройки → Устройства, выделена кнопка Add Device

  5. Если настройка попросит дополнительный пароль Telegram, введите пароль, который вы задали в Telegram. Это не одноразовый код. Терминал не показывает вводимые символы. Наберите пароль и нажмите Enter.

  6. Дождитесь, пока настройка подтвердит вход и проверит аккаунт и до пяти чатов.

3. Подключите агента

Чтобы пользоваться tg, агенту нужны инструкции. Они называются навыком. Setup спрашивает, какой агент вы используете, и устанавливает навык для него. Команда установки выше уже выполняет tg skill install --for all.

Чтобы установить навык заново:

tg skill install --for all

После этого откройте новую сессию агента, чтобы он загрузил инструкции. Другие агенты и MCP-приложения описаны в разделе Подключение агента.

4. Проверьте, что всё работает

Попросите агента:

Запрос
Use tg CLI. Покажи мой аккаунт Telegram и пять последних чатов. Ничего не отправляй.

Проверьте, что имя и чаты относятся к аккаунту, который вы хотели подключить. Если да, tg готов к работе.

Setup не скачивает всю историю чатов. Чтобы искать старые сообщения, попросите агента скачать нужную историю.

Вручную: tg personal doctor показывает, выполнен ли вход и где tg хранит файлы. К Telegram он не подключается.

Дальше: попробуйте первую задачу.

Вопросы и ответы

QR-код не сканируется

С агентом: попросите агента выбрать вход по номеру телефона. Введите номер и новый код для входа в запросах настройки, затем дополнительный пароль Telegram, если его попросят. Код может прийти в Telegram, а не по SMS; настройка скажет, куда.

Вручную:

tg personal setup --method phone

Агент не может показать мне терминал с QR-кодом

Агент запускает tg personal session start qr в фоне. Без терминала tg печатает QR-код текстом. Агент вставляет его в чат блоком кода точно как напечатано, а вы сканируете его с экрана. Когда Telegram обновляет код, агент вставляет новый и говорит, что старый истёк. Это работает, только если у tg уже есть приложение Telegram и у аккаунта нет дополнительного пароля; иначе запустите tg personal setup сами. Подробнее — в разделе если вход запускает агент.

Не получается зарегистрировать приложение Telegram

tg сам заполняет форму на my.telegram.org. Если Telegram изменит этот сайт, зарегистрируйте приложение вручную и передайте tg его два значения.

С агентом: попросите выбрать ручную регистрацию приложения. Агент откроет my.telegram.org/apps в браузере.

Вручную: выполните tg personal setup --app browser, затем:

  1. Откройте my.telegram.org/apps. Выберите страну, введите номер телефона и нажмите Next.

    Страница входа my.telegram.org с полями страны и номера телефона

  2. Telegram присылает код подтверждения сообщением в приложение Telegram, а не по SMS. Введите его на странице и нажмите Sign in. Никому не передавайте этот код и не вводите его в чат с агентом.

    Страница ввода кода подтверждения на my.telegram.org

  3. Откройте Development Tools и выберите Create new application.

    Главная страница my.telegram.org с карточкой Development Tools

  4. Заполните форму. Название должно быть не короче 5 символов. Краткое имя состоит только из латинских букв и цифр, от 5 до 32 символов. Не используйте слово "Telegram" ни в названии, ни в кратком имени. Выберите платформу, например Desktop. URL и описание можно не заполнять. Нажмите Create application. Если приложение уже есть, используйте его.

    Форма Create new application

  5. Скопируйте App api_id и App api_hash и введите их в терминал настройки, когда он попросит. Не показывайте хэш другим: тот, у кого он есть, может расходовать квоту вашего приложения. Хэш при вводе скрыт. Это данные подключения, а не токен бота.

    Раздел Credentials с App api_id и App api_hash

  6. Продолжите вход по QR-коду. Значения на этих снимках экрана вымышленные.

Где в Telegram сканер QR-кода?

Откройте Telegram на телефоне и используйте сканер самого Telegram, а не приложение камеры. Пункты меню зависят от телефона.

<Tabs items={["iOS", "Android"]}>

  1. Откройте Настройки, затем Устройства.
  2. Нажмите Подключить устройство (в английском интерфейсе Link Desktop Device) и разрешите доступ к камере, если Telegram спросит.
  3. Наведите камеру на QR-код в терминале.
  1. Откройте Настройки, затем Устройства.
  2. Нажмите Add Device и разрешите доступ к камере, если Telegram спросит.
  3. Наведите камеру на QR-код в терминале.

Telegram для Android, Настройки и Устройства, кнопка Add Device

Если у аккаунта есть дополнительный пароль Telegram, tg спросит его после сканирования. Если вы отсканировали код, но не ввели пароль, попытка появится в разделе Устройства в списке Incomplete login attempts. У неё нет доступа к вашим сообщениям. Завершите вход в tg или завершите попытку в этом списке.

Список Incomplete login attempts на экране Устройства в Telegram

QR-код истёк или настройка прервалась

С агентом: попросите агента завершить вход и снова запустить настройку.

Вручную: выполните tg personal session start, чтобы завершить вход, затем снова tg personal setup. Если вход уже выполнен, настройка использует его и не спрашивает заново.

tg не находится после установки

С агентом: перезапустите агента или попросите его открыть новый терминал. Терминал, открытый во время установки, не видит новую команду.

Вручную: откройте новый терминал и снова выполните tg --version. npm не может изменить PATH терминала, в котором его запустили. В Windows команда PowerShell из раздела Установите tg исправляет PATH, даже если npm пропустил свой сценарий установки, и обновляет текущий терминал.

pnpm не находит папку глобальных команд

Если pnpm сообщает ERR_PNPM_GLOBAL_BIN_DIR_NOT_IN_PATH, выполните pnpm setup, откройте новый терминал и повторите установку. Подробнее — pnpm setup.

Куда вводить коды и пароли?

В терминал настройки или на странице my.telegram.org, но никогда не в чат с агентом. Если не видите окно терминала, попросите агента его показать.

Агент не может пользоваться tg после настройки

С агентом: откройте новую сессию агента, чтобы он загрузил инструкции tg. Если не помогло, откройте Подключение агента.

Вручную: выполните tg skill install --for claude для Claude Code, --for agents для Codex, Gemini CLI и других агентов, которые читают ~/.agents, или --for all.

После обновления tg пишет, что профиль не назван

tg никогда не выбирает аккаунт сам: каждая команда, которой нужен аккаунт, начинается с имени профиля.

С агентом: назовите агенту имя профиля. Если вы раньше настраивали tg без имени профиля, он называется default.

Вручную: пишите имя первым словом (tg default chats list) или задайте его один раз: export TG_PROFILE=default в профиле оболочки. Если вы подключали tg к MCP-приложению, пересоздайте эту запись командой tg default mcp config. Всё остальное, что запускает tg serve или tg mcp за вас, например задание по расписанию, тоже должно называть профиль в команде: tg default serve.

После обновления tg останавливается и называет два файла архива

Обновление один раз переносит архив сообщений в папку WireCat. Если в старом и новом месте лежат разные копии, tg останавливается с кодом 3 и называет оба файла. Оставьте нужный, уберите другой и запустите команду снова. Ничего не перенесено и не изменено.

Нет чата или старых сообщений

Setup проверяет только несколько чатов. Попросите агента скачать нужный чат и период: см. Локальный архив. Пустой результат поиска не значит, что таких сообщений в чате нет.

Можно попробовать tg без установки?

Да: npx @wirecat/tg-cli --help. Так tg запускается один раз. Команда tg не появляется, и агент не подключается.

Где хранится вход?

Вход — это файл сессии в папке состояния tg (см. таблицу ниже). Тот, у кого есть этот файл, может читать ваши чаты, поэтому обращайтесь с ним как с паролем. App api_id и App api_hash хранятся в хранилище паролей операционной системы (ключнице). См. Безопасность.

Где хранятся файлы

ЧтоLinux и macOSWindows
Настройки~/.config/tg-cli/%APPDATA%\tg-cli\Config\
Состояние: вход, записи запусков, отправки, получатели~/.local/share/tg-cli/%LOCALAPPDATA%\tg-cli\Data\
Кэш~/.cache/tg-cli/%LOCALAPPDATA%\tg-cli\Cache\
Локальный архив сообщений, общий с max~/.local/share/WireCat/wirecat.db%LOCALAPPDATA%\WireCat\Data\wirecat.db
Модели распознавания речи~/.local/share/WireCat/models/audio/%LOCALAPPDATA%\WireCat\Data\models\audio\

tg personal doctor показывает точные пути на вашем компьютере. WIRECAT_STATE_DIR переносит всю папку WireCat. Как изменить эти папки и другие настройки, описано в разделах Настройки и справочник настроек tg.

Первый запуск после обновления со старого tg один раз переносит сюда архив и модели из ~/.local/share/cli-messaging/ и ~/.cache/cli-common/models/. В macOS старые версии держали свои папки в ~/Library; они тоже переносятся один раз.

Обновление

tg upgrade            # тем же менеджером пакетов, которым tg установлен: npm, pnpm или bun
tg upgrade --check    # только сообщает, есть ли новая версия

Если вы обновляетесь с версии, которая хранила сообщения в messages.db, сначала скопируйте заметки и метки, которые есть только на компьютере: старый файл удаляется, когда открывается новый архив. tg personal messages sync --all скачает сообщения заново, но не локальные заметки и метки.

Обновляйте max и memo вместе с tg: у них общий архив сообщений, и старый инструмент создаст новый архив на прежнем месте.

tg не обновляется сам. Раз в день он проверяет, есть ли новая версия, и пишет об этом одну строку в терминале. После обновления tg upgrade перезапускает фоновый serve, который запустил сам tg. Вход сохраняется.

Удаление

Удаление tg убирает команду, но не ваши данные. Сначала выйдите из аккаунта, пока tg ещё установлен:

tg personal server uninstall          # только если ставили фоновую службу
tg personal session end               # выйти на стороне Telegram и удалить файл сессии
npm uninstall -g @wirecat/tg-cli
rm -rf ~/.config/tg-cli ~/.local/share/tg-cli ~/.cache/tg-cli
rm -rf ~/.claude/skills/tg-cli ~/.agents/skills/tg-cli

Если вы подключали ботов, выполните также tg <profile> bot auth remove для каждого профиля бота. Выход оставляет App api_id и App api_hash в ключнице, под службой tg-cli; удалите эту запись средствами системы, если они больше не нужны. Удаляйте ~/.local/share/WireCat/ только если сохранённые сообщения больше не нужны другим инструментам, например max.

Из исходников

Устанавливайте из исходников, если меняете код или нужна ещё не выпущенная версия.

git clone https://github.com/WireCatLabs/tg-cli.git
cd tg-cli
pnpm install
pnpm build

В рабочей копии bin/tg хранит настройки, вход и архив в .tg/ внутри неё, а не в вашем настоящем профиле. node dist/bin/tg.js использует настоящие папки из таблицы выше. Обновление: git pull && pnpm install && pnpm build.