Metadati di presentazione di Matrix

OpenClaw associa metadati MessagePresentation normalizzati agli eventi Matrix m.room.message in uscita, sotto la chiave di contenuto com.openclaw.presentation.

I client Matrix standard continuano a visualizzare il testo normale di body. I client compatibili con OpenClaw possono leggere i metadati strutturati e visualizzare un'interfaccia utente nativa, ad esempio pulsanti, selettori, righe di contesto e divisori.

Contenuto dell'evento

{  "msgtype": "m.text",  "body": "Select model\n\nChoose model:\n- DeepSeek",  "com.openclaw.presentation": {    "version": 1,    "type": "message.presentation",    "title": "Select model",    "tone": "info",    "blocks": [      {        "type": "select",        "placeholder": "Choose model",        "options": [          {            "label": "DeepSeek",            "value": "/model deepseek/deepseek-chat"          }        ]      }    ]  }}

• version è la versione dello schema dei metadati; la versione attuale è 1. type è un discriminatore stabile, sempre "message.presentation". L'adattatore Matrix emette solo payload con esattamente questa versione e questo tipo; analogamente, i client dovrebbero ignorare le versioni sconosciute che non possono interpretare in modo sicuro, i valori type sconosciuti e i tipi di blocco sconosciuti.
• title e tone (info, success, warning, danger, neutral) sono indicazioni facoltative.
• I pulsanti e le opzioni di selezione possono includere un'action tipizzata ({ "type": "command", "command": "/..." } oppure { "type": "callback", "value": "..." }) insieme alla stringa legacy value. Quando sono presenti entrambe, preferire action.

Comportamento di fallback

OpenClaw genera sempre in body un fallback di testo normale leggibile. I metadati strutturati sono aggiuntivi e non devono essere necessari per l'interoperabilità di base con Matrix.

Regole di visualizzazione del fallback:

• I contenuti title, text e context vengono visualizzati come righe di testo normale.
• I pulsanti con un'azione command vengono visualizzati come etichetta: `/comando` , affinché il comando resti copiabile. I pulsanti con un'azione callback o con il solo value legacy mostrano soltanto l'etichetta, affinché i valori di callback opachi restino privati; i pulsanti disabilitati mostrano sempre soltanto l'etichetta. I pulsanti URL e delle app web vengono visualizzati come etichetta: URL.
• I blocchi di selezione visualizzano il segnaposto (oppure Opzioni:) come intestazione, seguito da righe contenenti soltanto le etichette delle opzioni.
• Se non viene visualizzato nulla, ad esempio in una presentazione contenente solo un divisore, il corpo usa --- come fallback.

I client non supportati continuano a mostrare il testo di fallback. I client compatibili con OpenClaw possono preferire i metadati strutturati per la visualizzazione, mantenendo il fallback per copia, ricerca, notifiche e accessibilità.

Blocchi supportati

L'adattatore Matrix in uscita dichiara il supporto nativo per:

• buttons
• select
• context
• divider

I blocchi text sono sempre supportati tramite il corpo di fallback. Considerare tutti i blocchi come indicazioni di presentazione basate sul massimo impegno possibile; ignorare i campi e i tipi di blocco sconosciuti anziché causare il fallimento dell'intero messaggio.

Interazioni

Questi metadati non aggiungono una semantica di callback a Matrix. I valori dei pulsanti e delle selezioni sono payload di interazione di fallback, in genere comandi slash o comandi testuali. Un client Matrix che desidera supportare l'interazione risolve il valore del controllo (action.command, quindi action.value, quindi value) e lo invia nuovamente alla stanza come messaggio normale.

Ad esempio, un pulsante con valore /model deepseek/deepseek-chat può essere gestito inviando tale valore come messaggio di testo Matrix crittografato nella stessa stanza.

Relazione con i metadati di approvazione

com.openclaw.presentation serve per la presentazione generale di messaggi avanzati.

Le richieste di approvazione usano i metadati dedicati com.openclaw.approval, poiché le approvazioni includono stato sensibile per la sicurezza, decisioni e dettagli di esecuzione/Plugin. Se entrambe le chiavi di metadati sono presenti nello stesso evento, i client dovrebbero preferire il visualizzatore dedicato alle approvazioni.

Messaggi multimediali

Quando una risposta contiene più URL multimediali, OpenClaw invia un evento Matrix per ogni URL multimediale. Il testo della didascalia e i metadati di presentazione vengono associati soltanto al primo evento, così i client ricevono un unico payload strutturato stabile senza visualizzatori duplicati. La stessa regola si applica quando un testo lungo viene suddiviso tra più eventi: i metadati vengono inclusi soltanto nel primo evento.

Mantenere compatti i metadati di presentazione. Il testo esteso visibile all'utente deve rimanere in body e usare il normale percorso di suddivisione del testo di Matrix.