The Developer's Guide to The OpenClaw Canvas (macOS App)

The OpenClaw Canvas is not just a UI panel—it's a developer's secret weapon for creating rich, interactive agent experiences directly within the macOS application. This guide cuts through the noise and gives you the exact details you need to master Canvas for building next-generation AI assistants.

What Canvas Actually Is (and Isn't)

Forget vague descriptions. Canvas is a persistent, borderless WKWebView panel embedded in the OpenClaw macOS app, serving HTML/CSS/JS from a local directory. It's your agent's personal sandbox for building UIs without spinning up a web server.

Key facts:

• Storage location: ~/Library/Application Support/OpenClaw/canvas/<session>/...
• URL scheme: openclaw-canvas://<session>/<path>
• Auto-reload: Any file change triggers an immediate reload in the panel
• Single instance: Only one Canvas session is visible at a time

Canvas is disabled when "Allow Canvas" is unchecked in Settings, returning CANVAS_DISABLED for API calls.

The Canvas API: What You Can Control

Your agent controls Canvas through gateway WebSocket commands. Here are the operations you can perform:

Show/Hide the Panel

openclaw nodes canvas present --node <id>
openclaw nodes canvas hide --node <id>

Navigate to Content

Canvas accepts three types of destinations:

1. Local paths: /, /widgets/todo/
2. HTTP URLs: http://localhost:8080
3. File URLs: file:///path/to/local.html

openclaw nodes canvas navigate --node <id> --url "/"

If no index.html exists, Canvas displays a built-in scaffold page—perfect for development.

Execute JavaScript

Run any JavaScript in the Canvas context:

openclaw nodes canvas eval --node <id> --js "document.title"

Capture Snapshots

Get a PNG of the current Canvas state:

openclaw nodes canvas snapshot --node <id>

A2UI: The Real Power Move

While raw HTML works, A2UI is where Canvas shines. The Gateway hosts A2UI and automatically navigates Canvas to http://<gateway-host>:18789/__openclaw__/a2ui/ when available.

Current limitation: Canvas only supports A2UI v0.8 messages:

• beginRendering
• surfaceUpdate
• dataModelUpdate
• deleteSurface

createSurface (v0.9) is not yet supported.

Push A2UI Content

Send A2UI JSONL to Canvas:

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>

For quick testing, use the one-liner:

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

Trigger Agent Actions from Canvas

Make your Canvas interactive by triggering new agent runs via deep links:

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

This prompts the user for confirmation unless a valid session key is provided, maintaining security while enabling powerful workflows.

Security Hardening

Canvas is designed with security in mind:

• Directory traversal blocked: Files must reside under the session root
• No loopback server required: Uses a custom URL scheme for local content
• External URL whitelisting: Only explicitly navigated http(s) URLs are loaded

Practical Use Cases

Use Canvas for:

• Interactive agent debugging: Display JSON state, logs, or API responses
• Configuration UIs: Let users tweak agent settings through forms
• Data visualization: Show charts, tables, or network diagrams
• Multi-step workflows: Guide users through complex processes with step-by-step UIs

Getting Started: Your First Canvas

1. Create /Users/jorden/Library/Application Support/OpenClaw/canvas/main/index.html
2. Add basic HTML content
3. Run openclaw nodes canvas present --node <your-node-id>
4. Watch it appear in the macOS app

The panel remembers position and size between sessions—no configuration needed.

Canvas transforms your agent from a text-only interface to a full application. Master it, and you'll build experiences that separate the pros from the amateurs.