Mattermost

• native e nativeSkills hanno come valore predefinito "auto", che per Mattermost viene interpretato come disabilitato. Impostarli esplicitamente su true.
• callbackPath ha come valore predefinito /api/channels/mattermost/command.
• Se callbackUrl viene omesso, OpenClaw ricava http://<gateway.customBindHost or localhost>:<gateway.port, default 18789><callbackPath>. Per gli host di associazione con caratteri jolly (0.0.0.0, ::) viene utilizzato come ripiego localhost.
• Nelle configurazioni con più account, commands può essere impostato al livello superiore o sotto channels.mattermost.accounts.<id>.commands (i valori dell'account prevalgono sui campi di livello superiore).
• I comandi slash esistenti con lo stesso trigger, creati da altre integrazioni, non vengono modificati (la registrazione li ignora); i comandi creati dal bot vengono aggiornati o ricreati quando cambia l'URL di callback.
• Le callback dei comandi vengono convalidate con i token specifici di ciascun comando restituiti da Mattermost quando OpenClaw registra i comandi oc_*.
• OpenClaw aggiorna la registrazione corrente dei comandi Mattermost prima di accettare ogni callback; in questo modo, i token obsoleti di comandi slash eliminati o rigenerati non vengono più accettati senza dover riavviare il gateway.
• La convalida della callback non viene autorizzata se l'API di Mattermost non può confermare che il comando sia ancora corrente; le convalide non riuscite vengono memorizzate brevemente nella cache, le ricerche simultanee vengono accorpate e l'avvio di nuove ricerche viene limitato per comando per contenere la pressione degli attacchi di replay.
• Le callback slash non vengono autorizzate se la registrazione non è riuscita, l'avvio è stato parziale o il token della callback non corrisponde al token registrato del comando risolto (un token valido per un comando non può raggiungere la convalida a monte per un comando diverso).
• Le callback accettate ricevono una risposta temporanea "Elaborazione in corso..."; la risposta effettiva arriva come messaggio normale.

L'endpoint di callback deve essere raggiungibile dal server Mattermost.

• Non impostare callbackUrl su localhost a meno che Mattermost non sia in esecuzione sullo stesso host/spazio dei nomi di rete di OpenClaw.
• Non impostare callbackUrl sull'URL di base di Mattermost, a meno che tale URL non inoltri tramite proxy inverso /api/channels/mattermost/command a OpenClaw.
• Una verifica rapida consiste nell'usare curl https://<gateway-host>/api/channels/mattermost/command; una richiesta GET deve restituire 405 Method Not Allowed da OpenClaw, non 404.

Se le callback puntano a indirizzi privati/tailnet/interni, impostare ServiceSettings.AllowedUntrustedInternalConnections di Mattermost in modo da includere l'host o il dominio della callback.

Utilizzare voci host/dominio, non URL completi.

• Corretto: gateway.tailnet-name.ts.net
• Errato: https://gateway.tailnet-name.ts.net

• partial (predefinita): un singolo post di anteprima che viene modificato man mano che la risposta cresce, quindi finalizzato con la risposta completa.
• block alterna l'anteprima tra blocchi di testo completato e di attività degli strumenti, in modo che ogni blocco rimanga visibile come post separato invece di essere sovrascritto sul posto. Gli aggiornamenti paralleli e consecutivi degli strumenti condividono il post corrente dell'attività degli strumenti.
• progress mostra un'anteprima dello stato durante la generazione e pubblica la risposta finale solo al completamento.
• off disattiva lo streaming dell'anteprima. Con streaming.block.enabled: true, i blocchi completati dell'assistente vengono comunque consegnati come normali risposte a blocchi (post separati), anziché come un singolo post finale aggregato.

• Se lo stream non può essere finalizzato sul posto (ad esempio, se il post è stato eliminato durante lo streaming), OpenClaw ricorre all'invio di un nuovo post finale, così la risposta non viene mai persa.
• I payload contenenti solo il ragionamento vengono esclusi dai post del canale, incluso il testo che arriva come citazione > Thinking. Impostare /reasoning on per visualizzare il ragionamento in altre superfici; il post finale di Mattermost contiene solo la risposta.
• Consultare Streaming per la matrice di associazione dei canali.

• I callback dei pulsanti usano la verifica HMAC-SHA256 (automatica, non richiede configurazione).
• L'intero blocco dell'allegato viene sostituito al clic, pertanto tutti i pulsanti vengono rimossi insieme: la rimozione parziale non è possibile.
• Gli ID delle azioni contenenti trattini o caratteri di sottolineatura vengono normalizzati automaticamente (limitazione dell'instradamento di Mattermost).
• I clic il cui action_id non corrisponde a un'azione del post originale vengono rifiutati con 403 ("Azione sconosciuta").

• channels.mattermost.capabilities: array di stringhe di funzionalità. Aggiungere "inlineButtons" per abilitare la descrizione dello strumento dei pulsanti nel prompt di sistema dell'agente.
• channels.mattermost.interactions.callbackBaseUrl: URL di base esterno facoltativo per i callback dei pulsanti (ad esempio https://gateway.example.com). Usarlo quando Mattermost non può raggiungere direttamente il Gateway presso il relativo host di associazione.
• Nelle configurazioni con più account, è possibile impostare lo stesso campo anche in channels.mattermost.accounts.<id>.interactions.callbackBaseUrl.
• Se interactions.callbackBaseUrl viene omesso, OpenClaw deriva l'URL di callback da gateway.customBindHost + gateway.port (valore predefinito: 18789), quindi ricorre a http://localhost:<port>. Il percorso del callback è /mattermost/interactions/<accountId>.
• Regola di raggiungibilità: l'URL di callback del pulsante deve essere raggiungibile dal server Mattermost. localhost funziona solo quando Mattermost e OpenClaw sono in esecuzione nello stesso host/spazio dei nomi di rete.
• channels.mattermost.interactions.allowedSourceIps: elenco degli IP di origine consentiti per i callback dei pulsanti. Senza di esso, vengono accettate solo le origini di loopback (127.0.0.1, ::1); pertanto, un server Mattermost remoto deve essere aggiunto all'elenco qui, altrimenti i relativi clic vengono rifiutati con 403. Dietro un proxy inverso, impostare anche gateway.trustedProxies affinché l'IP reale del client venga derivato dalle intestazioni inoltrate.
• Se la destinazione del callback è privata, su tailnet o interna, aggiungerne l'host/dominio a ServiceSettings.AllowedUntrustedInternalConnections di Mattermost.

• json.dumps di Python aggiunge spazi per impostazione predefinita ({"key": "val"}). Usare separators=(",", ":") per ottenere lo stesso output compatto di JavaScript ({"key":"val"}).
• Firmare sempre tutti i campi del contesto (tranne _token). Il Gateway rimuove _token, quindi firma tutti i campi rimanenti. La firma di un sottoinsieme causa un errore di verifica silenzioso.
• Usare sort_keys=True: il Gateway ordina le chiavi prima della firma e Mattermost potrebbe riordinare i campi del contesto quando archivia il payload.
• Derivare il segreto dal token del bot (in modo deterministico), non da byte casuali. Il segreto deve essere lo stesso nel processo che crea i pulsanti e nel Gateway che esegue la verifica.

Assicurarsi che il bot sia nel canale e menzionarlo (oncall), usare un prefisso di attivazione (onchar) oppure impostare chatmode: "onmessage".

• Controllare il token del bot, l'URL di base e che l'account sia abilitato.
• Problemi con gli account multipli: le variabili di ambiente si applicano solo all'account default.
• Gli host Mattermost privati/LAN richiedono network.dangerouslyAllowPrivateNetwork: true (la protezione SSRF blocca per impostazione predefinita gli IP privati).

• Unauthorized: invalid command token.: OpenClaw non ha accettato il token di callback. Cause tipiche:
  • la registrazione del comando slash non è riuscita o è stata completata solo parzialmente all'avvio
  • il callback raggiunge il Gateway o l'account errato
  • Mattermost contiene ancora vecchi comandi che puntano a una destinazione di callback precedente
  • il Gateway è stato riavviato senza riattivare i comandi slash
• Se i comandi slash nativi smettono di funzionare, controllare nei log la presenza di mattermost: failed to register slash commands o mattermost: native slash commands enabled but no commands could be registered.
• Se callbackUrl viene omesso e i log avvertono che il callback è stato risolto in un URL di loopback come http://localhost:18789/..., tale URL è probabilmente raggiungibile solo quando Mattermost viene eseguito nello stesso host o spazio dei nomi di rete di OpenClaw. Impostare invece un commands.callbackUrl esplicito e raggiungibile dall'esterno.

• I pulsanti appaiono come riquadri bianchi o non appaiono affatto: i dati del pulsante non sono validi. Ogni pulsante di presentazione richiede un label e un value (i pulsanti privi di uno dei due vengono ignorati).
• I pulsanti vengono visualizzati, ma i clic non producono alcun effetto: verificare che il Gateway sia raggiungibile dal server Mattermost, che l'IP del server Mattermost sia incluso in channels.mattermost.interactions.allowedSourceIps (senza questa impostazione viene accettato solo il loopback) e che ServiceSettings.AllowedUntrustedInternalConnections includa l'host del callback per le destinazioni private.
• I pulsanti restituiscono 404 al clic: il valore id del pulsante probabilmente contiene trattini o caratteri di sottolineatura. Il router delle azioni di Mattermost non funziona con ID non alfanumerici. Usare solo [a-zA-Z0-9].
• Il Gateway registra rejected callback source: il clic proviene da un IP esterno a interactions.allowedSourceIps. Aggiungere il server Mattermost o il punto di ingresso alla lista consentita e impostare gateway.trustedProxies dietro un proxy inverso.
• Il Gateway registra invalid _token: mancata corrispondenza HMAC. Verificare di firmare tutti i campi del contesto (non un sottoinsieme), usare chiavi ordinate e JSON compatto (senza spazi). Consultare la sezione HMAC precedente.
• Il Gateway registra missing _token in context: il campo _token non è presente nel contesto del pulsante. Assicurarsi che sia incluso durante la creazione del payload dell'integrazione.
• Il Gateway rifiuta il clic con Unknown action: context.action_id non corrisponde ad alcun id di azione nel post. Impostare entrambi sullo stesso valore normalizzato.
• L'agente non propone pulsanti: aggiungere capabilities: ["inlineButtons"] alla configurazione del canale Mattermost.