Widget Panel macOS Display

The macOS application ships with a native panel used to display hosted widget documents. This presentation path is handled by the Canvas plugin, and it does not function as a standalone visual workspace or as a destination for A2UI pushes.

For agents, the recommended route is show_widget combined with presentation.target: "node_panel". OpenClaw takes the widget, stores it as a hosted document, picks an available macOS node, brings up the panel, and points it at that document. If no suitable Mac is connected, or if the presentation attempt fails, the widget still shows up inline within the chat, and the tool's result message explains the steps to try again.

Inside the native panel, widgets are strictly render-only. Any host-integrated widget actions stay available in Control UI chat and on session dashboard surfaces, but not within the panel.

Panel behavior

The panel has no border, can be resized, and sits close to the menu bar or the mouse cursor.
Showing a widget never triggers an app switch or steals keyboard focus.
At any given moment, only one widget panel is visible.
Per session, the app remembers both the panel's dimensions and its position.

You can turn off Canvas via Settings -> Allow Canvas. With it turned off, panel commands respond with CANVAS_DISABLED.

Agent path

Instruct the agent to invoke show_widget and aim for the node panel. The tool only exposes node_panel while a widget presenter plugin is active.

{
  "title": "Build status",
  "widget_code": "<main><h1>Build passed</h1></main>",
  "presentation": { "target": "node_panel" }
}

When the presentation goes through, the result names the Mac that was selected. Currently, OpenClaw only chooses a connected macOS node that advertises canvas.present.

Node commands

The paired-node command surface offers three commands:

openclaw nodes canvas present --node <id>
openclaw nodes canvas navigate --node <id> "/__openclaw__/canvas/documents/<document-id>/index.html"
openclaw nodes canvas hide --node <id>

canvas.present brings up the panel. It also takes the same optional target and placement arguments as before.
canvas.navigate loads either a hosted widget-document path or an app-local Canvas URL.
canvas.hide hides the panel while leaving its current document untouched.

Hosted paths located under /__openclaw__/canvas/ get resolved through the node session's current scoped pluginSurfaceUrls.canvas URL. Before navigation, the app refreshes that short-lived capability, so callers should pass the document path rather than building or copying a capability URL.

For app-owned content, the app-local scheme is still available:

openclaw-canvas://<session>/<path>

Any file addressed through that scheme must stay within the session's Canvas root in Application Support. Directory traversal is blocked.

A2UI belongs on session dashboards

A2UI widgets render on session dashboards, where they follow the same pinning, layout, approval, and interaction rules as other dashboard widgets. Their renderer bundles keep loading from the Gateway's /__openclaw__/a2ui/ asset route.

The macOS panel rejects A2UI push/reset commands and will not automatically navigate to an A2UI page.

Panel behavior

Agent path

Node commands

A2UI belongs on session dashboards

Related