---
read_when:
- Web チャット、ネイティブアプリ、または Discord でエージェントにインタラクティブな結果を表示させたい場合
- ウィジェットのボタンからチャットにフォローアッププロンプトを送信する場合
- 共有デザイントークンを使用してウィジェットのテーマを設定する場合
- show_widget の入力、セキュリティ、または保持に関する契約が必要です
sidebarTitle: Show widget
summary: 対応するチャット画面に自己完結型の HTML ウィジェットを表示する
title: ウィジェットを表示
x-i18n:
generated_at: "2026-07-26T10:34:10Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 32
provider: openai
source_hash: 903adff1fadeb9d224d3e2d839c86082b5244e1e319255c8d3f6619344b749a3
source_path: tools/show-widget.md
workflow: 16
---
`show_widget` は、ユーザーの現在の画面に自己完結型 HTML ウィジェットを表示するコアツールです。OpenClaw は、Control UI、および iOS、Android、macOS、Linux の Quick Chat トランスクリプト内にインラインでレンダリングします。Linux ダッシュボードはブラウザー版 Control UI を使用します。[Activities](/channels/discord-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 はビューチケットに紐付けられたリクエストチャネルを使用します。[インタラクティブなウィジェット](#interactive-widgets)および[ダッシュボードの機能](#dashboard-capabilities)を参照してください。
- テーマブリッジは 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 ウィジェットには、クラス不要の基本スタイルシートと小規模なトークンセットが含まれます。
| トークン | 用途 |
| ------------------------------------------------------------------------------------- | ------------------------------------- |
| `--surface` | ページレベルのサーフェス色 |
| `--card` | カード、ボタン、コードの背景 |
| `--elevated` | 浮き上がったフォームコントロールの背景 |
| `--text` | 本文およびコントロールの既定テキスト |
| `--text-strong` | 見出しおよび目立たせる値 |
| `--muted` | セカンダリテキストおよび控えめな境界線 |
| `--border` | 標準の区切り線およびカードの境界線 |
| `--border-strong` | 強調されたコントロールの境界線 |
| `--accent` | リンクおよびフォーカスリング |
| `--accent-fill` | プライマリアクションの塗りつぶし |
| `--accent-fg` | プライマリアクション上のテキスト |
| `--ok` | 成功状態 |
| `--warn` | 警告状態 |
| `--danger` | エラーまたは破壊的な状態 |
| `--info` | 情報状態 |
| `--radius` | コントロールとカードで共有される角の丸み |
| `--font-body` | ホスト本文のフォントスタック |
| `--font-mono` | ホストの等幅フォントスタック |
| `--accent-subtle`、`--ok-subtle`、`--warn-subtle`、`--danger-subtle`、`--info-subtle` | 派生した半透明の状態背景 |
クラスを指定していない見出し、段落、リンク、ボタン、入力欄、セレクト、テキストエリア、表、コードブロックには基本スタイルが適用されます。ヘルパークラスは一般的なパターンを提供します。
- 境界線付きコンテンツサーフェス用の `.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 ファイルがダウンロードされます。
## ツールの使用
どちらの実装でも、同じ必須フィールドを使用します。
インラインプレビューおよびホストされたドキュメントのタイトルに表示される短いタイトル。
自己完結型の HTML または SVG。インラインウィジェットクライアントでは、トリミング後に入力が `
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:` アクションが含まれます。
コアの結果には Canvas プレビューハンドルが含まれるため、Control UI と対応するネイティブアプリはツール呼び出しからウィジェットを直接レンダリングし、履歴の再読み込み後に復元します。固定された結果にはボードウィジェット名も保持されるため、トランスクリプトの再読み込み後に Control UI が重複する固定操作を提示することはありません。Discord は、保存されたウィジェットと投稿済みメッセージの識別子を返します。
`discord_widget` は、1 リリースの間、非推奨のエイリアスとして引き続き登録されます。新しいエージェント呼び出しでは `show_widget` を使用してください。
## インタラクティブなウィジェット
Control UI では、ウィジェットスクリプトから会話を進行できます。ラッパードキュメントはグローバルな `sendPrompt(text)` 関数を定義します。この関数を呼び出すと、ユーザーがメッセージを入力して送信した場合と同様に、`text` がチャットに送信されます。ボタンやその他のコントロールに接続することで、選択ツール、クイズ、詳細表示ダッシュボードなどのインタラクティブなフローを構築できます。ネイティブアプリはインタラクティブなウィジェットコードをレンダリングしますが、このチャットプロンプトブリッジは公開しません。
```html
```
すべてのプロンプトは、フレーム境界の両側で検証されます。
- `sendPrompt` には、ウィジェット内での[一時的なユーザーアクティベーション](https://developer.mozilla.org/en-US/docs/Web/Security/User_activation)が必要です。ユーザーがウィジェット内でクリックまたはキーを押してから数秒間のみ機能するため、ボタンやその他のクリック対象に接続してください。読み込み時に自動で呼び出しても何も起こりません。ブリッジは送信エンドポイントを自身だけが使用できるよう非公開に保ち、ユーザーアクティベーションを公開しないブラウザーではフェイルクローズするため、ウィジェットコードはこの検査を回避できません。
- プロンプトの権限は、元のウィジェットドキュメントだけに属します。信頼されたブリッジは、ウィジェットコードが実行されたりフレームを移動したりする前にチャネルエンドポイントをチャットへ提示し、チャットは最初の提示だけを採用します。ナビゲーション時には、チャネルはドキュメントとともに破棄されます。外部で許可された埋め込み 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:` ケイパビリティが付与されている場合にのみ、既存のジョブを即座に実行します。
ネットワークアクセスはホストツールとは別です。正確な 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`](/ja-JP/web/control-ui#hosted-embeds) にも従います。デフォルトの `scripts` 階層は、オリジンの分離を維持しながらインタラクティブなウィジェットをサポートします。
許容される WebRTC データチャネル送信の残存リスクについては、[ダッシュボードアーキテクチャ](/web/dashboard-architecture#modeled-residual-webrtc-data-channels)に記載されています。
Canvas が保持するウィジェットは、セッションごとに最大 32 個です（セッションが利用できない場合はエージェントごと）。別のウィジェットを作成すると、そのスコープ内で最も古いドキュメントが削除されます。
## 関連項目
- [Control UI のホスト型埋め込み](/ja-JP/web/control-ui#hosted-embeds)
- [Discord アクティビティ](/channels/discord-activities)
- [Canvas Node コントロール](/ja-JP/plugins/reference/canvas)
- [Gateway プロトコルのクライアントケイパビリティ](/ja-JP/gateway/protocol#client-capabilities)