Telegram

Los bots de Telegram usan de forma predeterminada el modo de privacidad, que limita los mensajes de grupo que reciben.

Para ver todos los mensajes del grupo:

• desactive el modo de privacidad mediante /setprivacy, o
• convierta al bot en administrador del grupo.

Después de cambiar el modo de privacidad, elimine y vuelva a añadir 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 del grupo, lo que resulta útil para un comportamiento de grupo siempre activo.

• /setjoingroups — permitir/denegar que se añada el bot a grupos
• /setprivacy — comportamiento de visibilidad en grupos

La misma configuración está disponible en la aplicación web de BotFather si se prefiere una interfaz de usuario en lugar de comandos de chat.

OpenClaw transmite respuestas parciales en tiempo real en chats directos, grupos y temas: envía un mensaje de vista previa, ejecuta editMessageText repetidamente y finaliza en el mismo lugar.

• channels.telegram.streaming es off | partial | block | progress (valor predeterminado: partial)
• las vistas previas iniciales de respuestas breves se agrupan mediante antirrebote y, después, se materializan tras un retraso limitado si la ejecución sigue activa
• progress mantiene un único borrador de estado editable para el progreso de las herramientas, muestra la etiqueta de estado estable cuando la actividad de respuesta llega antes que el progreso de las herramientas, lo elimina 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 (valor predeterminado: true cuando la transmisión de vista previa está activa)
• streaming.preview.commandText controla los detalles de comandos/ejecución dentro de esas líneas: raw (valor predeterminado) o status (solo la etiqueta de la herramienta)
• streaming.progress.commentary (valor predeterminado: false) habilita los comentarios o el preámbulo del asistente en el borrador temporal de progreso
• se detectan channels.telegram.streamMode, los valores booleanos de streaming y las claves retiradas de vista previa de borradores nativos; ejecute openclaw doctor --fix para migrarlos

Las líneas de progreso de herramientas son las actualizaciones breves de estado que se muestran mientras se ejecutan las herramientas (ejecución de comandos, lectura de archivos, actualizaciones de planificación, resúmenes de parches y preámbulo/comentarios de Codex en el modo de servidor de aplicaciones). Telegram las mantiene activadas de forma predeterminada (coincide con el comportamiento publicado desde v2026.4.22 en adelante).

Mantener las ediciones de vista previa de la respuesta, pero ocultar las líneas de progreso de herramientas:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "toolProgress": false }      }    }  }}

Mantener visible el progreso de las herramientas, pero ocultar el texto de comandos/ejecución:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "commandText": "status" }      }    }  }}

El modo progress muestra el progreso de las herramientas sin editar la respuesta final dentro de ese mensaje. Coloque la directiva del texto de comandos bajo streaming.progress:

{  "channels": {    "telegram": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

streaming.mode: "off" desactiva las ediciones de vista previa y suprime los mensajes genéricos de herramientas/progreso en lugar de enviarlos como mensajes de estado independientes; las solicitudes de aprobación, el contenido multimedia y los errores se siguen enviando mediante la entrega final normal. streaming.preview.toolProgress: false conserva únicamente las ediciones de vista previa de la respuesta.

Para las respuestas que solo contienen texto: las vistas previas breves reciben la edición final en el mismo lugar; las respuestas finales largas que se dividen en varios mensajes reutilizan la vista previa como primer fragmento y después envían únicamente el resto; las respuestas finales del modo de progreso eliminan el borrador de estado y usan la entrega final normal; si la edición final falla antes de que se confirme la finalización, OpenClaw recurre a la entrega final normal y elimina la vista previa obsoleta. Para las respuestas complejas (cargas útiles multimedia), OpenClaw siempre recurre a la entrega final normal y elimina la vista previa.

La transmisión de vista previa y la transmisión por bloques son mutuamente excluyentes: cuando la transmisión por bloques está habilitada explícitamente, OpenClaw omite la transmisión de vista previa para evitar una transmisión duplicada.

Razonamiento: /reasoning stream transmite el razonamiento en la vista previa en vivo durante la generación y, después, elimina la vista previa del razonamiento tras la entrega final (use /reasoning on para mantenerla visible). La respuesta final se envía sin el texto del razonamiento.

De forma predeterminada, el texto saliente utiliza mensajes HTML estándar de Telegram, legibles en los clientes actuales: negrita, cursiva, enlaces, código, contenido oculto y citas; no bloques exclusivos del formato enriquecido de la API de bots 10.1 (tablas nativas, detalles, contenido multimedia enriquecido y fórmulas).

Habilitar los mensajes enriquecidos de la API de bots 10.1:

{channels: {telegram: {  richMessages: true,},},}

Cuando se habilita: se informa al agente de que hay mensajes enriquecidos disponibles para este bot o esta cuenta; el texto Markdown se representa mediante la representación intermedia de Markdown de OpenClaw como HTML enriquecido de Telegram; las cargas útiles explícitas de HTML enriquecido conservan las etiquetas compatibles de la API de bots 10.1 (encabezados, tablas, detalles, contenido multimedia enriquecido y fórmulas); las leyendas del contenido multimedia siguen usando leyendas HTML de Telegram (los mensajes enriquecidos no sustituyen las leyendas y estas tienen un límite de 1024 caracteres).

Esto mantiene el texto del modelo alejado de los símbolos especiales del Markdown enriquecido de Telegram, por lo que importes como $400-600K no se interpretan como fórmulas matemáticas. El texto enriquecido largo se divide automáticamente según los límites de Telegram. Las tablas que superan el límite de 20 columnas recurren a un bloque de código.

Valor predeterminado: desactivado, por compatibilidad con los clientes; algunos clientes actuales de escritorio, web, Android y de terceros muestran como no compatibles los mensajes enriquecidos aceptados. Mantenga esta opción desactivada a menos que todos los clientes utilizados con el bot puedan representarlos. /status muestra si los mensajes enriquecidos están activados o desactivados en la sesión actual.

Las vistas previas de enlaces están activadas de forma predeterminada. channels.telegram.linkPreview: false desactiva la detección automática de entidades para el texto enriquecido.

El menú de comandos de Telegram se registra al iniciar mediante setMyCommands. commands.native: "auto" habilita los comandos nativos para Telegram.

Añadir entradas personalizadas al menú de comandos:

{channels: {telegram: {  customCommands: [    { command: "backup", description: "Copia de seguridad de Git" },    { command: "generate", description: "Crear una imagen" },  ],},},}

Reglas: los nombres se normalizan (se elimina la / inicial y se convierten a minúsculas); patrón válido: a-z, 0-9, _; longitud: 1-32; los comandos personalizados no pueden anular los comandos nativos; los conflictos y duplicados se omiten y se registran.

Los comandos personalizados son únicamente entradas de menú: no implementan automáticamente ningún comportamiento. Los comandos de Plugin/skill pueden seguir funcionando al escribirlos aunque no aparezcan en el menú de Telegram. Si se desactivan los comandos nativos, se eliminan los integrados; los comandos personalizados o de Plugin aún pueden registrarse si están configurados.

Errores comunes de configuración:

• setMyCommands failed con BOT_COMMANDS_TOO_MUCH después de un reintento de recorte significa que el menú aún excede el límite; reduzca los comandos de plugins/skills/personalizados o desactive channels.telegram.commands.native.
• Si deleteWebhook, deleteMyCommands o setMyCommands fallan con 404: Not Found mientras que los comandos curl directos de la API de bots funcionan, normalmente significa que channels.telegram.apiRoot se estableció en el extremo completo /bot<TOKEN>. apiRoot debe ser únicamente la raíz de la API de bots; openclaw doctor --fix elimina un sufijo /bot<TOKEN> añadido accidentalmente.
• getMe returned 401 significa que Telegram rechazó el token de bot configurado. Actualice botToken, tokenFile o TELEGRAM_BOT_TOKEN (cuenta predeterminada) con el token actual de BotFather; OpenClaw se detiene antes del sondeo para que esto no se informe como un error de limpieza del Webhook.
• setMyCommands failed con errores de red o recuperación normalmente significa que el DNS/HTTPS saliente hacia api.telegram.org está bloqueado.

Comandos de vinculación de dispositivos (Plugin device-pair)

Cuando está instalado:

1. /pair genera un código de configuración
2. pegue el código en la aplicación para iOS
3. /pair pending enumera las solicitudes pendientes (incluidos la función y los ámbitos)
4. aprobar: /pair approve <requestId>, /pair approve (única solicitud pendiente) o /pair approve latest

Si un dispositivo vuelve a intentarlo con datos de autenticación modificados (función, ámbitos o clave pública), la solicitud pendiente anterior se sustituye por otra con un nuevo requestId; vuelva a ejecutar /pair pending antes de aprobarla.

Más información: Vinculación.

Configurar el ámbito del teclado en línea:

{channels: {telegram: {  capabilities: {    inlineButtons: "allowlist",  },},},}

Anulación por cuenta:

{channels: {telegram: {  accounts: {    main: {      capabilities: {        inlineButtons: "allowlist",      },    },  },},},}

Ámbitos: off, dm, group, all, allowlist (valor predeterminado). El valor heredado capabilities: ["inlineButtons"] se asigna a "all".

Ejemplo de acción de mensaje:

{action: "send",channel: "telegram",to: "123456789",message: "Elija una opción:",buttons: [[  { text: "Sí", callback_data: "yes" },  { text: "No", callback_data: "no" },],[{ text: "Cancelar", callback_data: "cancel" }],],}

Ejemplo de botón de Mini App:

{action: "send",channel: "telegram",to: "123456789",message: "Abrir aplicación:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "Iniciar", web_app: { url: "https://example.com/app" } }],  },],},}

Los botones web_app solo funcionan en chats privados entre un usuario y el bot.

Los clics de devolución de llamada que no reclama un controlador interactivo de Plugin registrado se pasan al agente como texto: callback_data: <value>.

Acciones:

• sendMessage (to, content, mediaUrl opcional, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content o caption, botones en línea presentation opcionales; las ediciones que solo contienen botones actualizan el marcado de respuesta)
• createForumTopic (chatId, name, iconColor opcional, iconCustomEmojiId)

Alias prácticos: send, react, delete, edit, sticker, sticker-search, topic-create.

Control de acceso: channels.telegram.actions.sendMessage, deleteMessage, reactions, sticker (valor predeterminado: deshabilitado). edit, createForumTopic y editForumTopic están habilitados de forma predeterminada sin un control específico. Los envíos en tiempo de ejecución usan la instantánea activa de configuración/secretos del inicio o la recarga, por lo que las rutas de acción no vuelven a resolver los valores SecretRef en cada envío.

Semántica de eliminación de reacciones: /tools/reactions.

Etiquetas explícitas de hilos de respuesta en la salida generada:

• [[reply_to_current]] — responde al mensaje que activó la acción
• [[reply_to:<id>]] — responde a un ID de mensaje específico

channels.telegram.replyToMode: off (valor predeterminado), first, all.

Cuando los hilos de respuesta están habilitados y el texto o pie de foto original está disponible, OpenClaw añade automáticamente un fragmento de cita nativo. Telegram limita el texto de las citas nativas a 1024 unidades de código UTF-16; los mensajes más largos se citan desde el principio y se recurre a una respuesta simple si Telegram rechaza la cita.

off solo deshabilita los hilos de respuesta implícitos; las etiquetas explícitas [[reply_to_*]] se siguen respetando.

Supergrupos con foro: las claves de sesión de los temas añaden :topic:<threadId>; las respuestas y el indicador de escritura se dirigen al hilo del tema; la ruta de configuración del tema es channels.telegram.groups.<chatId>.topics.<threadId>.

El tema general (threadId=1) es un caso especial: los envíos de mensajes omiten message_thread_id (Telegram rechaza sendMessage(...thread_id=1) con "thread not found"), pero las acciones de escritura siguen incluyendo message_thread_id (es necesario empíricamente para que aparezca el indicador de escritura).

Las entradas de los temas heredan la configuración del grupo salvo que se sobrescriba (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId es exclusivo del tema y no se hereda de los valores predeterminados del grupo. topics."*" establece los valores predeterminados de todos los temas de ese grupo; los ID de tema exactos siguen teniendo prioridad sobre "*".

Enrutamiento de agentes por tema: cada tema puede dirigirse a un agente diferente mediante agentId en la configuración del tema, lo que le proporciona su propio espacio de trabajo, memoria y sesión:

{  channels: {    telegram: {      groups: {        "-1001234567890": {          topics: {            "1": { agentId: "main" },      // Tema general -> agente principal            "3": { agentId: "zu" },        // Tema de desarrollo -> agente zu            "5": { agentId: "coder" }      // Revisión de código -> agente coder          }        }      }    }  }}

Cada tema tiene entonces su propia clave de sesión, por ejemplo, agent:zu:telegram:group:-1001234567890:topic:3.

Vinculación persistente de temas ACP: los temas del foro pueden fijar sesiones del entorno ACP mediante vinculaciones tipadas de nivel superior (bindings[] con type: "acp", match.channel: "telegram", peer.kind: "group" y un ID que incluya el tema, como -1001234567890:topic:42). Actualmente se limita a los temas del foro en grupos y supergrupos. Consulte Agentes ACP.

Creación de ACP vinculada al hilo desde el chat: /acp spawn <agent> --thread here|auto vincula el tema actual a una nueva sesión ACP; los mensajes posteriores se dirigen directamente a ella y OpenClaw fija la confirmación de creación en el tema. Requiere channels.telegram.threadBindings.spawnSessions (valor predeterminado: true).

El contexto de la plantilla expone MessageThreadId e IsForum. Los chats de mensajes directos con message_thread_id conservan los metadatos de respuesta, pero solo usan claves de sesión compatibles con hilos cuando getMe de Telegram informa de has_topics_enabled: true. Las sustituciones retiradas dm.threadReplies y direct.*.threadReplies ya no existen; el modo de hilos de BotFather es la única fuente de verdad. Ejecute openclaw doctor --fix para eliminar las claves de configuración obsoletas.

Mensajes de audio

Telegram distingue las notas de voz de los archivos de audio. Valor predeterminado: comportamiento de archivo de audio; use la etiqueta [[audio_as_voice]] en la respuesta del agente para forzar el envío como nota de voz. Las transcripciones de notas de voz entrantes se presentan en el contexto del agente como texto no confiable generado por una máquina, pero la detección de menciones sigue usando la transcripción sin procesar para que los mensajes de voz sujetos a menciones sigan funcionando.

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/voice.ogg",asVoice: true,}

Mensajes de vídeo

Telegram distingue los archivos de vídeo de las notas de vídeo. Las notas de vídeo no admiten pies de foto; el texto proporcionado en el mensaje se envía por separado.

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/video.mp4",asVideoNote: true,}

Ubicaciones y lugares

Use la acción send existente con un único objeto location independiente. Las coordenadas envían un marcador nativo; si se añaden tanto name como address, se envía una tarjeta de lugar nativa. Los envíos de ubicación no se pueden combinar con texto de mensaje ni contenido multimedia.

{action: "send",channel: "telegram",to: "123456789",location: {latitude: 48.858844,longitude: 2.294351,accuracy: 12,name: "Eiffel Tower",address: "Champ de Mars, Paris",},}

Stickers

Entrantes: los archivos WEBP estáticos se descargan y procesan (marcador de posición <media:sticker>); los archivos TGS animados y los vídeos WEBM se omiten.

Campos de contexto del sticker: Sticker.emoji, Sticker.setName, Sticker.fileId, Sticker.fileUniqueId, Sticker.cachedDescription. Las descripciones se almacenan en caché en el estado SQLite del plugin de OpenClaw para reducir las llamadas repetidas de visión.

Habilite las acciones de stickers:

{channels: {telegram: {  actions: {    sticker: true,  },},},}

Envíe:

{action: "sticker",channel: "telegram",to: "123456789",fileId: "CAACAgIAAxkBAAI...",}

Busque stickers almacenados en caché:

{action: "sticker-search",channel: "telegram",query: "cat waving",limit: 5,}

Las reacciones de Telegram llegan como actualizaciones message_reaction, separadas de las cargas útiles de los mensajes. Cuando están habilitadas, OpenClaw pone en cola eventos del sistema como Telegram reaction added: 👍 by Alice (@alice) on msg 42.

• channels.telegram.reactionNotifications: off | own | all (valor predeterminado: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (valor predeterminado: minimal)

own significa únicamente las reacciones de los usuarios a los mensajes enviados por el bot (según el mejor esfuerzo mediante una caché de mensajes enviados). Los eventos de reacción siguen respetando los controles de acceso de Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); se descartan los remitentes no autorizados.

Telegram no proporciona identificadores de hilos en las actualizaciones de reacciones: los grupos que no son foros se dirigen a la sesión del chat grupal; los grupos de foro se dirigen a la sesión del tema general (:topic:1), no al tema exacto de origen.

allowed_updates para sondeo/webhook incluye message_reaction automáticamente.

ackReaction envía un emoji de confirmación mientras OpenClaw procesa un mensaje entrante. messages.ackReactionScope determina cuándo se envía.

Orden de resolución de emojis:

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• respaldo mediante el emoji de identidad del agente (agents.list[].identity.emoji; de lo contrario, "👀")

Telegram espera un emoji Unicode (por ejemplo, "👀"); use "" para desactivar la reacción en un canal o una cuenta.

Ámbito (messages.ackReactionScope, valor predeterminado "group-mentions"; actualmente no se puede sobrescribir por cuenta ni por canal de Telegram):

all (mensajes directos + grupos, incluidos los eventos ambientales de sala), direct (solo mensajes directos), group-all (todos los mensajes de grupo excepto los eventos ambientales de sala; sin mensajes directos), group-mentions (grupos cuando se menciona al bot; sin mensajes directos — valor predeterminado), off / none (desactivado).

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 grupos (migrate_to_chat_id, actualiza channels.telegram.groups) y /config set / /config unset (requiere que los comandos estén habilitados).

Para desactivarlas:

{channels: {telegram: {  configWrites: false,},},}

El modo predeterminado es el sondeo prolongado. Para el modo Webhook, establezca channels.telegram.webhookUrl y channels.telegram.webhookSecret; opcionalmente, webhookPath (valor predeterminado /telegram-webhook), webhookHost (valor predeterminado 127.0.0.1), webhookPort (valor predeterminado 8787) y webhookCertPath (certificado PEM autofirmado para configuraciones con IP directa o sin dominio).

En el modo de sondeo prolongado, OpenClaw conserva su marca de reinicio solo después de que una actualización se despacha correctamente; si un controlador falla, esa actualización puede volver a intentarse en el mismo proceso en lugar de marcarse como completada.

El agente de escucha local se vincula a 127.0.0.1:8787 de forma predeterminada. Para el ingreso público, coloque un proxy inverso delante del puerto local o establezca webhookHost: "0.0.0.0" de forma intencionada.

El modo Webhook valida las protecciones de la solicitud, el token secreto de Telegram y el cuerpo JSON; después, confirma la actualización en su cola de ingreso duradera antes de devolver un 200 vacío. La adopción duradera correcta incluye x-openclaw-delivery-accepted: durable; las respuestas de estado, enrutamiento, autenticación, validación y error de almacenamiento omiten este encabezado. Los proxies inversos y los controladores de host pueden exigir el encabezado para distinguir la adopción por parte de OpenClaw de un 200 vacío genérico, sin inferir la aceptación a partir del tiempo de respuesta.

A continuación, OpenClaw procesa la actualización de forma asíncrona mediante los mismos carriles del bot por chat y por tema que utiliza el sondeo prolongado, por lo que los turnos lentos del agente no retienen la confirmación de entrega de Telegram.

• channels.telegram.textChunkLimit tiene un valor predeterminado de 4000; streaming.chunkMode="newline" prioriza los límites de párrafo (líneas en blanco) antes de dividir por longitud.
• channels.telegram.mediaMaxMb (valor predeterminado: 100) limita el tamaño de los archivos multimedia entrantes y salientes.
• channels.telegram.mediaGroupFlushMs (valor predeterminado: 500, intervalo: 10-60000) controla cuánto tiempo se almacenan en búfer los álbumes o grupos multimedia antes de que OpenClaw los despache como un único mensaje entrante. Auméntelo si las partes del álbum llegan tarde; redúzcalo para disminuir la latencia de respuesta a los álbumes.
• channels.telegram.timeoutSeconds reemplaza el tiempo de espera del cliente de la API (se aplica el valor predeterminado de grammY si no se establece). Los clientes de bot limitan los valores configurados por debajo de la protección de 60 segundos para solicitudes salientes de texto o indicación de escritura, de modo que grammY no cancele la entrega de respuestas visibles antes de que puedan ejecutarse la protección de transporte y el mecanismo alternativo de OpenClaw. El sondeo largo sigue utilizando una protección de 45 segundos para las solicitudes getUpdates, de modo que los sondeos inactivos no se abandonen indefinidamente.
• channels.telegram.pollingStallThresholdMs tiene un valor predeterminado de 120000; ajústelo entre 30000 y 600000 únicamente si se producen reinicios por falsos positivos de bloqueo del sondeo.
• el historial de contexto de los grupos utiliza channels.telegram.historyLimit o messages.groupChat.historyLimit (valor predeterminado: 50); 0 lo desactiva.
• el contexto adicional de respuestas, citas y reenvíos se normaliza en una única ventana seleccionada de contexto de conversación cuando el Gateway ha observado los mensajes principales; la caché de mensajes observados reside en el estado SQLite del plugin de OpenClaw, y openclaw doctor --fix importa los archivos auxiliares heredados. Telegram solo incluye un reply_to_message superficial por actualización, por lo que las cadenas anteriores a la caché se limitan a esa carga útil.
• las listas de permitidos de Telegram controlan principalmente quién puede activar el agente, no constituyen un límite completo de ocultación del contexto adicional.
• Historial de mensajes directos: channels.telegram.dmHistoryLimit, channels.telegram.dms["<user_id>"].historyLimit.
• 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 la respuesta final entrante utiliza un reintento limitado de envío seguro para fallos previos a la conexión, pero no reintenta envoltorios de red ambiguos posteriores al envío que podrían duplicar mensajes visibles.

Los destinos de envío de la CLI y de la herramienta de mensajes aceptan un ID numérico de chat, un nombre de usuario o un destino de tema de foro:

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"

Las encuestas utilizan openclaw message poll y admiten temas de foro:

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

Opciones de encuesta exclusivas de Telegram: --poll-duration-seconds (5-600), --poll-anonymous, --poll-public, --thread-id (o un destino :topic:). --poll-option se repite entre 2 y 12 veces (límite de opciones de Telegram).

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 una entrega fijada cuando el bot puede fijar mensajes en ese chat, y --force-document para enviar imágenes, GIF y vídeos salientes como documentos en lugar de cargas comprimidas, animadas o de vídeo.

Control de acciones: channels.telegram.actions.sendMessage=false desactiva todos los mensajes salientes, incluidas las encuestas; channels.telegram.actions.poll=false desactiva la creación de encuestas, pero mantiene habilitados los envíos normales.

Telegram admite aprobaciones de ejecución en los mensajes directos de los aprobadores y, opcionalmente, puede publicar solicitudes en el chat o tema de origen. Los aprobadores deben ser IDs numéricos de usuario de Telegram.

• channels.telegram.execApprovals.enabled ("auto" las habilita cuando se puede resolver al menos un aprobador)
• channels.telegram.execApprovals.approvers (utiliza como alternativa los IDs numéricos de propietarios de commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (valor predeterminado) | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom, groupAllowFrom y defaultTo controlan quién puede comunicarse con el bot y dónde envía este las respuestas normales; no convierten a nadie en aprobador de ejecución. El primer emparejamiento aprobado por mensaje directo inicializa commands.ownerAllowFrom cuando aún no existe ningún propietario de comandos, por lo que las configuraciones con un solo propietario funcionan sin duplicar IDs en execApprovals.approvers.

La entrega en el canal muestra el texto del comando en el chat; habilite channel o both únicamente en grupos o temas de confianza. Cuando la solicitud llega a un tema de foro, OpenClaw conserva el tema para la solicitud de aprobación y el seguimiento. Las aprobaciones de ejecución caducan 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 el prefijo plugin: se resuelven mediante las aprobaciones de plugins; los demás se resuelven primero mediante las aprobaciones de ejecución.

Consulte Aprobaciones de ejecución.

• Si requireMention=false, el modo de privacidad de Telegram debe permitir visibilidad completa: BotFather /setprivacy -> Disable y, a continuación, elimine el bot del grupo y vuelva a añadirlo.
• openclaw channels status muestra una advertencia cuando la configuración espera mensajes de grupo sin mención.
• openclaw channels status --probe comprueba IDs numéricos explícitos de grupos; no se puede comprobar la pertenencia con el comodín "*".
• Prueba rápida de sesión: /activation always.

• Cuando existe channels.telegram.groups, el grupo debe aparecer en la lista (o esta debe incluir "*").
• Verifique la pertenencia del bot al grupo.
• Revise openclaw logs --follow para consultar los motivos de omisión.

• Autorice la identidad del remitente (mediante emparejamiento o un valor numérico en allowFrom); la autorización de comandos sigue aplicándose aunque la política del grupo sea open.
• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa que el menú nativo contiene demasiadas entradas; reduzca los comandos de plugins, Skills o personalizados, o desactive los menús nativos.
• Las llamadas de inicio deleteMyCommands / setMyCommands y las llamadas de indicación de escritura sendChatAction están limitadas y se reintentan una vez mediante el mecanismo alternativo de transporte de Telegram cuando se agota el tiempo de espera de la solicitud. Los errores persistentes de red o recuperación suelen indicar que no se puede acceder a api.telegram.org mediante DNS/HTTPS.

• getMe returned 401 es un fallo de autenticación de Telegram relacionado con el token de bot configurado. Vuelva a copiar o genere de nuevo el token en BotFather y, a continuación, actualice channels.telegram.botToken, tokenFile, accounts.<id>.botToken o TELEGRAM_BOT_TOKEN (cuenta predeterminada).
• deleteWebhook 401 Unauthorized durante el inicio también es un fallo de autenticación; tratarlo como si «no existiera ningún webhook» solo pospondría el mismo fallo de token incorrecto hasta una llamada posterior a la API.

• Node 22+ con un sistema personalizado de recuperación o proxy puede provocar cancelaciones inmediatas si los tipos de AbortSignal no coinciden.
• Algunos hosts resuelven primero api.telegram.org mediante IPv6; una salida IPv6 defectuosa provoca fallos intermitentes de la API.
• Los registros con TypeError: fetch failed o Network request for 'getUpdates' failed! se reintentan como errores de red recuperables.
• Durante el inicio del sondeo, OpenClaw reutiliza para grammY la comprobación correcta de inicio mediante getMe, de modo que el ejecutor no necesite un segundo getMe antes del primer getUpdates.
• Si deleteWebhook falla debido a un error transitorio de red durante el inicio del sondeo, OpenClaw continúa con el sondeo largo en lugar de realizar otra llamada al plano de control previa al sondeo. Si el webhook sigue activo, se manifiesta como un conflicto de getUpdates; OpenClaw reconstruye el transporte y reintenta la limpieza del webhook.
• Si los sockets de Telegram se reciclan con una cadencia fija y breve, compruebe si channels.telegram.timeoutSeconds tiene un valor bajo: los clientes de bot limitan los valores configurados por debajo de las protecciones de las solicitudes salientes y de getUpdates, pero las versiones anteriores podían cancelar cada sondeo o respuesta cuando este valor se establecía por debajo de dichas protecciones.
• Polling stall detected en los registros significa que OpenClaw reinicia el sondeo y reconstruye el transporte después de 120 segundos sin actividad vital completada del sondeo largo de forma predeterminada.
• openclaw channels status --probe y openclaw doctor muestran una advertencia cuando una cuenta de sondeo en ejecución no ha completado getUpdates después del periodo de gracia del inicio, una cuenta de webhook en ejecución no ha completado setWebhook después del periodo de gracia del inicio o la última actividad correcta del transporte de sondeo está obsoleta.
• Aumente channels.telegram.pollingStallThresholdMs únicamente cuando las llamadas de larga duración a getUpdates sean correctas, pero el host siga informando de falsos reinicios por bloqueo del sondeo. Los bloqueos persistentes suelen indicar problemas de proxy, DNS, IPv6 o salida TLS hacia api.telegram.org.
• Telegram respeta las variables de entorno de proxy del proceso para el transporte de la API de bots: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY y sus variantes en minúsculas. NO_PROXY / no_proxy aún pueden omitir el proxy para api.telegram.org.
• Si OPENCLAW_PROXY_URL está establecida para un entorno de servicio y no existe ninguna variable de entorno de proxy estándar, Telegram también utiliza esa URL para el transporte de la API de bots.
• En hosts VPS con salida directa o TLS inestables, enrute las llamadas a la API de Telegram mediante un proxy:

channels:telegram:proxy: socks5://<user>:<password>@proxy-host:1080

• Node 22+ utiliza autoSelectFamily=true de forma predeterminada (excepto en WSL2). El orden de resultados DNS de Telegram respeta primero OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, después channels.telegram.network.dnsResultOrder y luego el valor predeterminado del proceso (por ejemplo, NODE_OPTIONS=--dns-result-order=ipv4first); si no se aplica ninguno, utiliza ipv4first como alternativa en Node 22+.
• En WSL2, o cuando el comportamiento exclusivo de IPv4 funcione mejor, fuerce la selección de familia:

channels:telegram:network:  autoSelectFamily: false

• Las respuestas del rango de referencia RFC 2544 (198.18.0.0/15) ya se permiten de forma predeterminada para las descargas de contenido multimedia de Telegram. Si una IP falsa de confianza o un proxy transparente reescribe api.telegram.org a alguna otra dirección privada, interna o de uso especial durante las descargas de contenido multimedia, active de forma explícita la omisión exclusiva para Telegram:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• La misma opción está disponible por cuenta en channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Si el proxy resuelve los hosts de contenido multimedia de Telegram como direcciones 198.18.x.x, deje primero desactivada la opción peligrosa, ya que ese rango se permite de forma predeterminada.

• Anulaciones temporales mediante variables de entorno: OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first.
• Valide las respuestas DNS:

dig +short api.telegram.org Adig +short api.telegram.org AAAA