Understanding Canvas on macOS

The OpenClaw Canvas is a lightweight, agent-controlled panel embedded in the macOS app via WKWebView. It serves as a visual workspace for rendering HTML/CSS/JS content, small interactive UI surfaces, and A2UI components—without the overhead of a full browser automation stack.

Where Canvas Lives

Canvas state is stored locally under Application Support:

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

The panel serves these files using a custom URL scheme:

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

For example:

• openclaw-canvas://main/ → Loads index.html from the main session's canvas directory
• openclaw-canvas://main/assets/app.css → Serves a CSS file
• openclaw-canvas://main/widgets/todo/ → Loads a widget's index.html

If no index.html exists, the Canvas displays a built-in scaffold page.

Panel Behavior

The Canvas appears as a borderless, resizable window anchored near the menu bar (or mouse cursor). It remembers its size and position per session and automatically reloads when local canvas files are updated.

Only one Canvas panel is active at a time. When a new session requests the Canvas, the display switches accordingly.

Canvas can be disabled via Settings → Allow Canvas. When disabled, Canvas-related node commands return CANVAS_DISABLED.

Agent API

Agents interact with the Canvas through the Gateway WebSocket using the nodes tool. Available actions include:

• present – Show the panel
• hide – Hide the panel
• navigate – Load a local path, http(s) URL, or file:// URL
• eval – Execute JavaScript in context
• snapshot – Capture the current view as an image
• a2ui push – Send A2UI v0.8 messages to render dynamic UI

Example CLI usage:

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>

A2UI in Canvas

A2UI is hosted by the Gateway and rendered inside the Canvas panel. When available, the macOS app auto-navigates to the A2UI host page on first open:

http://<gateway-host>:18789/__openclaw__/a2ui/

Canvas currently supports A2UI v0.8 server→client messages:

• beginRendering
• surfaceUpdate
• dataModelUpdate
• deleteSurface

createSurface (v0.9) is not yet supported.

You can push A2UI content directly using a JSONL stream:

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":"If you can read this, A2UI push works."},"usageHint":"body"}}}]}}
{"beginRendering":{"surfaceId":"main","root":"root"}}
EOFA2

openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>

Or send a simple message:

openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"

Triggering Agent Runs from Canvas

Canvas can trigger new agent runs using deep links:

openclaw://agent?message=Review%20this%20design

In JavaScript:

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

The macOS app prompts for confirmation unless a valid key is passed.

Security

• The Canvas scheme prevents directory traversal—files are sandboxed under the session root.
• Local content uses a custom URL scheme, eliminating the need for a loopback server.
• External http(s) URLs are permitted only when explicitly navigated.

When to Use Canvas vs Browser

Use Canvas when:

• You need a lightweight visual surface
• Rendering A2UI components dynamically
• Showing internal dashboards, widgets, or status panels
• Avoiding full browser overhead

Use Browser automation when:

• Interacting with external websites (e.g., Skool, Gmail)
• Handling login flows or CAPTCHAs
• Needing full DOM access or network inspection
• Working with SPAs that require complete browser context

Conclusion

Canvas is the ideal tool for lightweight, agent-driven UIs on macOS. Whether you're prototyping a widget, displaying real-time data, or integrating A2UI into your workflow, Canvas offers a fast, secure, and efficient alternative to full browser automation.

For more, see the full documentation: Canvas on macOS