Matrix presentation metadata

기준일: 2026-07-26
공식 기준: Matrix presentation metadata

Matrix presentation metadata 문서는 OpenClaw 공식 문서(channels/matrix-presentation)를 한국어로 정리한 가이드입니다. Matrix MessagePresentation metadata for OpenClaw-aware clients 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Matrix MessagePresentation metadata for OpenClaw-aware clients

한국어 가이드 범위: channels/matrix-presentation 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Event content
• Fallback behavior
• Supported blocks
• Interactions
• Relationship to approval metadata
• Media messages

상세 내용

본문

OpenClaw attaches normalized MessagePresentation metadata to outbound Matrix m.room.message events under the com.openclaw.presentation content key.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Event content

주요 항목:

• version is the metadata schema version; the current version is 1. type is a stable discriminator, always "message.presentation". The Matrix adapter only emits payloads with exactly this version and type; clients should likewise ignore unknown versions they cannot safely interpret, unknown type values, and unknown block types.
• title and tone (info, success, warning, danger, neutral) are optional hints.
• Buttons and select options can carry a typed action ({ "type": "command", "command": "/..." } or { "type": "callback", "value": "..." }) alongside the legacy string value. Prefer action when both are present.

{
  "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"
          }
        ]
      }
    ]
  }
}

Fallback behavior

OpenClaw always renders a readable plain text fallback into body. The structured metadata is additive and must not be required for basic Matrix interoperability.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• title, text, and context content renders as plain lines.
• Buttons with a command action render as label: `/command` so the command stays copyable. Buttons with a callback action or only a legacy value render label-only so opaque callback values stay private; disabled buttons are always label-only. URL and web-app buttons render as label: URL.
• Select blocks render the placeholder (or Options:) as a heading plus label-only option lines.
• If nothing renders, for example a divider-only presentation, the body falls back to ---.

Supported blocks

The Matrix outbound adapter advertises native support for:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• buttons
• select
• context
• divider

Interactions

This metadata does not add Matrix callback semantics. Button and select values are fallback interaction payloads, usually slash commands or text commands. A Matrix client that wants to support interaction resolves the control value (action.command, then action.value, then value) and sends it back to the room as a normal message.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Relationship to approval metadata

com.openclaw.presentation is for general rich message presentation.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Media messages

When a reply contains multiple media URLs, OpenClaw sends one Matrix event per media URL. Caption text and presentation metadata attach only to the first event so clients get one stable structured payload without duplicate renderers. The same rule applies when long text is chunked across events: the metadata rides on the first event only.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/channels/matrix-presentation
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  "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"
          }
        ]
      }
    ]
  }
}

관련 링크

• 공식 원문: channels/matrix-presentation
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.