WebChat Setup

There is an old Chinese proverb: "Shui dao qu cheng" — water flows naturally to its destination. WebChat embodies this principle. Users do not need to download, configure, or adapt to any specific platform. They simply open a browser, and the connection happens. No friction, no gatekeeping, no wondering whether their device is supported.

WebChat is the most accessible way to interact with your OpenClaw agent. It works on any device with a browser: phones, tablets, laptops, even that old computer in the corner that still runs Windows 7. If it has a browser and an internet connection, it can run WebChat.

What You Need

• A working OpenClaw instance
• A modern web browser (Chrome, Firefox, Safari, Edge)
• Network access to your OpenClaw gateway
• About 10 minutes for initial setup

How WebChat Fits Into OpenClaw

Think of WebChat as the concierge desk in a hotel. It is always visible, always accessible, and handles the first interaction with anyone who walks in. More specialized channels like Signal or Discord are like private suites — better for ongoing relationships, but you need to know how to get there first.

WebChat sits between your users and your OpenClaw instance. When someone opens the WebChat URL, their browser establishes a WebSocket connection to your gateway. Messages flow in real time, files can be uploaded, and the full power of your agent is available through a simple web interface.

Step 1: Enable WebChat in OpenClaw

First, ensure the WebChat channel is enabled in your OpenClaw configuration.

Check Your Configuration

Edit your OpenClaw config file (usually config.yaml):

# WebChat channel configuration
channels:
  entries:
    - name: webchat
      type: webchat
      enabled: true
      config:
        # Optional: require authentication
        requireAuth: false
        # Optional: allowed origins for CORS
        allowedOrigins:
          - "https://yourdomain.com"
        # Optional: custom path (default is /webchat)
        path: "/webchat"

Restart the Gateway

After enabling WebChat, restart your OpenClaw gateway:

# If using Docker Compose
docker compose restart

# If using systemd
sudo systemctl restart openclaw

# Or use the OpenClaw CLI
openclaw gateway restart

Step 2: Access the WebChat Interface

Once enabled, WebChat is available at your OpenClaw gateway URL.

Default WebChat URL

If your OpenClaw gateway runs at https://your-openclaw-instance.com, the WebChat interface is typically at:

https://your-openclaw-instance.com/webchat

Verify WebChat is Running

1. Open the WebChat URL in your browser
2. You should see a chat interface load
3. Check that the connection indicator shows "Connected"
4. Send a test message to verify responses work

Step 3: Configure Authentication (Optional)

For public-facing deployments, you may want to require authentication before users can chat with your agent.

Enable Authentication

channels:
  entries:
    - name: webchat
      type: webchat
      enabled: true
      config:
        requireAuth: true
        authProvider: "openclaw"  # or "oauth", "apikey"
        # Optional: token expiration
        sessionDuration: 3600  # seconds

API Key Authentication

For simple deployments, you can use API key authentication:

channels:
  entries:
    - name: webchat
      type: webchat
      enabled: true
      config:
        requireAuth: true
        authType: "apikey"
        # Keys can be set via environment variables
        apiKeys:
          - "WEBCHAT_API_KEY_1"
          - "WEBCHAT_API_KEY_2"

Step 4: Customize the Interface

WebChat can be themed to match your brand or embedded into existing websites.

Basic Theming

Add custom CSS through configuration:

channels:
  entries:
    - name: webchat
      type: webchat
      enabled: true
      config:
        theme:
          primaryColor: "#ef4444"  # Tailwind red-500
          backgroundColor: "#0a0a0a"
          fontFamily: "Inter, sans-serif"
          # Custom CSS file path (relative to config)
          customCss: "./webchat-custom.css"

Embedding WebChat

To embed WebChat as a widget on your website:

<!-- Add this to your HTML -->
<div id="openclaw-webchat"></div>

<script src="https://your-openclaw-instance.com/webchat/embed.js"></script>
<script>
  OpenClawWebChat.init({
    gatewayUrl: "wss://your-openclaw-instance.com",
    container: "#openclaw-webchat",
    theme: {
      primaryColor: "#ef4444",
      position: "bottom-right"
    }
  });
</script>

Step 5: Configure Session Handling

WebChat sessions work differently from persistent messaging apps. Users may close and reopen their browser, so plan your session strategy accordingly.

Session Persistence Options

channels:
  entries:
    - name: webchat
      type: webchat
      enabled: true
      config:
        sessionHandling:
          # Store session in browser localStorage
          persistLocally: true
          # Session ID cookie duration
          cookieDuration: "7d"
          # Allow resuming previous sessions
          allowResume: true
          # Clear session on browser close
          clearOnClose: false

Session Timeout

Set appropriate timeouts for your use case:

channels:
  entries:
    - name: webchat
      type: webchat
      enabled: true
      config:
        sessionTimeout: 1800  # 30 minutes of inactivity
        # Show warning before timeout
        timeoutWarning: 300   # Warn 5 minutes before

WebChat vs Other Channels

Troubleshooting

WebChat Does Not Load

• Check gateway status: Verify OpenClaw gateway is running with openclaw gateway status
• Verify channel enabled: Check that WebChat is in your channels list and enabled
• Check URL: Ensure you are using the correct path (default is /webchat)
• Firewall rules: Confirm no firewall is blocking the WebSocket port

Connection Drops Frequently

• WebSocket timeout: Increase timeout values in configuration
• Proxy issues: If behind a reverse proxy, ensure WebSocket upgrade is allowed
• Network stability: Check for unstable client connections

Messages Not Sending

• Model provider: Verify your LLM provider is configured and reachable
• Rate limiting: Check if you have rate limits configured that might be blocking messages
• Session expiry: The session may have expired; refresh the page

CORS Errors

If embedding WebChat on a different domain:

channels:
  entries:
    - name: webchat
      type: webchat
      enabled: true
      config:
        allowedOrigins:
          - "https://your-website.com"
          - "https://app.your-website.com"
        # Allow credentials (cookies)
        allowCredentials: true

Best Practices

Security

• Always use HTTPS in production
• Enable authentication for public-facing deployments
• Set reasonable session timeouts
• Validate file uploads on the server side
• Use CORS restrictions to prevent unauthorized embedding

User Experience

• Theme the interface to match your brand
• Provide clear instructions for first-time users
• Enable session persistence so users do not lose context
• Add a clear indicator showing connection status
• Consider a typing indicator for better feedback

Performance

• Use a CDN for static assets if you customize the interface
• Enable compression for WebSocket messages
• Monitor concurrent connection limits
• Consider rate limiting for high-traffic deployments

Summary

WebChat is the most accessible channel for OpenClaw. It requires no installation, works on any device with a browser, and can be embedded into existing websites. As Antoine de Saint-Exupéry observed about aircraft design: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." WebChat embodies this philosophy — it has fewer features than native apps precisely because it aims for universal accessibility. Each removed requirement (no install, no account, no platform) adds potential users.

Enable the channel in your configuration, access it through your browser, and optionally customize the theme and authentication to match your needs. For sensitive conversations, consider pairing WebChat with more secure channels like Signal.