Mainstream messaging

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

OpenClaw прикрепляет нормализованные метаданные MessagePresentation к исходящим событиям Matrix m.room.message в ключе содержимого com.openclaw.presentation.

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

Содержимое события

json

{  "msgtype": "m.text",  "body": "Выберите модель\n\nВыберите модель:\n- DeepSeek",  "com.openclaw.presentation": {    "version": 1,    "type": "message.presentation",    "title": "Выберите модель",    "tone": "info",    "blocks": [      {        "type": "select",        "placeholder": "Выберите модель",        "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 отображаются как label: `/command` , чтобы команду можно было скопировать. Кнопки с действием callback или только с устаревшим значением value отображаются только как метки, чтобы непрозрачные значения обратного вызова оставались конфиденциальными; отключённые кнопки всегда отображаются только как метки. Кнопки с URL и веб-приложениями отображаются как label: URL.
Блоки выбора отображают заполнитель (или Options:) как заголовок, за которым следуют строки вариантов, содержащие только метки.
Если ничего не отображается, например когда представление содержит только разделитель, тело заменяется на ---.

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

Поддерживаемые блоки

Исходящий адаптер Matrix заявляет нативную поддержку следующих блоков:

buttons
select
context
divider

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

Взаимодействия

Эти метаданные не добавляют семантику обратных вызовов Matrix. Значения кнопок и вариантов выбора являются резервными полезными нагрузками взаимодействия, обычно командами с косой чертой или текстовыми командами. Клиент Matrix, который хочет поддерживать взаимодействие, определяет значение элемента управления (action.command, затем action.value, затем value) и отправляет его обратно в комнату как обычное сообщение.

Например, кнопку со значением /model deepseek/deepseek-chat можно обработать, отправив это значение как зашифрованное текстовое сообщение Matrix в той же комнате.

Связь с метаданными подтверждений

com.openclaw.presentation предназначено для общего расширенного представления сообщений.

Для запросов подтверждения используются специальные метаданные com.openclaw.approval, поскольку подтверждения содержат состояние, решения и сведения о выполнении или плагине, связанные с безопасностью. Если в одном событии присутствуют оба ключа метаданных, клиентам следует предпочитать специальный обработчик отображения подтверждений.

Медиасообщения

Если ответ содержит несколько URL-адресов медиафайлов, OpenClaw отправляет отдельное событие Matrix для каждого URL-адреса. Текст подписи и метаданные представления прикрепляются только к первому событию, чтобы клиенты получали одну стабильную структурированную полезную нагрузку без дублирования обработчиков отображения. То же правило применяется, когда длинный текст разбивается на несколько событий: метаданные передаются только в первом событии.

Сохраняйте метаданные представления компактными. Большой объём видимого пользователю текста должен оставаться в body и передаваться через обычный механизм разбиения текста Matrix.

Was this useful?