Mainstream messaging

Метадані представлення Matrix

OpenClaw додає нормалізовані метадані MessagePresentation до вихідних подій Matrix m.room.message у ключі вмісту com.openclaw.presentation.

Стандартні клієнти Matrix продовжують відображати звичайний текст із body. Клієнти з підтримкою OpenClaw можуть читати структуровані метадані та відображати нативний інтерфейс, наприклад кнопки, списки вибору, контекстні рядки й роздільники.

Вміст події

json

{  "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 — версія схеми метаданих; поточна версія — 1. type — стабільний дискримінатор, який завжди має значення "message.presentation". Адаптер Matrix надсилає лише корисні навантаження саме з такою версією та типом; клієнти також мають ігнорувати невідомі версії, які вони не можуть безпечно інтерпретувати, невідомі значення type та невідомі типи блоків.
title і tone (info, success, warning, danger, neutral) — необов’язкові підказки.
Кнопки та варіанти вибору можуть містити типізовану дію action ({ "type": "command", "command": "/..." } або { "type": "callback", "value": "..." }) разом із застарілим рядковим значенням value. Якщо присутні обидва, віддавайте перевагу action.

Резервна поведінка

OpenClaw завжди формує в body читабельний резервний варіант у вигляді звичайного тексту. Структуровані метадані є доповненням і не повинні бути обов’язковими для базової сумісності з Matrix.

Правила резервного відображення:

Вміст title, text і context відображається як звичайні рядки.
Кнопки з дією command відображаються у форматі мітка: `/команда` , щоб команду можна було скопіювати. Кнопки з дією callback або лише із застарілим значенням value відображаються тільки як мітки, щоб непрозорі значення зворотного виклику залишалися приватними; вимкнені кнопки завжди відображаються лише як мітки. Кнопки з URL та вебзастосунками відображаються у форматі мітка: URL.
Блоки вибору відображають заповнювач (або Варіанти:) як заголовок, а нижче — рядки варіантів лише з мітками.
Якщо нічого не відображається, наприклад у представленні лише з роздільником, значення body набуває резервного вигляду ---.

Клієнти без підтримки продовжують показувати резервний текст. Клієнти з підтримкою OpenClaw можуть віддавати перевагу структурованим метаданим для відображення, зберігаючи резервний варіант для копіювання, пошуку, сповіщень і доступності.

Підтримувані блоки

Адаптер вихідних повідомлень Matrix заявляє нативну підтримку таких блоків:

buttons
select
context
divider

Блоки text завжди підтримуються через резервне значення body. Розглядайте всі блоки як необов’язкові підказки для представлення; ігноруйте невідомі поля й типи блоків замість того, щоб відхиляти все повідомлення.

Взаємодії

Ці метадані не додають семантики зворотних викликів Matrix. Значення кнопок і варіантів вибору є резервними корисними навантаженнями взаємодії, зазвичай слеш-командами або текстовими командами. Клієнт Matrix, який хоче підтримувати взаємодію, визначає значення елемента керування (action.command, потім action.value, потім value) і надсилає його назад до кімнати як звичайне повідомлення.

Наприклад, кнопку зі значенням /model deepseek/deepseek-chat можна обробити, надіславши це значення як зашифроване текстове повідомлення Matrix у тій самій кімнаті.

Зв’язок із метаданими схвалення

com.openclaw.presentation призначено для загального розширеного представлення повідомлень.

Запити на схвалення використовують спеціальні метадані com.openclaw.approval, оскільки схвалення містять чутливі з погляду безпеки стан, рішення та відомості про виконання або Plugin. Якщо в одній події присутні обидва ключі метаданих, клієнти мають віддавати перевагу спеціальному засобу відображення схвалень.

Медіаповідомлення

Коли відповідь містить кілька URL-адрес медіафайлів, OpenClaw надсилає окрему подію Matrix для кожної URL-адреси. Текст підпису та метадані представлення додаються лише до першої події, щоб клієнти отримували одне стабільне структуроване корисне навантаження без дублювання засобів відображення. Те саме правило діє, коли довгий текст розбивається на частини в кількох подіях: метадані передаються лише з першою подією.

Зберігайте метадані представлення компактними. Великий видимий користувачеві текст має залишатися в body і використовувати звичайний механізм поділу тексту Matrix на частини.

Was this useful?