OpenClaw Canvas: The Lightweight UI Automation Surface Explained

The OpenClaw macOS app includes a powerful feature called Canvas—a lightweight, agent-controlled visual workspace built on WKWebView. It's designed for small interactive UI surfaces, HTML/CSS/JS prototypes, and A2UI rendering, all while staying securely nested within your local environment.

Where Canvas Lives

Canvas state is stored in a dedicated directory within your macOS Application Support folder:

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

Each session gets its own isolated directory. The Canvas panel serves these files via a custom URL scheme: openclaw-canvas://<session>/<path>. For example, requesting openclaw-canvas://main/ serves index.html from the main session's canvas root. If no index.html exists, a built-in scaffold page is shown instead.

Panel Behavior and Security

The Canvas panel is borderless, resizable, and anchored near the menu bar or your cursor. It remembers its size and position per session and auto-reloads when local canvas files change. Only one Canvas panel is visible at a time, switching automatically when needed.

From a security standpoint, Canvas enforces strict rules:

• No directory traversal: Files must live under the session root.
• Custom local scheme: Uses openclaw-canvas:// instead of requiring a loopback server.
• Explicit navigation required: External http(s) URLs are only allowed when explicitly navigated via the navigate command.

Canvas can be globally disabled in Settings → Allow Canvas, useful for stricter environments.

Agent API: Controlling Canvas Programmatically

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

• present: Show the Canvas panel
• navigate: Load a local path, http(s) URL, or file:// URL
• eval: Execute JavaScript in the current Canvas context
• snapshot: Capture a PNG image of the current view

# Show and navigate Canvas
openclaw nodes canvas present --node <id>
openclaw nodes canvas navigate --node <id> --url "/widgets/todo/"

# Evaluate JS and capture a screenshot
openclaw nodes canvas eval --node <id> --js "document.title"
openclaw nodes canvas snapshot --node <id>

A2UI: The Future of In-App UIs

Canvas is the native host for A2UI, OpenClaw's emerging standard for agent-to-UI communication. When enabled, the macOS app auto-navigates to the A2UI host at http://<gateway-host>:18789/__openclaw__/a2ui/.

A2UI operates via JSONL messages. As of v0.8, Canvas supports:

• beginRendering
• surfaceUpdate
• dataModelUpdate
• deleteSurface

While createSurface (v0.9) isn't supported yet, you can still push dynamic content:

# Push a simple message
cat > /tmp/a2ui.jsonl <<'EOFA2'
{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Status Update"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"Canvas is active and rendering."},"usageHint":"body"}}}]}}
{"beginRendering":{"surfaceId":"main","root":"root"}}
EOFA2

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

This allows agents to render rich, interactive status dashboards without leaving the app.

When to Use Canvas vs Browser

Understanding when to use Canvas versus the full browser tool is crucial:

| Use Case | Canvas | Browser | |----------|--------|---------| | Small UIs | ✅ Ideal for widgets, panels, quick previews | Overkill | | Interactive prototyping | ✅ Great for quick HTML/CSS/JS tests | Possible, but heavier | | A2UI rendering | ✅ Native host | Not applicable | | Full web automation | ❌ Limited DOM access | ✅ Full Puppeteer-like control | | Navigation & login | ❌ Not designed for | ✅ Full session management | | Screenshot fidelity | ⚠️ Dependent on local content | ✅ Pixel-perfect, device-emulated | | External sites | ⚠️ Only via explicit navigate | ✅ Full access |

In essence: Canvas is for creating and controlling lightweight, secure UIs within the app, while Browser is for full-scale web interaction, automation, and external site access.

Bringing It All Together

Canvas bridges the gap between pure command-line agents and full visual interfaces. It allows you to:

1. Build agent-driven UIs without web hosting
2. Preview HTML/CSS/JS safely in a sandbox
3. Render A2UI for dynamic in-app displays
4. Trigger agent runs from Canvas via deep links like openclaw://agent?message=Review%20this

For developers and power users, Canvas unlocks a new dimension of agent interaction—keeping complex UIs close, secure, and under agent control.