Telegram

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

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

• channels.telegram.streaming es off | partial | block | progress (valor predeterminado: partial)
• las vistas previas breves de la respuesta inicial se retrasan mediante antirrebote y luego se materializan tras una demora limitada 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 se produce actividad de respuesta antes que 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 o progreso reutilizan el mismo mensaje de vista previa editado (valor predeterminado: true cuando la transmisión de la vista previa está activa)
• streaming.preview.commandText controla los detalles de comandos y 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 el texto de comentarios o preámbulo del asistente en el borrador temporal de progreso
• se detectan el valor heredado channels.telegram.streamMode, los valores booleanos de streaming y las claves retiradas de vista previa de borradores nativos; ejecute 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: "Copia de seguridad de Git" },
        { command: "generate", description: "Crear una imagen" },
      ],
    },
  },
}

• setMyCommands failed con BOT_COMMANDS_TOO_MUCH después de un reintento de recorte significa que el menú sigue superando el límite; reduzca los comandos de plugins, Skills o personalizados, o desactive channels.telegram.commands.native.
• Si deleteWebhook, deleteMyCommands o setMyCommands fallan con 404: Not Found mientras los comandos curl directos de la API de bots funcionan, suele significar que channels.telegram.apiRoot se configuró con el endpoint completo /bot<TOKEN>. apiRoot debe ser únicamente la raíz de la API de bots; openclaw doctor --fix elimina un /bot<TOKEN> final accidental.
• 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, por lo que esto no se notifica como un fallo de limpieza del Webhook.
• setMyCommands failed con errores de red o recuperación suele significar que el DNS o 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. pegue el código en la aplicación de iOS
3. /pair pending muestra las solicitudes pendientes (incluidos el rol y los ámbitos)
4. para aprobar: /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 integrados presentation opcionales; las ediciones que solo afectan a 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 vídeo

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

​

Ubicaciones y lugares

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  location: {
    latitude: 48.858844,
    longitude: 2.294351,
    accuracy: 12,
    name: "Torre Eiffel",
    address: "Campo de Marte, París",
  },
}

​

Stickers

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

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

{
  action: "sticker-search",
  channel: "telegram",
  query: "gato saludando",
  limit: 5,
}

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

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• emoji alternativo de la identidad del agente (agents.entries.*.identity.emoji; de lo contrario, ”👀”)

• 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.
• el historial de contexto de grupo usa channels.telegram.historyLimit o messages.groupChat.historyLimit (valor predeterminado: 50); 0 lo desactiva.
• el contexto complementario de respuestas, citas y reenvíos 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 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 complementario.
• historial de mensajes directos: channels.telegram.dmHistoryLimit, channels.telegram.dms["<user_id>"].historyLimit.

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" las habilita cuando se puede resolver al menos un aprobador)
• channels.telegram.execApprovals.approvers (recurre a los ID numéricos de propietarios de commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (valor predeterminado) | channel | both
• agentFilter, sessionFilter

• Si requireMention=false, el modo de privacidad de Telegram debe permitir la visibilidad completa: BotFather /setprivacy -> Disable; después, 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 ID numéricos de grupo explícitos; 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 incluir "*").
• Verifique que el bot pertenezca al grupo.
• Revise openclaw logs --follow para conocer los motivos de omisión.

• Autorice la identidad del remitente (mediante emparejamiento o el valor numérico allowFrom); 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; reduzca los comandos de plugins, Skills o personalizados, o desactive los menús nativos.
• Las llamadas de inicio deleteMyCommands / setMyCommands y las llamadas de escritura sendChatAction tienen límites y vuelven a intentarse una vez mediante el transporte alternativo de Telegram cuando la solicitud agota el tiempo de espera. Los errores persistentes de red o recuperación suelen significar que no se puede acceder mediante DNS/HTTPS a api.telegram.org.

• getMe returned 401 es un fallo de autenticación de Telegram para el token de bot configurado. Vuelva a copiar o generar 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 «no existe ningún Webhook» solo aplazaría el mismo fallo del token incorrecto hasta una llamada posterior a la API.

• Node 22+ con una implementación personalizada de recuperación o proxy puede provocar cancelaciones inmediatas si los tipos de AbortSignal no coinciden.
• Algunos hosts resuelven primero api.telegram.org como IPv6; una salida IPv6 defectuosa provoca fallos intermitentes de la API.
• Los registros con TypeError: fetch failed o Network request for 'getUpdates' failed! se vuelven a intentar como errores de red recuperables.
• Durante el inicio del sondeo, OpenClaw reutiliza para grammY la comprobación de inicio getMe completada correctamente, 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 el sondeo prolongado en lugar de realizar otra llamada al plano de control previa al sondeo. Un Webhook aún activo aparece entonces como un conflicto getUpdates; OpenClaw reconstruye el transporte y vuelve a intentar la limpieza del Webhook.
• Polling stall detected en los registros significa que OpenClaw reinicia el sondeo y reconstruye el transporte después de 120 segundos sin completar la comprobación de actividad del sondeo prolongado 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 período de gracia de inicio, una cuenta de Webhook en ejecución no ha completado setWebhook después del período de gracia de inicio, o la última actividad correcta del transporte de sondeo está obsoleta.
• Telegram respeta las variables de entorno de proxy del proceso para el transporte de la API del bot: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY y sus variantes en minúsculas. NO_PROXY / no_proxy aún pueden omitir api.telegram.org.
• Si OPENCLAW_PROXY_URL está establecido para un entorno de servicio y no existe ninguna variable de entorno de proxy estándar, Telegram también usa esa URL para el transporte de la API del bot.
• 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+ usa autoSelectFamily=true de forma predeterminada (excepto en WSL2). El orden de los resultados DNS de Telegram respeta OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, después channels.telegram.network.dnsResultOrder y, por último, el valor predeterminado del proceso (por ejemplo, NODE_OPTIONS=--dns-result-order=ipv4first); si ninguno se aplica, recurre a ipv4first en Node 22+.
• En WSL2, o cuando el comportamiento exclusivo de IPv4 funciona mejor, fuerce la selección de familia:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Las respuestas del intervalo de referencia de RFC 2544 (198.18.0.0/15) ya se permiten de forma predeterminada para las descargas de contenido multimedia de Telegram. Si un proxy de IP falsa o transparente de confianza reescribe api.telegram.org como alguna otra dirección privada, interna o de uso especial durante las descargas de contenido multimedia, habilite la omisión exclusiva de 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 dentro de 198.18.x.x, mantenga primero desactivada la opción peligrosa: ese intervalo ya se permite de forma predeterminada.

• Anulaciones temporales del 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 A
dig +short api.telegram.org AAAA