Mattermost

• native et nativeSkills valent "auto" par défaut, ce qui les désactive pour Mattermost. Définissez-les explicitement sur true.
• callbackPath vaut /api/channels/mattermost/command par défaut.
• Si callbackUrl est omis, OpenClaw génère http://<gateway.customBindHost or localhost>:<gateway.port, default 18789><callbackPath>. Les hôtes d’écoute génériques (0.0.0.0, ::) sont remplacés par localhost.
• Pour les configurations multicomptes, commands peut être défini au niveau supérieur ou sous channels.mattermost.accounts.<id>.commands (les valeurs du compte remplacent les champs de niveau supérieur).
• Les commandes slash existantes possédant le même déclencheur et créées par d’autres intégrations ne sont pas modifiées (leur enregistrement est ignoré) ; les commandes créées par le bot sont mises à jour ou recréées lorsque l’URL de rappel change.
• Les rappels de commande sont validés à l’aide des jetons propres à chaque commande renvoyés par Mattermost lorsque OpenClaw enregistre les commandes oc_*.
• OpenClaw actualise l’enregistrement actuel des commandes Mattermost avant d’accepter chaque rappel. Ainsi, les anciens jetons de commandes slash supprimées ou régénérées cessent d’être acceptés sans redémarrage du Gateway.
• La validation des rappels échoue de manière restrictive si l’API Mattermost ne peut pas confirmer que la commande est toujours active ; les échecs de validation sont brièvement mis en cache, les recherches simultanées sont regroupées et le lancement de nouvelles recherches est limité par commande afin de contenir la pression des attaques par rejeu.
• Les rappels slash échouent de manière restrictive si l’enregistrement a échoué, si le démarrage était partiel ou si le jeton de rappel ne correspond pas au jeton enregistré de la commande résolue (un jeton valide pour une commande ne peut pas atteindre la validation en amont d’une autre commande).
• Les rappels acceptés reçoivent un accusé de réception sous la forme d’une réponse éphémère « Traitement en cours… » ; la réponse réelle arrive sous forme de message normal.

Le point de terminaison de rappel doit être accessible depuis le serveur Mattermost.

• Ne définissez pas callbackUrl sur localhost, sauf si Mattermost s’exécute sur le même hôte ou dans le même espace de noms réseau qu’OpenClaw.
• Ne définissez pas callbackUrl sur l’URL de base de Mattermost, sauf si cette URL transmet /api/channels/mattermost/command à OpenClaw via un proxy inverse.
• Pour effectuer une vérification rapide, utilisez curl https://<gateway-host>/api/channels/mattermost/command ; une requête GET doit renvoyer 405 Method Not Allowed depuis OpenClaw, et non 404.

Si votre rappel cible des adresses privées, de tailnet ou internes, configurez ServiceSettings.AllowedUntrustedInternalConnections dans Mattermost afin d’y inclure l’hôte ou le domaine de rappel.

Utilisez des entrées d’hôte ou de domaine, et non des URL complètes.

• Correct : gateway.tailnet-name.ts.net
• Incorrect : https://gateway.tailnet-name.ts.net

• partial (par défaut) : une publication d’aperçu modifiée à mesure que la réponse s’allonge, puis finalisée avec la réponse complète.
• block fait alterner l’aperçu entre le texte terminé et les blocs d’activité des outils, afin que chaque bloc reste visible dans sa propre publication au lieu d’être remplacé sur place. Les mises à jour parallèles et consécutives des outils partagent la publication actuelle d’activité des outils.
• progress affiche un aperçu de l’état pendant la génération et ne publie la réponse finale qu’une fois celle-ci terminée.
• off désactive la diffusion en continu de l’aperçu. Avec blockStreaming: true, les blocs terminés de l’assistant sont tout de même distribués sous forme de réponses par blocs normales (publications distinctes), plutôt que sous la forme d’une seule publication finale fusionnée.

• Si le flux ne peut pas être finalisé sur place (par exemple, si la publication a été supprimée en cours de diffusion), OpenClaw se rabat sur l’envoi d’une nouvelle publication finale afin que la réponse ne soit jamais perdue.
• Les charges utiles contenant uniquement le raisonnement ne sont pas publiées dans les canaux, y compris le texte reçu sous la forme d’une citation > Thinking. Définissez /reasoning on pour voir le raisonnement sur d’autres surfaces ; la publication finale Mattermost ne conserve que la réponse.
• Consultez Diffusion en continu pour connaître la matrice de correspondance des canaux.

• Les rappels de boutons utilisent une vérification HMAC-SHA256 (automatique, aucune configuration nécessaire).
• L’intégralité du bloc de pièce jointe est remplacée lors du clic ; tous les boutons sont donc supprimés ensemble, sans possibilité de suppression partielle.
• Les identifiants d’action contenant des traits d’union ou des tirets bas sont automatiquement assainis (limitation de l’acheminement Mattermost).
• Les clics dont l’action_id ne correspond à aucune action de la publication d’origine sont rejetés avec le code 403 (« Action inconnue »).

• channels.mattermost.capabilities : tableau de chaînes de capacités. Ajoutez "inlineButtons" pour activer la description de l’outil de boutons dans l’invite système de l’agent.
• channels.mattermost.interactions.callbackBaseUrl : URL de base externe facultative pour les rappels de boutons (par exemple https://gateway.example.com). Utilisez-la lorsque Mattermost ne peut pas accéder directement au Gateway sur son hôte d’écoute.
• Dans les configurations multicomptes, vous pouvez également définir le même champ sous channels.mattermost.accounts.<id>.interactions.callbackBaseUrl.
• Si interactions.callbackBaseUrl est omis, OpenClaw déduit l’URL de rappel à partir de gateway.customBindHost + gateway.port (18789 par défaut), puis se rabat sur http://localhost:<port>. Le chemin de rappel est /mattermost/interactions/<accountId>.
• Règle d’accessibilité : l’URL de rappel des boutons doit être accessible depuis le serveur Mattermost. localhost ne fonctionne que lorsque Mattermost et OpenClaw s’exécutent sur le même hôte ou dans le même espace de noms réseau.
• channels.mattermost.interactions.allowedSourceIps : liste d’adresses IP sources autorisées pour les rappels de boutons. Sans celle-ci, seules les sources en local loopback (127.0.0.1, ::1) sont acceptées ; un serveur Mattermost distant doit donc être ajouté à cette liste, faute de quoi ses clics sont rejetés avec le code 403. Derrière un proxy inverse, définissez également gateway.trustedProxies afin que l’adresse IP réelle du client soit déduite des en-têtes transférés.
• Si votre cible de rappel est privée, appartient au réseau Tailscale ou est interne, ajoutez son hôte ou domaine à ServiceSettings.AllowedUntrustedInternalConnections dans Mattermost.

• La fonction json.dumps de Python ajoute des espaces par défaut ({"key": "val"}). Utilisez separators=(",", ":") pour correspondre à la sortie compacte de JavaScript ({"key":"val"}).
• Signez toujours tous les champs du contexte (à l’exception de _token). Le Gateway supprime _token, puis signe tout ce qui reste. La signature d’un sous-ensemble provoque un échec silencieux de la vérification.
• Utilisez sort_keys=True : le Gateway trie les clés avant la signature, et Mattermost peut réordonner les champs du contexte lors du stockage de la charge utile.
• Dérivez le secret du jeton du bot de façon déterministe, plutôt que d’utiliser des octets aléatoires. Le secret doit être identique dans le processus qui crée les boutons et dans le Gateway qui effectue la vérification.

Vérifiez que le bot se trouve dans le canal et mentionnez-le (oncall), utilisez un préfixe déclencheur (onchar) ou définissez chatmode: "onmessage".

• Vérifiez le jeton du bot, l'URL de base et si le compte est activé.
• Problèmes liés aux comptes multiples : les variables d'environnement s'appliquent uniquement au compte default.
• Les hôtes Mattermost privés ou sur le réseau local nécessitent network.dangerouslyAllowPrivateNetwork: true (la protection contre les SSRF bloque les adresses IP privées par défaut).

• Unauthorized: invalid command token. : OpenClaw n'a pas accepté le jeton de rappel. Causes habituelles :
  • l'enregistrement des commandes slash a échoué ou n'a été que partiellement effectué au démarrage
  • le rappel atteint le mauvais Gateway ou le mauvais compte
  • Mattermost possède encore d'anciennes commandes pointant vers une cible de rappel précédente
  • le Gateway a redémarré sans réactiver les commandes slash
• Si les commandes slash natives cessent de fonctionner, recherchez dans les journaux mattermost: failed to register slash commands ou mattermost: native slash commands enabled but no commands could be registered.
• Si callbackUrl est omis et que les journaux avertissent que le rappel a été résolu vers une URL local loopback telle que http://localhost:18789/..., cette URL n'est probablement accessible que lorsque Mattermost s'exécute sur le même hôte ou dans le même espace de noms réseau qu'OpenClaw. Définissez plutôt une valeur commands.callbackUrl explicite et accessible depuis l'extérieur.

• Les boutons apparaissent sous forme de cases blanches ou ne s'affichent pas du tout : les données des boutons sont mal formées. Chaque bouton de présentation nécessite un label et une value (les boutons auxquels l'un ou l'autre manque sont ignorés).
• Les boutons s'affichent, mais les clics n'ont aucun effet : vérifiez que le Gateway est accessible depuis le serveur Mattermost, que l'adresse IP du serveur Mattermost figure dans channels.mattermost.interactions.allowedSourceIps (seul local loopback est accepté sans cette option) et que ServiceSettings.AllowedUntrustedInternalConnections inclut l'hôte de rappel pour les cibles privées.
• Les boutons renvoient une erreur 404 lors d'un clic : l'id du bouton contient probablement des traits d'union ou des traits de soulignement. Le routeur d'actions de Mattermost ne fonctionne pas avec les identifiants non alphanumériques. Utilisez uniquement [a-zA-Z0-9].
• Le Gateway journalise rejected callback source : le clic provient d'une adresse IP absente de interactions.allowedSourceIps. Ajoutez le serveur Mattermost ou votre point d'entrée à la liste d'autorisation, puis définissez gateway.trustedProxies si vous utilisez un proxy inverse.
• Le Gateway journalise invalid _token : les HMAC ne correspondent pas. Vérifiez que vous signez tous les champs de contexte (et non un sous-ensemble), utilisez des clés triées et un JSON compact (sans espaces). Consultez la section HMAC ci-dessus.
• Le Gateway journalise missing _token in context : le champ _token ne figure pas dans le contexte du bouton. Assurez-vous de l'inclure lors de la création de la charge utile d'intégration.
• Le Gateway rejette le clic avec Unknown action : context.action_id ne correspond à l'id d'aucune action de la publication. Définissez les deux avec la même valeur normalisée.
• L'agent ne propose pas de boutons : ajoutez capabilities: ["inlineButtons"] à la configuration du canal Mattermost.