What is the Gateway

The OpenClaw Gateway is a cross-platform AI agent gateway that bridges multiple instant messaging platforms to your AI coding agent.

It's the central hub that receives messages from WhatsApp, Telegram, Discord, iMessage, and other platforms, routes them to the AI agent, and sends responses back.

Key principle: Send a message → get an agent response — anytime, from your phone.

Architecture

The Gateway sits at the center of the OpenClaw system:

WhatsApp / Telegram / Discord / iMessage
        │
        ▼
┌───────────────────────────┐
│         Gateway           │  ws://127.0.0.1:18789
│    (Single Source of      │
│         Truth)            │
└───────────┬───────────────┘
            │
            ├─ Pi Agent (RPC)
            ├─ CLI (openclaw …)
            ├─ Chat UI (SwiftUI)
            ├─ macOS App
            ├─ iOS Node (WebSocket)
            └─ Android Node (WebSocket)

Key Points

One Gateway per host - It's the only process that owns the WhatsApp Web session
Loopback first - Gateway WebSocket defaults to ws://127.0.0.1:18789
Secure access - Non-loopback binding requires a token

Running the Gateway

Start with Daemon (Recommended)

Install as a background service that starts on boot:

openclaw onboard --install-daemon

Manual Start

Run the gateway manually:

openclaw gateway --port 18789

Check Status

openclaw doctor

Access the Web UI

Once running, access the control panel at:

Local: http://127.0.0.1:18789/
Or: http://localhost:18789/

Configuration

Gateway configuration is stored in ~/.openclaw/openclaw.json

Default Behavior

Without any configuration, OpenClaw uses the built-in Pi binary in RPC mode, with each sender getting their own isolated session.

Basic Configuration Example

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@clawd"]
    }
  }
}

Key Configuration Options

Option	Description
`channels.whatsapp.allowFrom`	Whitelist of phone numbers that can control OpenClaw
`groups.requireMention`	Only respond in groups when @mentioned
`mentionPatterns`	Patterns that trigger OpenClaw in groups
`canvasHost.port`	Canvas host port (default: 18793)

See Configuration Reference for all options.

Security

Access Control

Lock down who can control your OpenClaw:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123", "+15555550124"]
    }
  }
}

Group Mention Rules

Prevent OpenClaw from responding to every message in groups:

{
  "channels": {
    "whatsapp": {
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Remote Access

For non-loopback access (e.g., via Tailscale):

openclaw gateway --bind tailnet --token YOUR_SECRET_TOKEN

See Tailscale Guide for secure remote access setup.

Troubleshooting

Gateway Won't Start

# Check for port conflicts
lsof -i :18789

# Run diagnostics
openclaw doctor

# Check logs
openclaw logs

WhatsApp Disconnected

# Re-pair WhatsApp
openclaw channels login

# Check session status
openclaw channels status

Messages Not Received

Check allowFrom whitelist includes your number
Verify gateway is running: openclaw doctor
Check if require mention is enabled in groups

Multiple Instances

Run multiple gateways on different ports:

CLAWDBOT_CONFIG_PATH=~/.openclaw/a.json \
CLAWDBOT_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

See Troubleshooting Guide for more solutions.

Gateway Setup