Canvas Surface

+15 Mana ✨
OpenClaw Canvas(DOCUMENTATION)

Introduction

The Canvas is a live UI surface on macOS that allows OpenClaw agents to present rich visual content, including web pages, interactive forms, code previews, and data visualizations. It extends the agent beyond text-only interaction into a visual collaboration space.

Key Concepts

  • Canvas Surface: A macOS-native UI window where agents can render HTML, present content, and interact with the user visually.
  • A2UI (Agent-to-UI): The protocol for agents to send content to the Canvas, including HTML, images, and interactive elements.
  • Web Navigation: Agents can browse web pages within the Canvas, taking screenshots and interacting with page elements.
  • Content Presentation: Agents can present code diffs, charts, documentation, and other visual content in the Canvas.

Real World Context

A data scientist asks their OpenClaw agent to analyze a CSV dataset. Instead of printing tables as text in the chat, the agent renders an interactive chart on the Canvas surface. The scientist can see the visualization, ask follow-up questions, and the agent updates the chart in real-time.

Deep Dive

The Canvas is activated on macOS nodes:

bash
# Start the OpenClaw node with Canvas enabled
openclaw node start --canvas

# The Canvas window opens as a macOS overlay

Agents interact with the Canvas through A2UI commands:

json
{
  "a2ui": {
    "action": "present",
    "content": {
      "type": "html",
      "body": "<div style='padding: 20px'><h1>Analysis Results</h1><canvas id='chart'></canvas><script src='chart.js'></script></div>"
    }
  }
}

This A2UI command tells the Canvas to render an HTML page with a chart. The agent can inject any HTML, CSS, and JavaScript into the Canvas surface.

Web navigation lets agents browse the web visually:

json
{
  "a2ui": {
    "action": "navigate",
    "url": "https://github.com/user/repo/pull/42",
    "screenshot": true
  }
}

The Canvas navigates to the URL, and if screenshot is true, the agent receives a screenshot of the rendered page for visual analysis.

Common Pitfalls

  1. Canvas is macOS-only — The Canvas surface requires macOS. Linux and Windows users need alternative approaches (web UI, TUI).
  2. Heavy HTML content — Rendering complex web applications in the Canvas can consume significant memory. Keep content focused.

Best Practices

  1. Use Canvas for visual tasks — Charts, diffs, documentation previews, and web browsing benefit from visual rendering. Simple Q&A is better in the chat.
  2. Combine Canvas with voice — Use Talk Mode for the conversation and Canvas for visual output for a hands-free visual collaboration experience.

Summary

  • Canvas is a macOS-native UI surface for rich visual agent interaction
  • A2UI protocol lets agents present HTML, navigate web pages, and render visualizations
  • Web navigation with screenshots enables visual page analysis
  • Canvas is macOS-only; other platforms use web UI or TUI
  • Best used for visual tasks like charts, code diffs, and documentation previews
✓ Completed