How to Use OpenClaw Canvas with A2UI

Canvas is OpenClaw’s lightweight visual workspace on macOS. The app embeds a WKWebView panel that the agent can show, hide, navigate, evaluate JavaScript inside, and snapshot. A2UI adds a structured UI message path so the Gateway can push surfaces into the panel without making you hand-roll every bit of HTML.

When this is the right move

Use Canvas when text is the wrong medium: visual status boards, small tools, forms, sketches, previews, and interactive UI fragments. Do not treat it as a full production web app host. It is a local agent workspace for quick operator surfaces and node-driven UI.

The practical workflow

1. Make sure the macOS app is running and Canvas is allowed in Settings. If Canvas is disabled, canvas node commands return CANVAS_DISABLED.
2. Present the Canvas panel on the target node and navigate to a local path, URL, or file URL depending on what you are rendering.
3. Use local canvas paths when possible. The app serves files through the openclaw-canvas:// custom scheme from the session canvas root.
4. For structured UI, push A2UI v0.8 JSONL with surfaceUpdate and beginRendering messages.
5. Snapshot the panel when you need verification, QA evidence, or a visual artifact for the agent to reason over.

Grounded command or config pattern

The docs show node Canvas CLI commands for present, navigate, eval, snapshot, and A2UI push.

openclaw nodes canvas present --node <id>
openclaw nodes canvas navigate --node <id> --url "/"
openclaw nodes canvas eval --node <id> --js "document.title"
openclaw nodes canvas snapshot --node <id>
openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"

Canvas paths map to Application Support files such as openclaw-canvas://main/ for the main session root. If no index.html exists at the root, the app shows a built-in scaffold page. A2UI’s default host URL is under the Gateway at /__openclaw__/a2ui/.

Operator notes

A2UI support is specifically v0.8 in the current Canvas docs. Supported server-to-client messages include beginRendering, surfaceUpdate, dataModelUpdate, and deleteSurface. createSurface from v0.9 is not supported, so do not build prompts or scripts that assume the newer command exists.

Rollout approach

For use openclaw canvas with a2ui, I would make the first pass deliberately small: one owner, one machine or channel, one visible test, and one rollback path. OpenClaw features become powerful when they connect to real tools and real messages, so the safest rollout is not a giant configuration day. It is a short rehearsal that proves the docs-grounded path works in your exact workspace before you depend on it while busy.

Common mistake

The common mistake is treating the command as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and a tiny verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A small note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or machine changes.

Safety checks

Canvas has guardrails: the custom scheme blocks directory traversal, files must live under the session root, and external http(s) URLs are only loaded when explicitly navigated. Still, treat Canvas content as UI that can trigger attention and deep links; review anything that asks for agent actions.

How to verify it worked

A good smoke test is simple: present Canvas, navigate to /, push a short A2UI text surface, and capture a snapshot. If the panel does not open, check the macOS app node connection and Canvas permission before debugging the content itself.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.