メッセージの表示

メッセージプレゼンテーションは、リッチなアウトバウンドチャット UI のための OpenClaw の共有コントラクトです。 これにより、エージェント、CLI コマンド、承認フロー、Plugin はメッセージの 意図を一度だけ記述でき、各チャネル Plugin が可能な限り最適なネイティブ形式でレンダーします。

ポータブルなメッセージ UI にはプレゼンテーションを使用します。

• テキストセクション
• 小さなコンテキスト/フッターテキスト
• 区切り線
• ボタン
• セレクトメニュー
• カードタイトルとトーン

共有メッセージツールに、Discord components、Slack blocks、Telegram buttons、Teams card、Feishu card などの新しいプロバイダー固有フィールドを追加しないでください。 これらはチャネル Plugin が所有するレンダラー出力です。

コントラクト

Plugin 作者は次から公開コントラクトをインポートします。

   MessagePresentation,  ReplyPayloadDelivery,} from "openclaw/plugin-sdk/interactive-runtime";

形状:

type MessagePresentation = {  title?: string;  tone?: "neutral" | "info" | "success" | "warning" | "danger";  blocks: MessagePresentationBlock[];}; type MessagePresentationBlock =  | { type: "text"; text: string }  | { type: "context"; text: string }  | { type: "divider" }  | { type: "buttons"; buttons: MessagePresentationButton[] }  | { type: "select"; placeholder?: string; options: MessagePresentationOption[] }; type MessagePresentationButton = {  label: string;  value?: string;  url?: string;  style?: "primary" | "secondary" | "success" | "danger";}; type MessagePresentationOption = {  label: string;  value: string;}; type ReplyPayloadDelivery = {  pin?:    | boolean    | {        enabled: boolean;        notify?: boolean;        required?: boolean;      };};

ボタンのセマンティクス:

• value は、チャネルがクリック可能なコントロールをサポートする場合に、チャネルの 既存のインタラクション経路を通じてルーティングされるアプリケーションアクション値です。
• url はリンクボタンです。value なしでも存在できます。
• label は必須で、テキストフォールバックでも使用されます。
• style は助言的です。レンダラーは、サポートされていないスタイルを送信失敗にするのではなく、安全な デフォルトにマッピングする必要があります。

セレクトのセマンティクス:

• options[].value は選択されたアプリケーション値です。
• placeholder は助言的で、ネイティブの セレクトサポートがないチャネルでは無視される場合があります。
• チャネルがセレクトをサポートしない場合、フォールバックテキストにはラベルが一覧表示されます。

プロデューサー例

シンプルなカード:

{  "title": "Deploy approval",  "tone": "warning",  "blocks": [    { "type": "text", "text": "Canary is ready to promote." },    { "type": "context", "text": "Build 1234, staging passed." },    {      "type": "buttons",      "buttons": [        { "label": "Approve", "value": "deploy:approve", "style": "success" },        { "label": "Decline", "value": "deploy:decline", "style": "danger" }      ]    }  ]}

URL のみのリンクボタン:

{  "blocks": [    { "type": "text", "text": "Release notes are ready." },    {      "type": "buttons",      "buttons": [{ "label": "Open notes", "url": "https://example.com/release" }]    }  ]}

セレクトメニュー:

{  "title": "Choose environment",  "blocks": [    {      "type": "select",      "placeholder": "Environment",      "options": [        { "label": "Canary", "value": "env:canary" },        { "label": "Production", "value": "env:prod" }      ]    }  ]}

CLI 送信:

openclaw message send --channel slack \  --target channel:C123 \  --message "Deploy approval" \  --presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Canary is ready."},{"type":"buttons","buttons":[{"label":"Approve","value":"deploy:approve","style":"success"},{"label":"Decline","value":"deploy:decline","style":"danger"}]}]}'

ピン留め配信:

openclaw message send --channel telegram \  --target -1001234567890 \  --message "Topic opened" \  --pin

明示的な JSON を使ったピン留め配信:

{  "pin": {    "enabled": true,    "notify": true,    "required": false  }}

レンダラーコントラクト

チャネル Plugin はアウトバウンドアダプターでレンダーサポートを宣言します。

const adapter: ChannelOutboundAdapter = {  deliveryMode: "direct",  presentationCapabilities: {    supported: true,    buttons: true,    selects: true,    context: true,    divider: true,  },  deliveryCapabilities: {    pin: true,  },  renderPresentation({ payload, presentation, ctx }) {    return renderNativePayload(payload, presentation, ctx);  },  async pinDeliveredMessage({ target, messageId, pin }) {    await pinNativeMessage(target, messageId, { notify: pin.notify === true });  },};

ケイパビリティフィールドは意図的に単純なブール値です。これらは、あらゆるネイティブプラットフォームの制限ではなく、 レンダラーが何をインタラクティブにできるかを記述します。レンダラーは、最大ボタン数、ブロック数、 カードサイズなどのプラットフォーム固有の制限も引き続き所有します。

コアレンダーフロー

ReplyPayload またはメッセージアクションに presentation が含まれる場合、コアは次を行います。

1. プレゼンテーションペイロードを正規化します。
2. 対象チャネルのアウトバウンドアダプターを解決します。
3. presentationCapabilities を読み取ります。
4. アダプターがペイロードをレンダーできる場合、renderPresentation を呼び出します。
5. アダプターが存在しない、またはレンダーできない場合、保守的なテキストにフォールバックします。
6. 結果のペイロードを通常のチャネル配信経路で送信します。
7. 最初の正常に送信されたメッセージの後に、delivery.pin などの配信メタデータを適用します。

コアはフォールバック動作を所有するため、プロデューサーはチャネル非依存のままでいられます。チャネル Plugin はネイティブレンダリングとインタラクション処理を所有します。

デグラデーションルール

プレゼンテーションは、制限のあるチャネルでも安全に送信できる必要があります。

フォールバックテキストには次が含まれます。

• 最初の行としての title
• 通常の段落としての text ブロック
• コンパクトなコンテキスト行としての context ブロック
• 視覚的な区切りとしての divider ブロック
• リンクボタンの URL を含むボタンラベル
• セレクトオプションラベル

サポートされていないネイティブコントロールは、送信全体を失敗させるのではなくデグレードする必要があります。 例:

• インラインボタンが無効な Telegram はテキストフォールバックを送信します。
• セレクトサポートのないチャネルは、セレクトオプションをテキストとして一覧表示します。
• URL のみのボタンは、ネイティブリンクボタンまたはフォールバック URL 行になります。
• 任意のピン留め失敗は、配信済みメッセージを失敗させません。

主な例外は delivery.pin.required: true です。ピン留めが必須として要求され、 チャネルが送信済みメッセージをピン留めできない場合、配信は失敗を報告します。

プロバイダーマッピング

現在のバンドル済みレンダラー:

プロバイダー固有ペイロード互換性は、既存の 返信プロデューサーのための移行支援です。新しい共有ネイティブフィールドを追加する理由にはなりません。

プレゼンテーションと InteractiveReply

InteractiveReply は、承認およびインタラクション ヘルパーで使用される古い内部サブセットです。次をサポートします。

• テキスト
• ボタン
• セレクト

MessagePresentation は正規の共有送信コントラクトです。次を追加します。

• タイトル
• トーン
• コンテキスト
• 区切り線
• URL のみのボタン
• ReplyPayload.delivery を通じた汎用配信メタデータ

古いコードを橋渡しする場合は、openclaw/plugin-sdk/interactive-runtime のヘルパーを使用します。

   interactiveReplyToPresentation,  normalizeMessagePresentation,  presentationToInteractiveControlsReply,  presentationToInteractiveReply,  renderMessagePresentationFallbackText,} from "openclaw/plugin-sdk/interactive-runtime";

新しいコードは MessagePresentation を直接受け入れるか生成する必要があります。

presentationToInteractiveReply(...) は、タイトル、テキスト、コンテキスト、ボタン、セレクトを古い InteractiveReply 形状にマッピングすることで、表示されるプレゼンテーションテキストを保持します。タイトル、テキスト、 コンテキスト、区切り線ブロックをすでにネイティブに描画しているコンポーネントレンダラーは、代わりに presentationToInteractiveControlsReply(...) を使用し、その後ボタンとセレクトコントロールのみを追加する必要があります。

renderMessagePresentationFallbackText(...) は、区切り線のみの プレゼンテーションなど、テキストフォールバックを持たないプレゼンテーションブロックに対して空文字列を返します。空でない送信本文を必要とするトランスポートは、 デフォルトのフォールバックコントラクトを変更せずに最小限の本文を選択するために emptyFallback を渡せます。

配信ピン留め

ピン留めは配信動作であり、プレゼンテーションではありません。channelData.telegram.pin などの プロバイダー固有フィールドではなく delivery.pin を使用します。

セマンティクス:

• pin: true は、最初に正常に配信されたメッセージをピン留めします。
• pin.notify のデフォルトは false です。
• pin.required のデフォルトは false です。
• 任意のピン留め失敗はデグレードし、送信済みメッセージはそのまま残ります。
• 必須のピン留め失敗は配信を失敗させます。
• チャンク化されたメッセージは、末尾のチャンクではなく最初に配信されたチャンクをピン留めします。

既存メッセージについて、プロバイダーがそれらの操作をサポートする場合、手動の pin、unpin、pins メッセージアクションは引き続き存在します。

Plugin 作者チェックリスト

• チャネルがセマンティックプレゼンテーションをレンダーまたは安全にデグレードできる場合、describeMessageTool(...) から presentation を宣言します。
• ランタイムアウトバウンドアダプターに presentationCapabilities を追加します。
• コントロールプレーンの Plugin セットアップコードではなく、ランタイムコードで renderPresentation を実装します。
• ネイティブ UI ライブラリをホットなセットアップ/カタログ経路に入れないでください。
• レンダラーとテストでプラットフォーム制限を保持します。
• サポートされていないボタン、セレクト、URL ボタン、タイトル/テキストの重複、および混在した message と presentation 送信に対するフォールバックテストを追加します。
• プロバイダーが送信済みメッセージ ID をピン留めできる場合のみ、deliveryCapabilities.pin と pinDeliveredMessage を通じて配信ピンサポートを追加します。
• 共有メッセージアクションスキーマを通じて、新しいプロバイダー固有のカード/ブロック/コンポーネント/ボタンフィールドを公開しないでください。

関連ドキュメント

• メッセージ CLI
• Plugin SDK 概要
• Plugin アーキテクチャ
• チャネルプレゼンテーションリファクタリング計画