Mattermost

• native et nativeSkills utilisent par défaut "auto", qui est interprété comme désactivé pour Mattermost. Définissez-les explicitement sur true.
• callbackPath utilise par défaut /api/channels/mattermost/command.
• Si callbackUrl est omis, OpenClaw déduit http://<gateway.customBindHost or localhost>:<gateway.port, default 18789><callbackPath>. Les hôtes d’écoute génériques (0.0.0.0, ::) se replient sur localhost.
• Pour les configurations à plusieurs comptes, 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 créées par d’autres intégrations avec le même déclencheur restent intactes (elles sont ignorées lors de l’enregistrement) ; 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 quand 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 du rappel échoue de manière fermée si l’API Mattermost ne peut pas confirmer que la commande est toujours actuelle ; 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 de commandes slash échouent de manière fermée 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 véritable réponse arrive sous la forme d’un 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 votre instance Mattermost, sauf si cette URL transmet /api/channels/mattermost/command à OpenClaw par 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, définissez ServiceSettings.AllowedUntrustedInternalConnections dans Mattermost de façon à 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 seule publication d’aperçu est 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 d’outils parallèles et consécutives partagent la publication d’activité des outils en cours.
• 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 streaming.block.enabled: true, les blocs terminés de l’assistant sont toujours livrés sous forme de réponses par blocs normales (publications distinctes), plutôt que dans une seule publication finale fusionnée.

• Si la diffusion ne peut pas être finalisée sur place (par exemple, si la publication est supprimée pendant la diffusion), OpenClaw envoie à la place 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 le canal, y compris le texte reçu sous forme de citation > Thinking. Définissez /reasoning on pour afficher le raisonnement dans 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 des 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 — une suppression partielle est impossible.
• Les identifiants d’action contenant des traits d’union ou des traits de soulignement sont automatiquement assainis (limitation du routage Mattermost).
• Les clics dont le action_id ne correspond à aucune action de la publication d’origine sont rejetés avec 403 (« Action inconnue »).

• channels.mattermost.capabilities : tableau de chaînes de fonctionnalité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 via son hôte d’écoute.
• Dans les configurations à plusieurs comptes, 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 (valeur par défaut : 18789), puis utilise http://localhost:<port> comme solution de repli. 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 de bouclage (127.0.0.1, ::1) sont acceptées ; un serveur Mattermost distant doit donc être ajouté à cette liste, sinon ses clics sont rejetés avec 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, interne ou située dans un réseau Tailscale, ajoutez son hôte ou son domaine à ServiceSettings.AllowedUntrustedInternalConnections de Mattermost.

• La fonction json.dumps de Python ajoute des espaces par défaut ({"key": "val"}). Utilisez separators=(",", ":") pour obtenir le même résultat compact que JavaScript ({"key":"val"}).
• Signez toujours tous les champs de contexte (à l’exception de _token). Le Gateway supprime _token, puis signe tous les champs restants. La signature d’un sous-ensemble entraîne un échec silencieux de la vérification.
• Utilisez sort_keys=True : le Gateway trie les clés avant la signature, et Mattermost peut réorganiser les champs de contexte lors du stockage de la charge utile.
• Dérivez le secret du jeton du bot (de manière déterministe), et non d’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 est présent dans le canal et mentionnez-le (oncall), utilisez un préfixe de déclenchement (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 du réseau local nécessitent network.dangerouslyAllowPrivateNetwork: true (la protection SSRF bloque les adresses IP privées par défaut).

• Unauthorized: invalid command token. : OpenClaw n’a pas accepté le jeton de rappel. Causes courantes :
  • l’enregistrement de la commande slash a échoué ou ne s’est achevé que partiellement au démarrage
  • le rappel atteint le mauvais Gateway ou 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 mattermost: failed to register slash commands ou mattermost: native slash commands enabled but no commands could be registered dans les journaux.
• Si callbackUrl est omis et que les journaux avertissent que le rappel a été résolu vers une URL de bouclage 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 incorrectes. Chaque bouton de présentation nécessite un label et un 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 est incluse dans channels.mattermost.interactions.allowedSourceIps (seule l’adresse de bouclage est acceptée sans ce paramètre) 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 : le 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 consigne rejected callback source : le clic provient d’une adresse IP extérieure à interactions.allowedSourceIps. Ajoutez le serveur Mattermost ou votre point d’entrée à la liste d’autorisation, puis définissez gateway.trustedProxies derrière un proxy inverse.
• Le Gateway consigne invalid _token : incompatibilité HMAC. 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 consigne missing _token in context : le champ _token ne figure pas dans le contexte du bouton. Veillez à l’inclure lors de la création de la charge utile de l’intégration.
• Le Gateway rejette le clic avec Unknown action : context.action_id ne correspond à aucun id d’action dans la publication. Définissez les deux sur la même valeur assainie.
• L’agent ne propose pas de boutons : ajoutez capabilities: ["inlineButtons"] à la configuration du canal Mattermost.