---
read_when:
    - Создание клиентов Matrix, отображающих форматированные ответы OpenClaw
    - Отладка содержимого событий com.openclaw.presentation
summary: Метаданные Matrix MessagePresentation для клиентов с поддержкой OpenClaw
title: Метаданные представления Matrix
x-i18n:
    generated_at: "2026-07-13T17:54:23Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 24
    provider: openai
    source_hash: c0de4d13c6cefc6f91dcc7a4b0edeea6bf001f3bd71f52c9f0498ad422783d8a
    source_path: channels/matrix-presentation.md
    workflow: 16
---

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.