Telegram

Exécutez un agent ZeroClaw en tant que bot Telegram via le long polling. Aucune URL publique ni webhook n’est requis. Ce guide commence par le câblage du runtime, puis décrit de la création du bot jusqu’à la première conversation autorisée.

Comment l’implémentation actuelle est connectée

La configuration de Telegram comporte trois sources de vérité distinctes. Le bloc canal possède la connexion Telegram, le bloc agent possède le routage, et les groupes de pairs possèdent l’autorisation entrante :

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 construit un TelegramChannel pour chaque alias activé appartenant à un agent. Le canal résout les membres du groupe de pairs correspondants depuis la Config partagée à l’arrivée de chaque message. Il accepte soit l’identifiant numérique Telegram de l’expéditeur, soit son nom d’utilisateur, puis transmet un ChannelMessage autorisé à la distribution de canal partagée et au cycle de vie du tour d’agent.

Il n’y a pas de champ allowed_users sous [channels.telegram.<alias>]. L’autorisation est gérée dans les Groupes de pairs ; cette page est la référence canonique pour les champs de groupe de pairs, la correspondance et le comportement multi-agent.

1. Créer un bot Telegram

1. Ouvrez @BotFather dans Telegram.
2. Envoyez /newbot et suivez les instructions pour un nom d’affichage et un nom d’utilisateur.
3. Copiez le jeton du bot. Le tutoriel officiel de Telegram couvre le même processus.

Traitez le token comme un mot de passe. Quiconque le possède peut contrôler le bot. Ne le collez pas dans config.toml, les journaux, les captures d’écran ou le contrôle de source.

2. Configurez un alias et attachez-le à un agent

Ce guide utilise home comme alias de canal et primary comme alias d’agent. L’alias est le nom local ZeroClaw pour cette instance de bot ; il n’est pas nécessaire qu’il corresponde au nom d’utilisateur du bot Telegram.

Définissez le jeton via l’invite secrète masquée, puis activez le canal :

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

Répertoriez vos alias d’agents, puis ajoutez telegram.home à la liste de canaux existante de l’agent ciblé. Omettre la valeur ouvre l’éditeur de liste, ce qui vous permet d’ajouter la nouvelle entrée sans supprimer les autres associations de canaux :

zeroclaw agents list
zeroclaw config set agents.primary.channels

Ensuite, la structure non secrète pertinente est équivalente à :

[channels.telegram.home]
enabled = true
# bot_token est stocké chiffré après l'invite masquée `config set`

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

Remplacez primary par un agent existant qui dispose déjà d’un fournisseur de modèle et d’un profil de risque fonctionnels. Dès qu’un agent de la configuration déclare une liste channels, un canal activé mais absent de la liste channels d’un agent activé n’est pas démarré. Si aucun agent ne déclare de liaisons de canaux, ZeroClaw bascule sur le routage hérité : chaque canal activé est démarré et servi par l’agent activé par défaut résolu. Déclarez des liaisons explicites comme indiqué ci-dessus afin qu’un bot non répertorié soit véritablement inactif plutôt que de s’exécuter silencieusement sous l’agent par défaut.

3. Choisissez comment les premiers utilisateurs sont autorisés

Choisissez l’un des chemins suivants avant de démarrer le bot.

Associez le premier utilisateur à un code à usage unique

Pour une première exécution privée, laissez l’ensemble des pairs externes résolus vide. En particulier, aucun groupe de pairs dont le channel est telegram ou telegram.home ne peut contribuer d’entrées external_peers. Un groupe correspondant qui ne contient que d’autres paramètres sans contribuer de pairs externes n’affecte pas le pairage.

Lorsque TelegramChannel est construit sans pairs résolus, il crée un code de couplage à usage unique et l’écrit dans la sortie de premier plan et les journaux structurés. Le premier utilisateur approuvé l’échange depuis Telegram avec /bind.

Pré-autoriser les utilisateurs connus

Si vous connaissez déjà les identifiants numériques des utilisateurs Telegram, autorisez-les avant le démarrage. Un identifiant numérique est préférable à un nom d’utilisateur, car il reste stable si l’utilisateur renomme son compte. Voici l’exemple minimal limité à l’alias :

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

Utilisez un channel = "telegram" à l’échelle du type uniquement lorsque les mêmes identités doivent être acceptées par chaque alias Telegram configuré. Pour le schéma complet et les règles de résolution, consultez Peer Groups.

Tout ensemble external-peer résolu non vide désactive l’appairage du premier utilisateur pour cette instance de canal. Cela inclut un groupe de pairs avec caractère générique.

[!CAUTION] external_peers = ["*"] accepte tout expéditeur Telegram pouvant joindre le bot et désactive le flux d’appairage unique. Ces expéditeurs peuvent piloter l’agent et tous les outils autorisés par son profil de risque. N’utilisez un caractère générique que pour un bot délibérément public associé à un agent convenablement restreint ; ce n’est pas un raccourci pour une configuration privée.

4. Démarrez le canal et inspectez-le

Utilisez le démon complet pour un fonctionnement normal, le processus en mode canal uniquement pour un diagnostic en avant-plan, ou le service installé pour une utilisation longue durée :

zeroclaw daemon

# Diagnostic alternatif au premier plan : démarre tous les canaux configurés.
zeroclaw channel start

# Si ZeroClaw est installé en tant que service géré.
zeroclaw service restart

Telegram utilise le long polling getUpdates, il n’a donc pas besoin d’un port entrant ni d’une URL de rappel publique. Dans un autre terminal, vérifiez la connectivité et suivez les journaux :

zeroclaw channel doctor
zeroclaw service logs --follow

Avec un ensemble de pairs vide, recherchez Telegram pairing required; one-time bind code issued. L’événement structuré inclut l’alias du canal et pairing_code. Les exécutions au premier plan de zeroclaw daemon et zeroclaw channel start affichent également le code directement. Traitez le code et la sortie du journal comme sensibles jusqu’à ce que le code soit consommé.

5. Associer le premier utilisateur avec /bind

Envoyez le code imprimé au bot depuis le compte Telegram que vous souhaitez approuver :

/bind 123456

Le chemin d’autorisation est :

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 cas de succès, ZeroClaw préfère l’identifiant numérique stable de l’expéditeur, l’ajoute à [peer_groups.telegram_home] pour telegram.home, et enregistre config.toml. Le résolveur de pairs du canal en cours d’exécution lit cette configuration partagée, de sorte que l’utilisateur peut envoyer le message suivant immédiatement sans redémarrage.

Le code est à usage unique. Lors des redémarrages ultérieurs, le pair sauvegardé rend l’ensemble résolu non vide, ce qui maintient le jumelage désactivé et aucun nouveau code n’est émis. Si le bot indique qu’il n’a effectué le jumelage que pour le runtime actuel en raison d’un échec de persistance, corrigez l’erreur de permission ou d’écriture de configuration signalée avant de redémarrer.

6. Lier un autre utilisateur depuis le CLI de l’opérateur

Un utilisateur non autorisé peut envoyer un message au bot pour recevoir une commande d’opérateur suggérée contenant son identifiant numérique. Exécutez cette commande sur l’hôte ZeroClaw. Pour l’alias home, elle se présente sous cette forme :

zeroclaw channel bind-telegram 111111111 --alias home

Vous pouvez aussi associer un nom d’utilisateur Telegram sans son @ initial :

zeroclaw channel bind-telegram example_user --alias home

--alias doit correspondre à la clé dans [channels.telegram.<alias>]. La CLI utilise default par défaut, donc n’omettez le drapeau que lorsque le canal configuré est réellement [channels.telegram.default] :

zeroclaw channel bind-telegram 111111111

La commande rejette un alias inconnu au lieu de créer un groupe de pairs qu’aucun canal en cours d’exécution ne lirait. Pour un alias valide, elle crée ou met à jour [peer_groups.telegram_<alias>], limite la portée du groupe à telegram.<alias> et enregistre l’identité de manière idempotente.

Comportement au redémarrage et à la persistance

Si le rechargement automatique échoue, la commande bind conserve la modification enregistrée et vous indique de redémarrer manuellement :

zeroclaw service stop
zeroclaw service start

Journaux et dépannage

Pour un service installé :

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

Pour une exécution au premier plan, lisez la sortie du processus. Lorsque la journalisation structurée persistante est activée, les événements sont également écrits sous le répertoire d’installation, à data/state/runtime-trace.jsonl; consultez Observabilité.

La liste complète des champs Telegram est générée à partir du schéma de configuration en direct :

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    # entrée masquée, stockée chiffrée

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=

Voir aussi

• Groupes de pairs : schéma canonique d’autorisation entrante
• Cycle de vie d’exécution du canal
• Gestion des services
• Observabilité