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

• /setjoingroups para permitir/denegar añadidos a grupos
• /setprivacy para el comportamiento de visibilidad en grupos

• chats directos: mensaje de vista previa + editMessageText
• grupos/temas: mensaje de vista previa + editMessageText

• channels.telegram.streaming es off | partial | block | progress (predeterminado: partial)
• progress se asigna a partial en Telegram (compatibilidad con nomenclatura entre canales)
• los valores heredados channels.telegram.streamMode y booleanos streaming se asignan automáticamente

• MD: OpenClaw conserva el mismo mensaje de vista previa y realiza una edición final en el mismo lugar (sin segundo mensaje)
• grupo/tema: OpenClaw conserva el mismo mensaje de vista previa y realiza una edición final en el mismo lugar (sin segundo mensaje)

• /reasoning stream envía el razonamiento a la vista previa en vivo mientras se genera
• la respuesta final se envía sin el texto del razonamiento

• El texto tipo Markdown se renderiza como HTML seguro para Telegram.
• El HTML sin procesar del modelo se escapa para reducir los fallos de análisis de Telegram.
• Si Telegram rechaza el HTML analizado, OpenClaw reintenta como texto sin formato.

• commands.native: "auto" habilita comandos nativos para Telegram

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

• los nombres se normalizan (eliminan el / 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

• los comandos personalizados son solo entradas de menú; no implementan el comportamiento automáticamente
• los comandos de plugins/Skills pueden seguir funcionando cuando se escriben incluso si no se muestran en el menú de Telegram

• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa que el menú de Telegram siguió desbordado después de recortarlo; reduce comandos de plugins/Skills/personalizados o deshabilita channels.telegram.commands.native.
• setMyCommands failed con errores de red/fetch normalmente significa que el DNS/HTTPS saliente hacia api.telegram.org está bloqueado.

​

Comandos de pairing de dispositivos (plugin device-pair)

1. /pair genera el código de configuración
2. pega el código en la app de iOS
3. /pair pending lista las solicitudes pendientes (incluidos rol/alcances)
4. aprueba la solicitud:
   • /pair approve <requestId> para aprobación explícita
   • /pair approve cuando solo hay una solicitud pendiente
   • /pair approve latest para la más reciente

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

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

• off
• dm
• group
• all
• allowlist (predeterminado)

{
  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" }],
  ],
}

• sendMessage (to, content, mediaUrl, replyToMessageId, messageThreadId opcionales)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, iconColor, iconCustomEmojiId opcionales)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (predeterminado: deshabilitado)

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

• off (predeterminado)
• first
• all

• las claves de sesión de temas añaden :topic:<threadId>
• las respuestas y las acciones de escritura se dirigen al hilo del tema
• ruta de configuración del tema: channels.telegram.groups.<chatId>.topics.<threadId>

• los envíos de mensajes omiten message_thread_id (Telegram rechaza sendMessage(...thread_id=1))
• las acciones de escritura siguen incluyendo message_thread_id

{
  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
          }
        }
      }
    }
  }
}

• bindings[] con type: "acp" y match.channel: "telegram"

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

• /acp spawn <agent> --thread here|auto puede enlazar el tema actual de Telegram a una nueva sesión ACP.
• Los mensajes posteriores del tema se enrutan directamente a la sesión ACP enlazada (no se requiere /acp steer).
• OpenClaw fija el mensaje de confirmación de creación dentro del tema después de un enlace correcto.
• Requiere channels.telegram.threadBindings.spawnAcpSessions=true.

• MessageThreadId
• IsForum

• los chats privados con message_thread_id mantienen el enrutamiento de MD pero usan claves de sesión y destinos de respuesta conscientes del hilo.

​

Mensajes 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

{
  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,
}

​

Stickers

• WEBP estático: se descarga y procesa (marcador <media:sticker>)
• TGS animado: se omite
• WEBM de vídeo: se omite

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

• ~/.openclaw/telegram/sticker-cache.json

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

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

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

• Telegram reaction added: 👍 by Alice (@alice) on msg 42

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

• own significa solo reacciones de usuarios a mensajes enviados por el bot (mejor esfuerzo mediante 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 ID de hilo en las actualizaciones de reacción.
  • los grupos que no son foros se enrutan a la sesión de chat grupal
  • los grupos de foro se enrutan a la sesión del tema general del grupo (:topic:1), no al tema exacto de origen

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

• Telegram espera emoji Unicode (por ejemplo, ”👀”).
• Usa "" para deshabilitar la reacción para un canal o cuenta.

• eventos de migración de grupos (migrate_to_chat_id) para actualizar channels.telegram.groups
• /config set y /config unset (requiere habilitación de comandos)

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

• configura channels.telegram.webhookUrl
• configura channels.telegram.webhookSecret (obligatorio cuando webhookUrl está configurado)
• channels.telegram.webhookPath opcional (predeterminado /telegram-webhook)
• channels.telegram.webhookHost opcional (predeterminado 127.0.0.1)
• channels.telegram.webhookPort opcional (predeterminado 8787)

• channels.telegram.textChunkLimit tiene como valor predeterminado 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.timeoutSeconds sobrescribe el tiempo de espera del cliente de la API de Telegram (si no se configura, se aplica el valor predeterminado de grammY).
• 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 pasa actualmente tal como se recibe.
• las listas de permitidos de Telegram controlan principalmente quién puede activar el agente, no son un límite completo de redacción del contexto suplementario.
• controles del historial de MD:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• la configuración channels.telegram.retry se aplica a los ayudantes de envío de Telegram (CLI/herramientas/acciones) para errores recuperables de API saliente.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

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

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id para temas de foros (o usa un destino :topic:)

• --buttons para teclados en línea cuando channels.telegram.capabilities.inlineButtons lo permite
• --force-document para enviar imágenes y GIF salientes como documentos en lugar de cargas comprimidas de foto o medios animados

• channels.telegram.actions.sendMessage=false deshabilita los mensajes salientes de Telegram, incluidos los sondeos
• channels.telegram.actions.poll=false deshabilita la creación de sondeos de Telegram y mantiene habilitados los envíos normales

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (opcional; recurre a los ID numéricos de propietario inferidos de allowFrom y defaultTo directo cuando es posible)
• channels.telegram.execApprovals.target (dm | channel | both, predeterminado: dm)
• agentFilter, sessionFilter

• target: "dm" envía solicitudes de aprobación solo a los MD de aprobadores resueltos
• target: "channel" envía la solicitud de vuelta al chat/tema de Telegram de origen
• target: "both" envía a los MD de aprobadores y al chat/tema de origen

• Los ID con prefijo plugin: siempre se resuelven mediante aprobaciones del plugin.
• Otros ID prueban primero exec.approval.resolve.
• Si Telegram también está autorizado para aprobaciones del plugin y el gateway dice que la aprobación de ejecución es desconocida o caducó, Telegram reintenta una vez mediante plugin.approval.resolve.
• Las denegaciones/errores reales de aprobación de ejecución no pasan silenciosamente a la resolución de aprobación del plugin.

• 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 muestra una advertencia cuando la configuración espera mensajes de grupo sin mención.
• openclaw channels status --probe puede comprobar ID numéricos explícitos de grupo; el comodín "*" no puede sondearse para 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 ver motivos de omisión

• autoriza la identidad de tu remitente (pairing 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 comandos de plugins/Skills/personalizados o deshabilita los menús nativos
• setMyCommands failed con errores de red/fetch normalmente indica problemas de alcance DNS/HTTPS hacia api.telegram.org

• Node 22+ + fetch/proxy personalizado pueden activar un 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 los reintenta como errores de red recuperables.
• En hosts VPS con salida/TLS directa inestable, enruta las llamadas a la API de Telegram mediante channels.telegram.proxy:

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

• Node 22+ usa de forma predeterminada autoSelectFamily=true (excepto WSL2) y dnsResultOrder=ipv4first.
• Si tu host es WSL2 o explícitamente funciona mejor con comportamiento solo IPv4, fuerza la selección de familia:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Las respuestas del rango de prueba RFC 2544 (198.18.0.0/15) ya están permitidas para descargas de medios de Telegram de forma predeterminada. Si una IP falsa de confianza o un proxy transparente reescribe api.telegram.org a alguna otra dirección privada/interna/de uso especial durante las descargas de medios, puedes habilitar la omisión solo para Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• La misma opción también está disponible por cuenta en channels.telegram.accounts.<accountId>.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 por defecto el rango de referencia RFC 2544.

• Anulaciones por entorno (temporales):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Validar respuestas DNS:

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