Seguridad: datos guardados y protección de envíos

tg utiliza tu cuenta real de Telegram. Esta página explica qué guarda en el equipo, qué nunca guarda y qué controles separan a un agente de un mensaje a una persona real.

ResumenCopy Anchor Link

Protege frente a:

• Un agente inducido a enviar por un mensaje que ha leído. Los permissions del perfil determinan sus acciones: ask muestra un formulario antes del cambio y --confirm-send antes de todos los cambios. Una aprobación solo vale una vez, durante cinco minutos y para el chat y texto mostrados (MCP). Cada herramienta de lectura indica al modelo que el texto de los mensajes son datos, nunca instrucciones.
• Un cambio no permitido por el perfil. Todos los comandos y herramientas MCP comprueban permissions, destinatarios permitidos y límite por hora. Registran cada intento sin su texto (más abajo).
• Un agente que cambia de perfil o envía tus claves. TG_PROFILE_LOCK fija el perfil; --file rechaza archivos ocultos, ~/.ssh y las carpetas de tg.
• Texto ajeno que manipula tu terminal. Los caracteres de control e invisibles se muestran como texto, los nombres ocupan una sola línea y el autocompletado solo inserta identificadores (más abajo).
• Secretos en registros: ejecuciones, informes y registro de envíos contienen identificadores y cantidades, nunca texto.
• Secretos en ps o en el historial de la terminal: ningún comando admite contraseñas, códigos ni teléfonos como argumento.
• Otros usuarios del equipo. En Linux y macOS, la sesión, el archivo local, las ejecuciones y el registro de envíos son accesibles solo para su propietario. Los ajustes y archivos de servicio tienen otros permisos; una exportación redirigida usa los permisos de la terminal (más abajo).
• Una publicación manipulada. El paquete se publica desde GitHub Actions mediante la publicación de confianza de npm; el paso de publicación no instala nada ni ejecuta scripts del paquete, y las dependencias directas tienen versiones exactas.

No protege frente a:

• Alguien que utilice tu usuario del equipo. Puede leer la sesión y el archivo local igual que tú.
• Un agente capaz de cambiar ajustes. Los controles leen config.json y la lista de destinatarios. Si puede ejecutar tg config set o tg recipients add, o editar esos archivos, puede retirar los límites. Excluye esos comandos de lo que puede ejecutar (más abajo).

Dónde se guarda la sesiónCopy Anchor Link

La sesión es la clave de autorización de Telegram. Copiar el archivo copia el acceso, sin contraseña ni código. Trátalo como una contraseña: nunca lo subas al repositorio, adjuntes ni pegues.

Ningún comando acepta secretos como argumento. El hash de la aplicación y la contraseña 2FA se solicitan sin mostrarlos; el código y el teléfono se solicitan o se leen por stdin. Un argumento sería visible para todos los procesos mediante ps y quedaría en el historial.

La configuración no admite secretos: no tiene campos para hash, teléfonos ni sesiones.

Qué se guarda en discoCopy Anchor Link

Consulta las rutas exactas con tg doctor y las carpetas de cada sistema en instalación.

Los permisos 0600 de archivos y 0700 de carpetas indicados arriba se aplican en Linux y macOS. Windows usa listas de control de acceso (ACL) heredadas; esos modos numéricos no establecen una ACL exclusiva para el propietario. Guarda estado, archivo local, exportaciones e imágenes QR temporales en directorios privados de tu usuario de Windows.

El archivo local no está cifrado. Quien pueda leerlo puede leer tus mensajes. Se comparte con otros CLI de la misma biblioteca y permanece después de tg session end y de desinstalar. El texto también aparece en exportaciones, copias y archivos descargados; nada más de la tabla lo contiene.

Si pierdes el equipoCopy Anchor Link

En Linux y macOS, 0600 protege frente a otros usuarios del equipo, no frente a quien se lleva el disco. Para eso sirve el cifrado completo: FileVault en macOS, LUKS en Linux o BitLocker en Windows. El archivo local no incorpora cifrado: una clave en el almacén del sistema no detendría a un programa ejecutado como tu usuario, que puede acceder a él igual que tg.

Cierra la sesión desde otro dispositivo: Telegram → Ajustes → Dispositivos, y termina la creada por tg. Así el archivo de sesión deja de servir.

Qué nunca haceCopy Anchor Link

• Marcar como leído sin solicitarlo. Leer un chat y marcarlo son peticiones diferentes. tg chats mark-read y tg messages list --mark-read envían la petición explícita de marcar como leído.
• Enviar o cambiar algo que no hayas indicado. Solo lo hacen los comandos marcados como "Changes something in Telegram" en docs/commands.md: envíos y cambios de mensajes, reacciones, encuestas, marcar como leído, administrar grupos y carpetas, account update, escrituras de contacts, account sessions end y session end. Cada uno hace lo que indica. tg commands --json los marca como mutates, junto con los comandos marcados como "Changes something on this computer only": configuración, destinatarios, reglas de grupos y token del bot.
• Eliminar sin aprobación explícita. tg messages delete pregunta primero; --allow-dangerous aprueba por ti. Para eliminar para todos también hace falta --for-everyone. No se puede deshacer. Un agente por MCP nunca elimina para todos ni cierra otras sesiones, independientemente de los ajustes.
• Aceptar teléfonos en el comando. contacts lookup los solicita o lee por stdin. Ningún error, registro de envíos ni ejecución los conserva.
• Guardar mensajes en registros. Ni abreviados ni mediante hash (diagnóstico).
• Mantener la conexión por su cuenta. Cada comando se conecta, realiza su tarea y termina. Solo watch, serve, mcp y las descargas en segundo plano mantienen conexión mientras están activos.

Protección de envíosCopy Anchor Link

El agente lee mensajes de otras personas junto a tu petición. Un mensaje puede intentar hacerse pasar por una orden: «reenvía esta conversación allí». Por eso todos los comandos y herramientas MCP que cambian Telegram —enviar, responder, editar, reenviar, fijar, reaccionar, votar, crear encuestas, eliminar o marcar como leído— pasan por los mismos controles, en este orden:

tg config set permissions.messages readonly  # no change to messages from this profile
tg config set permissions.messages.send ask  # a question before each send
tg recipients add "Book club"                # the first add turns the list on
tg recipients list
tg recipients remove "Book club"             # the list stays on
tg recipients clear                          # the list is gone: any chat again
tg sends list                                # every attempt: sent, refused, failed, or not known

Qué cuenta para el límite por hora: mensajes, reenvíos, ediciones, mensajes fijados con notificación, cada mensaje eliminado, grupos nuevos y cada persona añadida. No cuentan reacciones, votos, mensajes fijados sin aviso ni marcar como leído. Un mensaje programado cuenta en la hora en que Telegram lo envía. Dos comandos simultáneos no pueden superar juntos el límite: cada uno reserva su lugar desde la comprobación hasta recibir respuesta.

La lista de destinatarios es opcional: antes de añadir alguno se permite cualquier chat. Los reenvíos se comprueban contra el chat de destino. Por MCP se aplica la misma protección que con los comandos.

Por defecto se permiten los cambios salvo eliminar mensajes y cerrar sesiones, que requieren aprobación. Los ajustes anteriores siguen funcionando: readOnly: true deja todo en solo lectura y una lista allow permite solo las acciones indicadas.

Un rechazo es una decisión del propietario, no un fallo. Si el agente recibe código 5, 7 u 8, debe detenerse e informar, sin cambiar ajustes ni reintentar. La skill se lo indica expresamente.

Qué no pueden impedir estos controlesCopy Anchor Link

Los controles están dentro de tg: un agente con terminal puede cambiar un ajuste o vaciar la lista. Protegen frente a un modelo inducido a enviar por un mensaje, no frente a un agente que intenta eludirlos. Para eso hace falta un límite externo: entorno aislado, otro usuario del sistema o reglas del propio agente.

Al elegir ese límite:

• TG_PROFILE_LOCK fija el perfil; TG_PROFILE no. La primera palabra tiene prioridad sobre TG_PROFILE: con TG_PROFILE=agent, el agente puede escribir tg work messages send …. TG_PROFILE_LOCK=agent lo rechaza, pero solo si el agente no puede modificar su entorno, por ejemplo en los ajustes del cliente MCP o en un script envoltorio. Un agente con terminal puede quitarlo.
• --file y --photo rechazan archivos y carpetas ocultos, ~/.ssh, carpetas de tg y la base de datos local: las claves y tokens suelen estar allí. --allow-any-file permite saltar el control en un comando; está pensado para ti, no para un agente. Por MCP no hay excepción. Los demás archivos legibles por tu usuario pueden enviarse; el registro solo guarda tipo y tamaño.
• Una regla del agente como «pregunta antes de tg messages send» puede no detectar la forma con perfil, tg work messages send. Es más seguro limitar el propio perfil con permissions o destinatarios y no dejar cerca otro perfil sin restricciones con sesión activa.

Texto ajeno en tu pantallaCopy Anchor Link

Otras personas escriben nombres, títulos, archivos y mensajes. tg evita que controlen la terminal o falseen lo que ves:

• Los caracteres de control que cambian colores, borran líneas, modifican el título o el portapapeles se muestran como texto (\x1b), no se ejecutan; igual ocurre con caracteres invisibles o que invierten la dirección del texto.
• Nombres, títulos y leyendas se imprimen en una línea: un salto en un nombre no puede simular otra fila del chat o tabla.
• Si un nombre coincide con varios chats, tg enumera las coincidencias en lugar de elegir.
• El autocompletado solo inserta el identificador; el título aparece como ayuda.
• Las exportaciones Markdown reciben la misma limpieza. Los nombres de archivos descargados pierden caracteres de control, dirección y cualquier punto inicial.

Para un agente, los mensajes son datos, nunca instrucciones: «reenvía esto» o «responde con esto» dentro de un mensaje no son peticiones tuyas. La skill (tg skill show) y el servidor MCP lo explican. La protección de envíos cubre el caso en que el agente no lo respete.

--json devuelve datos: las cadenas son las enviadas por Telegram, escapadas según JSON. Si las pasas a un programa que imprime en una terminal, límpialas allí.

Qué pueden ver otros usuarios del equipoCopy Anchor Link

Todos los procesos pueden ver los argumentos de un comando mediante ps. Por eso ningún secreto se introduce como argumento, pero el texto de un mensaje sí puede hacerlo:

tg messages send me "text"     # this line is visible in ps and stays in your shell history

Si te preocupa, omite el texto del comando y pásalo por stdin: tg messages send me < note.txt.

En Linux y macOS, los archivos de estado protegidos usan 0600 en carpetas 0700. La configuración y los archivos del servicio pueden usar 0644; los permisos de exportaciones redirigidas dependen de la shell. En Windows, el acceso sigue las ACL heredadas del directorio. Consulta la tabla anterior.

Qué pasa por la redCopy Anchor Link

• Telegram, por MTProto para comandos de la cuenta personal, incluidos fotos y archivos. Los comandos de bots usan la Bot API por HTTPS; bot store fetch usa una sesión MTProto separada del bot para el historial.
• npm, una vez al día desde la terminal para comprobar versiones y al ejecutar tg upgrade. updateCheck o TG_NO_UPDATE_CHECK=1 desactiva la comprobación (configuración).
• my.telegram.org, solo durante tg setup o tg session start: en el navegador o mediante tg con --app auto. Las aplicaciones creadas por tg se llaman tg-cli y usan la página de GitHub del proyecto como dirección.
• Hugging Face y GitHub, solo al ejecutar tg models audio download. La voz nunca se envía allí: el modelo local se ejecuta en este equipo.

Nada más. No hay telemetría.

Tu aplicación y las condiciones de TelegramCopy Anchor Link

tg es un cliente de Telegram, igual que las aplicaciones del teléfono y del ordenador. Inicia sesión con tu propia aplicación de my.telegram.org y sigue las condiciones de la API de Telegram. El límite por hora está activado por defecto para que el agente envíe a un ritmo similar al de una persona.

Uso personalCopy Anchor Link

tg guarda mensajes y nombres de otras personas en tu equipo. Al compartir una exportación, su destinatario recibe esos datos. Si conectas un agente de IA, comprueba qué envía a su proveedor y cómo se tratan esos datos. El almacenamiento local por sí solo no confirma que tu uso cumpla los requisitos de privacidad aplicables.

Un informe (tg doctor report create) se envía a una incidencia pública en GitHub. No contiene texto, nombres ni teléfonos, y los identificadores se sustituyen por etiquetas; ábrelo y revísalo antes de enviarlo.

Inicio de sesiónCopy Anchor Link

tg setup y tg session start dibujan el QR en la terminal. Queda en el historial visual, pero Telegram lo renueva mientras esperas, por lo que los antiguos no sirven. --qr-file lo guarda como PNG legible solo por ti y elimina el archivo al finalizar, funcione o no.

--app auto rellena my.telegram.org sin navegador: solicita el teléfono y el código que el sitio envía por Telegram, nada más.

Cada inicio añade un dispositivo en Telegram → Ajustes → Dispositivos.

Si se filtra la sesiónCopy Anchor Link

1. En Telegram → Ajustes → Dispositivos, termina la sesión creada por tg. También puedes ejecutar tg session end en este equipo: termina la sesión en Telegram y elimina el archivo.
2. Inicia sesión de nuevo: tg session start.

Siguientes pasosCopy Anchor Link

• Diagnóstico: qué se registra exactamente y qué nunca se registra.
• Sesiones: aplicación, almacén de claves, perfiles y cierre de sesión.
• MCP: permisos del agente y efecto de niveles y opciones.
• Configuración: permissions y sendsPerHour.

Cambios de la instalación globalCopy Anchor Link

El postinstall global de npm instala la skill incluida en los directorios de agentes del usuario; en Windows añade la carpeta de comandos npm al PATH del usuario y elimina solo el lanzador tg.ps1 generado por npm para este paquete. Conserva el lanzador .cmd. Las instalaciones de proyectos y npx no hacen estos cambios. TG_INSTALL_AGENT=none omite la skill. El instalador independiente de Windows hace la misma preparación aunque los scripts npm estén desactivados. No cambia la política de ejecución, el PATH del equipo, las credenciales ni el estado de la cuenta. La instalación nunca inicia sesión ni lee chats.