How to Connect OpenClaw to WebChat

WebChat is the cleanest way to talk to OpenClaw when you want a first-party chat surface instead of a third-party channel. The docs are explicit that it is not a normal outbound provider. It is the gateway's own UI path, wired directly to the Gateway WebSocket from the Control UI or from native SwiftUI clients on macOS and iOS.

When this is the right move

Use WebChat when you want a direct operator view of the same sessions and routing rules the gateway already owns, without depending on Slack, Discord, or Telegram. It is also the right choice when you need remote access over SSH or Tailscale but do not want to run a second chat server just to reach the agent.

The practical workflow

1. Start the gateway and confirm the Control UI assets are available, because the gateway serves the browser UI from the same port as the WebSocket.
2. Make sure you have a valid gateway auth path. The docs say token, password, trusted proxy, or Tailscale identity headers can satisfy the connection depending on deployment mode.
3. Open the Control UI chat tab in a browser or use the native WebChat view in the macOS or iOS app.
4. If the gateway is remote, forward the gateway port over SSH or expose it with Tailscale Serve instead of inventing a separate WebChat service.
5. Use the session switcher when you need a non-default session; otherwise WebChat stays on the selected agent's main session by default.

Grounded command or config pattern

The web docs show the Control UI as a default-on gateway feature when assets are present. A minimal config looks like this.

{
  gateway: {
    controlUi: { enabled: true, basePath: "/openclaw" },
  },
}

openclaw gateway

For remote use, the docs say WebChat no longer needs a separate HTTP chat server. You forward or expose the gateway itself, then connect the UI to that gateway WebSocket. History comes from chat.history and is intentionally bounded and display-normalized for stability.

Operator notes

WebChat shares the same session model and deterministic routing rules as other channels. It can show cross-channel context because it attaches to a selected agent and defaults to that agent's main session. If the gateway becomes unreachable, the UI goes read-only instead of pretending messages are still being delivered, which is exactly the kind of honest failure mode you want.

Rollout approach

For connecting OpenClaw to WebChat, I would keep the first pass boring: one gateway, one auth path, one known session, and one remote method if you need it. Once that works, layering on Control UI base paths, remote tunnels, or alternative auth modes becomes much easier because you already know the chat path itself is healthy.

Common mistake

The common mistake is treating the command or config key as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and one small verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A short note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or host changes.

Safety checks

For non-loopback deployments, set gateway.controlUi.allowedOrigins explicitly instead of relying on dangerous host-header fallback behavior. If you expose the gateway through Tailscale Serve or a reverse proxy, keep the auth story clear. WebChat is convenient, but it still sits on top of your real gateway and real sessions.

How to verify it worked

Load the UI, send a message, then refresh or reopen the session to confirm the transcript persists through chat.history. If the gateway is remote, test that the same chat still works after reconnecting the SSH tunnel or Tailscale path. If the screen is read-only, fix gateway reachability before touching any session or model settings.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.