WebChat Guide

New to OpenClaw? Check out our Getting Started Tutorial to learn the basics. This page covers WebChat-specific features and the Gateway Control UI.

WebChat is OpenClaw's built-in web interface for interacting with your AI assistant. It uses the Gateway WebSocket connection and is accessible through the Gateway Control UI, providing a convenient browser-based chat interface that works on any device with a modern web browser.

Accessing WebChat is simple:

1. Start your OpenClaw Gateway
2. Open your web browser
3. Navigate to the Gateway Control UI
4. Start chatting!

Local Access

When running Gateway locally, access WebChat at:

http://127.0.0.1:18789/

The Gateway runs on port 18789 by default (loopback-only for security).

Remote Access

For remote access, you'll need to:

• Set up port forwarding or SSH tunneling
• Use Tailscale or similar VPN solution
• Configure Gateway to accept remote connections (with proper security)

See our Remote Access Guide for detailed instructions.

The Gateway Control UI (also called Dashboard) provides a comprehensive web interface for managing OpenClaw:

• WebChat Interface - Chat with your AI assistant
• Configuration Management - View and edit configuration
• Session Monitoring - Monitor active sessions
• Node Management - Manage connected nodes (iOS/Android apps)
• Gateway Status - View Gateway health and status
• Channel Status - Monitor connected channels

Chat Interface

WebChat provides a modern, responsive chat interface:

• Real-Time Messaging - Instant message delivery via WebSocket
• Message History - View conversation history
• Streaming Responses - See responses stream in real-time
• Markdown Support - Rich text formatting
• Code Blocks - Syntax-highlighted code blocks
• File Attachments - Send and receive files

Session Management

WebChat uses the main session by default, but you can:

• Switch Sessions - Access different conversation sessions
• Create Isolated Sessions - Start new isolated conversations
• View Session History - Browse past conversations

WebChat uses the Gateway WebSocket connection for real-time communication:

• No Separate Port - Uses the same Gateway port (18789)
• WebSocket Protocol - Real-time bidirectional communication
• Automatic Reconnection - Handles connection drops gracefully
• Low Latency - Direct connection to Gateway

WebSocket Endpoint

The WebSocket endpoint is available at:

ws://127.0.0.1:18789/ws

For HTTPS connections, use wss:// instead of ws://.

WebChat requires no separate configuration. It's automatically available when the Gateway is running. However, you can configure Gateway settings that affect WebChat:

Gateway Port

Change the Gateway port if needed:

{
  "gateway": {
    "port": 18789
  }
}

Remote Access

To enable remote access (use with caution and proper security):

{
  "gateway": {
    "port": 18789,
    "host": "0.0.0.0"
  }
}

Security Warning: Exposing Gateway to the internet without proper authentication and HTTPS is a security risk. Use SSH tunnels, VPNs, or reverse proxies with authentication.

WebChat works in any modern web browser that supports:

• WebSocket - For real-time communication
• ES6+ JavaScript - Modern JavaScript features
• CSS Grid/Flexbox - Layout features

Supported Browsers

• Chrome/Edge (latest versions)
• Firefox (latest versions)
• Safari (latest versions)
• Opera (latest versions)

Mobile Browsers

WebChat is responsive and works on mobile browsers, though native apps (iOS/Android) provide a better mobile experience.

Local Access (Default)

By default, Gateway only accepts connections from localhost (127.0.0.1), which is secure for local use.

Remote Access Security

If you need remote access, use secure methods:

• SSH Tunneling - Tunnel Gateway through SSH
• VPN - Use Tailscale or similar VPN
• Reverse Proxy - Use nginx/traefik with authentication
• HTTPS - Always use HTTPS for remote access
• Authentication - Add authentication layer

Best Practices

• Keep Default Settings - Use localhost-only unless needed
• Use VPN for Remote - Prefer VPN over direct exposure
• Regular Updates - Keep OpenClaw updated
• Monitor Access - Check Gateway logs regularly

Can't Access WebChat

If you can't access WebChat:

1. Verify Gateway is running: openclaw status
2. Check Gateway is listening on port 18789
3. Try accessing http://127.0.0.1:18789/ directly
4. Check firewall isn't blocking the port
5. Review Gateway logs for errors

WebSocket Connection Issues

If WebSocket fails to connect:

1. Check browser console for errors
2. Verify Gateway is running
3. Check network connectivity
4. Try refreshing the page
5. Check browser WebSocket support

Messages Not Sending

If messages aren't sending:

1. Check WebSocket connection status
2. Verify Gateway is processing messages
3. Check browser console for errors
4. Try reconnecting to WebSocket
5. Review Gateway logs