OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Mainstream messaging

Matrix プレゼンテーションメタデータ

OpenClaw は、正規化された MessagePresentation メタデータを、送信する Matrix の m.room.message イベントに com.openclaw.presentation コンテンツキーで付加します。

標準の Matrix クライアントは、引き続きプレーンテキストの body をレンダリングします。OpenClaw 対応クライアントは構造化メタデータを読み取り、ボタン、選択コントロール、コンテキスト行、区切り線などのネイティブ UI をレンダリングできます。

イベントの内容

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）は任意のヒントです。
  • ボタンと選択肢には、従来の文字列 value に加えて、型付きの action（{ "type": "command", "command": "/..." } または { "type": "callback", "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 は、汎用的なリッチメッセージのプレゼンテーションに使用します。

承認プロンプトでは、安全性に関わる状態、判断、実行や Plugin の詳細を扱うため、専用の com.openclaw.approval メタデータを使用します。同じイベントに両方のメタデータキーが存在する場合、クライアントは専用の承認レンダラーを優先する必要があります。

メディアメッセージ

返信に複数のメディア URL が含まれる場合、OpenClaw はメディア URL ごとに Matrix イベントを 1 件送信します。クライアントが重複したレンダラーなしで安定した構造化ペイロードを 1 つ受け取れるように、キャプションテキストとプレゼンテーションメタデータは最初のイベントにだけ付加されます。長いテキストが複数のイベントに分割される場合にも同じ規則が適用され、メタデータは最初のイベントだけに付加されます。

プレゼンテーションメタデータはコンパクトに保ってください。ユーザーに表示する長いテキストは body に格納し、通常の Matrix テキスト分割経路を使用する必要があります。

Was this useful?
On this page

On this page