Telegram

Ejecuta un agente ZeroClaw como bot de Telegram mediante long polling. No se requiere URL pública ni webhook. Esta guía comienza con el cableado del entorno de ejecución y luego recorre desde la creación del bot hasta la primera conversación autorizada.

Cómo está configurada la implementación actual

La configuración de Telegram tiene tres fuentes de verdad separadas. El bloque de canal es propietario de la conexión de Telegram, el bloque de agente es propietario del enrutamiento, y los grupos de pares son propietarios de la autorización de entrada:

flowchart LR
    T["channels.telegram.home<br/>token and channel behavior"] --> C["TelegramChannel<br/>alias = home"]
    P["matching peer groups<br/>authorized Telegram identities"] --> C
    G["Telegram Bot API<br/>getUpdates long poll"] --> C
    C -->|"authorized ChannelMessage"| R["AgentRouter"]
    A["agents.primary<br/>channels includes telegram.home"] --> R
    R --> L["agent turn and Telegram reply"]

collect_configured_channels constructs un TelegramChannel para cada alias habilitado y de propiedad del agente. El canal resuelve los miembros del grupo de pares coincidentes desde la Config compartida cuando llega cada mensaje. Acepta el ID de usuario numérico de Telegram del remitente o su nombre de usuario, luego entrega un ChannelMessage autorizado al despacho de canal compartido y al ciclo de vida del turno del agente.

No existe el campo allowed_users bajo [channels.telegram.<alias>]. La autorización se encuentra en Peer Groups; esa página es la referencia canónica de los campos de grupos de pares, la coincidencia y el comportamiento multiagente.

1. Crea un bot de Telegram

1. Abre @BotFather en Telegram.
2. Envía /newbot y sigue las instrucciones para un nombre de visualización y nombre de usuario.
3. Copia el token del bot. El tutorial oficial de Telegram cubre el mismo flujo.

Trata el token como una contraseña. Cualquiera que lo tenga puede controlar el bot. No lo pegues en config.toml, registros, capturas de pantalla ni en el control de versiones.

2. Configure un alias y asígnelo a un agente

Esta guía usa home como alias del canal y primary como alias del agente. El alias es el nombre local de ZeroClaw para esta instancia del bot; no tiene que coincidir con el nombre de usuario del bot de Telegram.

Configure el token a través del indicador de secreto enmascarado, luego habilite el canal:

zeroclaw config set channels.telegram.home.bot_token
zeroclaw config set channels.telegram.home.enabled true

Enumera los alias de tus agentes y, a continuación, añade telegram.home a la lista de canales existente del agente correspondiente. Si omites el valor, se abre el editor de la lista, de modo que puedas añadir la nueva entrada sin descartar otras asignaciones de canales:

zeroclaw agents list
zeroclaw config set agents.primary.channels

Después, la estructura no secreta relevante es equivalente a:

[channels.telegram.home]
enabled = true
# bot_token se almacena cifrado tras el aviso enmascarado de `config set`

[agents.primary]
channels = ["telegram.home"]

Reemplaza primary con un agente existente que ya tenga un proveedor de modelo y perfil de riesgo funcionales. Una vez que cualquier agente en la configuración declara una lista channels, un canal que está habilitado pero no está presente en la lista channels de ningún agente habilitado no se inicia. Si ningún agente declara ningún enlace de canal, ZeroClaw recurre al enrutamiento heredado: cada canal habilitado se inicia y es atendido por el agente predeterminado habilitado resuelto. Declara enlaces explícitos como se muestra arriba para que un bot no listado esté genuinamente inactivo en lugar de ejecutarse silenciosamente bajo el agente predeterminado.

3. Elige cómo se autoriza a los primeros usuarios

Elige una de las siguientes rutas antes de iniciar el bot.

Empareja al primer usuario con un código de un solo uso

Para una primera ejecución privada, deja vacío el conjunto de pares externos resuelto. En particular, ningún grupo de pares cuyo channel sea telegram o telegram.home puede aportar ninguna entrada de external_peers. Un grupo coincidente que solo contiene otros ajustes y no aporta pares externos no afecta al emparejamiento.

Cuando TelegramChannel se construye sin peers resueltos, crea un código de emparejamiento de un solo uso y lo escribe en la salida en primer plano y en los registros estructurados. El primer usuario aprobado lo canjea desde Telegram con /bind.

Pre-autorizar usuarios conocidos

Si ya conoce los identificadores numéricos de usuario de Telegram, autorícelos antes del inicio. Es preferible usar un identificador numérico en lugar de un nombre de usuario porque permanece estable si el usuario cambia el nombre de su cuenta. Este es el ejemplo mínimo con ámbito de alias:

[peer_groups.telegram_home]
channel = "telegram.home"
external_peers = ["111111111", "222222222"]

Usa un channel = "telegram" de tipo global solo cuando las mismas identidades deban ser aceptadas por cada alias de Telegram configurado. Para el esquema completo y las reglas de resolución, consulta Peer Groups.

Cualquier conjunto de pares externos resuelto no vacío deshabilita el emparejamiento del primer usuario para esa instancia de canal. Esto incluye un grupo de pares comodín.

[!CAUTION] external_peers = ["*"] acepta a todos los remitentes de Telegram que puedan llegar al bot y deshabilita el flujo de emparejamiento único. Esos remitentes pueden controlar el agente y cualquier herramienta que su perfil de riesgo permita. Usa un comodín solo para un bot deliberadamente público con un agente adecuadamente restringido; no es un atajo para una configuración privada.

4. Inicia el canal e inspecciónalo

Usa el demonio completo para operación normal, el proceso de solo canal para una ejecución de diagnóstico en primer plano, o el servicio instalado para uso prolongado:

zeroclaw daemon

# Diagnóstico alternativo en primer plano: inicia todos los canales configurados.
zeroclaw channel start

# Si ZeroClaw está instalado como un servicio administrado.
zeroclaw service restart

Telegram usa long polling con getUpdates, por lo que no necesita un puerto de entrada ni una URL de callback pública. En otra terminal, comprueba la conectividad y sigue los logs:

zeroclaw channel doctor
zeroclaw service logs --follow

Con un conjunto de pares vacío, busca Telegram pairing required; one-time bind code issued. El evento estructurado incluye el alias del canal y pairing_code. Las ejecuciones en primer plano de zeroclaw daemon y zeroclaw channel start también imprimen el código directamente. Trata el código y la salida del registro como información sensible hasta que se consuma el código.

5. Empareja el primer usuario con /bind

Envía el código impreso al bot desde la cuenta de Telegram que deseas aprobar:

/bind 123456

La ruta de autorización es:

flowchart TD
    S["Telegram update arrives"] --> I["Read username and numeric user ID"]
    I --> M{"Either identity matches<br/>the resolved peer set?"}
    M -->|"yes"| D["Dispatch ChannelMessage to the owning agent"]
    M -->|"no"| B{"Message is /bind code?"}
    B -->|"no"| H["Reply with the alias-aware operator bind command"]
    B -->|"yes, pairing active"| V{"One-time code is valid?"}
    V -->|"no"| X["Reject; repeated failures can lock out retries"]
    V -->|"yes"| P["Add numeric user ID to peer_groups.telegram_home"]
    P --> W["Save config.toml and accept subsequent messages"]

En caso de éxito, ZeroClaw prefiere el ID numérico estable del remitente, lo agrega a [peer_groups.telegram_home] para telegram.home y guarda config.toml. El resolver de peers del canal en ejecución lee esa configuración compartida, por lo que el usuario puede enviar el siguiente mensaje de inmediato sin necesidad de reiniciar.

El código es de un solo uso. En reinicios posteriores, el par guardado hace que el conjunto resuelto no esté vacío, por lo que el emparejamiento permanece desactivado y no se emite ningún código de reemplazo. Si el bot indica que el emparejamiento solo fue válido para el tiempo de ejecución actual debido a un fallo de persistencia, corrija el error de permisos de configuración o de escritura reportado antes de reiniciar.

6. Vincule otro usuario desde la CLI del operador

Un usuario no autorizado puede enviar un mensaje al bot para recibir un comando de operador sugerido que contiene su ID numérico. Ejecuta ese comando en el host de ZeroClaw. Para el alias home tiene esta forma:

zeroclaw channel bind-telegram 111111111 --alias home

También puedes vincular un nombre de usuario de Telegram sin su @ inicial:

zeroclaw channel bind-telegram example_user --alias home

--alias debe coincidir con la clave en [channels.telegram.<alias>]. La CLI usa default de forma predeterminada, así que omite la opción solo cuando el canal configurado realmente sea [channels.telegram.default]:

zeroclaw channel bind-telegram 111111111

El comando rechaza un alias desconocido en lugar de crear un grupo de pares que ningún canal en ejecución leería. Para un alias válido, crea o actualiza [peer_groups.telegram_<alias>], limita el alcance del grupo a telegram.<alias> y guarda la identidad de forma idempotente.

Comportamiento de reinicio y persistencia

Si la recarga automática falla, el comando bind conserva el cambio guardado y te indica que reinicies manualmente:

zeroclaw service stop
zeroclaw service start

Registros y solución de problemas

Para un servicio instalado:

zeroclaw service logs --lines 200
zeroclaw service logs --follow

Para una ejecución en primer plano, lee la salida del proceso. Cuando el registro estructurado persistente está habilitado, los eventos también se escriben en el directorio de instalación en data/state/runtime-trace.jsonl; consulta Observability.

La lista completa de campos de Telegram se genera a partir del esquema de configuración en vivo:

zeroclaw config set channels.telegram.<alias>.ack_reactions <value>

export ZEROCLAW_channels__telegram__<alias>__ack_reactions=

zeroclaw config set channels.telegram.<alias>.api_base_url <value>

export ZEROCLAW_channels__telegram__<alias>__api_base_url=

zeroclaw config set channels.telegram.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__telegram__<alias>__approval_timeout_secs=

zeroclaw config set channels.telegram.<alias>.bot_token    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_channels__telegram__<alias>__bot_token=

zeroclaw config set channels.telegram.<alias>.debounce_ms <value>

export ZEROCLAW_channels__telegram__<alias>__debounce_ms=

zeroclaw config set channels.telegram.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__telegram__<alias>__draft_update_interval_ms=

zeroclaw config set channels.telegram.<alias>.excluded_tools <value>

export ZEROCLAW_channels__telegram__<alias>__excluded_tools=

zeroclaw config set channels.telegram.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__telegram__<alias>__interrupt_on_new_message=

zeroclaw config set channels.telegram.<alias>.mention_only <value>

export ZEROCLAW_channels__telegram__<alias>__mention_only=

zeroclaw config set channels.telegram.<alias>.proxy_url <value>

export ZEROCLAW_channels__telegram__<alias>__proxy_url=

zeroclaw config set channels.telegram.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__telegram__<alias>__reply_min_interval_secs=

zeroclaw config set channels.telegram.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__telegram__<alias>__reply_queue_depth_max=

zeroclaw config set channels.telegram.<alias>.stream_mode <value>

export ZEROCLAW_channels__telegram__<alias>__stream_mode=

Ver también

• Grupos de pares: esquema canónico de autorización entrante
• Ciclo de vida del entorno de ejecución de canales
• Gestión de servicios
• Observabilidad