Mattermost

• native: "auto" è disabilitato per impostazione predefinita per Mattermost. Imposta native: true per abilitarlo.
• Se callbackUrl viene omesso, OpenClaw ne deriva uno da host/porta del gateway + callbackPath.
• Per configurazioni con più account, commands può essere impostato al livello superiore o sotto channels.mattermost.accounts.<id>.commands (i valori dell'account sovrascrivono i campi di livello superiore).
• Le callback dei comandi vengono convalidate con i token per comando restituiti da Mattermost quando OpenClaw registra i comandi oc_*.
• OpenClaw aggiorna la registrazione corrente dei comandi Mattermost prima di accettare ogni callback, così i token obsoleti di comandi slash eliminati o rigenerati smettono di essere accettati senza riavviare il gateway.
• La convalida della callback fallisce in modo chiuso se l'API Mattermost non può confermare che il comando sia ancora corrente; le convalide non riuscite vengono memorizzate brevemente nella cache, le ricerche concorrenti vengono accorpate e gli avvii di nuove ricerche sono limitati per frequenza per comando per contenere la pressione da replay.
• Le callback slash falliscono in modo chiuso 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 upstream per un comando diverso).

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

• Non impostare callbackUrl su localhost a meno che Mattermost non sia in esecuzione nello stesso host/namespace di rete di OpenClaw.
• Non impostare callbackUrl sull'URL di base di Mattermost a meno che quell'URL non inoltri tramite reverse proxy /api/channels/mattermost/command a OpenClaw.
• Un controllo rapido è curl https://<gateway-host>/api/channels/mattermost/command; una GET dovrebbe restituire 405 Method Not Allowed da OpenClaw, non 404.

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

Usa voci host/dominio, non URL completi.

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

• partial è la scelta abituale: un post di anteprima che viene modificato man mano che la risposta cresce, poi finalizzato con la risposta completa.
• block usa blocchi bozza in stile append all'interno del post di anteprima.
• progress mostra un'anteprima di stato durante la generazione e pubblica solo la risposta finale al completamento.
• off disabilita lo streaming dell'anteprima.

• Se lo stream non può essere finalizzato sul posto (per esempio il post è stato eliminato a metà stream), OpenClaw ripiega sull'invio di un nuovo post finale, così la risposta non viene mai persa.
• I payload solo di pensiero vengono soppressi dai post del canale, incluso il testo che arriva come blockquote > Thinking. Imposta /reasoning on per vedere il pensiero in altre superfici; il post finale di Mattermost mantiene solo la risposta.
• Vedi Streaming per la matrice di mapping dei canali.

• I callback dei pulsanti usano la verifica HMAC-SHA256 (automatica, non richiede configurazione).
• Mattermost rimuove i dati di callback dalle sue risposte API (funzionalità di sicurezza), quindi tutti i pulsanti vengono rimossi al clic: la rimozione parziale non è possibile.
• Gli ID azione che contengono trattini o underscore vengono sanificati automaticamente (limitazione del routing di Mattermost).

• channels.mattermost.capabilities: array di stringhe di funzionalità. Aggiungi "inlineButtons" per abilitare la descrizione dello strumento dei pulsanti nel prompt di sistema dell'agente.
• channels.mattermost.interactions.callbackBaseUrl: URL base esterno facoltativo per i callback dei pulsanti (ad esempio https://gateway.example.com). Usalo quando Mattermost non può raggiungere direttamente il gateway al suo host di bind.
• Nelle configurazioni multi-account, puoi impostare lo stesso campo anche sotto channels.mattermost.accounts.<id>.interactions.callbackBaseUrl.
• Se interactions.callbackBaseUrl viene omesso, OpenClaw deriva l'URL di callback da gateway.customBindHost + gateway.port, poi ripiega su http://localhost:<port>.
• 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 sullo stesso host/spazio dei nomi di rete.
• Se la destinazione del callback è privata/tailnet/interna, aggiungi il suo host/dominio a ServiceSettings.AllowedUntrustedInternalConnections di Mattermost.

• json.dumps di Python aggiunge spazi per impostazione predefinita ({"key": "val"}). Usa separators=(",", ":") per corrispondere all'output compatto di JavaScript ({"key":"val"}).
• Firma sempre tutti i campi del context (meno _token). Il gateway rimuove _token e poi firma tutto ciò che rimane. Firmare un sottoinsieme causa un errore di verifica silenzioso.
• Usa sort_keys=True: il gateway ordina le chiavi prima della firma e Mattermost potrebbe riordinare i campi del context durante la memorizzazione del payload.
• Deriva il segreto dal token del bot (deterministico), non da byte casuali. Il segreto deve essere lo stesso tra il processo che crea i pulsanti e il gateway che verifica.

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

• Controlla il token del bot, l'URL base e se l'account è abilitato.
• Problemi multi-account: le variabili d'ambiente si applicano solo all'account default.

• 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 sta raggiungendo il gateway/account sbagliato
  • Mattermost ha 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 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 il callback è stato risolto in http://127.0.0.1:18789/..., quell'URL è probabilmente raggiungibile solo quando Mattermost è in esecuzione sullo 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: l'agente potrebbe inviare dati dei pulsanti non validi. Controlla che ogni pulsante abbia entrambi i campi text e callback_data.
• I pulsanti vengono renderizzati ma i clic non producono effetti: verifica che AllowedUntrustedInternalConnections nella configurazione del server Mattermost includa 127.0.0.1 localhost e che EnablePostActionIntegration sia true in ServiceSettings.
• I pulsanti restituiscono 404 al clic: l'id del pulsante probabilmente contiene trattini o underscore. Il router delle azioni di Mattermost si interrompe con ID non alfanumerici. Usa solo [a-zA-Z0-9].
• I log del gateway mostrano invalid _token: mancata corrispondenza HMAC. Controlla di firmare tutti i campi del context (non un sottoinsieme), di usare chiavi ordinate e JSON compatto (senza spazi). Vedi la sezione HMAC sopra.
• I log del gateway mostrano missing _token in context: il campo _token non è nel context del pulsante. Assicurati che sia incluso quando costruisci il payload di integrazione.
• La conferma mostra l'ID grezzo invece del nome del pulsante: context.action_id non corrisponde all'id del pulsante. Impostali entrambi allo stesso valore sanificato.
• L'agente non sa dei pulsanti: aggiungi capabilities: ["inlineButtons"] alla configurazione del canale Mattermost.