# Instala la CLI y el servidor MCP de Telegram (/es/docs/tg/installation)

En esta página conectarás tu cuenta de Telegram a un agente de IA en tu ordenador. Después podrás pedirle que lea tus chats, busque mensajes y prepare respuestas. Necesitas unos cinco minutos y tu teléfono con la sesión de Telegram iniciada.

## Los pasos [#los-pasos]

1. [Instala tg](#install). tg es un pequeño programa que da a tu agente acceso a tu cuenta de Telegram. El agente puede instalarlo por ti, o puedes hacerlo a mano.
2. [Inicia sesión en Telegram](#log-in). Confirmas dos veces en el teléfono: primero con un código que registra tg en Telegram, luego escaneando un código QR. Así tu ordenador pasa a ser un dispositivo nuevo de tu cuenta.
3. [Conecta tu agente](#connect-agent). El agente recibe las instrucciones que necesita para usar tg.
4. [Comprueba que funciona](#check). El agente muestra tu cuenta y algunos chats.

Si un paso no funciona, consulta las [preguntas y respuestas](#questions).

## 1. Instala tg [#1-instala-tg]

Hay dos formas de instalarlo. El resultado es el mismo.

### Con tu agente [#con-tu-agente]

Usa un agente que pueda ejecutar programas en este ordenador, por ejemplo Claude Code, Codex, Cursor o Gemini CLI. Si solo usas un chat con el agente en el navegador o en el teléfono, sigue la guía [Conectar desde la web o el teléfono](/llms.mdx/docs/es/browser-apps/content.md).

Copia esta petición en el chat con tu agente. Te ayudará a instalar la herramienta e iniciar sesión en tu ordenador.

```text prompt
Ayúdame a conectar mi cuenta de Telegram a mi agente de IA en este ordenador.
Sigue https://wirecat.dev/es/docs/tg/installation: comprueba los programas necesarios y ayúdame a instalar la herramienta.
Muéstrame los pasos de inicio de sesión para que yo confirme el acceso a mi cuenta.
Conecta las instrucciones de la herramienta a mi agente. Al final muestra mi cuenta y algunos chats. No envíes mensajes.
```

El agente te guía por estos pasos:

1. **Revisa tu ordenador.** tg necesita Node.js 22.19 o posterior. Si falta, el agente te explica cómo instalarlo.
2. **Instala tg.** En este paso tu cuenta no se toca.
3. **Inicia el acceso.** El agente ejecuta `tg personal setup` en una ventana de terminal. Confirmas en el teléfono, como se explica en [Inicia sesión en Telegram](#log-in). Si el agente no puede mostrarte esa ventana, pega el código QR en el chat como texto: consulta [el agente no puede mostrarme el terminal](#q-agent-qr).
4. **Se conecta a tg.** El agente instala para sí las instrucciones de tg.
5. **Muestra el resultado.** Ves el nombre de tu cuenta y algunos chats. El agente no envía nada.

Tú confirmas el acceso, en tu teléfono. No pegues códigos ni contraseñas en el chat con el agente.

### A mano en un terminal [#a-mano-en-un-terminal]

Abre Terminal en macOS o Linux, o PowerShell en Windows.

1. **Instala Node.js 22.19 o posterior** (22.x o 24+), o Bun. Consulta [Node.js, npm y encontrar el comando](/llms.mdx/docs/es/installation/content.md#nodejs).
2. **Instala tg:**

   ```sh
   npm install -g @wirecat/tg-cli && tg skill install --for all
   ```

   npm puede informar de scripts de instalación bloqueados. El segundo comando instala las instrucciones del agente de forma explícita. Lee los avisos del gestor de paquetes y comprueba la versión en el paso siguiente. En Windows, abre otra terminal si no se encuentra `tg`.

   En Windows puedes usar un solo comando. Instala tg, lo añade a `PATH` (las carpetas donde el terminal busca comandos) y conecta todos los agentes compatibles:

   ```powershell
   & ([scriptblock]::Create((Invoke-RestMethod 'https://wirecat.dev/install.ps1'))) -Tool tg -Agent all
   ```

3. **Comprueba la instalación:**

   ```sh
   tg --version
   ```

   Verás un número de versión. Si el terminal dice que no encuentra el comando, consulta [tg no se encuentra después de instalarlo](#q-not-found).

4. **Inicia el acceso:**

   ```sh
   tg personal setup
   ```

   Continúa con el paso siguiente.

## 2. Inicia sesión en Telegram [#2-inicia-sesión-en-telegram]

El acceso añade tu ordenador como un dispositivo nuevo de tu cuenta de Telegram, igual que Telegram Desktop. Puedes ver ese dispositivo en Telegram en el teléfono y quitarlo cuando quieras. El acceso no descarga el historial de chats.

`tg personal setup` muestra el acceso. Lo inicia tu agente o lo ejecutas tú.

`personal` es el nombre de este acceso en tu ordenador, llamado perfil. Sirve cualquier nombre. Los comandos siguientes empiezan con el mismo nombre, por ejemplo `tg personal doctor`.

Telegram pide dos confirmaciones. Primero, tg registra para tu cuenta su propia aplicación de Telegram: dos valores, App api_id y App api_hash, que identifican el programa pero por sí solos no permiten leer mensajes. Después escaneas un código QR, y tg inicia sesión.

1. Cuando la configuración pida tu número de teléfono, introdúcelo con el prefijo del país, por ejemplo +34… . Esta primera confirmación permite a tg preparar los datos de conexión que Telegram requiere para tu cuenta.
2. Abre Telegram en el teléfono y busca el mensaje de servicio de Telegram con el código para my.telegram.org. Este código llega a Telegram, no por SMS. Introdúcelo cuando lo pida la configuración. tg obtiene los datos de conexión existentes o los crea por ti; no necesitas programar.

   ![Mensaje de Telegram con el código para acceder a my.telegram.org](/screenshots/telegram/code-message.jpg)

3. Después espera a que aparezca el código QR de inicio de sesión en el ordenador. Son dos confirmaciones distintas: el primer código prepara la conexión y el QR conecta tg a tu cuenta.
4. En Telegram en el teléfono, abre **Configuración → Dispositivos** y elige **Vincular dispositivo de escritorio** o **Vincular dispositivo**. Permite el acceso a la cámara si se solicita y apunta el escáner al QR que muestra la configuración en el ordenador. Usa el escáner de Telegram, no la cámara habitual del teléfono. ¿No lo encuentras? Mira los [pasos para iOS y Android](#q-scan).

   ![Telegram: Configuración → Dispositivos, con Add Device resaltado](/screenshots/telegram/add-device.jpg)

5. Si la configuración pide la contraseña adicional de Telegram, introduce la que configuraste en Telegram. No es el código de un solo uso. El terminal no muestra lo que escribes. Escríbela y pulsa Enter.
6. Espera a que la configuración confirme el acceso y revise tu cuenta y hasta cinco chats.

## 3. Conecta tu agente [#3-conecta-tu-agente]

El agente necesita instrucciones para usar tg. Esas instrucciones se llaman skill. La configuración pregunta qué agente usas e instala la skill para él. El comando de instalación de arriba ya ejecuta `tg skill install --for all`.

Para instalarla de nuevo:

```sh
tg skill install --for all
```

Después abre una sesión nueva del agente para que cargue las instrucciones. Para otros agentes y aplicaciones MCP, consulta [Conectar el agente](/llms.mdx/docs/es/agents/content.md).

## 4. Comprueba que funciona [#4-comprueba-que-funciona]

Pide a tu agente:

```text prompt
Use tg CLI. Muestra mi cuenta de Telegram y mis cinco chats más recientes. No envíes nada.
```

Comprueba que el nombre y los chats son de la cuenta que querías conectar. Si es así, tg está listo.

La configuración no descarga todo el historial de chats. Para buscar mensajes antiguos, pide al agente que [descargue el historial que necesitas](/llms.mdx/docs/es/tg/archive/content.md).

A mano, `tg personal doctor` muestra si has iniciado sesión y dónde guarda tg sus archivos. No se conecta a Telegram.

**Siguiente:** [prueba tu primera tarea](/llms.mdx/docs/es/first-tasks/content.md).

## Preguntas y respuestas [#preguntas-y-respuestas]

### El código QR no se escanea [#el-código-qr-no-se-escanea]

**Con tu agente:** pide al agente que use el acceso por número de teléfono. Introduce el número y el nuevo código cuando lo pida la configuración, seguido de la contraseña adicional de Telegram si se solicita. El código puede llegar a Telegram en lugar de por SMS; la configuración indica cuál.

**A mano:**

```sh
tg personal setup --method phone
```

### El agente no puede mostrarme el terminal con el código QR [#el-agente-no-puede-mostrarme-el-terminal-con-el-código-qr]

El agente ejecuta `tg personal session start qr` en segundo plano. Sin terminal, tg imprime el código QR como texto. El agente lo pega en el chat como bloque de código, tal como se imprimió, y tú lo escaneas desde la pantalla. Cuando Telegram renueva el código, el agente pega el nuevo y dice que el anterior caducó. Solo funciona si tg ya tiene su aplicación de Telegram y tu cuenta no tiene contraseña adicional; si no, ejecuta `tg personal setup` tú mismo. Más en [cuando el agente inicia la sesión](/llms.mdx/docs/es/agents/content.md#agent-login).

### No se puede registrar la aplicación de Telegram [#no-se-puede-registrar-la-aplicación-de-telegram]

tg rellena por ti el formulario de my.telegram.org. Si Telegram cambia ese sitio, registra la aplicación a mano y da a tg sus dos valores.

**Con tu agente:** pídele que use el registro manual de la aplicación. Abre my.telegram.org/apps en tu navegador.

**A mano:** ejecuta `tg personal setup --app browser` y después:

1. Abre my.telegram.org/apps. Elige tu país, escribe tu número de teléfono y pulsa **Next**.

   ![La página de acceso de my.telegram.org con el país y el número de teléfono](/screenshots/telegram/telegram-app-1-sign-in.png)

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

   ![La página del código de confirmación de my.telegram.org](/screenshots/telegram/telegram-app-2-code.png)

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

   ![La página principal de my.telegram.org con la tarjeta Development Tools](/screenshots/telegram/telegram-app-3-development-tools.png)

4. Rellena el formulario. El título necesita al menos 5 caracteres. El nombre corto lleva solo letras y cifras, de 5 a 32 caracteres. Evita la palabra "Telegram" en los dos. Elige una plataforma, por ejemplo **Desktop**. La URL y la descripción son opcionales. Pulsa **Create application**. Si ya existe una aplicación, úsala.

   ![El formulario Create new application](/screenshots/telegram/telegram-app-4-create-application.png)

5. Copia App api_id y App api_hash e introdúcelos en el terminal de configuración cuando los pida. Mantén el hash en privado, porque quien lo tenga puede usar la cuota de tu aplicación. El hash permanece oculto al escribir. Son datos de conexión, no un token de bot.

   ![La sección Credentials con App api_id y App api_hash](/screenshots/telegram/telegram-app-5-credentials.png)

6. Continúa con el inicio de sesión por QR. Los valores de estas capturas son ejemplos.

### ¿Dónde está el escáner QR en Telegram? [#dónde-está-el-escáner-qr-en-telegram]

Abre Telegram en el teléfono y usa el escáner de Telegram, no la app de cámara del teléfono. El menú depende del teléfono.

**iOS**

1. Abre **Configuración** y después **Dispositivos**.
2. Pulsa **Vincular dispositivo de escritorio** (en inglés **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.

**Android**

1. Abre **Configuración** y después **Dispositivos**.
2. Pulsa **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, Configuración y Dispositivos, con el botón Add Device](/screenshots/telegram/telegram-android-add-device.png)

Si tu cuenta tiene una contraseña adicional de Telegram, tg la pide después del escaneo. Si escaneaste el código pero no escribiste esa contraseña, el intento aparece en **Dispositivos** bajo **Incomplete login attempts**. No tiene acceso a tus mensajes. Termina el acceso en tg o cierra el intento en esa lista.

![La lista Incomplete login attempts en la pantalla Dispositivos de Telegram](/screenshots/telegram/telegram-android-incomplete-login.png)

### El código QR caducó o la configuración se detuvo [#el-código-qr-caducó-o-la-configuración-se-detuvo]

**Con tu agente:** pídele que termine el acceso y vuelva a ejecutar la configuración.

**A mano:** ejecuta `tg personal session start` para terminar el acceso y después `tg personal setup` de nuevo. Si ya iniciaste sesión, la configuración usa ese acceso y no vuelve a preguntar.

### tg no se encuentra después de instalarlo [#tg-no-se-encuentra-después-de-instalarlo]

**Con tu agente:** reinicia el agente o pídele que abra un terminal nuevo. Un terminal que estaba abierto durante la instalación no ve el comando nuevo.

**A mano:** abre un terminal nuevo y vuelve a ejecutar `tg --version`. npm no puede cambiar el `PATH` del terminal donde se ejecutó. En Windows, el comando de PowerShell de [Instala tg](#install) también corrige `PATH` cuando npm omitió su script de instalación, y actualiza el terminal actual.

### pnpm no encuentra su directorio global de comandos [#pnpm-no-encuentra-su-directorio-global-de-comandos]

Si pnpm muestra `ERR_PNPM_GLOBAL_BIN_DIR_NOT_IN_PATH`, ejecuta `pnpm setup`, abre otra terminal y repite la instalación. Consulta [pnpm setup](https://pnpm.io/cli/setup).

### ¿Dónde escribo los códigos y las contraseñas? [#dónde-escribo-los-códigos-y-las-contraseñas]

En el terminal de configuración o en la página de my.telegram.org, nunca en el chat con el agente. Si no encuentras la ventana del terminal, pide al agente que te la muestre.

### El agente no puede usar tg después de la configuración [#el-agente-no-puede-usar-tg-después-de-la-configuración]

**Con tu agente:** abre una sesión nueva del agente para que cargue las instrucciones de tg. Si sigue sin poder, consulta [Conectar el agente](/llms.mdx/docs/es/agents/content.md).

**A mano:** ejecuta `tg skill install --for claude` para Claude Code, `--for agents` para Codex, Gemini CLI y otros agentes que leen `~/.agents`, o `--for all`.

### Tras actualizar, tg dice que no se indicó un perfil [#tras-actualizar-tg-dice-que-no-se-indicó-un-perfil]

tg nunca elige una cuenta por sí mismo: cada comando que usa tu cuenta empieza con el nombre del perfil.

**Con tu agente:** dile el nombre del perfil. Si configuraste tg antes sin nombrar un perfil, se llama `default`.

**A mano:** escribe el nombre primero (`tg default chats list`) o fíjalo una vez: `export TG_PROFILE=default` en el perfil de tu shell. Si añadiste tg a una aplicación MCP, vuelve a crear esa entrada con `tg default mcp config`. Cualquier otra cosa que inicie `tg serve` o `tg mcp` por ti, como una tarea programada, también necesita el perfil en su comando: `tg default serve`.

### Tras actualizar, tg se detiene y nombra dos archivos de mensajes [#tras-actualizar-tg-se-detiene-y-nombra-dos-archivos-de-mensajes]

La actualización mueve una sola vez el archivo de mensajes a la carpeta WireCat. Si el sitio antiguo y el nuevo tienen copias distintas, tg se detiene con el código 3 y nombra los dos archivos. Conserva el que necesitas, aparta el otro y vuelve a ejecutar el comando. No se ha movido ni cambiado nada.

### Falta un chat o mensajes antiguos [#falta-un-chat-o-mensajes-antiguos]

La configuración solo revisa algunos chats. Pide al agente que descargue el chat y el período que necesitas: consulta [Archivo local](/llms.mdx/docs/es/tg/archive/content.md). Un resultado de búsqueda vacío no significa que el chat no tenga esos mensajes.

### ¿Puedo probar tg sin instalarlo? [#puedo-probar-tg-sin-instalarlo]

Sí: `npx @wirecat/tg-cli --help`. Así tg se ejecuta una vez. No añade el comando `tg` ni conecta tu agente.

### ¿Dónde se guarda el acceso? [#dónde-se-guarda-el-acceso]

El acceso es un archivo de sesión en la carpeta de estado de tg (ver la tabla). Quien tenga ese archivo puede leer tus chats, así que trátalo como una contraseña. App api_id y App api_hash se guardan en el almacén de contraseñas del sistema operativo (el llavero). Consulta [Seguridad](/llms.mdx/docs/es/security/content.md).

## Dónde se guardan los archivos [#dónde-se-guardan-los-archivos]

| Qué | Linux y macOS | Windows |
| --- | --- | --- |
| Ajustes | `~/.config/tg-cli/` | `%APPDATA%\tg-cli\Config\` |
| Estado: el acceso, registros de ejecución, envíos, destinatarios | `~/.local/share/tg-cli/` | `%LOCALAPPDATA%\tg-cli\Data\` |
| Caché | `~/.cache/tg-cli/` | `%LOCALAPPDATA%\tg-cli\Cache\` |
| Archivo local de mensajes, compartido con max | `~/.local/share/WireCat/wirecat.db` | `%LOCALAPPDATA%\WireCat\Data\wirecat.db` |
| Modelos de reconocimiento de voz | `~/.local/share/WireCat/models/audio/` | `%LOCALAPPDATA%\WireCat\Data\models\audio\` |

`tg personal doctor` muestra las rutas exactas en tu ordenador. `WIRECAT_STATE_DIR` mueve toda la carpeta WireCat. Para cambiar estas carpetas u otros ajustes, consulta [Configuración](/llms.mdx/docs/es/configuration/content.md) y la [referencia de ajustes de tg](/llms.mdx/docs/es/tg/configuration/content.md).

La primera ejecución tras actualizar desde un tg anterior mueve aquí una sola vez el archivo y los modelos, desde `~/.local/share/cli-messaging/` y `~/.cache/cli-common/models/`. En macOS, las versiones anteriores guardaban sus carpetas en `~/Library`; también se mueven una vez.

## Actualizar [#actualizar]

```sh
tg upgrade            # usa el gestor de paquetes que instaló tg: npm, pnpm o bun
tg upgrade --check    # solo indica si hay una versión más nueva
```

Si actualizas desde una versión que guardaba los mensajes en `messages.db`, copia antes las notas o etiquetas que solo existen en tu ordenador: el archivo antiguo se borra al abrir el nuevo. `tg personal messages sync --all` vuelve a descargar los mensajes, pero no las notas ni etiquetas locales.

Actualiza max y memo junto con tg: comparten el archivo de mensajes, y una herramienta antigua crearía un archivo nuevo en el sitio anterior.

tg no se actualiza solo. Una vez al día comprueba si hay una versión nueva y lo indica en una línea del terminal. Tras actualizar, `tg upgrade` reinicia el `serve` en segundo plano que inició tg. El acceso se conserva.

## Desinstalar [#desinstalar]

Desinstalar tg quita el comando, no tus datos. Cierra sesión antes, mientras tg sigue instalado:

```sh
tg personal server uninstall          # solo si instalaste el servicio en segundo plano
tg personal session end               # cerrar sesión en Telegram y borrar el archivo de sesión
npm uninstall -g @wirecat/tg-cli
rm -rf ~/.config/tg-cli ~/.local/share/tg-cli ~/.cache/tg-cli
rm -rf ~/.claude/skills/tg-cli ~/.agents/skills/tg-cli
```

Si conectaste bots, ejecuta también `tg <profile> bot auth remove` para cada perfil de bot. Cerrar sesión deja App api_id y App api_hash en el llavero, bajo el servicio `tg-cli`; borra esa entrada con la herramienta del sistema si ya no los necesitas. Borra `~/.local/share/WireCat/` solo si ninguna otra herramienta, como max, necesita los mensajes guardados.

## Desde el código fuente [#desde-el-código-fuente]

Instala desde el código fuente si cambias el código o quieres una versión que aún no se ha publicado.

```sh
git clone https://github.com/WireCatLabs/tg-cli.git
cd tg-cli
pnpm install
pnpm build
```

En una copia de trabajo, `bin/tg` guarda sus ajustes, el acceso y el archivo en `.tg/` dentro de ella, nunca en tu perfil real. `node dist/bin/tg.js` usa las carpetas reales de la tabla. Para actualizar: `git pull && pnpm install && pnpm build`.
