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 multi-account, commands può essere impostato al livello principale o sotto channels.mattermost.accounts.<id>.commands (i valori dell'account sovrascrivono i campi di livello principale).
• I callback dei comandi vengono convalidati 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 provenienti da comandi slash eliminati o rigenerati smettono di essere accettati senza riavviare il Gateway.
• La convalida del 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.
• I callback slash falliscono in modo chiuso quando la registrazione non è riuscita, l'avvio è stato parziale o il token del 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 sullo stesso host/namespace di rete di OpenClaw.
• Non impostare callbackUrl sul base URL di Mattermost a meno che quell'URL non esegua reverse proxy di /api/channels/mattermost/command verso OpenClaw.
• Un controllo rapido è curl https://<gateway-host>/api/channels/mattermost/command; una richiesta GET dovrebbe restituire 405 Method Not Allowed da OpenClaw, non 404.

Se il callback punta a indirizzi privati/tailnet/interni, imposta ServiceSettings.AllowedUntrustedInternalConnections di Mattermost in modo da includere host/dominio del 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 (ad esempio il post è stato eliminato durante lo stream), OpenClaw ripiega sull'invio di un nuovo post finale, così la risposta non viene mai persa.
• I payload di solo ragionamento vengono soppressi dai post del canale, incluso il testo che arriva come blockquote > Reasoning:. Imposta /reasoning on per vedere il pensiero in altre superfici; il post finale Mattermost mantiene solo la risposta.
• Consulta Streaming per la matrice di mappatura dei canali.

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

• channels.mattermost.capabilities: array di stringhe di capability. Aggiungi "inlineButtons" per abilitare la descrizione dello strumento dei pulsanti nel prompt di sistema dell'agente.
• channels.mattermost.interactions.callbackBaseUrl: URL base esterno opzionale per i callback dei pulsanti (ad esempio https://gateway.example.com). Usalo quando Mattermost non può raggiungere il gateway direttamente 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 vengono eseguiti sullo stesso host/namespace 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 di firmare, e Mattermost può riordinare i campi del context quando memorizza il 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 di attivazione (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 i log per 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 viene eseguito sullo stesso host/namespace di rete di OpenClaw. Imposta invece un commands.callbackUrl esplicito raggiungibile dall'esterno.

• I pulsanti appaiono come riquadri bianchi: l'agente potrebbe inviare dati dei pulsanti malformati. 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 rompe 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 crei il payload di integrazione.
• La conferma mostra l'ID grezzo invece del nome del pulsante: context.action_id non corrisponde all'id del pulsante. Imposta entrambi sullo stesso valore sanificato.
• L'agente non sa dei pulsanti: aggiungi capabilities: ["inlineButtons"] alla configurazione del canale Mattermost.