Canaux sociaux

Intégrations de diffusion / flux sociaux. Ces dernières diffèrent des canaux de chat en deux points : les messages sont généralement publics et l’agent agit souvent comme un diffuseur plutôt que comme un répondant bidirectionnel.

Note de compilation : Les canaux sociaux ne sont pas inclus dans la version allégée par défaut. Pour les utiliser, compilez avec --features channels-full (tous les canaux) ou avec l’indicateur de fonctionnalité spécifique (par ex. --features channel-twitter). Les binaires précompilés n’incluent pas ces canaux par défaut. Consultez Channels → Overview pour le tableau complet des options de compilation.

Twitch

Le chat Twitch est un adaptateur léger au-dessus d’IRC. Compilez-le avec --features channel-twitch ou incluez-le via --features channels-full ; la compilation légère par défaut ne l’inclut pas.

Configurez enabled, bot_username, oauth_token et les canaux à rejoindre sous un alias Twitch. mention_only est facultatif et vaut false par défaut. Une instance minimale se présente ainsi :

[channels.twitch.default]
enabled = true
bot_username = "zeroclaw_bot"
oauth_token = "replace-with-twitch-token"
channels = ["zeroclaw_channel"]
mention_only = true

[peer_groups.twitch_default]
channel = "twitch.default"
external_peers = ["zeroclaw_user"]

• Authentification : utilisez un jeton d’accès utilisateur Twitch pour le compte du bot avec les autorisations chat:read et chat:edit. Après avoir configuré la Twitch CLI, générez-le en étant connecté à ce compte avec twitch token -u -s 'chat:read chat:edit', puis stockez-le via un mécanisme de configuration protégé. ZeroClaw supprime les espaces superflus de la valeur et ajoute le préfixe oauth: requis lorsqu’il est omis.
• Canaux : les entrées de channels peuvent inclure le # en tête ; ZeroClaw l’ajoute s’il est absent et normalise les noms de canal en minuscules.
• Entrants et sortants : les messages de canal reçoivent une réponse dans le même canal. mention_only = true ignore les messages de canal qui ne mentionnent pas bot_username. Si Twitch transmet un PRIVMSG IRC hors canal à l’identifiant de connexion du bot, ZeroClaw répond à cet expéditeur ; l’adaptateur ne configure pas de transport distinct pour les messages privés.
• Mise en forme : Les réponses Twitch utilisent du texte brut et sont découpées pour tenir dans les trames IRC. La mise en forme Markdown n’est pas conservée.
• Limites de débit : l’adaptateur écrit directement des trames IRC PRIVMSG et ne dispose d’aucun limiteur de débit spécifique à Twitch ni de mécanisme de temporisation après un HTTP 429. Maintenez la cadence de publication de l’agent dans les limites de Twitch Chat et limitez à la source les flux de travail générant des rafales.

Bluesky (protocole AT)

Les expéditeurs entrants sont filtrés par rapport au peer set résolu pour l’agent lié, issu de la configuration peer_groups à laquelle l’agent appartient. La correspondance supprime le @ initial et est insensible à la casse par rapport à l’identifiant d’expéditeur natif du canal. Un ensemble vide refuse tout le monde ; un ensemble contenant "*" accepte n’importe qui ; sinon, seuls les pairs externes listés (et les agents pairs) sont acceptés. Ceci est distinct de l’appairage de la passerelle (gateway.require_pairing), qui authentifie les clients HTTP/WebSocket, et non les expéditeurs des canaux de discussion.

Un groupe de pairs pour Bluesky définit channel à bluesky, liste les expéditeurs autorisés dans external_peers (pour Bluesky, le handle ou le DID de l’expéditeur ; un DID reste valide même si le handle change ; ["*"] accepte tout le monde), nomme éventuellement des agents pairs pour la distribution inter-agents, définit une liste de blocage ignore et un output_modality (mirror, voice ou text). Consultez Groupes de pairs pour la référence des champs.

Où définir ce paramètre :

• Auth : mot de passe d’application Bluesky (pas votre vrai mot de passe). Créez-en un dans les paramètres.
• Entrant : notifications mention et reply, provenant uniquement de pairs.
• Sortant : publications de 300 caractères ; les réponses plus longues sont automatiquement divisées en plusieurs fils.
• Protocole : AT Protocol via le crate atrium-api.

Une entrée de pair peut être soit le handle, soit le DID. Privilégiez le DID si vous voulez que l’entrée survive au renommage du compte lui-même.

Chaque interrogation parcourt les notifications non lues jusqu’à la fin avant d’en livrer une seule, de sorte qu’un échec en cours de parcours ne livre rien et réessaie toute la plage lors de l’interrogation suivante. C’est un compromis : un court délai contre le fait de ne pas re-livrer les pages déjà reçues, car une notification à laquelle l’agent a déjà répondu est pire qu’une notification à laquelle il répond cinq secondes plus tard.

Nostr

Les expéditeurs entrants sont filtrés par rapport au peer set résolu pour l’agent lié, issu de la configuration peer_groups à laquelle l’agent appartient. La correspondance supprime le @ initial et est insensible à la casse par rapport à l’identifiant d’expéditeur natif du canal. Un ensemble vide refuse tout le monde ; un ensemble contenant "*" accepte n’importe qui ; sinon, seuls les pairs externes listés (et les agents pairs) sont acceptés. Ceci est distinct de l’appairage de la passerelle (gateway.require_pairing), qui authentifie les clients HTTP/WebSocket, et non les expéditeurs des canaux de discussion.

Un groupe de pairs pour nostr définit channel à nostr, liste les expéditeurs autorisés dans external_peers (pour nostr, la clé publique hexadécimale de l’expéditeur ; ["*"] accepte tout le monde), nomme éventuellement des agents pairs pour la répartition inter-agents, une liste de blocage ignore, et un output_modality (mirror, voice ou text). Consultez Peer Groups pour la référence des champs.

Où définir ce paramètre :

• Auth : clé privée brute (nsec bech32 ou hexadécimal).
• Entrant : kind-1 (texte), kind-4 (DM, NIP-04) et kind-1059 (cadeau-emballé, NIP-17).
• Sortant : mêmes types. La gestion des Zap est expérimentale.
• Relais : l’agent se connecte à tous les relais répertoriés ; utilisez-en 3 à 5 pour plus de fiabilité. Si relays est omis, ZeroClaw se connecte à un ensemble intégré de relais publics populaires.

Twitter / X

Les expéditeurs entrants sont filtrés par rapport au peer set résolu pour l’agent lié, issu de la configuration peer_groups à laquelle l’agent appartient. La correspondance supprime le @ initial et est insensible à la casse par rapport à l’identifiant d’expéditeur natif du canal. Un ensemble vide refuse tout le monde ; un ensemble contenant "*" accepte n’importe qui ; sinon, seuls les pairs externes listés (et les agents pairs) sont acceptés. Ceci est distinct de l’appairage de la passerelle (gateway.require_pairing), qui authentifie les clients HTTP/WebSocket, et non les expéditeurs des canaux de discussion.

Un groupe de pairs pour twitter définit channel à twitter, liste les expéditeurs autorisés dans external_peers (pour twitter, le @username Twitter/X ; ["*"] accepte n’importe qui), nomme éventuellement des agents pairs pour la répartition inter-agents, une liste de blocage ignore, et une output_modality (mirror, voice ou text). Consultez Peer Groups pour la référence des champs.

Où définir ce paramètre :

• Auth : Twitter API v2 OAuth 2.0 Bearer Token uniquement.
• Entrant : mentions via le point de terminaison du flux filtré.
• Sortant : publications, réponses, fils de discussion.
• Avertissement : le plan gratuit est soumis à des limites de débit qui le rendent presque inutilisable. Prévoyez votre budget en conséquence.

Reddit

Les expéditeurs entrants sont filtrés par rapport au peer set résolu pour l’agent lié, issu de la configuration peer_groups à laquelle l’agent appartient. La correspondance supprime le @ initial et est insensible à la casse par rapport à l’identifiant d’expéditeur natif du canal. Un ensemble vide refuse tout le monde ; un ensemble contenant "*" accepte n’importe qui ; sinon, seuls les pairs externes listés (et les agents pairs) sont acceptés. Ceci est distinct de l’appairage de la passerelle (gateway.require_pairing), qui authentifie les clients HTTP/WebSocket, et non les expéditeurs des canaux de discussion.

Un groupe de pairs pour reddit définit channel à reddit, liste les expéditeurs autorisés dans external_peers (pour reddit, le nom d’utilisateur Reddit sans le préfixe u/ (insensible à la casse) ; ["*"] accepte tout le monde), nomme facultativement les agents pairs pour la distribution inter-agents, une liste de blocage ignore, et une output_modality (mirror, voice ou text). Voir Peer Groups pour la référence des champs.

Où définir ce paramètre :

• Auth : OAuth 2.0 avec un jeton de rafraîchissement. Générez-en un avec une application Reddit de type script et le flux password ou code.
• L’« inbox » non lue, qui regroupe les mentions, les réponses aux commentaires et les messages privés. Chaque élément doit provenir d’un pair.
• Sortant : publications, commentaires, messages privés.

subreddits restreint d’où un élément peut provenir ; l’ensemble de pairs détermine qui peut en envoyer un. Les deux s’appliquent, et aucun ne remplace l’autre. Un DM ne porte aucun subreddit, donc subreddits ne peut pas le filtrer, et l’ensemble de pairs est le seul filtre.

Gérer les canaux sociaux en toute sécurité

Les bots sur les réseaux sociaux publics attirent des entrées malveillantes. Deux précautions :

1. Restreindre les personnes auxquelles l’agent répond. Filtrez les expéditeurs entrants à l’aide d’un groupe de pairs (par canal, voir ci-dessus) : un ensemble de pairs vide refuse tout le monde, ["*"] accepte tout le monde. Cela s’applique à chaque canal social, donc un canal activé sans groupe de pairs configuré ne répond à personne tant que vous ne l’avez pas renseigné.
2. Maintenez le niveau d’autonomie à Supervised ou inférieur. Un agent exposé publiquement en autonomie Full est en pratique un shell public. Pour les canaux exposés publiquement, restreignez la surface d’outils dans la configuration globale tool-policy plutôt que de compter sur un tools_allow par canal (aucun champ de ce type par canal n’existe).

Limites de débit

La gestion de la limitation de débit varie selon le canal. Twitch écrit directement les trames IRC PRIVMSG et ne dispose d’aucun limiteur propre à l’adaptateur. Si vous rencontrez une limitation de débit persistante, réduisez la cadence de publication de l’agent à la source plutôt que de vous fier aux paramètres de diffusion propres à chaque canal (aucun de ces canaux n’expose d’intervalles de mise à jour des brouillons ; leur schéma est volontairement minimal).