# Inicio de sesión y perfiles de la CLI de Telegram (/es/docs/tg/sessions)

Conecta la herramienta a tu cuenta para que el agente pueda leer los chats que elijas y ayudarte a responder. Esta guía explica el acceso, su comprobación y cómo gestionar o cerrar una sesión. Iniciar sesión añade un dispositivo autorizado; no descarga todo el historial.

Lea esta página cuando conecte `tg` a su cuenta de Telegram por primera vez, cuando agregue una segunda cuenta o cuando `tg` diga que no ha iniciado sesión. Al final, sabrá cómo iniciar sesión, cómo verificar con quién inició sesión, cómo cerrar sesión y dónde guarda `tg` lo que necesita para permanecer conectado.

Primero, las palabras que utiliza esta página:

- **Sesión**: el inicio de sesión de `tg` en esta computadora. Telegram lo emite cuando inicias sesión y lo incluye en la aplicación Telegram como un dispositivo más. `tg` lo guarda en un archivo. Quien tenga ese archivo puede leer tus chats, así que trátalo como tu contraseña.
- **App** (`api_id` y `api_hash`): dos valores de [my.telegram.org](https://my.telegram.org/apps) que identifican el programa ante Telegram. Cada usuario registra su propia aplicación una vez; `tg` puede hacerlo por usted.
- **Llavero**: el almacén de contraseñas de tu sistema operativo. `tg` mantiene los valores de la aplicación allí.
- **Perfil**: un nombre para un inicio de sesión en esta computadora, con su propia sesión, aplicación y configuración. Todo comando que usa una cuenta lo nombra, así que eliges un nombre durante la configuración (`tg personal setup`) y lo usas desde entonces ([perfiles](#profiles)).

No confunda `tg personal session` con `tg personal account sessions`. `tg personal session` es el inicio de sesión del propio `tg`; `tg personal account sessions` enumera todos los demás dispositivos y aplicaciones que hayan iniciado sesión en su cuenta.

## Primera ejecución [#primera-ejecución]

`tg personal setup` guía una primera ejecución a través de la aplicación y la sesión, verifica cinco chats y ofrece una skill de agente. Espere unos cinco minutos; Las descargas del historial son un paso aparte. Ejecútelo en una terminal. Utilice `tg personal setup --app browser` para el registro manual de la aplicación o `--method phone` para iniciar sesión por teléfono. `tg personal session start` sigue siendo el comando para iniciar sesión únicamente, incluida la reanudación de un inicio de sesión interrumpido. El programa de instalación comprueba una sesión existente y no vuelve a iniciar sesión silenciosamente si se rechaza.

## La aplicación de my.telegram.org [#la-aplicación-de-mytelegramorg]

> **Ver la pantalla de acceso de my.telegram.org**
>
> ![Pantalla oficial de my.telegram.org con el campo del teléfono vacío.](/telegram-app-login.png)
>
> Este es el acceso al sitio para obtener las credenciales de aplicación de Telegram. El código llega por Telegram, no por SMS. Tras entrar, elige **API development tools**. La autorización del CLI por QR viene después. [my.telegram.org](https://my.telegram.org/apps)

Cada usuario registra su propia aplicación. Telegram proporciona una aplicación por número de teléfono; por eso `tg` no incluye ni comparte un identificador de aplicación. Se necesita una vez por perfil; `tg personal session start` solo lo pide si el perfil todavía no tiene uno.

Hay dos formas de obtenerlo:

- **`--app
browser`** abre [my.telegram.org/apps](https://my.telegram.org/apps). Inicie sesión allí, cree una aplicación si no tiene ninguna (cualquier título y nombre corto, plataforma de escritorio) y pegue `App api_id` y `App api_hash` cuando `tg` lo solicite. El hash no se muestra mientras escribe. Este es el valor predeterminado para `tg personal session start`.
- **`--app auto`** completa el sitio por usted. Le solicita su número de teléfono y el código que my.telegram.org le envía como mensaje en Telegram, luego lee su aplicación o crea una si no tiene ninguna. El sitio no tiene API, por lo que `tg` sigue su formulario web; un cambio por parte de Telegram puede romper esto. `--app browser` todavía funciona entonces. Este es el valor predeterminado para `tg setup`.

La aplicación solo se guarda después de que Telegram acepte el inicio de sesión.

### Crear la aplicación a mano [#crear-la-aplicación-a-mano]

Sigue estos pasos con `--app browser`, o cuando `--app auto` falle. Se hace una vez por cada cuenta de Telegram.

1. **Inicia sesión en [my.telegram.org](https://my.telegram.org/apps).** Elige tu país, escribe tu número de teléfono y pulsa **Next**.

   ![La página de inicio de sesión de my.telegram.org con los campos de país y número de teléfono](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-app-1-sign-in.png)

   Telegram envía un código de confirmación como mensaje en tu aplicación de Telegram, no por SMS. Escríbelo en la página y pulsa **Sign in**. No le des este código a nadie y nunca lo escribas en un chat con el agente.

   ![La página del código de confirmación de my.telegram.org](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-app-2-code.png)

2. **Abre Development Tools** y elige **Create new application**.

   ![La página principal de my.telegram.org con la tarjeta Development Tools](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-app-3-development-tools.png)

   Rellena el formulario. El título (title) necesita al menos 5 caracteres. El nombre corto (short name) solo admite letras y dígitos, de 5 a 32 caracteres. Evita la palabra "Telegram" en ambos. Elige una plataforma, por ejemplo **Desktop**. La URL y la descripción son opcionales. Después pulsa **Create application**.

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

3. **Copia `api_id` y `api_hash`** de la sección Credentials. Mantén el hash en privado: quien lo tenga puede usar la cuota de tu aplicación.

   ![La sección Credentials con App api_id y App api_hash](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-app-5-credentials.png)

4. **Da ambos valores a `tg`** cuando pida `App api_id` y `App api_hash`. El hash no se muestra mientras escribes.

El número de teléfono y los datos de la aplicación de estas capturas son ejemplos.

## Iniciar sesión [#iniciar-sesión]

```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:** escanea el código en la aplicación Telegram, como describe la sección siguiente. El código se renueva mientras esperas.

**Teléfono:** escriba el número en formato internacional, luego el código de inicio de sesión. Si la cuenta tiene una contraseña de nube (2FA), `tg` la solicita sin mostrar lo que escribe. Con `--app auto`, el número de teléfono se solicita solo una vez. El código suele llegar a la aplicación Telegram; `--sms` solicita un SMS en su lugar, pero Telegram elige y `tg` dice de qué manera se envió. Cuando Telegram no tiene SMS para la cuenta, `tg` lo dice y pide el código desde la app.

Después de cualquiera de los dos, Telegram incluye un nuevo dispositivo en la lista de sesiones de la aplicación.

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

### Cuando un agente inicia la sesión [#cuando-un-agente-inicia-la-sesión]

Su agente de IA puede iniciar el inicio de sesión por usted. Sin terminal, `tg` imprime el código QR como texto plano y el agente lo pega en el chat para que lo escanee:

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

El agente lo ejecuta en segundo plano, porque el comando espera el escaneo y una herramienta de shell no muestra nada hasta que el comando termina. Lee la salida y pega el bloque QR en el chat como bloque de código, tal como se imprimió. Cuando Telegram renueva el código, se imprime un bloque nuevo: el agente lo pega y dice que el anterior caducó. Con `--json`, cada código también es una línea en stderr, `{"event":"qr","qr":{"text":…,"expires_at":…,"scan":…}}`. Una vez escaneado el código, tg dice `scan accepted, finishing sign-in`, y con `--json`, `{"event":"progress","step":"scanned","message":…}`: Telegram puede tardar diez segundos o más en terminar.

El código está dibujado para un tema de terminal oscuro. Sin terminal, esto funciona sólo cuando el perfil ya tiene su aplicación y la cuenta no tiene contraseña 2FA: cualquier otra cosa tienes que escribirla tú mismo. Un programa que muestra las preguntas en su propia ventana, como WireCat Desktop, ejecuta `tg personal session start phone --json --answer-stdin`: cada pregunta es una línea `needs` en stderr y se responde con una línea en stdin. `tg personal setup` funciona igual. El inicio de sesión no se ofrece como herramienta MCP: un agente que solo tiene MCP le pide que ejecute el comando, o lo ejecuta desde su shell.

### Vincular un dispositivo con un código QR [#vincular-un-dispositivo-con-un-código-qr]

Telegram llama a esto vincular un dispositivo de escritorio. `tg` muestra un código QR en el terminal y lo escaneas con la aplicación de Telegram en tu teléfono. Usa el escáner del propio Telegram, no la aplicación de cámara.

#### Android [#android]

1. Abre Telegram y ve a **Ajustes** y después a **Dispositivos**.
2. Pulsa el botón para añadir un dispositivo (Add Device) y permite el acceso a la cámara si Telegram lo pide.
3. Apunta la cámara al código QR de tu terminal.

![Telegram para Android, Ajustes y Dispositivos, con el botón para añadir un dispositivo](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-android-add-device.png)

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

1. Abre Telegram y ve a **Ajustes** y después a **Dispositivos**.
2. Pulsa el botón para vincular un dispositivo de escritorio (Link Desktop Device) y permite el acceso a la cámara si Telegram lo pide.
3. Apunta la cámara al código QR de tu terminal.

Si tu cuenta tiene una contraseña de verificación en dos pasos (2FA), `tg` la pide después del escaneo. El terminal no muestra lo que escribes.

**Intentos de inicio de sesión incompletos.** Si escaneaste el código pero no introdujiste la contraseña 2FA, el intento aparece en **Dispositivos**, en la lista de intentos incompletos (Incomplete login attempts). No tiene acceso a tus mensajes. Termina el inicio de sesión en `tg` o cierra el intento en esa misma lista.

![La lista de intentos de inicio de sesión incompletos en la pantalla Dispositivos de Telegram](https://raw.githubusercontent.com/WireCatLabs/tg-cli/v0.123.0/docs/images/telegram-android-incomplete-login.png)

## Comprobar la cuenta y cerrar sesión [#comprobar-la-cuenta-y-cerrar-sesión]

```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` también cierra la sesión **en Telegram**: el dispositivo desaparece de la lista de la aplicación. No elimina el identificador ni el hash de la aplicación del llavero y deja intacto el archivo local.

Para olvidar un perfil por completo, usa `tg personal account remove --keep-data` o `--delete-data`. Cierra la sesión de la misma forma y luego elimina el identificador y el hash de la aplicación del perfil, la contraseña de su proxy, las sesiones de historial de sus bots y lo que cli-core guarda para él. Con `--keep-data` sus mensajes siguen en el almacén y se pueden buscar. Con `--delete-data` se eliminan. El token de un perfil de bot con el mismo nombre se conserva: un bot es una cuenta aparte.

## Cuánto dura una sesión [#cuánto-dura-una-sesión]

Hasta que finalice: por `tg personal session end`, desde la lista de dispositivos en una aplicación de Telegram, o por el propio Telegram una vez que la sesión no se haya utilizado durante más tiempo que el límite de sesiones inactivas de la cuenta (`authorization_ttl_days` en [API de Telegram](https://core.telegram.org/method/account.setAuthorizationTTL)), que las aplicaciones te permiten configurar en la lista de dispositivos. Un perfil que se ejecuta todos los días nunca llega a él. Cuando finaliza una sesión, cada comando responde "no inició sesión o la sesión finalizó" con el código de salida `4`; inicie sesión nuevamente con `tg personal session start` ([qué hacer cuando finalizó la sesión](/llms.mdx/docs/es/tg/troubleshooting/content.md#not-logged-in-or-the-session-was-ended--run-tg-session-start)).

## Perfiles [#perfiles]

Un perfil es una conexión con nombre a una cuenta Telegram en el CLI. Normalmente usas uno por número: `personal` para la cuenta personal y `work` para la cuenta laboral. Cada conexión tiene su sesión, credenciales de aplicación, ajustes, destinatarios permitidos y ejecuciones.

`work` es una etiqueta que eliges, no un número. Conecta la cuenta laboral con:

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

Usa el número laboral para registrar credenciales; para el QR, cambia Telegram del teléfono a la cuenta laboral. Comprueba después qué cuenta corresponde a la etiqueta:

```sh
tg work account show
```

Puedes conectar la misma cuenta en varios perfiles; un perfil no crea una cuenta Telegram. Su nombre es **la primera palabra después de `tg`**, antes del comando:

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

**La primera palabra es el perfil si no es un comando.** Por eso un perfil no puede llamarse `chats`, `messages` ni usar otra palabra de comando; `tg personal session start` rechaza esos nombres. Los nombres admiten letras, cifras, puntos, guiones y guiones bajos, y deben empezar por una letra o cifra.

El orden de prioridad, de mayor a menor, es: primera palabra, luego `TG_PROFILE`. Si no hay ninguno, un comando que usa una cuenta se detiene con el código de salida `2` y muestra la lista de perfiles de esta computadora; si todavía no hay ninguno, indica que ejecutes `tg personal setup`. `tg` nunca elige uno, ni siquiera el único que hay. Los comandos que no usan ninguna cuenta funcionan sin perfil: `--help`, `--version`, `commands`, `skill show`, `account list` y `config show`.

Si una palabra no es un comando y no va seguida de ningún comando, se muestra este error:

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

**`TG_PROFILE_LOCK` limita un proceso a un perfil.** Defínelo en el entorno del agente: cualquier primera palabra o `TG_PROFILE` que indique otro perfil se rechazará (código de salida `5`). Sin él, un agente podría elegir un perfil con menos restricciones.

Para qué sirve cada perfil y cómo funciona un perfil con un bot: [perfiles y bots](/llms.mdx/docs/es/tg/profiles/content.md).

## Dónde se guarda cada parte [#dónde-se-guarda-cada-parte]

| Contenido | Ubicación |
|---|---|
| sesión | `sessions/<profile>.session` en el directorio de estado |
| identificador y hash de la aplicación | llavero del sistema, servicio `tg-cli`, entrada `<profile>:api` |
| identificador y hash sin llavero | `credentials.json` en el directorio de configuración |
| identificador y hash para CI | `TG_API_ID` y `TG_API_HASH`; tienen prioridad sobre el llavero |

Los directorios se enumeran en [dónde van los archivos](/llms.mdx/docs/es/tg/installation/content.md#where-files-go).

En equipos sin llavero (habitual en contenedores), la aplicación se guarda en `credentials.json`, junto a la configuración. `tg` lo avisa una vez por stderr.

> ⚠ **`TG_CONFIG_DIR`, `TG_STATE_DIR` y `TG_CACHE_DIR` también cambian la entrada del llavero.** Si alguna está definida, el nombre del servicio incluye el directorio de configuración. Una sesión creada sin ellas no es visible al definirlas, y viceversa. Úsalas siempre o nunca.

> ⚠ **En Linux, el llavero se accede a través de `XDG_RUNTIME_DIR`.** cron, ssh y algunos clientes MCP > inicia `tg` sin él, y cada comando dice que no se encontraron las credenciales de la aplicación "aunque ha iniciado sesión en esta máquina". **No volver a iniciar sesión**: eso agrega otro dispositivo y no arregla el entorno. Configure `XDG_RUNTIME_DIR` > ([credenciales de la aplicación no encontradas después de iniciar sesión](/llms.mdx/docs/es/tg/troubleshooting/content.md#no-telegram-app-credentials-found--although-it-has-logged-in-on-this-machine)).

## Siguiente paso [#siguiente-paso]

- [Lee tus primeros chats](/llms.mdx/docs/es/tg/usage/content.md)
- [Configuraciones y el orden en que se resuelven](/llms.mdx/docs/es/tg/configuration/content.md)
- [Lo que llega al disco, y lo que nunca llega](/llms.mdx/docs/es/tg/security/content.md)
