--- read_when: - Trabajar en funciones de Telegram o Webhooks summary: Estado de soporte, capacidades y configuración del bot de Telegram title: Telegram x-i18n: generated_at: "2026-05-12T12:49:03Z" model: gpt-5.5 provider: openai source_hash: 185ac6051d3da2037b2727a6afca98bef946bc62c3f2b22cc9afe9831669297b source_path: channels/telegram.md workflow: 16 --- Listo para producción para DM y grupos de bots mediante grammY. El sondeo largo es el modo predeterminado; el modo Webhook es opcional. La política predeterminada de DM para Telegram es el emparejamiento. Diagnósticos multicanal y guías de reparación. Patrones y ejemplos completos de configuración de canales. ## Configuración rápida Abre Telegram y chatea con **@BotFather** (confirma que el identificador sea exactamente `@BotFather`). Ejecuta `/newbot`, sigue las indicaciones y guarda el token. ```json5 { channels: { telegram: { enabled: true, botToken: "123:abc", dmPolicy: "pairing", groups: { "*": { requireMention: true } }, }, }, } ``` Alternativa de entorno: `TELEGRAM_BOT_TOKEN=...` (solo la cuenta predeterminada). Telegram **no** usa `openclaw channels login telegram`; configura el token en config/env y luego inicia el Gateway. ```bash openclaw gateway openclaw pairing list telegram openclaw pairing approve telegram ``` Los códigos de emparejamiento vencen después de 1 hora. Agrega el bot a tu grupo y luego obtén los dos ID que necesita el acceso al grupo: - tu ID de usuario de Telegram, usado en `allowFrom` / `groupAllowFrom` - el ID de chat del grupo de Telegram, usado como clave bajo `channels.telegram.groups` Para la configuración inicial, obtén el ID de chat del grupo desde `openclaw logs --follow`, un bot de ID reenviado o `getUpdates` de la Bot API. Después de permitir el grupo, `/whoami@` puede confirmar los ID de usuario y de grupo. Los ID negativos de supergrupos de Telegram que empiezan con `-100` son ID de chat de grupo. Ponlos bajo `channels.telegram.groups`, no bajo `groupAllowFrom`. El orden de resolución de tokens tiene en cuenta la cuenta. En la práctica, los valores de configuración prevalecen sobre la alternativa de entorno, y `TELEGRAM_BOT_TOKEN` solo se aplica a la cuenta predeterminada. ## Configuración del lado de Telegram Los bots de Telegram usan **modo de privacidad** de forma predeterminada, lo que limita los mensajes de grupo que reciben. Si el bot debe ver todos los mensajes de grupo, puedes: - desactivar el modo de privacidad mediante `/setprivacy`, o - convertir el bot en administrador del grupo. Al cambiar el modo de privacidad, elimina y vuelve a agregar el bot en cada grupo para que Telegram aplique el cambio. El estado de administrador se controla en la configuración del grupo de Telegram. Los bots administradores reciben todos los mensajes de grupo, lo que es útil para comportamiento de grupo siempre activo. - `/setjoingroups` para permitir/denegar agregados a grupos - `/setprivacy` para el comportamiento de visibilidad en grupos ## Control de acceso y activación `channels.telegram.dmPolicy` controla el acceso por mensaje directo: - `pairing` (predeterminado) - `allowlist` (requiere al menos un ID de remitente en `allowFrom`) - `open` (requiere que `allowFrom` incluya `"*"`) - `disabled` `dmPolicy: "open"` con `allowFrom: ["*"]` permite que cualquier cuenta de Telegram que encuentre o adivine el nombre de usuario del bot lo controle. Úsalo solo para bots intencionalmente públicos con herramientas estrictamente restringidas; los bots de un solo propietario deben usar `allowlist` con ID de usuario numéricos. `channels.telegram.allowFrom` acepta ID de usuario numéricos de Telegram. Los prefijos `telegram:` / `tg:` se aceptan y se normalizan. En configuraciones con varias cuentas, un `channels.telegram.allowFrom` de nivel superior restrictivo se trata como un límite de seguridad: las entradas de nivel de cuenta `allowFrom: ["*"]` no hacen pública esa cuenta a menos que la allowlist efectiva de la cuenta siga conteniendo un comodín explícito después de la combinación. `dmPolicy: "allowlist"` con `allowFrom` vacío bloquea todos los DM y la validación de configuración lo rechaza. La configuración solo pide ID de usuario numéricos. Si actualizaste y tu configuración contiene entradas de allowlist `@username`, ejecuta `openclaw doctor --fix` para resolverlas (mejor esfuerzo; requiere un token de bot de Telegram). Si antes dependías de archivos de allowlist del almacén de emparejamientos, `openclaw doctor --fix` puede recuperar entradas en `channels.telegram.allowFrom` en flujos allowlist (por ejemplo, cuando `dmPolicy: "allowlist"` todavía no tiene ID explícitos). Para bots de un solo propietario, prefiere `dmPolicy: "allowlist"` con ID numéricos explícitos en `allowFrom` para mantener la política de acceso duradera en la configuración (en lugar de depender de aprobaciones de emparejamiento previas). Confusión común: aprobar el emparejamiento de DM no significa "este remitente está autorizado en todas partes". El emparejamiento concede acceso a DM. Si aún no existe un propietario de comandos, el primer emparejamiento aprobado también establece `commands.ownerAllowFrom` para que los comandos solo para propietarios y las aprobaciones de ejecución tengan una cuenta de operador explícita. La autorización de remitentes de grupo sigue viniendo de allowlists explícitas de configuración. Si quieres "me autorizo una vez y funcionan tanto los DM como los comandos de grupo", pon tu ID de usuario numérico de Telegram en `channels.telegram.allowFrom`; para comandos solo para propietarios, asegúrate de que `commands.ownerAllowFrom` contenga `telegram:`. ### Encontrar tu ID de usuario de Telegram Más seguro (sin bot de terceros): 1. Envía un DM a tu bot. 2. Ejecuta `openclaw logs --follow`. 3. Lee `from.id`. Método oficial de Bot API: ```bash curl "https://api.telegram.org/bot/getUpdates" ``` Método de terceros (menos privado): `@userinfobot` o `@getidsbot`. Dos controles se aplican juntos: 1. **Qué grupos están permitidos** (`channels.telegram.groups`) - sin configuración de `groups`: - con `groupPolicy: "open"`: cualquier grupo puede pasar las comprobaciones de ID de grupo - con `groupPolicy: "allowlist"` (predeterminado): los grupos se bloquean hasta que agregues entradas de `groups` (o `"*"`) - `groups` configurado: actúa como allowlist (ID explícitos o `"*"`) 2. **Qué remitentes están permitidos en grupos** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (predeterminado) - `disabled` `groupAllowFrom` se usa para filtrar remitentes de grupo. Si no está establecido, Telegram recurre a `allowFrom`. Las entradas de `groupAllowFrom` deben ser ID de usuario numéricos de Telegram (los prefijos `telegram:` / `tg:` se normalizan). No pongas ID de chat de grupos o supergrupos de Telegram en `groupAllowFrom`. Los ID de chat negativos pertenecen bajo `channels.telegram.groups`. Las entradas no numéricas se ignoran para la autorización de remitentes. Límite de seguridad (`2026.2.25+`): la autenticación de remitentes de grupo **no** hereda las aprobaciones del almacén de emparejamientos de DM. El emparejamiento sigue siendo solo para DM. Para grupos, establece `groupAllowFrom` o `allowFrom` por grupo/tema. Si `groupAllowFrom` no está establecido, Telegram recurre a la configuración `allowFrom`, no al almacén de emparejamientos. Patrón práctico para bots de un solo propietario: establece tu ID de usuario en `channels.telegram.allowFrom`, deja `groupAllowFrom` sin establecer y permite los grupos de destino bajo `channels.telegram.groups`. Nota de ejecución: si falta por completo `channels.telegram`, el runtime usa de forma predeterminada `groupPolicy="allowlist"` con cierre seguro, a menos que `channels.defaults.groupPolicy` esté establecido explícitamente. Configuración de grupo solo para propietarios: ```json5 { channels: { telegram: { enabled: true, dmPolicy: "pairing", allowFrom: [""], groupPolicy: "allowlist", groups: { "": { requireMention: true, }, }, }, }, } ``` Pruébalo desde el grupo con `@ ping`. Los mensajes de grupo simples no activan el bot mientras `requireMention: true`. Ejemplo: permitir cualquier miembro en un grupo específico: ```json5 { channels: { telegram: { groups: { "-1001234567890": { groupPolicy: "open", requireMention: false, }, }, }, }, } ``` Ejemplo: permitir solo usuarios específicos dentro de un grupo específico: ```json5 { channels: { telegram: { groups: { "-1001234567890": { requireMention: true, allowFrom: ["8734062810", "745123456"], }, }, }, }, } ``` Error común: `groupAllowFrom` no es una allowlist de grupos de Telegram. - Pon ID negativos de chats de grupos o supergrupos de Telegram, como `-1001234567890`, bajo `channels.telegram.groups`. - Pon ID de usuario de Telegram, como `8734062810`, bajo `groupAllowFrom` cuando quieras limitar qué personas dentro de un grupo permitido pueden activar el bot. - Usa `groupAllowFrom: ["*"]` solo cuando quieras que cualquier miembro de un grupo permitido pueda hablar con el bot. Las respuestas de grupo requieren mención de forma predeterminada. La mención puede venir de: - una mención nativa `@botusername`, o - patrones de mención en: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` Alternadores de comandos a nivel de sesión: - `/activation always` - `/activation mention` Estos solo actualizan el estado de la sesión. Usa configuración para persistencia. Ejemplo de configuración persistente: ```json5 { channels: { telegram: { groups: { "*": { requireMention: false }, }, }, }, } ``` Obtener el ID de chat del grupo: - reenvía un mensaje de grupo a `@userinfobot` / `@getidsbot` - o lee `chat.id` desde `openclaw logs --follow` - o inspecciona `getUpdates` de Bot API - después de permitir el grupo, ejecuta `/whoami@` si los comandos nativos están habilitados ## Comportamiento en tiempo de ejecución - Telegram pertenece al proceso del Gateway. - El enrutamiento es determinista: las entradas de Telegram responden de vuelta a Telegram (el modelo no elige canales). - Los mensajes entrantes se normalizan en el sobre de canal compartido con metadatos de respuesta, marcadores de posición de medios y contexto persistido de cadena de respuestas para respuestas de Telegram que el Gateway ha observado. - Las sesiones de grupo se aíslan por ID de grupo. Los temas de foros agregan `:topic:` para mantener los temas aislados. - Los mensajes de DM pueden llevar `message_thread_id`; OpenClaw conserva el ID de hilo para las respuestas, pero mantiene los DM en la sesión plana de forma predeterminada. Configura `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` o una configuración de tema coincidente cuando quieras intencionalmente aislamiento de sesión por tema en DM. - El sondeo largo usa grammY runner con secuenciación por chat/por hilo. La concurrencia general del receptor del runner usa `agents.defaults.maxConcurrent`. - El sondeo largo está protegido dentro de cada proceso del Gateway para que solo un sondeador activo pueda usar un token de bot a la vez. Si sigues viendo conflictos 409 de `getUpdates`, es probable que otro Gateway de OpenClaw, script o sondeador externo esté usando el mismo token. - Los reinicios del vigilante de sondeo largo se activan después de 120 segundos sin actividad completada de `getUpdates` de forma predeterminada. Aumenta `channels.telegram.pollingStallThresholdMs` solo si tu despliegue sigue viendo reinicios falsos por bloqueo de sondeo durante trabajos de larga duración. El valor está en milisegundos y se permite desde `30000` hasta `600000`; se admiten reemplazos por cuenta. - Telegram Bot API no tiene soporte de confirmación de lectura (`sendReadReceipts` no se aplica). ## Referencia de funciones OpenClaw puede transmitir respuestas parciales en tiempo real: - chats directos: mensaje de vista previa + `editMessageText` - grupos/temas: mensaje de vista previa + `editMessageText` Requisito: - `channels.telegram.streaming` es `off | partial | block | progress` (predeterminado: `partial`) - `progress` conserva un borrador de estado editable para el progreso de herramientas, lo borra al finalizar y envía la respuesta final como un mensaje normal - `streaming.preview.toolProgress` controla si las actualizaciones de herramientas/progreso reutilizan el mismo mensaje de vista previa editado (predeterminado: `true` cuando la transmisión de vista previa está activa) - `streaming.preview.commandText` controla el detalle de comando/ejecución dentro de esas líneas de progreso de herramientas: `raw` (predeterminado, conserva el comportamiento publicado) o `status` (solo etiqueta de herramienta) - se detectan los valores heredados `channels.telegram.streamMode` y los valores booleanos de `streaming`; ejecuta `openclaw doctor --fix` para migrarlos a `channels.telegram.streaming.mode` Las actualizaciones de vista previa de progreso de herramientas son las líneas de estado breves que se muestran mientras se ejecutan las herramientas, por ejemplo ejecución de comandos, lecturas de archivos, actualizaciones de planificación o resúmenes de parches. Telegram las mantiene habilitadas de forma predeterminada para coincidir con el comportamiento publicado de OpenClaw desde `v2026.4.22` y versiones posteriores. Para conservar la vista previa editada para el texto de respuesta pero ocultar las líneas de progreso de herramientas, establece: ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "toolProgress": false } } } } } ``` Para mantener visible el progreso de herramientas pero ocultar el texto de comando/ejecución, establece: ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "commandText": "status" } } } } } ``` Usa el modo `progress` cuando quieras progreso de herramientas visible sin editar la respuesta final en ese mismo mensaje. Coloca la política de texto de comando bajo `streaming.progress`: ```json { "channels": { "telegram": { "streaming": { "mode": "progress", "progress": { "toolProgress": true, "commandText": "status" } } } } } ``` Usa `streaming.mode: "off"` solo cuando quieras entrega únicamente final: las ediciones de vista previa de Telegram se deshabilitan y la charla genérica de herramientas/progreso se suprime en lugar de enviarse como mensajes de estado independientes. Las solicitudes de aprobación, las cargas de medios y los errores siguen pasando por la entrega final normal. Usa `streaming.preview.toolProgress: false` cuando solo quieras conservar las ediciones de vista previa de la respuesta mientras ocultas las líneas de estado de progreso de herramientas. Las respuestas a citas seleccionadas de Telegram son la excepción. Cuando `replyToMode` es `"first"`, `"all"` o `"batched"` y el mensaje entrante incluye texto de cita seleccionado, OpenClaw envía la respuesta final por la ruta nativa de respuesta con cita de Telegram en lugar de editar la vista previa de respuesta, por lo que `streaming.preview.toolProgress` no puede mostrar las líneas de estado breves para ese turno. Las respuestas al mensaje actual sin texto de cita seleccionado aún conservan la transmisión de vista previa. Establece `replyToMode: "off"` cuando la visibilidad del progreso de herramientas importe más que las respuestas nativas con cita, o establece `streaming.preview.toolProgress: false` para aceptar la compensación. Para respuestas solo de texto: - vistas previas breves de DM/grupo/tema: OpenClaw conserva el mismo mensaje de vista previa y realiza la edición final en el mismo lugar - las respuestas finales de texto largo que se dividen en varios mensajes de Telegram reutilizan la vista previa existente como el primer fragmento final cuando es posible, y luego envían solo los fragmentos restantes - las respuestas finales en modo progreso borran el borrador de estado y usan entrega final normal en lugar de editar el borrador para convertirlo en la respuesta - si la edición final falla antes de que se confirme el texto completado, OpenClaw usa la entrega final normal y limpia la vista previa obsoleta Para respuestas complejas (por ejemplo cargas de medios), OpenClaw vuelve a la entrega final normal y luego limpia el mensaje de vista previa. La transmisión de vista previa está separada de la transmisión por bloques. Cuando la transmisión por bloques está habilitada explícitamente para Telegram, OpenClaw omite la transmisión de vista previa para evitar una doble transmisión. Flujo de razonamiento solo para Telegram: - `/reasoning stream` envía el razonamiento a la vista previa en vivo mientras genera - la vista previa de razonamiento se elimina después de la entrega final; usa `/reasoning on` cuando el razonamiento deba permanecer visible - la respuesta final se envía sin texto de razonamiento El texto saliente usa Telegram `parse_mode: "HTML"`. - El texto similar a Markdown se renderiza como HTML seguro para Telegram. - Las etiquetas HTML compatibles con Telegram se conservan; el HTML no compatible se escapa. - Si Telegram rechaza el HTML analizado, OpenClaw reintenta como texto sin formato. Las vistas previas de enlaces están habilitadas de forma predeterminada y se pueden deshabilitar con `channels.telegram.linkPreview: false`. El registro del menú de comandos de Telegram se gestiona al iniciar con `setMyCommands`. Valores predeterminados de comandos nativos: - `commands.native: "auto"` habilita comandos nativos para Telegram Añade entradas personalizadas al menú de comandos: ```json5 { channels: { telegram: { customCommands: [ { command: "backup", description: "Git backup" }, { command: "generate", description: "Create an image" }, ], }, }, } ``` Reglas: - los nombres se normalizan (se elimina la `/` inicial, minúsculas) - patrón válido: `a-z`, `0-9`, `_`, longitud `1..32` - los comandos personalizados no pueden sobrescribir comandos nativos - los conflictos/duplicados se omiten y se registran Notas: - los comandos personalizados son solo entradas de menú; no implementan comportamiento automáticamente - los comandos de plugin/skill aún pueden funcionar al escribirse aunque no se muestren en el menú de Telegram Si los comandos nativos están deshabilitados, los integrados se eliminan. Los comandos personalizados/de plugin aún pueden registrarse si están configurados. Errores comunes de configuración: - `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa que el menú de Telegram siguió desbordándose después del recorte; reduce los comandos de plugin/skill/personalizados o deshabilita `channels.telegram.commands.native`. - `deleteWebhook`, `deleteMyCommands` o `setMyCommands` fallan con `404: Not Found` mientras los comandos curl directos de la Bot API funcionan puede significar que `channels.telegram.apiRoot` se estableció en el endpoint completo `/bot`. `apiRoot` debe ser solo la raíz de la Bot API, y `openclaw doctor --fix` elimina un `/bot` final accidental. - `getMe returned 401` significa que Telegram rechazó el token de bot configurado. Actualiza `botToken`, `tokenFile` o `TELEGRAM_BOT_TOKEN` con el token actual de BotFather; OpenClaw se detiene antes del sondeo, por lo que esto no se informa como un error de limpieza de Webhook. - `setMyCommands failed` con errores de red/fetch normalmente significa que el DNS/HTTPS saliente hacia `api.telegram.org` está bloqueado. ### Comandos de emparejamiento de dispositivos (plugin `device-pair`) Cuando el plugin `device-pair` está instalado: 1. `/pair` genera un código de configuración 2. pega el código en la app de iOS 3. `/pair pending` lista las solicitudes pendientes (incluidos rol/ámbitos) 4. aprueba la solicitud: - `/pair approve ` para aprobación explícita - `/pair approve` cuando solo hay una solicitud pendiente - `/pair approve latest` para la más reciente El código de configuración lleva un token de arranque de corta duración. La transferencia de arranque integrada mantiene el token del nodo primario en `scopes: []`; cualquier token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` y `operator.write`. Las comprobaciones de ámbito de arranque tienen prefijo de rol, por lo que esa lista de permitidos de operador solo satisface solicitudes de operador; los roles que no son de operador aún necesitan ámbitos bajo su propio prefijo de rol. Si un dispositivo reintenta con detalles de autenticación cambiados (por ejemplo rol/ámbitos/clave pública), la solicitud pendiente anterior se sustituye y la nueva solicitud usa un `requestId` diferente. Vuelve a ejecutar `/pair pending` antes de aprobar. Más detalles: [Emparejamiento](/es/channels/pairing#pair-via-telegram-recommended-for-ios). Configura el alcance del teclado en línea: ```json5 { channels: { telegram: { capabilities: { inlineButtons: "allowlist", }, }, }, } ``` Anulación por cuenta: ```json5 { channels: { telegram: { accounts: { main: { capabilities: { inlineButtons: "allowlist", }, }, }, }, }, } ``` Alcances: - `off` - `dm` - `group` - `all` - `allowlist` (predeterminado) El valor heredado `capabilities: ["inlineButtons"]` se asigna a `inlineButtons: "all"`. Ejemplo de acción de mensaje: ```json5 { action: "send", channel: "telegram", to: "123456789", message: "Choose an option:", buttons: [ [ { text: "Yes", callback_data: "yes" }, { text: "No", callback_data: "no" }, ], [{ text: "Cancel", callback_data: "cancel" }], ], } ``` Los clics de callback se pasan al agente como texto: `callback_data: ` Las acciones de herramientas de Telegram incluyen: - `sendMessage` (`to`, `content`, `mediaUrl` opcional, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - `createForumTopic` (`chatId`, `name`, `iconColor` opcional, `iconCustomEmojiId`) Las acciones de mensajes de canal exponen alias ergonómicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). Controles de activación: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (predeterminado: deshabilitado) Nota: `edit` y `topic-create` están habilitados actualmente de forma predeterminada y no tienen interruptores `channels.telegram.actions.*` separados. Los envíos en tiempo de ejecución usan la instantánea activa de configuración/secretos (inicio/recarga), por lo que las rutas de acción no realizan una resolución ad hoc de SecretRef por cada envío. Semántica de eliminación de reacciones: [/tools/reactions](/es/tools/reactions) Telegram admite etiquetas explícitas de hilos de respuesta en la salida generada: - `[[reply_to_current]]` responde al mensaje activador - `[[reply_to:]]` responde a un ID de mensaje de Telegram específico `channels.telegram.replyToMode` controla la gestión: - `off` (predeterminado) - `first` - `all` Cuando los hilos de respuesta están habilitados y el texto o pie de foto original de Telegram está disponible, OpenClaw incluye automáticamente un extracto de cita nativa de Telegram. Telegram limita el texto de cita nativa a 1024 unidades de código UTF-16, por lo que los mensajes más largos se citan desde el inicio y vuelven a una respuesta sin formato si Telegram rechaza la cita. Nota: `off` deshabilita los hilos de respuesta implícitos. Las etiquetas explícitas `[[reply_to_*]]` aún se respetan. Supergrupos de foro: - las claves de sesión de tema añaden `:topic:` - las respuestas y la indicación de escritura apuntan al hilo del tema - ruta de configuración de tema: `channels.telegram.groups..topics.` Caso especial del tema general (`threadId=1`): - los envíos de mensajes omiten `message_thread_id` (Telegram rechaza `sendMessage(...thread_id=1)`) - las acciones de escritura aún incluyen `message_thread_id` Herencia de temas: las entradas de tema heredan la configuración del grupo salvo que se anule (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). `agentId` es exclusivo del tema y no hereda de los valores predeterminados del grupo. **Enrutamiento de agente por tema**: cada tema puede enrutarse a un agente diferente estableciendo `agentId` en la configuración del tema. Esto da a cada tema su propio espacio de trabajo, memoria y sesión aislados. Ejemplo: ```json5 { channels: { telegram: { groups: { "-1001234567890": { topics: { "1": { agentId: "main" }, // General topic → main agent "3": { agentId: "zu" }, // Dev topic → zu agent "5": { agentId: "coder" } // Code review → coder agent } } } } } } ``` Cada tema tiene entonces su propia clave de sesión: `agent:zu:telegram:group:-1001234567890:topic:3` **Vinculación persistente de temas ACP**: Los temas de foro pueden fijar sesiones del arnés ACP mediante vinculaciones ACP tipadas de nivel superior (`bindings[]` con `type: "acp"` y `match.channel: "telegram"`, `peer.kind: "group"`, y un id calificado por tema como `-1001234567890:topic:42`). Actualmente está limitado a temas de foro en grupos/supergrupos. Consulta [Agentes ACP](/es/tools/acp-agents). **Creación de ACP vinculada al hilo desde el chat**: `/acp spawn --thread here|auto` vincula el tema actual a una nueva sesión ACP; las respuestas posteriores se enrutan allí directamente. OpenClaw fija la confirmación de creación en el tema. Requiere que `channels.telegram.threadBindings.spawnSessions` permanezca habilitado (predeterminado: `true`). El contexto de plantilla expone `MessageThreadId` e `IsForum`. Los chats DM con `message_thread_id` mantienen el enrutamiento DM y los metadatos de respuesta en sesiones planas de forma predeterminada; solo usan claves de sesión con reconocimiento de hilos cuando se configuran con `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` o una configuración de tema coincidente. Usa `channels.telegram.dm.threadReplies` de nivel superior para el valor predeterminado de la cuenta, o `direct..threadReplies` para un DM. ### Mensajes de audio Telegram distingue las notas de voz de los archivos de audio. - predeterminado: comportamiento de archivo de audio - etiqueta `[[audio_as_voice]]` en la respuesta del agente para forzar el envío como nota de voz - las transcripciones entrantes de notas de voz se enmarcan como texto generado por máquina y no confiable en el contexto del agente; la detección de menciones sigue usando la transcripción sin procesar, por lo que los mensajes de voz controlados por menciones siguen funcionando. Ejemplo de acción de mensaje: ```json5 { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/voice.ogg", asVoice: true, } ``` ### Mensajes de video Telegram distingue los archivos de video de las notas de video. Ejemplo de acción de mensaje: ```json5 { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/video.mp4", asVideoNote: true, } ``` Las notas de video no admiten pies de foto; el texto de mensaje proporcionado se envía por separado. ### Pegatinas Manejo de pegatinas entrantes: - WEBP estático: se descarga y procesa (marcador de posición ``) - TGS animado: se omite - WEBM de video: se omite Campos de contexto de pegatina: - `Sticker.emoji` - `Sticker.setName` - `Sticker.fileId` - `Sticker.fileUniqueId` - `Sticker.cachedDescription` Archivo de caché de pegatinas: - `~/.openclaw/telegram/sticker-cache.json` Las pegatinas se describen una vez (cuando es posible) y se almacenan en caché para reducir las llamadas de visión repetidas. Habilitar acciones de pegatinas: ```json5 { channels: { telegram: { actions: { sticker: true, }, }, }, } ``` Acción de envío de pegatina: ```json5 { action: "sticker", channel: "telegram", to: "123456789", fileId: "CAACAgIAAxkBAAI...", } ``` Buscar pegatinas en caché: ```json5 { action: "sticker-search", channel: "telegram", query: "cat waving", limit: 5, } ``` Las reacciones de Telegram llegan como actualizaciones `message_reaction` (separadas de las cargas de mensajes). Cuando está habilitado, OpenClaw encola eventos del sistema como: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` Configuración: - `channels.telegram.reactionNotifications`: `off | own | all` (predeterminado: `own`) - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (predeterminado: `minimal`) Notas: - `own` significa solo reacciones de usuarios a mensajes enviados por el bot (mejor esfuerzo mediante la caché de mensajes enviados). - Los eventos de reacción siguen respetando los controles de acceso de Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); los remitentes no autorizados se descartan. - Telegram no proporciona IDs de hilo en las actualizaciones de reacción. - los grupos que no son de foro se enrutan a la sesión de chat del grupo - los grupos de foro se enrutan a la sesión del tema general del grupo (`:topic:1`), no al tema de origen exacto `allowed_updates` para sondeo/Webhook incluye `message_reaction` automáticamente. `ackReaction` envía un emoji de confirmación mientras OpenClaw procesa un mensaje entrante. Orden de resolución: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - respaldo de emoji de identidad del agente (`agents.list[].identity.emoji`; si no existe, "👀") Notas: - Telegram espera emoji unicode (por ejemplo, "👀"). - Usa `""` para deshabilitar la reacción para un canal o cuenta. Las escrituras de configuración del canal están habilitadas de forma predeterminada (`configWrites !== false`). Las escrituras activadas por Telegram incluyen: - eventos de migración de grupo (`migrate_to_chat_id`) para actualizar `channels.telegram.groups` - `/config set` y `/config unset` (requiere habilitación de comandos) Deshabilitar: ```json5 { channels: { telegram: { configWrites: false, }, }, } ``` El valor predeterminado es el sondeo largo. Para el modo Webhook, define `channels.telegram.webhookUrl` y `channels.telegram.webhookSecret`; opcionalmente `webhookPath`, `webhookHost`, `webhookPort` (valores predeterminados `/telegram-webhook`, `127.0.0.1`, `8787`). En modo de sondeo largo, OpenClaw conserva su marca de agua de reinicio solo después de que una actualización se despacha correctamente. Si un controlador falla, esa actualización sigue siendo reintentable en el mismo proceso y no se escribe como completada para la deduplicación de reinicio. El listener local se vincula a `127.0.0.1:8787`. Para entrada pública, coloca un proxy inverso delante del puerto local o establece `webhookHost: "0.0.0.0"` intencionalmente. El modo Webhook valida los guardas de solicitud, el token secreto de Telegram y el cuerpo JSON antes de devolver `200` a Telegram. Luego OpenClaw procesa la actualización de forma asíncrona mediante las mismas vías de bot por chat/por tema usadas por el sondeo largo, por lo que los turnos lentos del agente no retienen el ACK de entrega de Telegram. - El valor predeterminado de `channels.telegram.textChunkLimit` es 4000. - `channels.telegram.chunkMode="newline"` prefiere límites de párrafo (líneas en blanco) antes de dividir por longitud. - `channels.telegram.mediaMaxMb` (predeterminado 100) limita el tamaño de los medios entrantes y salientes de Telegram. - `channels.telegram.mediaGroupFlushMs` (predeterminado 500) controla cuánto tiempo se almacenan en búfer los álbumes/grupos de medios de Telegram antes de que OpenClaw los despache como un único mensaje entrante. Auméntalo si las partes del álbum llegan tarde; redúcelo para disminuir la latencia de respuesta del álbum. - `channels.telegram.timeoutSeconds` anula el tiempo de espera del cliente de la API de Telegram (si no se establece, se aplica el valor predeterminado de grammY). Los clientes bot limitan los valores configurados por debajo del guarda de solicitudes salientes de texto/escritura de 60 segundos para que grammY no aborte la entrega de respuestas visibles antes de que el guarda de transporte y el respaldo de OpenClaw puedan ejecutarse. El sondeo largo sigue usando un guarda de solicitud `getUpdates` de 45 segundos para que los sondeos inactivos no se abandonen indefinidamente. - `channels.telegram.pollingStallThresholdMs` tiene como valor predeterminado `120000`; ajústalo entre `30000` y `600000` solo para reinicios por estancamiento de sondeo falsos positivos. - el historial de contexto de grupo usa `channels.telegram.historyLimit` o `messages.groupChat.historyLimit` (predeterminado 50); `0` lo deshabilita. - el contexto complementario de respuesta/cita/reenvío se normaliza en una única ventana de contexto de conversación seleccionada cuando el Gateway ha observado los mensajes principales; la caché de mensajes observados se conserva junto al almacén de sesiones. Telegram solo incluye un `reply_to_message` superficial en las actualizaciones, por lo que las cadenas más antiguas que la caché quedan limitadas a la carga de actualización actual de Telegram. - Las listas de permitidos de Telegram principalmente controlan quién puede activar el agente, no son un límite completo de redacción de contexto complementario. - Controles de historial de DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - la configuración `channels.telegram.retry` se aplica a los auxiliares de envío de Telegram (CLI/herramientas/acciones) para errores recuperables de la API saliente. La entrega de respuesta final entrante también usa un reintento de envío seguro acotado para fallos de preconexión de Telegram, pero no reintenta sobres de red ambiguos posteriores al envío que podrían duplicar mensajes visibles. Los destinos de envío de CLI y de la herramienta de mensajes pueden ser un ID numérico de chat, un nombre de usuario o un destino de tema de foro: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic" ``` Los sondeos de Telegram usan `openclaw message poll` y admiten temas de foro: ```bash openclaw message poll --channel telegram --target 123456789 \ --poll-question "Ship it?" --poll-option "Yes" --poll-option "No" openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \ --poll-duration-seconds 300 --poll-public ``` Flags de sondeo solo para Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - `--thread-id` para temas de foro (o usa un destino `:topic:`) El envío de Telegram también admite: - `--presentation` con bloques `buttons` para teclados en línea cuando `channels.telegram.capabilities.inlineButtons` lo permite - `--pin` o `--delivery '{"pin":true}'` para solicitar entrega fijada cuando el bot pueda fijar en ese chat - `--force-document` para enviar imágenes, GIF y videos salientes como documentos en lugar de cargas comprimidas de foto, medios animados o video Control de acciones: - `channels.telegram.actions.sendMessage=false` deshabilita los mensajes salientes de Telegram, incluidas las encuestas - `channels.telegram.actions.poll=false` deshabilita la creación de encuestas de Telegram mientras deja habilitados los envíos normales Telegram admite aprobaciones de exec en DM de aprobadores y puede publicar opcionalmente avisos en el chat o tema de origen. Los aprobadores deben ser IDs numéricos de usuario de Telegram. Ruta de configuración: - `channels.telegram.execApprovals.enabled` (se habilita automáticamente cuando al menos un aprobador se puede resolver) - `channels.telegram.execApprovals.approvers` (recurre a IDs numéricos de propietarios de `commands.ownerAllowFrom`) - `channels.telegram.execApprovals.target`: `dm` (predeterminado) | `channel` | `both` - `agentFilter`, `sessionFilter` `channels.telegram.allowFrom`, `groupAllowFrom` y `defaultTo` controlan quién puede hablar con el bot y dónde envía las respuestas normales. No convierten a nadie en aprobador de exec. El primer emparejamiento DM aprobado inicializa `commands.ownerAllowFrom` cuando aún no existe ningún propietario de comandos, por lo que la configuración de un solo propietario sigue funcionando sin duplicar IDs en `execApprovals.approvers`. La entrega al canal muestra el texto del comando en el chat; habilita `channel` o `both` solo en grupos/temas de confianza. Cuando el aviso llega a un tema de foro, OpenClaw conserva el tema para el aviso de aprobación y el seguimiento. Las aprobaciones de exec expiran después de 30 minutos de forma predeterminada. Los botones de aprobación en línea también requieren que `channels.telegram.capabilities.inlineButtons` permita la superficie de destino (`dm`, `group` o `all`). Los IDs de aprobación con prefijo `plugin:` se resuelven mediante aprobaciones de plugins; los demás se resuelven primero mediante aprobaciones de exec. Consulta [Aprobaciones de exec](/es/tools/exec-approvals). ## Controles de respuesta de error Cuando el agente encuentra un error de entrega o de proveedor, Telegram puede responder con el texto del error o suprimirlo. Dos claves de configuración controlan este comportamiento: | Clave | Valores | Predeterminado | Descripción | | ----------------------------------- | ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | | `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envía un mensaje de error amable al chat. `silent` suprime por completo las respuestas de error. | | `channels.telegram.errorCooldownMs` | número (ms) | `60000` | Tiempo mínimo entre respuestas de error al mismo chat. Evita el spam de errores durante interrupciones. | Se admiten anulaciones por cuenta, por grupo y por tema (la misma herencia que otras claves de configuración de Telegram). ```json5 { channels: { telegram: { errorPolicy: "reply", errorCooldownMs: 120000, groups: { "-1001234567890": { errorPolicy: "silent", // suppress errors in this group }, }, }, }, } ``` ## Solución de problemas - Si `requireMention=false`, el modo de privacidad de Telegram debe permitir visibilidad completa. - BotFather: `/setprivacy` -> Disable - luego elimina y vuelve a añadir el bot al grupo - `openclaw channels status` advierte cuando la configuración espera mensajes de grupo sin mención. - `openclaw channels status --probe` puede comprobar ID de grupo numéricos explícitos; el comodín `"*"` no se puede comprobar mediante sondeo de membresía. - prueba rápida de sesión: `/activation always`. - cuando existe `channels.telegram.groups`, el grupo debe estar listado (o incluir `"*"`) - verifica la membresía del bot en el grupo - revisa los registros: `openclaw logs --follow` para conocer los motivos de omisión - autoriza tu identidad de remitente (emparejamiento y/o `allowFrom` numérico) - la autorización de comandos sigue aplicándose incluso cuando la política del grupo es `open` - `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa que el menú nativo tiene demasiadas entradas; reduce los comandos de plugins/Skills/personalizados o desactiva los menús nativos - las llamadas de inicio `deleteMyCommands` / `setMyCommands` y las llamadas de escritura `sendChatAction` están acotadas y reintentan una vez mediante la reserva de transporte de Telegram cuando se agota el tiempo de espera de la solicitud. Los errores persistentes de red/fetch suelen indicar problemas de alcance DNS/HTTPS hacia `api.telegram.org` - `getMe returned 401` es un fallo de autenticación de Telegram para el token de bot configurado. - Vuelve a copiar o regenerar el token del bot en BotFather y luego actualiza `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` o `TELEGRAM_BOT_TOKEN` para la cuenta predeterminada. - `deleteWebhook 401 Unauthorized` durante el inicio también es un fallo de autenticación; tratarlo como "no existe ningún Webhook" solo aplazaría el mismo fallo de token incorrecto a llamadas de API posteriores. - Node 22+ + fetch/proxy personalizado puede activar comportamiento de cancelación inmediata si los tipos de AbortSignal no coinciden. - Algunos hosts resuelven `api.telegram.org` primero a IPv6; una salida IPv6 defectuosa puede causar fallos intermitentes de la API de Telegram. - Si los registros incluyen `TypeError: fetch failed` o `Network request for 'getUpdates' failed!`, OpenClaw ahora reintenta estos casos como errores de red recuperables. - Durante el inicio del sondeo, OpenClaw reutiliza la comprobación `getMe` de inicio correcta para grammY, de modo que el ejecutor no necesite un segundo `getMe` antes del primer `getUpdates`. - Si `deleteWebhook` falla con un error de red transitorio durante el inicio del sondeo, OpenClaw continúa con sondeo largo en lugar de hacer otra llamada de plano de control previa al sondeo. Un Webhook aún activo aparece como un conflicto de `getUpdates`; entonces OpenClaw reconstruye el transporte de Telegram y reintenta la limpieza del Webhook. - Si los sockets de Telegram se reciclan con una cadencia fija corta, comprueba si `channels.telegram.timeoutSeconds` es bajo; los clientes de bot limitan los valores configurados por debajo de las protecciones de solicitudes salientes y `getUpdates`, pero las versiones anteriores podían abortar cada sondeo o respuesta cuando esto se establecía por debajo de esas protecciones. - Si los registros incluyen `Polling stall detected`, OpenClaw reinicia el sondeo y reconstruye el transporte de Telegram tras 120 segundos sin actividad de sondeo largo completada de forma predeterminada. - `openclaw channels status --probe` y `openclaw doctor` advierten cuando una cuenta de sondeo en ejecución no ha completado `getUpdates` tras el margen de inicio, cuando una cuenta de Webhook en ejecución no ha completado `setWebhook` tras el margen de inicio, o cuando la última actividad correcta del transporte de sondeo está obsoleta. - Aumenta `channels.telegram.pollingStallThresholdMs` solo cuando las llamadas `getUpdates` de larga duración están sanas, pero tu host aún informa reinicios falsos por sondeo detenido. Las detenciones persistentes suelen apuntar a problemas de proxy, DNS, IPv6 o salida TLS entre el host y `api.telegram.org`. - Telegram también respeta las variables de entorno de proxy del proceso para el transporte de la API de bot, incluidas `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` y sus variantes en minúsculas. `NO_PROXY` / `no_proxy` aún pueden omitir `api.telegram.org`. - Si el proxy gestionado de OpenClaw se configura mediante `OPENCLAW_PROXY_URL` para un entorno de servicio y no hay variables de entorno de proxy estándar presentes, Telegram también usa esa URL para el transporte de la API de bot. - En hosts VPS con salida directa/TLS inestable, enruta las llamadas de API de Telegram mediante `channels.telegram.proxy`: ```yaml channels: telegram: proxy: socks5://:@proxy-host:1080 ``` - Node 22+ usa `autoSelectFamily=true` de forma predeterminada (excepto WSL2). El orden de resultados DNS de Telegram respeta `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, luego `channels.telegram.network.dnsResultOrder`, luego el valor predeterminado del proceso como `NODE_OPTIONS=--dns-result-order=ipv4first`; si no aplica ninguno, Node 22+ recurre a `ipv4first`. - Si tu host es WSL2 o funciona explícitamente mejor con comportamiento solo IPv4, fuerza la selección de familia: ```yaml channels: telegram: network: autoSelectFamily: false ``` - Las respuestas del rango de referencia RFC 2544 (`198.18.0.0/15`) ya están permitidas para descargas de medios de Telegram de forma predeterminada. Si un proxy fake-IP de confianza o transparente reescribe `api.telegram.org` a alguna otra dirección privada/interna/de uso especial durante descargas de medios, puedes optar por la omisión solo para Telegram: ```yaml channels: telegram: network: dangerouslyAllowPrivateNetwork: true ``` - La misma opción está disponible por cuenta en `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - Si tu proxy resuelve hosts de medios de Telegram en `198.18.x.x`, deja primero desactivada la marca peligrosa. Los medios de Telegram ya permiten el rango de referencia RFC 2544 de forma predeterminada. `channels.telegram.network.dangerouslyAllowPrivateNetwork` debilita las protecciones SSRF de medios de Telegram. Úsalo solo para entornos de proxy de confianza controlados por el operador, como enrutamiento fake-IP de Clash, Mihomo o Surge cuando sinteticen respuestas privadas o de uso especial fuera del rango de referencia RFC 2544. Déjalo desactivado para acceso normal de Telegram a internet público. - Anulaciones de entorno (temporales): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - Valida las respuestas DNS: ```bash dig +short api.telegram.org A dig +short api.telegram.org AAAA ``` Más ayuda: [Solución de problemas de canales](/es/channels/troubleshooting). ## Referencia de configuración Referencia principal: [Referencia de configuración - Telegram](/es/gateway/config-channels#telegram). - inicio/autenticación: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` debe apuntar a un archivo normal; los enlaces simbólicos se rechazan) - control de acceso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de nivel superior (`type: "acp"`) - aprobaciones de ejecución: `execApprovals`, `accounts.*.execApprovals` - comando/menú: `commands.native`, `commands.nativeSkills`, `customCommands` - hilos/respuestas: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` - transmisión: `streaming` (vista previa), `streaming.preview.toolProgress`, `blockStreaming` - formato/entrega: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - medios/red: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` - raíz de API personalizada: `apiRoot` (solo raíz de API de bot; no incluyas `/bot`) - Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - acciones/capacidades: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - reacciones: `reactionNotifications`, `reactionLevel` - errores: `errorPolicy`, `errorCooldownMs` - escrituras/historial: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` Precedencia multicuenta: cuando se configuran dos o más ID de cuenta, establece `channels.telegram.defaultAccount` (o incluye `channels.telegram.accounts.default`) para hacer explícito el enrutamiento predeterminado. De lo contrario, OpenClaw recurre al primer ID de cuenta normalizado y `openclaw doctor` advierte. Las cuentas con nombre heredan `channels.telegram.allowFrom` / `groupAllowFrom`, pero no los valores de `accounts.default.*`. ## Relacionado Empareja un usuario de Telegram con el Gateway. Comportamiento de lista de permitidos para grupos y temas. Enruta mensajes entrantes a agentes. Modelo de amenazas y endurecimiento. Asigna grupos y temas a agentes. Diagnósticos entre canales.