# Вход, сессии и профили CLI Telegram (/ru/docs/tg/sessions)

Подключите инструмент к своему аккаунту мессенджера, чтобы агент мог читать выбранные чаты и помогать с ответами. Здесь вы пройдёте вход, проверите подключение и узнаете, как управлять сессией или завершить её. Вход добавляет разрешённое устройство; всю историю чатов он не скачивает.

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

Во-первых, слова, которые используются на этой странице:

- **Сессия**: логин `tg` на этом компьютере. Telegram выдает его при входе в систему и указывает в приложении Telegram как еще одно устройство. `tg` сохраняет его в файле. Тот, у кого есть этот файл, может читать ваши чаты, поэтому относитесь к нему как к паролю.
- **Приложение** (`api_id` и `api_hash`): два значения из [my.telegram.org](https://my.telegram.org/apps), которые идентифицируют программу в Telegram. Каждый пользователь регистрирует свое приложение один раз; `tg` может сделать это за вас.
- **Связка ключей**: хранилище паролей вашей операционной системы. `tg` сохраняет там значения приложения.
- **Профиль**: имя для одного входа на этом компьютере с собственной сессией, приложением и настройками. Его называет каждая команда, которой нужен аккаунт, поэтому вы выбираете одно имя при настройке (`tg personal setup`) и дальше используете его ([профили](#profiles)).

Не путайте `tg personal session` с `tg personal account sessions`. `tg personal session` — это логин самого `tg`; `tg personal account sessions` перечисляет все остальные устройства и приложения, на которых выполнен вход в ваш аккаунт.

## Первый запуск [#первый-запуск]

`tg personal setup` помогает при первом запуске приложения и сессии, проверяет пять чатов и предлагает навыки агента. Подождите около пяти минут; Загрузка истории — это отдельный шаг. Запустите его в терминале. Используйте `tg personal setup --app browser` для регистрации приложения вручную или `--method phone` для входа в систему по телефону. `tg personal session start` остается командой только для входа в систему, включая возобновление прерванного входа в систему. Программа установки проверяет существующую сессию и не выполняет повторный вход в автоматическом режиме, если он отклонен.

## Приложение с my.telegram.org [#приложение-с-mytelegramorg]

> **Посмотреть экран входа my.telegram.org**
>
> ![Официальный экран входа my.telegram.org: поле номера телефона не заполнено.](/telegram-app-login.png)
>
> Это вход на сайт для получения данных приложения Telegram. Код приходит сообщением в Telegram, не по SMS. После входа выберите **API development tools**. Подтверждение доступа CLI через QR-код будет следующим этапом. [my.telegram.org](https://my.telegram.org/apps)

Каждый пользователь регистрирует своё приложение. Telegram выдаёт одно приложение на номер телефона, поэтому общий идентификатор не включён в `tg`. Данные нужны один раз для каждого профиля; `tg personal session start` запрашивает их только при отсутствии.

Есть два способа получить данные:

- **`--app browser`** открывает [my.telegram.org/apps](https://my.telegram.org/apps). Войдите туда, создайте приложение, если у вас его нет (любое название и краткое имя, платформа Desktop), и вставьте `App api_id` и `App api_hash`, когда `tg` спросит. Хэш не отображается при вводе. Это значение по умолчанию для `tg personal session start`.
- **`--app auto`** заполняет сайт за вас. Он запрашивает ваш номер телефона, а my.telegram.org отправляет вам код сообщением в Telegram, затем читает ваше приложение или создает его, если у вас его нет. На сайте нет API, поэтому `tg` соответствует его веб-форме; изменение на стороне Telegram может сломать это. Тогда `--app
  browser` все еще работает. Это значение по умолчанию для `tg setup`.

Данные приложения сохраняются только после успешного входа в Telegram.

### Создание приложения вручную [#создание-приложения-вручную]

Выполните эти шаги с `--app browser` или если `--app auto` не сработал. Это делается один раз для каждого аккаунта Telegram.

1. **Войдите на [my.telegram.org](https://my.telegram.org/apps).** Выберите страну, введите номер телефона и нажмите **Next**.

   ![Страница входа my.telegram.org с полями страны и номера телефона](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-app-1-sign-in.png)

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

   ![Страница кода подтверждения my.telegram.org](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-app-2-code.png)

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

   ![Главная страница my.telegram.org с карточкой Development Tools](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-app-3-development-tools.png)

   Заполните форму. Название (title) — не меньше 5 символов. Краткое имя (short name) — только буквы и цифры, от 5 до 32 символов. Не используйте в них слово «Telegram». Выберите платформу, например **Desktop**. URL и описание необязательны. Затем нажмите **Create application**.

   ![Форма Create new application](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-app-4-create-application.png)

3. **Скопируйте `api_id` и `api_hash`** из раздела Credentials. Храните хеш в тайне: любой, у кого он есть, может расходовать квоту вашего приложения.

   ![Раздел Credentials с App api_id и App api_hash](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-app-5-credentials.png)

4. **Передайте оба значения `tg`**, когда он запросит `App api_id` и `App api_hash`. Хеш не отображается при вводе.

Номер телефона и данные приложения на этих снимках экрана — примеры.

## Вход в систему [#вход-в-систему]

```sh
tg personal session start  # a QR code in the terminal
tg personal session start phone  # a phone number, the code Telegram sends, and your 2FA password
tg personal session start phone --sms  # the same, asking Telegram for the code by SMS
```

**QR:** отсканируйте код в приложении Telegram, как описано в следующем разделе. Код обновляется, пока вы ждёте.

**Телефон:** введите номер в международном формате, а затем код для входа. Если у аккаунта есть облачный пароль (2FA), `tg` запрашивает его, не показывая, что вы вводите. При использовании `--app auto` номер телефона запрашивается только один раз. Код обычно приходит в приложение Telegram; `--sms` вместо этого запрашивает SMS, но Telegram выбирает, а `tg` сообщает, каким способом оно было отправлено. Когда в Telegram нет СМС для аккаунта, `tg` говорит об этом и запрашивает код из приложения.

После этого Telegram добавляет новое устройство в список сессий приложения.

```text
Logged in as <your name> (@<username>, id <id>) — profile personal.
Session:  ~/.local/share/tg-cli/sessions/personal.session
App keys: in the keyring
Next:     tg personal chats list · tg personal server install to keep the archive current
```

### Если вход запускает агент [#если-вход-запускает-агент]

Ваш ИИ-агент может запустить для вас вход в систему. Без терминала `tg` печатает QR-код обычным текстом, и агент вставляет его в чат, чтобы вы его отсканировали:

```sh
tg personal session start qr
```

Агент запускает команду в фоне: она ждёт сканирования, а инструмент оболочки ничего не показывает, пока команда не завершится. Агент читает вывод и вставляет блок с QR-кодом в чат блоком кода, точно как напечатано. Когда Telegram обновляет код, печатается новый блок: агент вставляет его и говорит, что старый истёк. С `--json` каждый код также печатается одной строкой в stderr, `{"event":"qr","qr":{"text":…,"expires_at":…,"scan":…}}`. Когда код отсканирован, tg пишет `scan accepted, finishing sign-in`, а с `--json` — `{"event":"progress","step":"scanned","message":…}`: Telegram может завершать вход десять секунд и дольше.

Код нарисован для тёмной темы терминала. Без терминала это работает только в том случае, если в профиле уже есть приложение, а у аккаунта нет пароля 2FA: все остальное вам придется вводить самостоятельно.
Программа, которая показывает вопросы в своём окне, например WireCat Desktop, запускает
`tg personal session start phone --json --answer-stdin`: каждый вопрос приходит строкой `needs` в stderr,
а ответ — одной строкой в stdin.
`tg personal setup` работает так же. Вход не предлагается как инструмент MCP: агент, у которого есть только MCP, просит вас запустить команду или запускает её через свою оболочку.

### Подключение устройства по QR-коду [#подключение-устройства-по-qr-коду]

В Telegram это называется подключением настольного устройства. `tg` показывает QR-код в терминале, а вы сканируете его приложением Telegram на телефоне. Используйте сканер самого Telegram, а не приложение камеры.

#### Android [#android]

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

![Telegram для Android, «Настройки» и «Устройства», с кнопкой подключения устройства](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-android-add-device.png)

#### iPhone и iPad [#iphone-и-ipad]

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

Если у аккаунта есть пароль двухэтапной проверки (2FA), `tg` запросит его после сканирования. Терминал не показывает, что вы вводите.

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

![Список незавершённых попыток входа на экране «Устройства» в Telegram](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-android-incomplete-login.png)

## Проверка и выход [#проверка-и-выход]

```sh
tg personal account show     # who this profile is logged in as
tg account list              # every profile on this computer, and the account each is logged in as
tg personal account sessions list  # every device and app logged in to the account; ends nothing
tg personal session end      # log out on Telegram's side, and delete the session file here
```

`tg personal session end` завершает сессию **и на стороне Telegram**: устройство исчезает из списка в приложении. Идентификатор и хеш приложения остаются в хранилище ключей, локальная база не меняется.

Чтобы полностью забыть профиль, используйте `tg personal account remove --keep-data` или `--delete-data`. Команда так же завершает сессию, а затем удаляет идентификатор и хеш приложения профиля, пароль его прокси, сессии его ботов для чтения истории и то, что cli-core хранит для профиля. С `--keep-data` его сообщения остаются в хранилище и находятся поиском. С `--delete-data` они удаляются. Токен бота с профилем того же имени остаётся, потому что бот является отдельным аккаунтом.

## Срок действия сессии [#срок-действия-сессии]

Сессия действует, пока её не завершат: `tg personal session end`, из списка устройств в приложении Telegram или самим Telegram, если сессия не используется дольше, чем лимит аккаунта для неактивных сессий (`authorization_ttl_days` в [Telegram API](https://core.telegram.org/method/account.setAuthorizationTTL)), который приложения позволяют вам установить в списке устройств. Профиль, который запускается каждый день, никогда не достигает его. Когда сессия завершена, каждая команда отвечает «не вошел в систему или сессия завершена» с кодом выхода `4`; войдите снова с помощью `tg personal session start` ([что делать, когда сессия завершилась](/llms.mdx/docs/ru/tg/troubleshooting/content.md#not-logged-in-or-the-session-was-ended--run-tg-session-start)).

## Профили [#профили]

Профиль — именованное подключение аккаунта Telegram в CLI. Обычно отдельный профиль создают для каждого номера: например, `personal` для личного аккаунта и `work` для рабочего. У каждого подключения свои сессия входа, данные приложения, настройки, разрешённые получатели и записи запусков.

Имя `work` — выбранная вами метка, а не номер телефона. Чтобы подключить рабочий аккаунт, выполните:

```sh
tg work session start --app browser
```

При регистрации приложения укажите рабочий номер; при QR-входе переключите Telegram на телефоне на рабочий аккаунт. После входа проверьте, какой аккаунт связан с меткой:

```sh
tg work account show
```

Один и тот же аккаунт тоже можно подключить в нескольких профилях; профиль сам по себе не создаёт новый аккаунт Telegram. Имя профиля указывается **первым словом после `tg`**, перед командой:

```sh
tg personal chats list     # profile "personal"
tg work chats list         # profile "work"
export TG_PROFILE=work     # the same for the whole shell session
```

**Первое слово считается профилем, если это не команда.** Поэтому профиль нельзя назвать `chats`, `messages` или другим словом команды; `tg personal session start` отклоняет такое имя. Разрешены буквы, цифры, точки, дефисы и подчёркивания; первый символ — буква или цифра.

Приоритет: сначала первое слово команды, затем `TG_PROFILE`. Если нет ни того, ни другого, команда, которой нужен аккаунт, останавливается с кодом выхода `2` и перечисляет профили на этом компьютере; если профилей ещё нет, она предлагает запустить `tg personal setup`. `tg` никогда не выбирает профиль сам, даже единственный. Команды, которым аккаунт не нужен, работают без профиля: `--help`, `--version`, `commands`, `skill show`, `account list` и `config show`.

Слово, которое не является командой и за которым нет команды, вызывает поясняющую ошибку:

```text
"nonsense" is not a command, so it was read as a profile name — and no command followed it.
```

**`TG_PROFILE_LOCK` фиксирует процесс на одном профиле.** Задайте его в окружении агента: другой профиль первым словом или через `TG_PROFILE` будет отклонён с кодом `5`. Без этой переменной агент может выбрать профиль с меньшими ограничениями.

Для чего нужен каждый профиль и как профиль работает с ботом: [профили и боты](/llms.mdx/docs/ru/tg/profiles/content.md).

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

| Данные | Место хранения |
|---|---|
| сессия | `sessions/<profile>.session` в каталоге состояния |
| идентификатор и хеш приложения | системное хранилище ключей, сервис `tg-cli`, запись `<profile>:api` |
| идентификатор и хеш без хранилища ключей | `credentials.json` в каталоге настроек |
| идентификатор и хеш для CI | `TG_API_ID` и `TG_API_HASH`; приоритет над хранилищем ключей |

Каталоги перечислены в [куда идут файлы](/llms.mdx/docs/ru/tg/installation/content.md#where-files-go).

Если хранилища ключей нет (часто в контейнерах), данные приложения сохраняются в `credentials.json` рядом с настройками. `tg` один раз сообщает об этом в stderr.

> ⚠ **`TG_CONFIG_DIR`, `TG_STATE_DIR` и `TG_CACHE_DIR` также меняют запись хранилища ключей.** При любой из этих переменных имя сервиса включает каталог настроек. Сессия, созданная без переменных, не видна с ними, и наоборот. Задавайте их всегда или не задавайте вовсе.

> ⚠ **В Linux доступ к связке ключей осуществляется через `XDG_RUNTIME_DIR`.** cron, ssh и некоторые клиенты MCP запускают `tg` без него, и каждая команда затем говорит, что учетные данные приложения не найдены, «хотя вход выполнен в систему на этом компьютере». **Не входите повторно**: это добавляет еще одно устройство и не исправляет среду. Установите `XDG_RUNTIME_DIR` > ([учетные данные приложения не найдены после входа в систему](/llms.mdx/docs/ru/tg/troubleshooting/content.md#no-telegram-app-credentials-found--although-it-has-logged-in-on-this-machine)).

## Дальше [#дальше]

- [Читать свои первые чаты](/llms.mdx/docs/ru/tg/usage/content.md)
- [Настройки и приоритет значений](/llms.mdx/docs/ru/tg/configuration/content.md)
- [Что достигает диска, а что никогда](/llms.mdx/docs/ru/tg/security/content.md)
