ウィジェットを表示

show_widget は、ユーザーの現在の画面に自己完結型 HTML ウィジェットを表示するコアツールです。OpenClaw は、Control UI、および iOS、Android、macOS、Linux の Quick Chat トランスクリプト内にインラインでレンダリングします。Linux ダッシュボードはブラウザー版 Control UI を使用します。Activities が有効な Discord セッションでは、Discord Plugin が Open widget ボタンを投稿し、Activity として起動します。

ウィジェットの仕組み

エージェントが show_widget を呼び出すと、OpenClaw コアは widget_code を最小限の HTML ドキュメントでラップし、Canvas ドキュメントとして保存して、プレビューハンドルを返します。Control UI はそのハンドルをサンドボックス化された iframe 内でレンダリングし、iOS、Android、macOS、Linux の Quick Chat は分離された Web ビューを使用します。完全なチャットクライアントは履歴の再読み込み後にウィジェットを復元します。Quick Chat はアクティブな返信の間、ウィジェットを保持します。

Control UI セッションでは、Canvas ウィジェットをセッションダッシュボードに固定することもできます。ツール呼び出しで pin: true を設定するか、既存のトランスクリプトウィジェットで Pin to dashboard を使用します。固定された HTML は、MCP Apps で使用されるものと同じ専用オリジンの二重 iframe サンドボックスホストの背後で実行されます。ブラウザーが信頼されていないフレーム内でウィジェットのデータバインディングを解決することはありません。

ブラウザーへの埋め込みでは、ラッパードキュメントがウィジェットコードの周囲に 4 つの小さなホストブリッジを挿入します。

• サイズレポーターは、レンダリングされたコンテンツの高さを埋め込み先チャットに送信します。チャットは高さを制限し、iframe を適合させます（160～1200 ピクセル）。
• ホストブリッジは、従来の sendPrompt(text) ヘルパーに加え、構造化された openclaw.prompt、openclaw.state、openclaw.data、openclaw.cron API を定義します。インラインチャットプロンプトは専用の非公開メッセージチャネルを維持し、ダッシュボード API はビューチケットに紐付けられたリクエストチャネルを使用します。インタラクティブなウィジェットおよびダッシュボードの機能を参照してください。
• テーマブリッジは Control UI の現在のデザイントークンを監視し、読み込み時およびテーマが変更されるたびに CSS 変数として適用します。
• スナップショットブリッジは、埋め込み先チャットがエクスポートを要求すると、現在のウィジェットドキュメントを PNG としてレンダリングします。

それ以外はすべてフレーム内に留まります。ドキュメントは厳格な Content Security Policy が適用された不透明なオリジンで実行されるため、ウィジェットスクリプトは Control UI、Gateway、ネットワークにアクセスできません。

コア実装は、呼び出し元の Gateway クライアントが inline-widgets 機能を宣言している場合にのみ利用できます。Control UI と対応するネイティブアプリは、この機能を自動的に宣言します。カスタム TLS リーフピンを必要とする Gateway 接続では、プラットフォームの WebView がそのピンをバインドできないため、Linux Quick Chat はテキストのみになります。Discord 実装は、Activities が設定されている Discord セッションでのみ利用できます。他のチャネルの実行には show_widget は提供されません。

機能の転送は、組み込み、Codex app-server、CLI ベースのモデルバックエンドに対応します。グラント認証済みの MCP 呼び出し元と直接 HTTP ツール呼び出し元はクライアント機能を宣言しないため、引き続きフェイルクローズします。

デザインシステム

すべての Canvas ウィジェットには、クラス不要の基本スタイルシートと小規模なトークンセットが含まれます。

クラスを指定していない見出し、段落、リンク、ボタン、入力欄、セレクト、テキストエリア、表、コードブロックには基本スタイルが適用されます。ヘルパークラスは一般的なパターンを提供します。

• 境界線付きコンテンツサーフェス用の .card
• コンパクトなステータスラベル用の .badge と、.ok、.warn、.danger、または .info
• 目立つ数値用の .metric
• セカンダリテキスト用の .muted
• 折り返し可能な水平レイアウト用の .row
• プライマリアクション用の button.primary

Control UI は、ウィジェットの読み込み時とテーマの変更時に、アクティブなテーマ値を含む openclaw:widget-theme メッセージを送信します。そのためウィジェットは、再読み込みすることなく、Claw、Knot、Dash、カスタムテーマを含むすべてのテーマファミリーに追従します。ネイティブアプリや直接開いた場合など Control UI の外部では、ウィジェットは prefers-color-scheme で選択された組み込みのライトまたはダークパレットを使用します。

ウィジェットは次の 3 つのルールに従って作成してください。

1. すべての色と背景にデザイン変数を使用してください。色の値をハードコードしないでください。
2. ウィジェットがホストサーフェスになじむように、ページ背景を透明に保ってください。
3. --accent-fill は最大 1 つのプライマリアクションにのみ使用してください。

エクスポート： Web チャットでは、ウィジェットカードのメニューを開き、レンダリングされたウィジェットをクリップボードにコピーするか、PNG としてダウンロードできます。スナップショットブリッジを持たない古いウィジェットドキュメントでは、代わりに HTML ファイルがダウンロードされます。

ツールの使用

どちらの実装でも、同じ必須フィールドを使用します。

Discord は、Activity 起動ボタン用の任意の button_label テキストも受け付けます。Canvas スキーマでは、この Discord 専用フィールドを意図的に省略しています。

コア Canvas ツールは、次の任意のダッシュボード配置フィールドを受け付けます。

• pin：ウィジェットをセッションダッシュボードにも配置します。
• name：安定したウィジェット名。既定では title のスラッグです。
• tab：配置先タブのスラッグ。
• size：sm、md、lg、xl、full のいずれか。
• after：このウィジェットをその後に配置する兄弟ウィジェット名。
• capabilities：固定されたウィジェットが要求するアクセス権。netOrigins には正確な HTTPS オリジン、tools には prompt、許可リストに登録された読み取りバインディング、または正確な cron.trigger:<jobId> アクションが含まれます。

コアの結果には Canvas プレビューハンドルが含まれるため、Control UI と対応するネイティブアプリはツール呼び出しからウィジェットを直接レンダリングし、履歴の再読み込み後に復元します。固定された結果にはボードウィジェット名も保持されるため、トランスクリプトの再読み込み後に Control UI が重複する固定操作を提示することはありません。Discord は、保存されたウィジェットと投稿済みメッセージの識別子を返します。

discord_widget は、1 リリースの間、非推奨のエイリアスとして引き続き登録されます。新しいエージェント呼び出しでは show_widget を使用してください。

インタラクティブなウィジェット

Control UI では、ウィジェットスクリプトから会話を進行できます。ラッパードキュメントはグローバルな sendPrompt(text) 関数を定義します。この関数を呼び出すと、ユーザーがメッセージを入力して送信した場合と同様に、text がチャットに送信されます。ボタンやその他のコントロールに接続することで、選択ツール、クイズ、詳細表示ダッシュボードなどのインタラクティブなフローを構築できます。ネイティブアプリはインタラクティブなウィジェットコードをレンダリングしますが、このチャットプロンプトブリッジは公開しません。

<button onclick="sendPrompt('失敗したテストを詳しく表示')">失敗したテスト</button>

すべてのプロンプトは、フレーム境界の両側で検証されます。

• sendPrompt には、ウィジェット内での一時的なユーザーアクティベーションが必要です。ユーザーがウィジェット内でクリックまたはキーを押してから数秒間のみ機能するため、ボタンやその他のクリック対象に接続してください。読み込み時に自動で呼び出しても何も起こりません。ブリッジは送信エンドポイントを自身だけが使用できるよう非公開に保ち、ユーザーアクティベーションを公開しないブラウザーではフェイルクローズするため、ウィジェットコードはこの検査を回避できません。
• プロンプトの権限は、元のウィジェットドキュメントだけに属します。信頼されたブリッジは、ウィジェットコードが実行されたりフレームを移動したりする前にチャネルエンドポイントをチャットへ提示し、チャットは最初の提示だけを採用します。ナビゲーション時には、チャネルはドキュメントとともに破棄されます。外部で許可された埋め込み URL が採用されることはありません。
• ウィジェットフレームはチャットのトランスクリプト内に表示され、フォーカスを保持している必要があります。これは、ユーザーが実際にこのウィジェットを操作していることをホスト側で確認する追加シグナルです。
• テキストはトリミング後に空であってはならず、最大 4,000 文字です。
• / で始まるプロンプトは拒否されるため、ウィジェットコードは /approve や /stop などのチャットコマンドを起動できません。
• 各ウィジェットドキュメントが送信できるプロンプトは、移動する 1 分間あたり最大 10 件です。超過したプロンプトは通知なく破棄されます。

受け付けられたプロンプトは通常のユーザーメッセージとしてトランスクリプトに表示され、ウィジェットを所有するセッションで通常のエージェントターンを開始します。ウィジェットへ戻るフィードバックチャネルはありません。破棄されたプロンプトは通知なく失敗し、ウィジェットはエージェントの返信を読み取れません。

ダッシュボードの機能

固定されたウィジェットは、オペレーターが保留中のカードに表示された宣言を確認した後、チケットに紐付けられた 1 つのホスト API を使用できます。

• openclaw.prompt.send(text) には一時的なユーザーアクティベーションが必要で、表示可能なコンポーザーメッセージを投稿します。prompt ツール樱限を宣言して受け取ると、クリックごとの追加確認は省略されますが、検証、フォーカスチェック、レート制限は引き続き適用されます。
• openclaw.state.emit(payload) はセッション通知を追加します。ペイロードは 8 KiB に制限され、5 秒以内にクライアントから送信された同一の内容は統合されます。
• openclaw.data.read(bindingId, params?) は Gateway でのみ解決されます。権限を付与できるバインディングは、sessions.list、usage.status、usage.cost、cron.list、cron.status、agents.list、および health です。
• openclaw.cron.trigger(jobId) は、完全に一致する cron.trigger:<jobId> ケイパビリティが付与されている場合にのみ、既存のジョブを即座に実行します。

ネットワークアクセスはホストツールとは別です。正確な HTTPS オリジンを capabilities.netOrigins に指定してください。承認後、ウィジェットの connect-src に追加されるのは、それらのオリジンだけです。ワイルドカード、資格情報、パス、クエリ文字列、および宣言されていないオリジンは引き続きブロックされます。リテラルポートは、宣言されたオリジンの一部である場合にのみ許可されます。

セキュリティとストレージ

ウィジェットドキュメントには、制限の厳しい Content Security Policy が適用されます。インラインのスタイルとスクリプトは許可されますが、外部リソースの読み込みは引き続きブロックされます。インラインのトランスクリプトウィジェットはネットワークから取得できません。固定されたダッシュボードウィジェットは、エージェントが宣言し、オペレーターが権限を付与した正確な HTTPS オリジンからのみ取得できます。

Control UI の iframe では、グローバル埋め込みモードが trusted の場合でも、常に allow-same-origin が省略されるため、ウィジェットスクリプトは親アプリケーションのオリジンを読み取れません。ネイティブクライアントは、分離された非永続的な Web ビューを使用し、ホストされているウィジェットから別の場所への移動をブロックします。また、コアドキュメントホストは Content-Security-Policy: sandbox allow-scripts レスポンスヘッダーを付けてウィジェットを配信するため、直接レンダリングする場合でも、ウィジェットはアプリケーションオリジンではなく不透明なオリジンで実行されます。その分離されたフレーム内で実行しても問題のないウィジェットコードのみをレンダリングしてください。

iframe は gateway.controlUi.embedSandbox にも従います。デフォルトの scripts 階層は、オリジンの分離を維持しながらインタラクティブなウィジェットをサポートします。

許容される WebRTC データチャネル送信の残存リスクについては、ダッシュボードアーキテクチャに記載されています。

Canvas が保持するウィジェットは、セッションごとに最大 32 個です（セッションが利用できない場合はエージェントごと）。別のウィジェットを作成すると、そのスコープ内で最も古いドキュメントが削除されます。

関連項目

• Control UI のホスト型埋め込み
• Discord アクティビティ
• Canvas Node コントロール
• Gateway プロトコルのクライアントケイパビリティ