# Диагностика команд CLI Telegram (/ru/docs/tg/diagnostics)

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

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

- **Запуск** — это один вызов `tg` от начала до выхода.
- **Запись о запуске** — это папка, в которой хранится то, что сделал один запуск: его командная строка, результат и одна строка на каждый запрос к Telegram. Эти строки никогда не содержат текст сообщения, имена или заголовки. Что сохраняется из введённой командной строки, описано в разделе [Что вы ввели](#what-you-typed).
- **`tg personal doctor`** проверяет установку: версию, логин, настройки и локальный архив.
- **Отчет о проблеме** – это один файл JSON, созданный на основе `tg personal doctor`, и неудачный запуск. Вы прикрепляете его к проблеме.

## Что можно сделать [#что-можно-сделать]

| Задача | Команда | Сохраняет что-нибудь? |
|---|---|---|
| Просматривайте каждый запрос в реальном времени | `tg personal --trace …` | нет, печатает только в stderr |
| Найти запуск позже | `tg personal runs list` | каждый запуск сохраняется сам по себе |
| Не сохранять один запуск | `tg personal --no-record …` | ничего |
| Сохранять только неудачные запуски | `tg personal config set record false` | неудачные запуски |
| Проверьте установку | `tg personal doctor`, `tg personal doctor --online` | нет |
| Сообщить о проблеме | `tg personal doctor reports create` | да, один файл вы отправите |

## Показать операции: `--trace` [#показать-операции---trace]

```sh
tg personal --trace messages list "Book club" --limit 5
```

`--trace` выводит операции в stderr по мере выполнения: `→` — запрос, `←` — ответ. Указываются идентификаторы, количество объектов, длительность и код ошибки, если она возникла.

```text
→ messages.list    chat -1001234567890
← messages.list    chat -1001234567890  118ms  5 messages
```

Он также передает строки журнала библиотеки Telegram внизу. stdout не меняется, поэтому канал по-прежнему получает только данные.

## Сохранить запуск: `--record` [#сохранить-запуск---record]

Каждый запуск сохраняется сам по себе. `--record` нужен только командам, которые работают, пока вы их не остановите (`watch`, `serve`,
`mcp serve`), и командам, которые WireCat Desktop запускает для себя: удачный запуск они сохраняют только с `--record`.

```sh
tg personal runs list        # recorded runs, newest first
tg personal runs show <run-id>  # one run: its outcome, and one line per request
tg personal runs path <run-id>  # the folder that holds it
```

`runs show` перечисляет каждый запрос к Telegram: его метод (`messages.getHistory` или `sendMessage` в Bot API), сколько он занял и чем закончился. Когда Telegram просит подождать (`FLOOD_WAIT` или `429` в Bot API), а `tg` ждёт и пробует снова, за отклонённым запросом идёт повтор как попытка 2 с временем ожидания. Запуск хранит не больше 2000 таких строк или 1 МБ, а остальные только считает.

Запись запуска — это папка под `runs/<day>/` в папке состояния (`~/.local/share/tg-cli/runs/` в Linux). Её имя — время и команда. Она содержит два файла:

- `run.json` — команда, профиль, версии `tg`, Node и системы, время начала и завершения, количество запросов, результат и код ошибки;
- `events.jsonl` — операции, которые показывает `--trace`, и каждый запрос под ними, по одной на строку.

Удачный запуск без запросов не оставляет папки: это одна строка в индексе дня, и `runs show` всё равно его находит.

## Неудачные запуски сохраняются автоматически [#неудачные-запуски-сохраняются-автоматически]

Если команда завершается ошибкой, её запуск сохраняется, даже если `record` установлен в `false`; тогда в `run.json` есть `"kept_because_failed": true`. Это справедливо для каждой команды и каждой ошибки: плохой параметр, неизвестная команда, проверка перед любой работой и команды, которые никогда не подключаются (`models`, `server`, `upgrade`). Сбой до запуска команды, например файл конфигурации, который не загружается, сохраняется как запуск с именем `tg`. Что запись хранит из командной строки, описано в разделе [Что вы ввели](#what-you-typed); в запуске, настройки которого не загрузились, скрыто каждое введённое значение, которое может быть текстом.

Поэтому к отчёту о проблеме всегда можно приложить неудачный запуск. Не сохранить неудачный запуск можно только с `--no-record`.

Успешные поисковые и статистические запросы сохраняют свою собственную историю, помимо записей о запусках. У неё свои настройки: см. [сохраненные поисковые запросы и историю](/llms.mdx/docs/ru/tg/search/content.md#saved-searches-and-history).

## Как сохранять только неудачные запуски [#как-сохранять-только-неудачные-запуски]

```sh
tg personal config set record false         # profile "personal": failed runs only
tg personal --no-record chats list          # this run: nothing at all
```

Удачный запуск хранит идентификаторы чатов, которые вы читали, а при включённом `record_input` — то, что вы ввели (отправленное сообщение, чат, названный по заголовку). Он хранится только на этом компьютере, доступен для чтения только вам и живёт 7 дней. Установите `record` в `false`, если не хотите хранить его вовсе.

## Срок хранения [#срок-хранения]

Удачный запуск хранится **7 дней** (`keep_successful_runs_for_days`), неудачный — **30 дней** (`keep_runs_for_days`). Папка запусков также остаётся меньше **200 МБ** (`runs_size_limit_mb`): сверх этого первыми удаляются самые старые удачные запуски. Старые записи удаляются только при сохранении новой, проверка идёт раз в день, целыми днями, по имени папки, без чтения файлов.

## Что не попадает в записи [#что-не-попадает-в-записи]

События запуска и `--trace` содержат имя операции, идентификаторы, количество, продолжительность и коды ошибок. Они никогда не несут:

- текст сообщения или подпись;
- название чата, имя человека или имя пользователя;
- номер телефона, код входа, пароль 2FA, сессию или хеш приложения.

### Что вы ввели [#что-вы-ввели]

`run.json` также хранит командную строку. Что именно сохраняется, зависит от вашей версии `tg`:

- **Версия, у которой `record_input` есть в выводе `tg personal config show`**, хранит командную строку так, как вы её
  ввели, — название чата, поисковый запрос, текст сообщения, — чтобы можно было посмотреть, что вы запускали. Секрет
  всегда заменяется на `[redacted]`: значение параметра, названного по токену, паролю, парольной фразе, секрету, учётным данным,
  cookie, авторизации или ключу API; значение, которое `tg` помечает как секрет, например `bot api --body`; пароль внутри URL;
  длинная строка, похожая на токен. Чтобы снова скрывать каждое введённое значение, которое может быть текстом:

  ```sh
  tg personal config set record_input false     # everywhere
  tg personal config set record_input failed    # kept only in a run that failed
  ```

- **Более старая версия** хранит слова команды и имена параметров, например `messages list --limit`.
  Каждое значение, которое может быть текстом, например введённое вместо `<chat>`, заменяется на `[redacted]`.

Отчёт о проблеме, составленный по записи запуска, скрывает эти введённые значения в любой версии.

## Проверить установку: `tg personal doctor` [#проверить-установку-tg-personal-doctor]

```sh
tg personal doctor     # connects to nothing
tg personal doctor --online  # also connects once and reads the account; sends nothing to Telegram
```

Команда показывает версию, среду выполнения, профиль, файл конфигурации, наличие сессии и данных приложения (без значений), изменение записи хранилища ключей через `TG_*_DIR`, локальную базу (путь, версию, количество чатов и сообщений), отправки за последний час и сохранённые запуски.

- **`config.issues`** перечисляет все проблемы файла настроек: некорректный JSON (со строкой и столбцом, где чтение
  остановилось), настройку или ключ разрешения, которых `tg` не знает, значение неправильного типа. Каждая проблема
  говорит, каким должно быть значение, но никогда не показывает само значение. Все, кроме некорректного JSON,
  приходят с командой `config unset`, которая их убирает (`fix`). `doctor` всё равно отвечает, с кодом выхода `0`.
- **`login`** — это `not checked` без `--online`. Наличие файла сессии на диске не означает, что Telegram все еще его принимает. При `--online` это `ok` или `failed` с подсказкой.
- **`files`** и **`telegram.session.files`** называют каждый личный файл или папку, которые могут читать другие пользователи этого компьютера: файл настроек (ему нужен `0600`) и его папка (`0700`), сессия, хранилище, их файлы SQLite `-wal` и `-shm`, журнал отправки и папка запусков. Каждая проблема — это `{ path, mode, want }`, а в stderr печатается исправляющая её команда `chmod`: `to make it private: chmod 600
  '<path>'`. Если профиль не назван или настройки отклонены, `files` проверяет только файл настроек и его папку. `doctor` сам никогда не меняет режим файла. В Windows Unix-права доступа не проверяются.
- **`online.clock`** (с `--online`) сравнивает часы этого компьютера с часами Telegram.   `skew_ms` положителен, когда этот компьютер впереди. Он предупреждает (`ok: false`) через 10 секунд. Telegram отклоняет запрос, который опережает собственные часы более чем на 30 секунд.
- **`online.standing`** (с `--online`) — это `active`, `frozen`, `banned`, `deactivated` или `revoked` или `unknown`, когда ответ Telegram не может быть определен. Замороженный аккаунт может читать, но не писать. Там, где Telegram их предоставляет, указывается дата, когда аккаунт был заморожен, дата, когда Telegram его удалит, и ссылка на апелляцию. Повторный вход не восстанавливает аккаунт, закрытый Telegram.
- **`flood`** перечисляет ожидания, которые Telegram попросил сохранить в этом профиле (`deadlines`) и задержать отправку (`send_block`). `doctor` только читает, за одним исключением: **`doctor --online` записывает блокировку отправки для замороженного аккаунта.** Когда он считывает аккаунт как замороженный, он удерживает отправку до даты Telegram. Когда он считает его активным, он снимает удержание. Он никогда не снимает ограничение на спам — `tg personal flood clear` делает это.

## Отчёт об ошибке [#отчёт-об-ошибке]

```sh
tg personal doctor reports create          # about the newest failed run
tg personal doctor reports create --run <run-id>  # about this one
```

Он записывает файл JSON — то, что показывает `tg personal doctor` плюс запуск — и говорит, куда его отправить: новая задача на [github.com/WireCatLabs/tg-cli/issues](https://github.com/WireCatLabs/tg-cli/issues/new). Прочтите его, прежде чем отправить. Он не содержит текста сообщения, и каждый идентификатор отображается в виде метки, а не номера Telegram. [Как сообщить о проблеме](/llms.mdx/docs/ru/tg/troubleshooting/content.md#report-a-problem) перечисляет все, что содержится в файле.

Если записи неудачного запуска нет, повторите проблемную команду: ошибка сохранится автоматически.

## Анализ записей [#анализ-записей]

Записи имеют формат JSON, поэтому их можно анализировать через `jq`. `tg personal runs list --json` возвращает `{ items, page: { limit, has_more }, meta }`, где `items` — содержимое `run.json` для каждого запуска, от новых к старым:

```sh
tg personal runs list --limit 100 --json | jq '[.items[] | select(.status == "failed") | {command, error_code}]'
tg personal runs list --limit 100 --json | jq '[.items[] | .duration_ms] | add / length'  # average duration
tg personal runs list --limit 100 --json | jq '[.items[] | select(.requests > 10) | {command, requests}]'
```

`tg personal runs show <run-id>` выводит те же события таблицей без повторяющихся полей. Полный файл находится в каталоге, который показывает `tg personal runs path <run-id>`.

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

- [Что означает ошибка и что делать](/llms.mdx/docs/ru/tg/troubleshooting/content.md)
- [Что вообще доходит до диска](/llms.mdx/docs/ru/tg/security/content.md)

## Найти ошибку или частичный запуск [#найти-ошибку-или-частичный-запуск]

```sh
tg personal search runs error_code:rate_limited --json
tg personal search runs status:partial 'started_at>=2026-10-01' --json
```

`search runs` ищет буквальный текст в метаданных и безопасных диагностических событиях.
Термы `status:`, `error_code:`, `operation:`, `profile:` и сравнения или диапазоны `started_at:`, а также параметры `--limit` и `--page` уточняют поиск. Одна страница — до 100
запусков; в запуске возвращается до 100 совпавших событий, `events_truncated` сообщает о сокращении.
Ошибка отдельного файла или страницы истории создаёт частичную запись `status: "partial"` с
неудачными ID, этапами и кодами. Текст сообщений и текст отказа сервера в неё не копируются.
Запись сохраняется по умолчанию, если её явно не выключили. Поиск сам не создаёт новый запуск.

В MCP вызовите `tg_read` с `command: "search runs"`; поля `arguments`: `query` (включая условия по времени), `limit`, `page`. Он читает только записи активного профиля, не подключается к Telegram и не открывает сырые
журналы фоновых заданий. Полный результат частичной команды содержит действия для восстановления;
диагностическая запись сохраняет только безопасные идентификаторы и коды.
