Mattermost

• Il valore predefinito di native e nativeSkills è "auto", che per Mattermost viene interpretato come disabilitato. Impostali esplicitamente su true.
• Il valore predefinito di callbackPath è /api/channels/mattermost/command.
• Se callbackUrl viene omesso, OpenClaw ricava http://<gateway.customBindHost or localhost>:<gateway.port, default 18789><callbackPath>. Gli host di associazione con caratteri jolly (0.0.0.0, ::) usano localhost come ripiego.
• Nelle configurazioni con più account, commands può essere impostato al livello superiore o in channels.mattermost.accounts.<id>.commands (i valori dell'account sostituiscono i 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 mediante i token specifici per comando restituiti da Mattermost quando OpenClaw registra i comandi oc_*.
• OpenClaw aggiorna la registrazione corrente dei comandi Mattermost prima di accettare ogni callback, quindi i token obsoleti di comandi slash eliminati o rigenerati cessano di essere accettati senza dover riavviare il Gateway.
• La convalida delle callback non consente l'accesso 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 è soggetto a un limite di frequenza per comando, così da contenere la pressione dei tentativi di ripetizione.
• Le callback slash non consentono l'accesso quando 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 conferma con 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 o nello stesso 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.
• Per una verifica rapida, usa curl https://<gateway-host>/api/channels/mattermost/command; una richiesta GET deve restituire 405 Method Not Allowed da OpenClaw, non 404.

Se la callback è indirizzata a indirizzi privati/tailnet/interni, imposta ServiceSettings.AllowedUntrustedInternalConnections di Mattermost in modo da includere l'host o il dominio della callback.

Usa 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 mentre la risposta cresce, quindi finalizzato con la risposta completa.
• block alterna l'anteprima tra blocchi di testo completato e di attività degli strumenti, così ogni blocco rimane visibile come post separato anziché 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 disabilita lo streaming dell'anteprima. Con blockStreaming: true, i blocchi completati dell'assistente vengono comunque consegnati come normali risposte a blocchi (post separati), anziché come un unico post finale aggregato.

• Se lo stream non può essere finalizzato sul posto, ad esempio perché il post è stato eliminato durante lo streaming, OpenClaw ricorre all'invio di un nuovo post finale, così la risposta non va mai persa.
• I payload contenenti solo il ragionamento non vengono pubblicati nei post del canale, incluso il testo che arriva come citazione > Thinking. Imposta /reasoning on per visualizzare il ragionamento in altre interfacce; il post finale di Mattermost mantiene solo la risposta.
• Consulta Streaming per la matrice di mappatura dei canali.

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

• channels.mattermost.capabilities: array di stringhe delle funzionalità. Aggiungi "inlineButtons" per abilitare la descrizione dello strumento per i 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. Usalo quando Mattermost non può raggiungere direttamente il Gateway tramite il relativo host di binding.
• Nelle configurazioni con più account, puoi impostare lo stesso campo anche in channels.mattermost.accounts.<id>.interactions.callbackBaseUrl.
• Se interactions.callbackBaseUrl viene omesso, OpenClaw ricava l'URL di callback da gateway.customBindHost + gateway.port (valore predefinito: 18789), quindi ripiega su http://localhost:<port>. Il percorso di callback è /mattermost/interactions/<accountId>.
• Regola di raggiungibilità: l'URL di callback dei pulsanti deve essere raggiungibile dal server Mattermost. localhost funziona solo quando Mattermost e OpenClaw sono in esecuzione sullo stesso host/spazio dei nomi di rete.
• channels.mattermost.interactions.allowedSourceIps: elenco di indirizzi IP di origine consentiti per i callback dei pulsanti. Senza questa opzione, vengono accettate solo le origini local loopback (127.0.0.1, ::1), quindi un server Mattermost remoto deve essere aggiunto qui all'elenco degli indirizzi consentiti, altrimenti le sue selezioni vengono rifiutate con 403. Dietro un proxy inverso, imposta anche gateway.trustedProxies, così l'IP reale del client viene ricavato dalle intestazioni inoltrate.
• Se la destinazione del callback è privata, interna o nella tailnet, aggiungi il relativo host/dominio a ServiceSettings.AllowedUntrustedInternalConnections di Mattermost.

• Per impostazione predefinita, json.dumps di Python aggiunge spazi ({"key": "val"}). Usa separators=(",", ":") per ottenere lo stesso output compatto di JavaScript ({"key":"val"}).
• Firma sempre tutti i campi del contesto, escluso _token. Il Gateway rimuove _token, quindi firma tutto ciò che rimane. Firmare solo un sottoinsieme causa un errore di verifica senza notifiche.
• Usa sort_keys=True: il Gateway ordina le chiavi prima della firma e Mattermost potrebbe riordinare i campi del contesto durante l'archiviazione del payload.
• Deriva il segreto dal token del bot in modo deterministico, anziché usare byte casuali. Il segreto deve essere identico nel processo che crea i pulsanti e nel Gateway che esegue la verifica.

Assicurati che il bot sia nel canale e menzionalo (oncall), usa un prefisso di attivazione (onchar) oppure imposta chatmode: "onmessage".

• Controlla il token del bot, l'URL di base e che l'account sia abilitato.
• Problemi con più account: le variabili di ambiente si applicano solo all'account default.
• Gli host Mattermost privati/LAN richiedono network.dangerouslyAllowPrivateNetwork: true (per impostazione predefinita, la protezione SSRF blocca 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
  • la callback raggiunge il Gateway o l'account errato
  • Mattermost conserva 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, controlla 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 avvisano che la callback è stata risolta in un URL local loopback come http://localhost:18789/..., probabilmente tale URL è raggiungibile solo quando Mattermost viene eseguito nello stesso host/spazio dei nomi di rete di OpenClaw. Imposta 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: verifica 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 local loopback) e che ServiceSettings.AllowedUntrustedInternalConnections includa l'host di callback per le destinazioni private.
• I pulsanti restituiscono un errore 404 al clic: probabilmente l'id del pulsante contiene trattini o trattini bassi. Il router delle azioni di Mattermost non funziona con ID non alfanumerici. Usa esclusivamente [a-zA-Z0-9].
• Nei log del Gateway compare rejected callback source: il clic proviene da un IP non incluso in interactions.allowedSourceIps. Aggiungi il server Mattermost o il tuo ingresso all'elenco dei consentiti e imposta gateway.trustedProxies se utilizzi un proxy inverso.
• Nei log del Gateway compare invalid _token: mancata corrispondenza HMAC. Verifica di firmare tutti i campi del contesto (non solo un sottoinsieme), di usare chiavi ordinate e JSON compatto (senza spazi). Consulta la sezione HMAC precedente.
• Nei log del Gateway compare missing _token in context: il campo _token non è presente nel contesto del pulsante. Assicurati che venga incluso durante la creazione del payload dell'integrazione.
• Il Gateway rifiuta il clic con Unknown action: context.action_id non corrisponde all'id di alcuna azione nel post. Imposta entrambi sullo stesso valore normalizzato.
• L'agente non propone pulsanti: aggiungi capabilities: ["inlineButtons"] alla configurazione del canale Mattermost.