# Установка CLI и MCP-сервера Telegram (/ru/docs/tg/installation)

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

## Шаги [#шаги]

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

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

## 1. Установите tg [#1-установите-tg]

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

### С помощью агента [#с-помощью-агента]

Подойдёт агент, который умеет запускать программы на этом компьютере, например Claude Code, Codex, Cursor или Gemini CLI. Если вы пользуетесь только чатом с агентом в браузере или на телефоне, откройте [подключение из веба или с телефона](/llms.mdx/docs/ru/browser-apps/content.md).

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

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

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

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

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

### Вручную в терминале [#вручную-в-терминале]

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

1. **Установите Node.js 22.19 или новее** (22.x или 24+) либо Bun. См. [Node.js, npm и поиск команды](/llms.mdx/docs/ru/installation/content.md#nodejs).
2. **Установите tg:**

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

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

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

   ```powershell
   & ([scriptblock]::Create((Invoke-RestMethod 'https://wirecat.dev/install.ps1'))) -Tool tg -Agent all
   ```

3. **Проверьте установку:**

   ```sh
   tg --version
   ```

   Появится номер версии. Если терминал пишет, что команда не найдена, см. [tg не находится после установки](#q-not-found).

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

   ```sh
   tg personal setup
   ```

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

## 2. Войдите в Telegram [#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](/screenshots/telegram/code-message.jpg)

3. Затем дождитесь QR-кода для входа в аккаунт на экране компьютера. Это два отдельных подтверждения: предыдущий код нужен для настройки подключения, а QR-код — для входа tg в ваш аккаунт.
4. В Telegram на телефоне откройте «Настройки» → «Устройства» и выберите «Привязать настольное устройство» или «Добавить устройство» (Add Device). Разрешите доступ к камере, если приложение попросит, и наведите сканер на QR-код, который настройка показала на компьютере. Используйте сканер внутри Telegram, а не обычное приложение камеры. Не нашли? Смотрите [шаги для iOS и Android](#q-scan).

   ![Telegram: Настройки → Устройства, выделена кнопка Add Device](/screenshots/telegram/add-device.jpg)

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

## 3. Подключите агента [#3-подключите-агента]

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

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

```sh
tg skill install --for all
```

После этого откройте новую сессию агента, чтобы он загрузил инструкции. Другие агенты и MCP-приложения описаны в разделе [Подключение агента](/llms.mdx/docs/ru/agents/content.md).

## 4. Проверьте, что всё работает [#4-проверьте-что-всё-работает]

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

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

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

Setup не скачивает всю историю чатов. Чтобы искать старые сообщения, попросите агента [скачать нужную историю](/llms.mdx/docs/ru/tg/archive/content.md).

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

**Дальше:** [попробуйте первую задачу](/llms.mdx/docs/ru/first-tasks/content.md).

## Вопросы и ответы [#вопросы-и-ответы]

### QR-код не сканируется [#qr-код-не-сканируется]

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

**Вручную:**

```sh
tg personal setup --method phone
```

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

Агент запускает `tg personal session start qr` в фоне. Без терминала tg печатает QR-код текстом. Агент вставляет его в чат блоком кода точно как напечатано, а вы сканируете его с экрана. Когда Telegram обновляет код, агент вставляет новый и говорит, что старый истёк. Это работает, только если у tg уже есть приложение Telegram и у аккаунта нет дополнительного пароля; иначе запустите `tg personal setup` сами. Подробнее — в разделе [если вход запускает агент](/llms.mdx/docs/ru/agents/content.md#agent-login).

### Не получается зарегистрировать приложение Telegram [#не-получается-зарегистрировать-приложение-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 с полями страны и номера телефона](/screenshots/telegram/telegram-app-1-sign-in.png)

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

   ![Страница ввода кода подтверждения на my.telegram.org](/screenshots/telegram/telegram-app-2-code.png)

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

   ![Главная страница my.telegram.org с карточкой Development Tools](/screenshots/telegram/telegram-app-3-development-tools.png)

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

   ![Форма Create new application](/screenshots/telegram/telegram-app-4-create-application.png)

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

   ![Раздел Credentials с App api_id и App api_hash](/screenshots/telegram/telegram-app-5-credentials.png)

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

### Где в Telegram сканер QR-кода? [#где-в-telegram-сканер-qr-кода]

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

**iOS**

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

**Android**

1. Откройте **Настройки**, затем **Устройства**.
2. Нажмите **Add Device** и разрешите доступ к камере, если Telegram спросит.
3. Наведите камеру на QR-код в терминале.

![Telegram для Android, Настройки и Устройства, кнопка Add Device](/screenshots/telegram/telegram-android-add-device.png)

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

![Список Incomplete login attempts на экране Устройства в Telegram](/screenshots/telegram/telegram-android-incomplete-login.png)

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

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

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

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

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

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

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

Если pnpm сообщает `ERR_PNPM_GLOBAL_BIN_DIR_NOT_IN_PATH`, выполните `pnpm setup`, откройте новый терминал и повторите установку. Подробнее — [pnpm setup](https://pnpm.io/cli/setup).

### Куда вводить коды и пароли? [#куда-вводить-коды-и-пароли]

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

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

**С агентом:** откройте новую сессию агента, чтобы он загрузил инструкции tg. Если не помогло, откройте [Подключение агента](/llms.mdx/docs/ru/agents/content.md).

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

### После обновления tg пишет, что профиль не назван [#после-обновления-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 останавливается и называет два файла архива [#после-обновления-tg-останавливается-и-называет-два-файла-архива]

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

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

Setup проверяет только несколько чатов. Попросите агента скачать нужный чат и период: см. [Локальный архив](/llms.mdx/docs/ru/tg/archive/content.md). Пустой результат поиска не значит, что таких сообщений в чате нет.

### Можно попробовать tg без установки? [#можно-попробовать-tg-без-установки]

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

### Где хранится вход? [#где-хранится-вход]

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

## Где хранятся файлы [#где-хранятся-файлы]

| Что | Linux и macOS | Windows |
| --- | --- | --- |
| Настройки | `~/.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. Как изменить эти папки и другие настройки, описано в разделах [Настройки](/llms.mdx/docs/ru/configuration/content.md) и [справочник настроек tg](/llms.mdx/docs/ru/tg/configuration/content.md).

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

## Обновление [#обновление]

```sh
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 ещё установлен:

```sh
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.

## Из исходников [#из-исходников]

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

```sh
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`.
