On this page
💻 Why WebChat?
| Advantage | Details |
|---|---|
| Zero setup | Already built into the Gateway. Start the gateway → open browser → chat. |
| No app needed | Works in any modern browser — Chrome, Firefox, Safari, Edge. |
| Dashboard access | Same UI gives you config, logs, sessions, and debug tools alongside chat. |
| Talk Mode | Click the mic icon for voice conversations directly from the browser. |
| Best for testing | Fastest way to test your agent without setting up Telegram/WhatsApp/Discord first. |
✅ Fastest path to chat: Just run
openclaw onboard --install-daemon and open the browser. No channel configuration needed. WebChat works immediately.🔗 Accessing WebChat
# Start the gateway (if not already running as daemon)
openclaw gateway --port 18789
# Open in browser:
# http://127.0.0.1:18789
# Or open directly:
openclaw dashboard
# WebChat is at:
# http://127.0.0.1:18789/webchat
The Control UI is the main page. WebChat is either a tab within it or accessible at /webchat.
💡 Gateway token: On first access, you'll need the gateway token shown during setup. Save it — you'll need it to pair the dashboard.
🎛️ Control UI dashboard
The web interface at localhost:18789 is much more than just chat:
| Tab | What it does |
|---|---|
| Overview | Gateway health, connected channels, agent status |
| WebChat | Chat directly with your agent |
| Config | Edit openclaw.json via form or raw JSON editor |
| Sessions | View active sessions, token usage, costs |
| Logs | Real-time gateway logs (like openclaw logs --follow) |
| Cron | Manage scheduled jobs |
| Canvas | A2UI agent-driven visual workspace |
✨ WebChat features
| Feature | Status | Notes |
|---|---|---|
| Text messages | ✅ Full | Markdown rendering, code highlighting |
| File uploads | ✅ Full | Drag and drop or click to upload |
| Code blocks | ✅ Full | Syntax highlighted with copy button |
| Voice (Talk Mode) | ✅ Full | Click mic icon for hands-free voice chat |
| Streaming | ✅ Full | Responses appear word-by-word in real-time |
| Slash commands | ✅ Full | /status, /model, /reset, etc. |
| Canvas | ✅ Full | Agent-driven visual workspace for rich outputs |
| Debug tools | ✅ Full | Inspect sessions, tokens, tool calls |
| Mobile | ✅ Responsive | Works on phone browsers (via Tailscale for remote) |
🌍 Remote access (Tailscale)
By default, WebChat only works on localhost. To access from other devices, use Tailscale Serve/Funnel:
# Install Tailscale (tailscale.com)
# Then expose the gateway:
tailscale serve --https=443 http://127.0.0.1:18789
# Now access from any device on your tailnet:
# https://your-machine.tail-net.ts.net
⚠️ Never expose port 18789 directly to the internet without authentication. Use Tailscale for private network access, or set up a reverse proxy with authentication. The gateway has built-in auth modes:
{
"gateway": {
"port": 18789,
"bind": "lan",
"auth": {
"mode": "password",
"password": "your-secure-password"
}
}
}
Bind modes
| Mode | Who can connect |
|---|---|
"local" | Only localhost (default, safest) |
"lan" | Local network devices |
"public" | ⚠️ Anywhere (requires auth) |
🎤 Voice from browser
Click the microphone icon in WebChat to start Talk Mode directly in your browser:
- Browser captures audio via Web Audio API
- Speech is transcribed (Whisper STT)
- Agent processes and responds
- Response is spoken back (ElevenLabs TTS)
⚠️ HTTPS required for remote: Browsers block microphone access over plain HTTP (except localhost). Use Tailscale Serve (which provides HTTPS) or a reverse proxy with TLS cert.
⚙️ Configuration
// WebChat is a built-in channel — minimal config needed
{
"gateway": {
"port": 18789,
"bind": "local",
"auth": {
"mode": "token"
}
}
}
WebChat uses the gateway's WebSocket connection. All slash commands, session management, and tools work exactly the same as in messaging channels.
Enable Chat Completions API
For third-party voice clients (like openclaw-voice), enable the HTTP endpoint:
{
"gateway": {
"http": {
"endpoints": {
"chatCompletions": {
"enabled": true
}
}
}
}
}
🔧 Troubleshooting
| Problem | Fix |
|---|---|
| Can't access localhost:18789 | Ensure gateway is running: openclaw gateway status. Check port isn't taken. |
| Dashboard shows “not connected” | Enter the gateway token from initial setup. Check openclaw gateway status for the token. |
| Mic doesn't work remotely | Browser requires HTTPS for mic access. Use Tailscale Serve or add TLS via reverse proxy. |
| WebCrypto error | Same HTTPS issue — device identity generation requires secure context. Use localhost or HTTPS. |
| Slow responses | Check model and API connectivity. Run openclaw logs --follow for latency info. |
| Can't upload files | Check browser permissions. Try drag-and-drop instead of file picker. |