Telegram

• desactiva el modo de privacidad mediante /setprivacy, o
• convierte el bot en administrador del grupo.

• /setjoingroups — permitir/denegar agregados a grupos
• /setprivacy — comportamiento de visibilidad de grupo

• channels.telegram.streaming es off | partial | block | progress (predeterminado: partial)
• las vistas previas cortas de respuesta inicial se atenúan con debounce y luego se materializan tras una demora acotada si la ejecución sigue activa
• progress mantiene un borrador de estado editable para el progreso de herramientas, muestra la etiqueta de estado estable cuando llega actividad de respuesta antes del progreso de herramientas, lo borra al completarse 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: raw (predeterminado) o status (solo etiqueta de herramienta)
• streaming.progress.commentary (predeterminado: false) habilita texto de comentario/preámbulo del asistente en el borrador temporal de progreso
• se detectan channels.telegram.streamMode heredado, valores booleanos de streaming y claves retiradas de vista previa de borrador nativo; ejecuta openclaw doctor --fix para migrarlos

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

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

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

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

• setMyCommands failed con BOT_COMMANDS_TOO_MUCH después de un reintento de recorte significa que el menú aún se desborda; reduce los comandos de Plugin, Skills o personalizados, o desactiva channels.telegram.commands.native.
• Si deleteWebhook, deleteMyCommands o setMyCommands fallan con 404: Not Found mientras los comandos directos de curl de Bot API funcionan, normalmente significa que channels.telegram.apiRoot se configuró con el endpoint completo /bot<TOKEN>. apiRoot debe ser solo la raíz de Bot API; openclaw doctor --fix elimina un /bot<TOKEN> final accidental.
• getMe returned 401 significa que Telegram rechazó el token de bot configurado. Actualiza botToken, tokenFile o TELEGRAM_BOT_TOKEN (cuenta predeterminada) con el token actual de BotFather; OpenClaw se detiene antes del sondeo, así que esto no se informa como un fallo 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)

1. /pair genera un código de configuración
2. pega el código en la app de iOS
3. /pair pending enumera las solicitudes pendientes (incluidos rol/alcances)
4. aprueba: /pair approve <requestId>, /pair approve (única solicitud pendiente) o /pair approve latest

• 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 solo de botones actualizan el marcado de respuesta)
• createForumTopic (chatId, name, iconColor opcional, iconCustomEmojiId)

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

​

Mensajes de audio

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

​

Mensajes de video

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

​

Stickers

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

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

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

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

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• reserva de emoji de identidad del agente (agents.list[].identity.emoji, o ”👀”)

• channels.telegram.textChunkLimit predeterminado 4000; 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 medios entrantes y salientes.
• channels.telegram.mediaGroupFlushMs (predeterminado 500, rango 10-60000) controla cuánto tiempo se almacenan en búfer los álbumes/grupos de medios antes de que OpenClaw los despache como un solo mensaje entrante. Auméntalo si las partes del álbum llegan tarde; redúcelo para disminuir la latencia de respuesta al álbum.
• channels.telegram.timeoutSeconds sobrescribe el timeout del cliente de API (se aplica el predeterminado de grammY si no se establece). Los clientes de bot limitan los valores configurados por debajo de la protección de solicitud saliente de texto/escritura de 60 segundos para que grammY no aborte la entrega de respuestas visibles antes de que puedan ejecutarse la protección de transporte y la reserva de OpenClaw. Long polling todavía usa una protección de solicitud getUpdates de 45 segundos para que los polls inactivos no queden abandonados indefinidamente.
• channels.telegram.pollingStallThresholdMs tiene un valor predeterminado de 120000; ajusta entre 30000 y 600000 solo para reinicios por bloqueo de polling falsos positivos.
• el historial de contexto de grupo usa channels.telegram.historyLimit o messages.groupChat.historyLimit (predeterminado 50); 0 lo deshabilita.
• el contexto suplementario de respuesta/cita/reenvío se normaliza en una única ventana de contexto de conversación seleccionada cuando el gateway ha observado los mensajes padre; la caché de mensajes observados vive en el estado del Plugin SQLite de OpenClaw, y openclaw doctor --fix importa sidecars heredados. Telegram solo incluye un reply_to_message superficial por actualización, por lo que las cadenas más antiguas que la caché quedan limitadas a esa carga útil.
• Las listas de permitidos de Telegram controlan principalmente quién puede activar el agente, no son un límite completo de redacción de contexto suplementario.
• Historial de DM: channels.telegram.dmHistoryLimit, channels.telegram.dms["<user_id>"].historyLimit.
• channels.telegram.retry se aplica a los helpers de envío de Telegram (CLI/herramientas/acciones) para errores de API saliente recuperables. La entrega de respuesta final entrante usa un reintento de envío seguro acotado para fallos previos a la conexión, pero no reintenta envoltorios de red ambiguos posteriores al envío que podrían duplicar mensajes visibles.

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"

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

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

• 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 avisa cuando la configuración espera mensajes de grupo sin mención.
• openclaw channels status --probe comprueba ID numéricos explícitos de grupo; el comodín "*" no puede sondearse para pertenencia.
• Prueba rápida de sesión: /activation always.

• Cuando existe channels.telegram.groups, el grupo debe estar listado (o incluir "*").
• Verifica la pertenencia del bot al grupo.
• Revisa openclaw logs --follow para ver 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 de grupo es open.
• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa que el menú nativo tiene demasiadas entradas; reduce los comandos de plugin/Skills/personalizados o deshabilita los menús nativos.
• Las llamadas de inicio deleteMyCommands / setMyCommands y las llamadas de escritura sendChatAction están limitadas y se reintentan una vez mediante el fallback de transporte de Telegram en caso de timeout de solicitud. Los errores persistentes de red/fetch suelen significar que DNS/HTTPS hacia api.telegram.org no es accesible.

• getMe returned 401 es un fallo de autenticación de Telegram para el token de bot configurado. Vuelve a copiar o regenera el token en BotFather y luego actualiza 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 “no existe ningún Webhook” solo diferiría el mismo fallo de token incorrecto a una llamada de API posterior.

• Node 22+ con un fetch/proxy personalizado puede activar comportamiento de aborto inmediato si los tipos de AbortSignal no coinciden.
• Algunos hosts resuelven api.telegram.org a IPv6 primero; una salida IPv6 defectuosa causa fallos intermitentes de API.
• Los logs con TypeError: fetch failed o Network request for 'getUpdates' failed! se reintentan como errores de red recuperables.
• Durante el inicio de polling, OpenClaw reutiliza el sondeo getMe de inicio correcto para grammY, de modo que el ejecutor no necesita un segundo getMe antes del primer getUpdates.
• Si deleteWebhook falla con un error de red transitorio durante el inicio de polling, OpenClaw continúa con long polling en lugar de hacer otra llamada de plano de control previa al polling. Un Webhook aún activo aparece entonces como conflicto de getUpdates; OpenClaw reconstruye el transporte y reintenta la limpieza del Webhook.
• Si los sockets de Telegram se reciclan en una cadencia fija corta, comprueba si channels.telegram.timeoutSeconds es bajo: los clientes de bot restringen los valores configurados por debajo de los guardas de solicitud saliente y getUpdates, pero versiones antiguas podían abortar cada sondeo o respuesta cuando esto se configuraba por debajo de esos guardas.
• Polling stall detected en los logs significa que OpenClaw reinicia el polling y reconstruye el transporte después de 120 segundos sin liveness de long-poll completada de forma predeterminada.
• openclaw channels status --probe y openclaw doctor avisan cuando una cuenta de polling en ejecución no ha completado getUpdates después de la gracia de inicio, una cuenta de Webhook en ejecución no ha completado setWebhook después de la gracia de inicio, o la última actividad correcta del transporte de polling está obsoleta.
• Aumenta channels.telegram.pollingStallThresholdMs solo cuando las llamadas getUpdates de larga duración están sanas pero tu host sigue informando reinicios falsos por bloqueo de polling. Los bloqueos persistentes suelen apuntar a 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 Bot API: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY y variantes en minúsculas. NO_PROXY / no_proxy aún puede omitir api.telegram.org.
• Si OPENCLAW_PROXY_URL está configurado para un entorno de servicio y no hay ninguna variable de entorno de proxy estándar presente, Telegram también usa esa URL para el transporte de Bot API.
• En hosts VPS con salida directa/TLS inestable, enruta las llamadas a la API de Telegram mediante un proxy:

channels:
  telegram:
    proxy: socks5://<user>:<password>@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 (por ejemplo NODE_OPTIONS=--dns-result-order=ipv4first), y recurre a ipv4first en Node 22+ si no aplica ninguno.
• En WSL2, o cuando el comportamiento solo IPv4 funciona mejor, fuerza la selección de familia:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Las respuestas del rango de benchmark RFC 2544 (198.18.0.0/15) ya están permitidas para descargas de medios de Telegram de forma predeterminada. Si un fake-IP o proxy transparente de confianza reescribe api.telegram.org a alguna otra dirección privada/interna/de uso especial durante descargas de medios, habilita el bypass solo para Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• La misma habilitación está disponible por cuenta en channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Si tu proxy resuelve hosts de medios de Telegram a 198.18.x.x, deja primero desactivada la marca peligrosa: ese rango ya está permitido de forma predeterminada.

• Sobrescrituras temporales de entorno: OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first.
• Valida las respuestas DNS:

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