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

macOS companion app

キャンバス

macOS アプリには、エージェントが制御する Canvas パネルが WKWebView を使用して組み込まれています。これは、HTML/CSS/JS、A2UI、および小規模なインタラクティブ UI サーフェス向けの軽量なビジュアルワークスペースです。

Canvas の保存場所

Canvas の状態は Application Support 配下に保存されます。

  • ~/Library/Application Support/OpenClaw/canvas/<session>/...

Canvas パネルは、カスタム URL スキーム openclaw-canvas://<session>/<path> を介してこれらのファイルを提供します。

  • openclaw-canvas://main/ -> <canvasRoot>/main/index.html
  • openclaw-canvas://main/assets/app.css -> <canvasRoot>/main/assets/app.css
  • openclaw-canvas://main/widgets/todo/ -> <canvasRoot>/main/widgets/todo/index.html

ルートに index.html が存在しない場合、アプリは組み込みのスキャフォールドページを表示します。

パネルの動作

  • メニューバー（またはマウスカーソル）の近くに固定される、枠なしでサイズ変更可能なパネル。
  • セッションごとにサイズと位置を記憶。
  • ローカルの Canvas ファイルが変更されると自動的に再読み込み。
  • 一度に表示される Canvas パネルは 1 つのみ（必要に応じてセッションを切り替え）。

Canvas は Settings -> Allow Canvas から無効にできます。無効にすると、Canvas の Node コマンドは CANVAS_DISABLED を返します。

エージェント API サーフェス

Canvas は Gateway WebSocket を介して公開されるため、エージェントはパネルの表示と非表示、パスまたは URL への移動、JavaScript の評価、およびスナップショット画像のキャプチャを行えます。

bash
openclaw nodes canvas present --node <id>openclaw nodes canvas navigate --node <id> "/"openclaw nodes canvas eval --node <id> --js "document.title"openclaw nodes canvas snapshot --node <id>

canvas.navigate は、ローカルの Canvas パス、http(s) URL、および file:// URL を受け付けます。"/" を渡すと、ローカルのスキャフォールドまたは index.html が表示されます。

/__openclaw__/canvas/ および /__openclaw__/a2ui/ 配下の Gateway ホスト対象は、Node セッションの現在のスコープ付き Canvas URL を介して解決されます。アプリは移動前にこの短期間有効なケイパビリティを更新するため、ケイパビリティ URL を自分で構築またはコピーする必要はありません。

Canvas 内の A2UI

A2UI は Gateway の Canvas ホストによってホストされ、Canvas パネル内にレンダリングされます。Gateway が Canvas ホストを通知すると、macOS アプリは初回起動時に A2UI ホストページへ自動的に移動します。

通知される URL はケイパビリティでスコープされており、たとえば http://<gateway-host>:18789/__openclaw__/cap/<token>/__openclaw__/a2ui/?platform=macos です。安定したリンクではなく、一時的な認証情報として扱ってください。

A2UI コマンド（v0.8）

Canvas は、A2UI v0.8 のサーバーからクライアントへのメッセージ beginRendering、surfaceUpdate、dataModelUpdate、deleteSurface を受け付けます。createSurface（v0.9）はまだサポートされていません。

bash
cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas（A2UI v0.8）"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"これを読める場合、A2UI プッシュは機能しています。"},"usageHint":"body"}}}]}}{"beginRendering":{"surfaceId":"main","root":"root"}}EOFA2 openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>

簡単なスモークテスト：

bash
openclaw nodes canvas a2ui push --node <id> --text "A2UI からこんにちは"

Canvas からのエージェント実行のトリガー

Canvas は、openclaw://agent?... ディープリンクを介して新しいエージェント実行をトリガーできます。

js
window.location.href = "openclaw://agent?message=Review%20this%20design";

サポートされるクエリパラメータ：

パラメータ 意味
message 入力済みのエージェントプロンプト。
sessionKey 安定したセッション識別子。
thinking 任意の思考プロファイル。
deliver, to, channel 配信先。
timeoutSeconds 任意の実行タイムアウト。
key 信頼済みのローカル呼び出し元向けにアプリが生成する安全トークン。

有効なキーが指定されていない限り、アプリは確認を求めます。キーなしのリンクでは、承認前にメッセージと URL が表示され、配信ルーティングフィールドは無視されます。キー付きのリンクでは、通常の Gateway 実行パスが使用されます。

セキュリティに関する注意事項

  • Canvas スキームはディレクトリトラバーサルをブロックします。ファイルはセッションルート配下に存在する必要があります。
  • ローカルの Canvas コンテンツはカスタムスキームを使用します（ループバックサーバーは不要）。
  • 外部の http(s) URL は、明示的に移動した場合にのみ許可されます。
  • 通常のウェブページはレンダリング専用です。エージェントアクションは、アプリ所有の Canvas スキーム、またはアプリが選択した正確なケイパビリティスコープ付き Gateway A2UI ドキュメントからのみ受け付けられます。サブフレーム、リダイレクト、期限切れのケイパビリティ、および変更されたクエリからはアクションを送信できません。

関連項目

Was this useful?
On this page

On this page