Slack

Exécutez votre agent ZeroClaw en tant que bot Slack. Ce guide vous accompagne étape par étape. À la fin, vous aurez un bot dans votre espace de travail qui répond lorsque les gens lui envoient un message ou le mentionnent avec @.

Qui peut parler à l’agent

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 slack définit channel à slack, liste les expéditeurs autorisés dans external_peers (pour slack, l’ID utilisateur Slack ; ["*"] 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 :

Démarrage rapide

Slack nécessite deux jetons : un jeton de bot (avec lequel le bot communique) et un jeton d’application (qui permet au bot de se connecter sans que vous ayez à héberger une URL publique). Les deux proviennent de la même page d’application.

1. Créez l’application Slack

1. Allez sur api.slack.com/apps et cliquez sur Create New App -> From scratch.
2. Nommez-la, choisissez votre espace de travail, puis Create App.

2. Ajoutez les permissions dont le bot a besoin

1. Dans la barre latérale de gauche, ouvrez OAuth & Permissions.
2. Sous Scopes -> Bot Token Scopes, ajoutez : app_mentions:read, channels:history, chat:write et channels:read. (Ajoutez également im:history et im:write si vous souhaitez utiliser les messages directs.)

3. Activez le mode Socket et obtenez le jeton d’application

1. Dans la barre latérale gauche, ouvrez Socket Mode et activez-le (on).
2. Slack vous invite à créer un token de niveau application. Nommez-le, attribuez-lui la portée connections:write, puis cliquez sur Generate.
3. Copiez le jeton qui commence par xapp-. Il s’agit de votre app_token.

Le mode Socket (Socket Mode) permet au bot de maintenir une connexion sortante vers Slack, ce qui vous évite d’avoir besoin d’une URL de webhook publique ou de toute redirection de port. C’est la solution la plus simple.

4. Installez l’application et obtenez le jeton du bot

1. Ouvrez Install App dans la barre latérale et cliquez sur Install to Workspace, puis sur Allow.
2. De retour sur OAuth & Permissions, copiez le Bot User OAuth Token qui commence par xoxb-. Il s’agit de votre bot_token.

5. Indiquez les deux jetons à ZeroClaw

Les deux jetons sont des secrets, il faut donc les définir via une interface qui les chiffre :

channels.slack.<alias>.bot_token est un secret. Stocké de manière chiffrée, jamais en clair dans config.toml. Définissez-le via l’une de ces méthodes, qui chiffrent à l’écriture :

zeroclaw config set channels.slack.<alias>.bot_token    # demande une saisie masquée, stocke de manière chiffrée

Définissez app_token de la même manière (il s’agit du jeton xapp- de l’étape 3).

Alternative par variable d’environnement. Les deux jetons peuvent être fournis depuis l’environnement du démon plutôt que par le fichier de configuration : bot_token est résolu à partir de ZEROCLAW_SLACK_BOT_TOKEN, puis de SLACK_BOT_TOKEN ; app_token à partir de ZEROCLAW_SLACK_APP_TOKEN, puis de SLACK_APP_TOKEN. Une valeur du fichier de configuration est prioritaire sur l’environnement. Cela vous permet d’omettre entièrement bot_token du fichier config.toml (par exemple pour les gestionnaires de secrets qui injectent des variables d’environnement) sans que le chargement de la configuration n’échoue.

6. Invitez le bot et testez

Dans Slack, accédez à un canal et tapez /invite @YourBotName. Envoyez ensuite un message ou @-mentionnez le bot. Démarrez ZeroClaw (zeroclaw service restart ou zeroclaw daemon) et il devrait répondre. Sinon, consultez Dépannage.

Configuration

La liste complète des champs, dérivée du schéma en direct. Pour un bot Socket Mode basique, vous ne définissez que bot_token et app_token.

zeroclaw config set channels.slack.<alias>.app_token    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__slack__<alias>__app_token=

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

export ZEROCLAW_channels__slack__<alias>__approval_timeout_secs=

zeroclaw config set channels.slack.<alias>.bot_token    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__slack__<alias>__bot_token=

zeroclaw config set channels.slack.<alias>.cancel_reaction <value>

export ZEROCLAW_channels__slack__<alias>__cancel_reaction=

zeroclaw config set channels.slack.<alias>.channel_ids <value>

export ZEROCLAW_channels__slack__<alias>__channel_ids=

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

export ZEROCLAW_channels__slack__<alias>__draft_update_interval_ms=

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

export ZEROCLAW_channels__slack__<alias>__excluded_tools=

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

export ZEROCLAW_channels__slack__<alias>__interrupt_on_new_message=

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

export ZEROCLAW_channels__slack__<alias>__mention_only=

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

export ZEROCLAW_channels__slack__<alias>__proxy_url=

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

export ZEROCLAW_channels__slack__<alias>__reply_min_interval_secs=

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

export ZEROCLAW_channels__slack__<alias>__reply_queue_depth_max=

zeroclaw config set channels.slack.<alias>.stream_drafts <value>

export ZEROCLAW_channels__slack__<alias>__stream_drafts=

zeroclaw config set channels.slack.<alias>.strict_mention_in_thread <value>

export ZEROCLAW_channels__slack__<alias>__strict_mention_in_thread=

zeroclaw config set channels.slack.<alias>.thread_context_max_messages <value>

export ZEROCLAW_channels__slack__<alias>__thread_context_max_messages=

zeroclaw config set channels.slack.<alias>.thread_replies <value>

export ZEROCLAW_channels__slack__<alias>__thread_replies=

zeroclaw config set channels.slack.<alias>.use_markdown_blocks <value>

export ZEROCLAW_channels__slack__<alias>__use_markdown_blocks=

Socket Mode vs HTTP

Lorsque app_token est défini, le bot utilise le Socket Mode : il établit une connexion sortante vers Slack, donc aucune URL publique n’est requise. C’est la configuration recommandée et celle utilisée par le démarrage rapide ci-dessus. Sans app_token, Slack doit atteindre votre bot via HTTP, ce qui implique d’héberger un point de terminaison d’événements public, plus de configuration et plus d’éléments à sécuriser.

Threads et contexte

Lorsqu’une conversation Slack se déroule dans un fil de discussion, ce fil constitue sa propre conversation. ZeroClaw dérive une clé de session distincte par fil, de sorte que chaque fil dispose d’une fenêtre de contexte et d’un historique indépendants : les messages d’un fil ne débordent jamais dans un autre, et l’agent ne voit pas les tours précédents d’un fil voisin. Pour Slack, ce comportement est contrôlé par thread_replies : lorsque cette option est activée, les messages de premier niveau ouvrent un fil et chaque fil est une conversation distincte ; lorsqu’elle est désactivée, les réponses sont publiées à la racine du canal et l’historique est indexé par expéditeur et destinataire plutôt que par fil.

• L’isolation est l’objectif. Le contexte de chaque thread est autonome : il ne fuit pas en dehors du thread, et rien de l’extérieur du thread ne s’y infiltre. Les threads parallèles conservent des états conversationnels distincts, de sorte que des tâches sans rapport ne se contaminent jamais entre elles.
• Les threads longs font croître le contexte. Un thread accumule l’historique tant qu’il reste actif, donc un thread très long finit par remplir la fenêtre de contexte du modèle comme toute autre conversation longue. Démarrez un nouveau thread pour réinitialiser.
• Le travail en cours est limité à chaque fil de discussion. Un nouveau message dans un fil n’annule pas une réponse en cours dans un autre ; la tâche de chaque fil est indépendante.

Définissez le comportement du thread sur n’importe quelle surface :

zeroclaw config set channels.slack.<alias>.thread_replies true     # réponses en fil de discussion activées
zeroclaw config set channels.slack.<alias>.thread_replies false    # réponses à la racine du canal

strict_mention_in_thread renforce encore ce comportement : lorsque la valeur est true, le bot ne répond dans un fil de discussion que si un message y mentionne le bot avec @, au lieu de répondre à chaque message d’un fil dont il fait partie.

Lors du premier message que ZeroClaw traite dans un fil existant, il récupère les réponses précédentes et ajoute en préfixe un bloc limité [Thread context] afin que l’agent puisse répondre en tenant compte de la discussion précédente. thread_context_max_messages contrôle le nombre de messages précédents les plus récents disponibles dans la fenêtre de récupération qui sont inclus, tout en conservant l’ordre chronologique. La valeur par défaut est 0, la valeur maximale est 50, et 0 désactive cette hydratation automatique. Définissez explicitement une valeur non nulle pour l’activer.

Une hydratation effectue au maximum trois tentatives au total de conversations.replies, y compris les nouvelles tentatives après des réponses HTTP 429. ZeroClaw respecte la valeur Retry-After de Slack avant de réessayer tant qu’il reste du budget de requêtes. Si un fil plus long comporte encore une autre page, ZeroClaw utilise le contexte partiel borné, ajoute un marqueur d’omission et enregistre le fil comme hydraté afin que les réponses ultérieures ne relancent pas l’analyse. Un échec de l’API Slack n’abandonne pas le message actuel ; il ignore l’hydratation et libère la réservation afin que la prochaine réponse éligible puisse réessayer.

Mentions et mise en forme

• mention_only : lorsque la valeur est true, le bot ne répond qu’aux messages qui le @-mentionnent, ce qui lui permet de rester silencieux dans les canaux très actifs.
• use_markdown_blocks : affiche les réponses avec la mise en forme Slack Block Kit pour une mise en page plus riche. Désactivez cette option pour du texte brut.

Diffusion en continu

Slack diffuse les réponses en continu via le booléen stream_drafts :

• false (par défaut) : la réponse entière est publiée en un seul message une fois que l’agent a terminé.
• true : le bot publie immédiatement un message provisoire et le modifie sur place au fur et à mesure que la réponse arrive en streaming. draft_update_interval_ms régule la fréquence des modifications ; augmentez-le si Slack les limite (rate-limit).

Posez-le sur n’importe quelle surface :

zeroclaw config set channels.slack.<alias>.stream_drafts <value>

draft_update_interval_ms contrôle la fréquence à laquelle le brouillon en streaming est modifié (augmentez-le si Slack limite le débit des modifications), et cancel_reaction définit un emoji avec lequel les utilisateurs peuvent réagir pour annuler une réponse en cours.

Dépannage

Voir aussi

• Qui peut parler à l’agent (groupes de pairs)
• Discord
• Vue d’ensemble des canaux