Canvas & Sessions in OpenClaw: A Developer's Guide

OpenClaw provides robust capabilities for developers building interactive agent experiences through its macOS Canvas and session management system. This guide explains how these components work together to support richer UIs and maintain conversational context.

Canvas: The Embedded UI Panel

The OpenClaw macOS app embeds a Canvas panel using WKWebView, creating a lightweight visual workspace for HTML, CSS, JavaScript, and A2UI interfaces. Unlike full browser automation, Canvas operates as a dedicated panel that appears alongside your main chat interface.

Canvas state is stored in ~/Library/Application\ Support/OpenClaw/canvas/<session>/, with content served via the custom URL scheme openclaw-canvas://<session>/<path>. This isolation ensures session-specific content remains contained while allowing developers to build interactive tools that respond to agent activity.

Canvas Behavior and Lifecycle

The Canvas panel has several key characteristics:

• Borderless and resizable - appears as a floating panel anchored near the menu bar or cursor
• Session-specific persistence - remembers size and position per session
• Auto-reloading - detects file changes and refreshes content automatically
• Single visibility - only one Canvas panel can be visible at a time across sessions

Developers can control Canvas programmatically through the Gateway WebSocket API using commands like present, navigate, eval, and snapshot. These capabilities enable agents to show UI elements in response to user requests, evaluate JavaScript expressions, or capture visual outputs.

A2UI Integration

Canvas serves as the host for A2UI (Agent-to-UI) interfaces, rendering server-sent UI updates from agents. When enabled, the Canvas automatically navigates to the A2UI host at http://<gateway-host>:18789/__openclaw__/a2ui/. Currently, Canvas supports A2UI v0.8 messages including beginRendering, surfaceUpdate, dataModelUpdate, and deleteSurface.

This integration allows agents to push rich UI components like forms, data visualizations, or interactive controls directly to the user interface without requiring external web servers.

Session Management Architecture

OpenClaw's session system maintains conversational context across interactions, with the Gateway serving as the definitive source of truth for all session state.

Session Isolation Strategies

Developers can configure session isolation based on their use case:

• main (default) - all direct messages share one session for continuity
• per-peer - isolates by sender ID across channels
• per-channel-peer - isolates by channel and sender (recommended for multi-user inboxes)
• per-account-channel-peer - isolates by account, channel, and sender (for multi-account setups)

For shared inbox scenarios, the per-channel-peer configuration provides security by preventing context leakage between users while maintaining conversation continuity for each individual.

Secure DM Mode

When multiple users can message an agent, enabling secure DM mode is critical. Without proper isolation, Alice's private conversation about a medical appointment could be exposed when Bob asks