Inicio de sesión y perfiles de la CLI de Telegram
Inicia sesión en Telegram, gestiona perfiles y sesiones y resuelve problemas de autenticación desde tu ordenador.
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
tgen esta computadora. Telegram lo emite cuando inicias sesión y lo incluye en la aplicación Telegram como un dispositivo más.tglo guarda en un archivo. Quien tenga ese archivo puede leer tus chats, así que trátalo como tu contraseña. - App (
api_idyapi_hash): dos valores de my.telegram.org que identifican el programa ante Telegram. Cada usuario registra su propia aplicación una vez;tgpuede hacerlo por usted. - Llavero: el almacén de contraseñas de tu sistema operativo.
tgmantiene 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).
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
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
Ver la pantalla de acceso de my.telegram.org

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
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 browserabre 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 pegueApp api_idyApp api_hashcuandotglo solicite. El hash no se muestra mientras escribe. Este es el valor predeterminado paratg personal session start.--app autocompleta 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 quetgsigue su formulario web; un cambio por parte de Telegram puede romper esto.--app browsertodavía funciona entonces. Este es el valor predeterminado paratg setup.
La aplicación solo se guarda después de que Telegram acepte el inicio de sesión.
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.
-
Inicia sesión en my.telegram.org. Elige tu país, escribe tu número de teléfono y pulsa Next.

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.

-
Abre Development Tools y elige Create new application.

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.

-
Copia
api_idyapi_hashde la sección Credentials. Mantén el hash en privado: quien lo tenga puede usar la cuota de tu aplicación.
-
Da ambos valores a
tgcuando pidaApp api_idyApp 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
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 SMSQR: 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.
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 currentCuando 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:
tg personal session start qrEl 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
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
- Abre Telegram y ve a Ajustes y después a Dispositivos.
- Pulsa el botón para añadir un dispositivo (Add Device) y permite el acceso a la cámara si Telegram lo pide.
- Apunta la cámara al código QR de tu terminal.

iPhone y iPad
- Abre Telegram y ve a Ajustes y después a Dispositivos.
- 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.
- 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.

Comprobar la cuenta y cerrar sesión
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 heretg 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
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), 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).
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:
tg work session start --app browserUsa 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:
tg work account showPuedes 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:
tg personal chats list # profile "personal"
tg work chats list # profile "work"
export TG_PROFILE=work # the same for the whole shell sessionLa 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:
"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.
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.
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_DIRyTG_CACHE_DIRtambié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 > iniciatgsin é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. ConfigureXDG_RUNTIME_DIR> (credenciales de la aplicación no encontradas después de iniciar sesión).