OpenClaw
OpenClaw WebChat Channel
Messaging
Easy
WebChat is the built-in chat interface for OpenClaw Gateway. It connects directly via WebSocket — no external services, API keys, or third-party accounts required. Simply start the Gateway, configure authentication, and open the WebChat UI to begin chatting with your AI assistant. All messages are routed deterministically, meaning replies always return to the WebChat session that initiated the conversation.
Quick Info
Difficulty
Easy
Category
Messaging
Features Supported
1
/ 6
WebChat Supported Features
Text Messages
Supported
Media & Files
Not Supported
Reactions
Not Supported
Threads
Not Supported
Voice Messages
Not Supported
Group Chat
Not Supported
WebChat Prerequisites
- OpenClaw Gateway installed and running
- Gateway authentication configured (token or password mode)
- A modern web browser (Control UI) or the native macOS/iOS client
- Network access to the Gateway WebSocket port (default: 3000)
WebChat Quick Setup
1
Start the Gateway
Launch your OpenClaw Gateway. WebChat is built in — no separate installation or plugin is needed. Run 'openclaw start' to bring up the Gateway service.
2
Configure authentication
Set up gateway.auth.mode with either 'token' or 'password' authentication in your openclaw.json. Authentication is mandatory for all connections, including localhost.
3
Open WebChat
Access the WebChat interface through the Control UI chat tab in your browser, or launch the native macOS/iOS client. Connect to the Gateway at ws://localhost:3000 (or your configured host and port).
4
Start chatting
Send a test message to verify the connection. Your AI assistant will respond through the same WebChat session. Conversation history is managed by the Gateway and persists across reconnections.
WebChat Configuration Example
config.json
{
"gateway": {
"port": 3000,
"bind": "127.0.0.1",
"auth": {
"mode": "token",
"token": "YOUR_SECRET_TOKEN"
}
}
}WebChat Deep Dive
Architecture Overview
WebChat communicates with the OpenClaw Gateway through a WebSocket connection using three primary operations:
• chat.history — Retrieve the conversation history from the Gateway
• chat.send — Transmit user messages to the AI assistant
• chat.inject — Append assistant notes directly to transcripts and broadcast to the UI without triggering an agent run
Unlike other channels that rely on external services and webhooks, WebChat is fully native to the Gateway. Messages never leave your infrastructure — the WebSocket connection is direct between the UI client and the Gateway process. The routing is deterministic: replies from the AI always return to the WebChat session that initiated the conversation.
WebChat is the simplest channel to set up since it requires no external accounts or API keys — just the Gateway itself.
The chat.inject operation is useful for adding system notes or context to a conversation without triggering an AI response.
Gateway Authentication
Authentication is required for all WebChat connections, even on loopback (localhost). This prevents unauthorized access to your AI assistant.
OpenClaw supports two authentication modes:
• token — A shared secret token passed in the WebSocket handshake. Ideal for programmatic access and single-user setups.
• password — Password-based authentication. Suitable for multi-user environments where each user has their own credentials.
At least one of token or password must be configured for WebChat to accept connections. Configure these in the gateway.auth settings of your openclaw.json.
openclaw.json
{
"gateway": {
"auth": {
"mode": "token",
"token": "a-strong-random-token-here"
}
}
}
Authentication is mandatory even for localhost connections. Never run the Gateway without authentication configured — any process on the machine could access your AI assistant.
Remote Access
WebChat supports remote connectivity without running a separate web server. Two approaches are recommended:
• SSH Tunnel — Forward the Gateway port through SSH: ssh -L 3000:localhost:3000 user@remote-host. This lets you access WebChat locally while the Gateway runs on a remote machine.
• Tailscale — Connect your devices through Tailscale's mesh VPN. The Gateway becomes accessible at its Tailscale IP address without port forwarding or firewall configuration.
For remote connections, configure gateway.remote settings with the target WebSocket URL and authentication credentials. The native client handles reconnection automatically when network conditions change.
openclaw.json
{
"gateway": {
"remote": {
"url": "wss://your-remote-host:3000",
"token": "YOUR_REMOTE_TOKEN"
}
}
}
SSH tunneling is the quickest way to get remote access without any extra software — just ensure SSH access to the Gateway host.
Tailscale provides a zero-config VPN that makes the Gateway accessible across all your devices without port forwarding.
Session Management
WebChat uses Gateway-managed sessions to maintain conversation context. Each WebChat connection is associated with a session that stores conversation history and AI context.
Sessions are persistent across reconnections — if the WebSocket drops and reconnects, the conversation continues where it left off. The chat.history operation retrieves the full conversation from the Gateway on reconnect.
Session configuration is managed through the session.* settings in openclaw.json, including storage backend and default session keys.
Conversation history is Gateway-sourced, not stored locally. This means you can switch devices and pick up the same conversation.
Use session.defaultKey to assign a consistent session identifier for your WebChat conversations.
Read-Only Mode
When the Gateway becomes unreachable, WebChat enters read-only mode automatically. In this state:
• Previous conversation history remains visible
• New messages cannot be sent
• The UI indicates the disconnected status
• Automatic reconnection attempts occur in the background
Once the Gateway comes back online, WebChat automatically reconnects and restores full functionality. No messages are lost from the conversation history since all history is Gateway-sourced.
Read-only mode is a graceful degradation — users can still review past conversations while the Gateway is temporarily unavailable.
Native Client Features
WebChat is implemented as a native SwiftUI application on Apple platforms:
• macOS — Full desktop experience with keyboard shortcuts, system notifications, and menu bar integration
• iOS — Mobile-optimized interface with push notifications and background refresh
The native implementation provides a responsive, platform-native experience without the overhead of an embedded browser or Electron wrapper. Text rendering, scrolling, and input handling all use native platform components.
For other platforms (Windows, Linux, Android), access WebChat through the Control UI chat tab in any modern web browser.
The native macOS/iOS client offers the best experience with platform-specific features like system notifications and keyboard shortcuts.
The browser-based Control UI chat tab works on all platforms and provides the same core functionality.
Message Delivery
WebChat handles message delivery through the WebSocket connection with configurable chunking for long AI responses:
• textChunkLimit — Maximum characters per message chunk (default: 2000). Long responses are automatically split.
• blockStreaming — When enabled, responses are sent in block-based chunks as they're generated, providing real-time feedback.
Messages are delivered instantly through the WebSocket — there's no polling or webhook delay. The bidirectional WebSocket connection means both sending and receiving happen in real time.
openclaw.json
{
"channels": {
"webchat": {
"textChunkLimit": 2000,
"blockStreaming": true
}
}
}Security Best Practices
WebChat security is built around the Gateway authentication layer. Follow these best practices for secure deployments:
• Always configure authentication — No anonymous access is permitted
• Use TLS encryption — Connect via wss:// (WebSocket Secure) for all remote connections
• Restrict bind address — Use gateway.bind: "127.0.0.1" for local-only access; avoid binding to 0.0.0.0 unless behind a reverse proxy
• Use strong credentials — Generate random tokens or strong passwords
• Reverse proxy — For production deployments, place the Gateway behind a reverse proxy (nginx, Caddy) with TLS termination
If using a reverse proxy on the same machine, configure gateway.trustedProxies to ensure proper client IP detection.
Never expose the Gateway WebSocket port directly to the internet without TLS encryption and strong authentication. Use a reverse proxy with TLS termination for production deployments.
WebChat Configuration Reference
| Key | Type | Default | Description |
|---|---|---|---|
| gateway.port | number | 3000 | WebSocket port number for the Gateway |
| gateway.bind | string | "127.0.0.1" | Host address the Gateway binds to for WebSocket connections |
| gateway.auth.mode | string | "token" | Authentication mode: 'token' for shared secret or 'password' for credential-based auth |
| gateway.auth.token | string | "" | Shared secret token for WebSocket authentication |
| gateway.auth.password | string | "" | Password for WebSocket authentication |
| gateway.remote.url | string | "" | Remote Gateway WebSocket URL (e.g., wss://remote-host:3000) |
| gateway.remote.token | string | "" | Authentication token for connecting to a remote Gateway |
| gateway.remote.password | string | "" | Authentication password for connecting to a remote Gateway |
| session.defaultKey | string | "" | Default session key for WebChat conversations |
| session.storage | string | "memory" | Session storage backend (memory, file, redis, etc.) |
| textChunkLimit | number | 2000 | Maximum characters per outbound message chunk |
| blockStreaming | boolean | false | Send responses as block-based chunks during generation for real-time feedback |
gateway.port
Type:
number
Default:
3000
WebSocket port number for the Gateway
gateway.bind
Type:
string
Default:
"127.0.0.1"
Host address the Gateway binds to for WebSocket connections
gateway.auth.mode
Type:
string
Default:
"token"
Authentication mode: 'token' for shared secret or 'password' for credential-based auth
gateway.auth.token
Type:
string
Default:
""
Shared secret token for WebSocket authentication
gateway.auth.password
Type:
string
Default:
""
Password for WebSocket authentication
gateway.remote.url
Type:
string
Default:
""
Remote Gateway WebSocket URL (e.g., wss://remote-host:3000)
gateway.remote.token
Type:
string
Default:
""
Authentication token for connecting to a remote Gateway
gateway.remote.password
Type:
string
Default:
""
Authentication password for connecting to a remote Gateway
session.defaultKey
Type:
string
Default:
""
Default session key for WebChat conversations
session.storage
Type:
string
Default:
"memory"
Session storage backend (memory, file, redis, etc.)
textChunkLimit
Type:
number
Default:
2000
Maximum characters per outbound message chunk
blockStreaming
Type:
boolean
Default:
false
Send responses as block-based chunks during generation for real-time feedback
WebChat Frequently Asked Questions
WebChat Troubleshooting
WebChat shows 'Disconnected' and won't reconnect
The Gateway is not running, or the WebSocket port is blocked by a firewall.
Verify the Gateway is running with 'openclaw status'. Check that the configured gateway.port is not blocked by a firewall. Ensure gateway.bind allows connections from your client's network address.
Authentication fails when connecting
The token or password doesn't match the Gateway configuration.
Verify gateway.auth.token or gateway.auth.password matches your client credentials exactly. Check for trailing spaces or encoding issues. Restart the Gateway after changing authentication settings.
Messages send but no AI response appears
The AI agent is not configured, or the AI provider API key is invalid.
Check the Gateway logs for errors. Verify your agent configuration in openclaw.json. Ensure the AI provider (e.g., OpenAI, Anthropic) API key is valid and has available quota.
Remote connection via SSH tunnel fails
The SSH tunnel is not forwarding the correct port, or the Gateway is not listening on the expected address.
Ensure the SSH command matches the Gateway port: ssh -L 3000:localhost:3000 user@host. On the remote machine, verify the Gateway is listening on the expected port. Check that gateway.bind is set to 127.0.0.1 for SSH tunnel access.
Chat history is empty after reconnection
The session expired or was cleared between connections.
Check session configuration settings in openclaw.json. Ensure the Gateway has sufficient storage for session persistence. Verify the session key matches between connections.