Mastering Canvas: OpenClaw's GUI Automation Tool

The Canvas tool in OpenClaw provides a lightweight visual workspace for HTML/CSS/JS, A2UI, and small interactive UI surfaces on macOS. This guide explores its capabilities and practical uses for seamless automation.

What is Canvas?

Canvas is a borderless, resizable panel embedded in the OpenClaw macOS app using WKWebView. It serves as a dynamic interface for agents to present, interact with, and capture visual content directly from their workflows. The panel is anchored near the menu bar or mouse cursor, remembers its size and position per session, and auto-reloads when local files change.

Key Features

1. Local File Hosting

Canvas hosts files from ~/Library/Application Support/OpenClaw/canvas/<session>/. These are accessible via the custom URL scheme openclaw-canvas://<session>/<path>. For example:

• openclaw-canvas://main/ → serves index.html from the main session's canvas directory
• openclaw-canvas://main/assets/app.css → serves a CSS file

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

2. Agent Control via API

Agents control Canvas through the Gateway WebSocket using these commands:

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

CLI equivalents allow direct testing:

openclaw nodes canvas present --node <id>
openclaw nodes canvas navigate --node <id> --url "/widgets/todo/"
openclaw nodes canvas eval --node <id> --js "document.title"
openclaw nodes canvas snapshot --node <id>)

3. A2UI Integration

Canvas supports A2UI v0.8 for rendering structured UIs from JSONL streams. Supported commands include beginRendering, surfaceUpdate, dataModelUpdate, and deleteSurface. The createSurface command (v0.9) is not yet supported.

A simple smoke test:

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

4. Security and Permissions

Canvas is disabled by default. Users must enable it in Settings → Allow Canvas. The tool enforces security by:

• Blocking directory traversal attacks
• Restricting local content to session-specific directories
• Requiring explicit navigation for external http(s) URLs

This ensures automation remains safe and contained.

Practical Use Cases

• Present real-time dashboards from automation scripts
• Capture UI state for debugging or reporting
• Build interactive configuration wizards for agents
• Display visual feedback during long-running tasks

Canvas turns OpenClaw from a text-only assistant into a full visual automation platform, making complex workflows easier to monitor and control.