OpenClaw Canvas and A2UI: A safer first workflow with a real undo path

By OpenClawBlog Team

May 18, 2026 · 11 min read

An OpenClaw widget can look like a harmless card. The harder question starts when you want it gone. Did you close a view, remove a saved widget, clear the conversation, or delete the whole session?

There is another source of confusion. In the current documentation, A2UI and the macOS Canvas panel are related but different surfaces. A2UI JSONL renders on a session dashboard. The macOS panel presents a hosted widget document and is render-only. The macOS panel is not an A2UI push target. The distinction is documented in the Session Dashboards guide and the macOS widget-panel reference.

This tutorial starts with the smaller experiment: one pinned A2UI widget containing synthetic values, no declared capabilities, and a named removal step. It then shows the equivalent low-risk Canvas check on a paired Mac. The aim is modest. You should finish knowing which surface you used, what it was allowed to reach, and which action actually removes it.

Start by choosing the surface

A2UI is the right path when the result should live with an OpenClaw session dashboard. The dashboard belongs to the session and is stored with the owning agent. The Canvas plugin registers the A2UI content kind, and the documentation says the plugin and its hosted routes are enabled by default. A2UI widgets use the dashboard's stable names, tabs, sizing, pinning, sandbox, and update behavior.

The Control UI dashboard is therefore more than a preview window. A pinned widget becomes session state. It can appear from another device connected to the same Gateway, and closing the Dashboard tab does not delete it. A browser reload starts a fresh view of the widget, but it does not mean that the saved board was rolled back.

Use the macOS Canvas panel when the goal is simply to show a hosted HTML widget beside the Mac's menu bar or cursor. Its current agent-facing route is show_widget with presentation.target: 'node_panel'. The panel has no host-integrated widget actions. If the goal is an interactive A2UI surface, use the session dashboard instead of trying to force A2UI commands through the Mac panel.

Prerequisites for a disposable first pass

Keep the first run inside a personal or otherwise trusted Gateway boundary. Do not begin from a production channel, a shared workspace, a personal browser profile, or a folder containing private documents. Use literal test values such as PASS, 2, and synthetic data only. No file is needed for this check.

1. Have a working OpenClaw Gateway, a model route, and a connected Control UI. If you need a local handoff, openclaw dashboard --no-open prints a URL without opening the browser; see the Dashboard CLI reference.
2. Run a read-only preflight and keep its output with the test note:

openclaw health
openclaw security audit

The security documentation explicitly places openclaw security audit after configuration changes and before opening network surfaces. Running it before a first visual test is a conservative operator check, not a special A2UI requirement. Read warnings rather than treating a green-looking widget as proof that the Gateway, plugins, or channels are safe.

If you also want the Mac-panel lane, check the node before sending any Canvas command:

openclaw nodes status
openclaw nodes describe --node <id-or-name>
openclaw nodes pending

Pairing a node is not the same as approving every command it might advertise. The node-pairing documentation separates device approval from command-surface approval. The node command policy adds a third gate: the node must declare the command, the paired record must approve it, and Gateway policy must allow it. For this tutorial, do not widen the node to system.run just to make Canvas work.

Recommended path: one capless A2UI widget

1. Open a new dashboard session

Open the Control UI and create a new thread or use a disposable thread with no production context. Choose Dashboard in the side panel. There is no separate dashboard service to install. The board belongs to the thread.

Ask the agent for one pinned A2UI widget with a stable name. The following is an operator prompt, not a shell command. It deliberately describes what the agent must leave out:

Create one pinned A2UI widget on this session dashboard.

Stable widget name: a2ui-first-check
Use only these literal values:
- status: PASS
- count: 2
- note: synthetic data only

Do not request capabilities. Leave out netOrigins and tools.
Do not read files, use a browser, call a channel, fetch a URL, or trigger an action.
Use one compact widget and no extra tabs.
Report the final widget name and capabilityState.

The exact agent call can vary with the installed tool surface. The important parts are the stable name, pin: true behavior, synthetic content, and the absence of a capability declaration. The show_widget reference describes title plus a content input, dashboard pinning, stable names, registered content kinds, and the capability state returned for pinned widgets. The dashboard architecture describes the Canvas plugin's A2UI registration.

2. Check the result before interacting

Expected result: a single A2UI widget appears on the current session dashboard. It should show the literal values you supplied, not data collected from a file or service. The result should identify the stable name a2ui-first-check. When no capabilities are requested, look for a capability state of none. A pending or rejected state is a reason to stop and inspect the request, not to approve it automatically.

This is the useful boundary of a capless widget. It can render, but it has no declared network origin and no granted Gateway data, prompt, cron, or plugin action. Dashboard widgets run in a hard sandbox, and the host only adds the reach described by a declared and approved capability manifest. The docs distinguish a widget's sandbox from the wider Gateway: sandboxing does not move the Gateway, native plugins, or control-plane RPC into that frame. That is why a passive widget is a small test, not a complete deployment security argument. See the supported capability matrix.

3. Leave buttons out of the first render

A static metric or text block answers the first question: can this surface render the content I intended? You do not need an action to prove that. If you add an A2UI button in the next iteration, keep the same synthetic data and ask for no prompt grant. Current dashboard documentation says ordinary A2UI clicks become quiet session notices that the agent sees on its next turn. A prompt grant changes the result: the action can send a visible prompt into the thread. That is a new permission decision, not a cosmetic improvement.

Undo the dashboard test

Use the stable widget name when removing the test. In the Control UI, use the widget's remove or delete control if it is available. From the agent tool surface, the documented dashboard operation is widget_remove. A precise request looks like this:

Remove the pinned widget named a2ui-first-check from this session dashboard.
Do not reset the thread and do not delete the session.

The first line is the change. The second line prevents a broader cleanup. Verify that the widget is gone from the board before creating a replacement. If you want to try a different A2UI source, recreate it with a new reviewable version or the same name after removal. Current widget grants are tied to the exact approved bytes. Changing the source requires a new decision even if the new declaration is smaller.

This is why /reset is not the undo command for a dashboard test. The dashboard guide says that resetting a board-bearing thread keeps the board, while deleting the thread deletes its board. Removing a widget is the narrow operation. Deleting the thread is a separate, destructive decision.

Removal is also not time travel. If a later widget received a prompt or action grant and a click already started an agent turn or automation, taking the widget off the board does not cancel that work. The first test avoids that problem by asking for no capabilities. Once a workflow has an outside effect, handle that effect through its own stop, audit, or credential-revocation path.

If you mean Canvas on a macOS node

The macOS lane uses a native panel for hosted widget documents. It is useful for showing a small HTML artifact on a paired Mac. It is not the place to test A2UI. The current macOS reference says the panel is render-only, remembers its size and position per session, and selects a connected node that declares canvas.present.

For a first panel test, keep the document self-contained. Avoid a CDN, an external image, a login page, or JavaScript that calls an API. At the agent tool layer, the documented shape is:

{
  "title": "Canvas first check",
  "widget_code": "<main><h1>Canvas check</h1><p>PASS: synthetic content only.</p></main>",
  "presentation": { "target": "node_panel" }
}

That example asks show_widget to create a simple hosted document and send it to the Mac panel. It does not pin a dashboard copy and it declares no capabilities. If the Mac is not eligible or the node command fails, OpenClaw may show the widget inline in chat instead. Treat that fallback as a useful failure signal, not as proof that the native panel worked.

For direct operator control, the current node surface is:

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. canvas.navigate loads a hosted document path or an app-local Canvas URL. canvas.hide hides the panel without changing its current document. The app resolves a hosted path through its current scoped capability URL, so pass the document path from the tool result rather than copying a short-lived capability URL into a script.

There is no equivalent A2UI push or reset operation on the current macOS panel surface. If you need an A2UI widget, return to the session dashboard. If you need to stop seeing a Mac widget, hide the panel. If you need to replace the document, send a corrected widget or navigate to a known safe document. Hiding is a view change, not deletion.

Failure paths and limits

The dashboard is blank or the A2UI kind is unavailable

Check whether the Canvas plugin and its hosted routes are enabled. The dashboard documentation says they are enabled by default, but a local configuration can differ. Disabling the plugin makes stored A2UI widgets unavailable until it is enabled again. Do not repair a blank view by adding network permissions or changing Gateway exposure. First check the plugin state and the Control UI connection.

The widget asks for access

Stop at a pending or rejected capability state. Read the exact request. A first render should not need netOrigins, a Gateway data binding, a cron action, or a prompt grant. The permission model is per widget and the grant is tied to the approved source bytes. If the agent cannot produce the passive version, remove the widget and start again with a smaller request.

The Mac is paired but Canvas commands fail

Read the node's pending requests and command surface. Device pairing admits the node connection, but a command surface is approved separately. The node command policy then checks the declaration, paired approval, and Gateway allowlist. A status line that says paired does not authorize arbitrary host execution. Keep the test limited to the Canvas command the Mac declares.

The widget appeared inline instead of on the Mac

That is an expected recovery path when no eligible Mac is connected or the node command fails. Check that the macOS app is running in node mode, that it declares canvas.present, and that the selected node is online. Do not switch to a copied capability URL or broaden the node to system.run as a workaround.

The Gateway is remote

Use the narrowest access pattern that fits the job. The Gateway exposure runbook recommends loopback plus an SSH tunnel for personal administration and says to explain who can reach the Gateway, how they authenticate, which agents they can trigger, and which tools those agents can use. Run the audit before changing bind, proxy, Tailscale, or channel policy. A visual widget does not make a remotely reachable Gateway private.

What to add after the first pass

Once the passive render and the removal step both make sense, add one boundary at a time. A read-only data binding tests a different permission from a network origin. A prompt grant tests a different boundary again. Keep the stable name, save the capability decision, and expect changed widget bytes to trigger a new review.

For the macOS panel, keep the first HTML document small and local. The panel's isolated web view reduces what the document can reach, but it does not turn untrusted source into trusted source. A sandbox is a boundary to inspect, not a reason to skip source review.

The useful first workflow is therefore short: render one synthetic surface, inspect its authority, remove the exact widget, and record what remains. If you cannot tell whether an action hides, removes, resets, or deletes, the test is not ready to grow.

Sources

All sources below were opened and checked on 2026-09-13. Publication dates are not stated on these documentation pages.

1. Session Dashboards - OpenClaw · accessed 2026-09-13
2. Dashboard Architecture - OpenClaw · accessed 2026-09-13
3. Show widget - OpenClaw · accessed 2026-09-13
4. Widget panel - OpenClaw · accessed 2026-09-13
5. Dashboard CLI - OpenClaw · accessed 2026-09-13
6. Node pairing and status - OpenClaw · accessed 2026-09-13
7. Node command policy - OpenClaw · accessed 2026-09-13
8. Supported capability matrix - OpenClaw · accessed 2026-09-13
9. Running the security audit - OpenClaw · accessed 2026-09-13
10. Gateway exposure runbook - OpenClaw · accessed 2026-09-13