mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-26 12:26:38 -06:00
Peter Steinberger
ae55a4090c
* refactor(canvas): retire legacy host and commands * refactor(apple): narrow shared Canvas contracts * refactor(macos): keep Canvas as widget presenter * refactor(ios): remove Canvas client * refactor(android): remove Canvas client * refactor(linux): remove Canvas client * fix(ci): isolate native locale artifacts * fix(linux): regenerate companion lockfile * fix(canvas): refresh native tool display metadata * test(canvas): align coverage with presenter surface * test(canvas): remove obsolete asset root seam * test(canvas): stabilize retirement CI coverage * refactor(swift): remove orphaned resource wrapper * test(ios): remove retired canvas layout assertion * fix(macos): reserve retired canvas command namespace * refactor(macos): isolate canvas command policy * fix(canvas): select only eligible macOS panels * fix(canvas): keep panel selection plugin-owned
98 lines
3.4 KiB
Markdown
98 lines
3.4 KiB
Markdown
---
|
|
summary: "Present hosted widgets in the macOS panel"
|
|
read_when:
|
|
- Showing an agent-created widget on a Mac
|
|
- Controlling the macOS widget panel from a paired node
|
|
- Debugging hosted widget navigation
|
|
title: "Widget panel"
|
|
doc-schema-version: 1
|
|
---
|
|
|
|
The macOS app includes a native panel for presenting hosted widget documents.
|
|
The Canvas plugin owns this presentation path; it is not a standalone visual
|
|
workspace or an A2UI push target.
|
|
|
|
The recommended agent path is [`show_widget`](/tools/show-widget) with
|
|
`presentation.target: "node_panel"`. OpenClaw stores the widget as a hosted
|
|
document, selects a connected macOS node, opens the panel, and navigates it to
|
|
that document. If no eligible Mac is connected or presentation fails, the
|
|
widget still appears inline in chat and the tool result explains how to retry.
|
|
|
|
Widgets in the native panel are render-only. Host-integrated widget actions
|
|
remain available in Control UI chat and [session dashboard](/web/dashboards)
|
|
surfaces, not in the panel.
|
|
|
|
## Panel behavior
|
|
|
|
- The panel is borderless, resizable, and anchored near the menu bar or mouse
|
|
cursor.
|
|
- Presenting a widget does not switch apps or take keyboard focus.
|
|
- Only one widget panel is visible at a time.
|
|
- The app remembers the panel's size and position per session.
|
|
|
|
Canvas can be disabled from **Settings -> Allow Canvas**. When it is disabled,
|
|
panel commands return `CANVAS_DISABLED`.
|
|
|
|
## Agent path
|
|
|
|
Ask the agent to use `show_widget` and target the node panel. The tool exposes
|
|
`node_panel` only while a widget presenter plugin is active.
|
|
|
|
```json
|
|
{
|
|
"title": "Build status",
|
|
"widget_code": "<main><h1>Build passed</h1></main>",
|
|
"presentation": { "target": "node_panel" }
|
|
}
|
|
```
|
|
|
|
The result identifies the selected Mac when presentation succeeds. OpenClaw
|
|
currently selects only a connected macOS node that declares `canvas.present`.
|
|
|
|
## Node commands
|
|
|
|
The paired-node command surface contains three commands:
|
|
|
|
```bash
|
|
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` shows the panel. It also accepts the existing optional
|
|
target and placement arguments.
|
|
- `canvas.navigate` loads a hosted widget-document path or an app-local Canvas
|
|
URL.
|
|
- `canvas.hide` hides the panel without changing its current document.
|
|
|
|
Hosted paths under `/__openclaw__/canvas/` are resolved through the node
|
|
session's current scoped `pluginSurfaceUrls.canvas` URL. The app refreshes that
|
|
short-lived capability before navigation; callers should pass the document
|
|
path, not construct or copy a capability URL.
|
|
|
|
The app-local scheme remains available for app-owned content:
|
|
|
|
```text
|
|
openclaw-canvas://<session>/<path>
|
|
```
|
|
|
|
Files addressed by that scheme must remain inside the session's Canvas root in
|
|
Application Support. Directory traversal is blocked.
|
|
|
|
## A2UI belongs on session dashboards
|
|
|
|
A2UI widgets render on [session dashboards](/web/dashboards), where they share
|
|
the same pinning, layout, approval, and interaction model as other dashboard
|
|
widgets. Their renderer bundles continue to load from the Gateway's
|
|
`/__openclaw__/a2ui/` asset route.
|
|
|
|
The macOS panel does not accept A2UI push/reset commands and does not
|
|
automatically navigate to an A2UI page.
|
|
|
|
## Related
|
|
|
|
- [Show widget](/tools/show-widget)
|
|
- [Session dashboards](/web/dashboards)
|
|
- [macOS app](/platforms/macos)
|
|
- [Nodes](/nodes)
|