WebChat Widget

Embeddable web chat widget for OpenClaw. Drop a script tag into any website to add an AI chat interface connected to your Gateway.

The WebChat Widget is an embeddable chat interface that connects any website to your OpenClaw Gateway. Drop a single script tag into your HTML and visitors (or just you) get a floating chat bubble that opens into a full conversational UI powered by your agent. It supports Canvas rendering, so your agent can display interactive content, charts, and custom views directly in the chat. This is the simplest way to add an AI assistant to a website without routing through a third-party messaging platform. Since it connects directly to your Gateway via WebSocket, you maintain full control over the AI backend — models, system prompts, skills, and tools. There's no intermediary service taking a cut or adding latency. The widget is designed for flexibility: configure the Gateway URL, authentication token, and visual appearance. CORS must be enabled on your Gateway to allow cross-origin WebSocket connections from the embedding domain. The chat interface is responsive and works across desktop and mobile browsers. Community members have also built alternative webchat clients (like PinchChat) for users who want more customization beyond the built-in widget — features like message editing, branching conversations, and E2E encrypted phone sync. The official widget prioritizes simplicity and quick deployment over extensive customization.

Tags: web, widget, embed, chat

Use Cases

  • Internal company AI assistant — embed the widget in your company intranet or internal tools dashboard
  • Customer support prototype — quick proof-of-concept AI chatbot on your website without complex integrations
  • Personal knowledge base — add a chat interface to your notes site or wiki for AI-powered search and Q&A
  • Development testing — fastest way to interact with your OpenClaw agent during development without setting up channels
  • Demo and presentations — embed a live AI chat on a landing page to showcase your agent's capabilities

Tips

  • Use the webchat widget for internal tools and dashboards where you control the audience — it's simpler than setting up a full messaging channel
  • Scope your authentication token to limit what the webchat session can access — don't reuse your main admin Gateway token
  • For public-facing use, put the Gateway behind a reverse proxy (nginx, Caddy) with rate limiting and TLS
  • Combine with Canvas capabilities for rich interactive outputs — agents can render charts, forms, and dashboards inline
  • Test the widget locally first (localhost Gateway) before deploying to production

Known Issues & Gotchas

  • CORS must be enabled on your Gateway for cross-origin WebSocket connections — without it, the widget silently fails to connect
  • The Gateway authentication token is embedded in the client-side code — use a scoped/limited token, not your main admin token
  • Do not expose your Gateway publicly without proper authentication — the webchat widget connects over WebSocket which is an admin surface
  • The widget is minimal by design — for advanced features like message editing, branching, or conversation management, consider community alternatives
  • Mobile browser support varies — some mobile browsers handle WebSocket connections less reliably in background tabs

Community Feedback

Got tired of the default Control UI so I ended up building my own webchat client for OpenClaw. The built-in widget is fine for basic use but lacks editing and branching.

— Reddit r/OpenClawInstall

Built an open-source chat UI with message editing, branching, and E2E encrypted phone sync — works with any model via OpenClaw. The webchat widget was my starting inspiration.

— Reddit r/selfhosted

The REAL magic is chatting through your regular messaging apps! But the webchat is great for quick testing and sharing with non-technical users who don't want to set up Telegram or Discord.

— Reddit r/OpenClawInstall

Frequently Asked Questions

How do I enable CORS on my OpenClaw Gateway?

Add CORS configuration in your openclaw.json or openclaw.yaml under the gateway section. Allow the origin domain where the widget is hosted. Without CORS, the WebSocket connection will be blocked by the browser.

Is the webchat widget secure for public websites?

The widget connects to your Gateway via WebSocket, which is an admin surface. For public use, always put the Gateway behind a reverse proxy with TLS, use scoped authentication tokens, and implement rate limiting. Never expose your full admin token.

Can I customize the widget's appearance?

The built-in widget supports basic configuration (position, colors, initial state). For deeper customization, consider community alternatives like PinchChat, or build your own client using the Gateway WebSocket protocol.

Does the webchat widget support file uploads?

Basic text chat and Canvas rendering are supported. File upload support depends on the Gateway configuration and the capabilities enabled for the session.

How does the webchat compare to using Telegram or Discord?

The webchat is simpler to set up (just a script tag) but lacks the rich features of established platforms — no push notifications, no mobile app, no offline messaging. Use it for quick access or internal tools; use channels for daily driving.