Gateway

The Gateway is the heart of OpenClaw—a WebSocket server that acts as the central control plane for all messaging channels, AI agents, and platform apps.

What is the Gateway?

The Gateway is a background process that:

Runs a WebSocket server at ws://127.0.0.1:18789 (default)
Manages messaging channels (WhatsApp, Telegram, Discord, etc.)
Routes messages to appropriate AI agents based on configuration
Maintains sessions for conversation context
Provides HTTP endpoints for Control UI and webhooks
Broadcasts events to connected clients

Gateway Process

Starting the Gateway

Manual Start:

oclaw gateway --port 18789 --verbose

With Daemon:

# Install daemon (launchd/systemd)
oclaw onboard --install-daemon

# Start/stop (systemd)
systemctl --user start openclaw-gateway
systemctl --user stop openclaw-gateway

# macOS (launchd)
launchctl start openclaw-gateway
launchctl stop openclaw-gateway

Location: src/gateway/, src/daemon/

Gateway Lock

The Gateway uses a lock file to prevent multiple instances:

~/.openclaw/.gateway.lock

If the Gateway won’t start, check for stale lock files:

oclaw gateway --force

Location: src/infra/gateway-lock.ts:6

Process Modes

The Gateway can run in different modes:

Local: Binds to 127.0.0.1 (default, most secure)
LAN: Binds to 0.0.0.0 (all interfaces)
Tailscale: Auto-configures Tailscale Serve/Funnel
Custom: Specific IP address

Configuration:

{
  "gateway": {
    "bind": "loopback",
    "port": 18789
  }
}

Location: src/config/types.gateway.ts:1

WebSocket Server

The Gateway’s WebSocket server provides real-time communication between channels, agents, and clients.

Connection

Connect to the Gateway:

const ws = new WebSocket('ws://127.0.0.1:18789');

ws.on('open', () => {
  // Authenticate
  ws.send(JSON.stringify({
    method: 'auth',
    params: { token: 'your-token' }
  }));
});

Authentication

The Gateway supports multiple auth modes: Token Authentication:

{
  "method": "auth",
  "params": {
    "token": "your-gateway-token"
  }
}

Password Authentication:

{
  "method": "auth",
  "params": {
    "password": "your-password"
  }
}

Configuration:

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "secure-random-token-here"
    }
  }
}

Always use authentication when binding to non-localhost interfaces.

Location: src/gateway/auth.ts:9

Protocol Methods

The Gateway supports these JSON-RPC methods:

agent

Send a message to the agent:

{
  "method": "agent",
  "params": {
    "message": "Hello, what can you help with?",
    "sessionKey": "main",
    "model": "anthropic/claude-opus-4-6",
    "thinkingLevel": "medium"
  }
}

sessions.list

List all active sessions:

{
  "method": "sessions.list",
  "params": {}
}

sessions.get

Get session details:

{
  "method": "sessions.get",
  "params": {
    "sessionKey": "agent:main:telegram:default:user123"
  }
}

channels.status

Get channel status:

{
  "method": "channels.status",
  "params": {}
}

gateway.info

Get Gateway information:

{
  "method": "gateway.info",
  "params": {}
}

Event Streaming

The Gateway pushes events to connected clients: Agent Events:

agent.text: Streaming text response
agent.thinking: Extended thinking output
agent.tool.start: Tool invocation started
agent.tool.result: Tool execution result
agent.done: Message complete

Channel Events:

presence: Channel online/offline status
typing: Typing indicators
message: Inbound message

Session Events:

session.created: New session
session.updated: Session metadata changed
session.pruned: Session history compacted

Example Event:

{
  "event": "agent.text",
  "data": {
    "sessionKey": "main",
    "text": "Here's the answer...",
    "delta": "answer..."
  }
}

HTTP Server

The Gateway also runs an HTTP server for web access and webhooks.

Control UI

Access the Control UI at http://127.0.0.1:18789/:

{
  "gateway": {
    "controlUi": {
      "enabled": true,
      "basePath": "/",
      "allowedOrigins": ["https://yourapp.com"]
    }
  }
}

The Control UI provides:

Dashboard: Gateway status and metrics
Sessions: View and manage sessions
Channels: Channel status and configuration
WebChat: Browser-based chat interface
Logs: Real-time log streaming
Configuration: Edit config via UI

Location: src/provider-web.ts, ui/

REST Endpoints

GET /health

Health check endpoint:

curl http://127.0.0.1:18789/health

Response:

{
  "status": "ok",
  "version": "2026.2.19",
  "uptime": 3600
}

POST /webhook

Webhook endpoint for external triggers:

curl -X POST http://127.0.0.1:18789/webhook/my-hook \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from webhook"}'

Configure webhooks:

{
  "hooks": {
    "webhooks": [
      {
        "id": "my-hook",
        "path": "/webhook/my-hook",
        "agentId": "main",
        "message": "Webhook triggered: {{body.message}}"
      }
    ]
  }
}

Location: src/hooks/

Configuration

Basic Configuration

{
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "mode": "local"
  }
}

Remote Access

LAN Access:

{
  "gateway": {
    "port": 18789,
    "bind": "lan",
    "auth": {
      "mode": "password",
      "password": "secure-password"
    }
  }
}

Tailscale Serve (tailnet-only):

{
  "gateway": {
    "bind": "loopback",
    "tailscale": {
      "mode": "serve"
    }
  }
}

Tailscale Funnel (public):

{
  "gateway": {
    "bind": "loopback",
    "auth": {
      "mode": "password",
      "password": "required-for-funnel"
    },
    "tailscale": {
      "mode": "funnel",
      "resetOnExit": true
    }
  }
}

Tailscale Serve/Funnel requires the tailscale CLI to be installed and authenticated.

TLS Configuration

{
  "gateway": {
    "tls": {
      "enabled": true,
      "certPath": "~/.openclaw/certs/cert.pem",
      "keyPath": "~/.openclaw/certs/key.pem",
      "autoGenerate": true
    }
  }
}

Auto-generated certificates are self-signed and suitable for development. For production, use certificates from Let’s Encrypt or your CA. Location: src/infra/tls/

Discovery Configuration

mDNS/Bonjour:

{
  "gateway": {
    "discovery": {
      "mdns": {
        "mode": "minimal"
      }
    }
  }
}

Modes:

off: Disable mDNS entirely
minimal: Advertise Gateway without sensitive info
full: Include CLI path and SSH port in TXT records

Wide-Area Discovery:

{
  "gateway": {
    "discovery": {
      "wideArea": {
        "enabled": true,
        "domain": "openclaw.internal"
      }
    }
  }
}

Location: src/config/types.gateway.ts:16

Management

Status

Check Gateway status:

oclaw gateway status

Output:

Gateway Status
--------------
Running: Yes
PID: 12345
Uptime: 2h 34m
Port: 18789
Bind: loopback
Channels: 3 connected
Sessions: 12 active

Logs

View Gateway logs:

# Follow logs
oclaw logs --follow

# Last 100 lines
oclaw logs --tail 100

# Filter by level
oclaw logs --level error

Log Locations:

Daemon logs: ~/.openclaw/logs/gateway.log
Console output: stderr when running manually

Location: src/logging/

Restart

Restart the Gateway:

oclaw gateway restart

Or manually:

oclaw gateway stop
oclaw gateway start

Diagnostics

Run Gateway diagnostics:

oclaw doctor

This checks:

Configuration validity
Port availability
File permissions
Channel credentials
Session integrity
Migration status

Location: src/commands/doctor.ts

Performance

Connection Limits

Channels: 10-20 concurrent
Platform apps: 5-10
CLI clients: Unlimited
WebSocket connections: Hundreds

Memory Usage

Typical memory footprint:

Base: 100-200 MB
+10-50 MB per channel
+1-5 MB per active session

CPU Usage

Idle: less than 1%
Active messaging: 5-15%
Peak (tool execution): 30-60%

Security

Default Security

Binds to localhost by default
No authentication required for localhost
DM pairing for unknown senders
Allowlists for channel access

Production Security

Enable authentication

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "generate-secure-random-token"
    }
  }
}

Enable TLS

{
  "gateway": {
    "tls": {
      "enabled": true,
      "certPath": "/path/to/cert.pem",
      "keyPath": "/path/to/key.pem"
    }
  }
}

Configure firewall

Only allow connections from trusted IPs:

# iptables example
iptables -A INPUT -p tcp --dport 18789 -s 192.168.1.0/24 -j ACCEPT
iptables -A INPUT -p tcp --dport 18789 -j DROP

Use reverse proxy

Run behind Caddy, nginx, or Pomerium for additional auth:

Caddy -> OpenClaw Gateway
(OAuth)   (localhost only)

See the security guide for detailed recommendations.

Troubleshooting

Gateway won't start

Check for:

Port conflicts: lsof -i :18789 or ss -ltnp | grep 18789
Stale lock file: rm ~/.openclaw/.gateway.lock
Config errors: openclaw config validate
Permission issues: Check ~/.openclaw/ permissions

Can't connect to Gateway

Verify:

Gateway is running: openclaw gateway status
Correct port: Check gateway.port in config
Firewall: Ensure port is open
Authentication: Use correct token/password

High memory usage

Common causes:

Too many active sessions: Prune old sessions
Large message history: Enable auto-compaction
Memory leak: Restart Gateway and file a bug report

Channels disconnecting

Check:

Network connectivity
Channel credentials validity
Rate limiting (too many messages)
Gateway logs for errors

Next Steps

Agents

Learn about AI agent configuration and runtime

Channels

Configure messaging channel integrations

Sessions

Understand session management and storage

Deployment

Deploy Gateway to production environments

Getting Started

Core Concepts

Channels

Platform Apps

Guides

​Gateway

​What is the Gateway?

​Gateway Process

​Starting the Gateway

​Gateway Lock

​Process Modes

​WebSocket Server

​Connection

​Authentication

​Protocol Methods

​agent

​sessions.list

​sessions.get

​channels.status

​gateway.info

​Event Streaming

​HTTP Server

​Control UI

​REST Endpoints

​GET /health

​POST /webhook

​Configuration

​Basic Configuration

​Remote Access

​TLS Configuration

​Discovery Configuration

​Management

​Status

​Logs

​Restart

​Diagnostics

​Performance

​Connection Limits

​Memory Usage

​CPU Usage

​Security

​Default Security

​Production Security

​Troubleshooting

​Next Steps

Agents

Channels

Sessions

Deployment

Gateway

What is the Gateway?

Gateway Process

Starting the Gateway

Gateway Lock

Process Modes

WebSocket Server

Connection

Authentication

Protocol Methods

agent

sessions.list

sessions.get

channels.status

gateway.info

Event Streaming

HTTP Server

Control UI

REST Endpoints

GET /health

POST /webhook

Configuration

Basic Configuration

Remote Access

TLS Configuration

Discovery Configuration

Management

Status

Logs

Restart

Diagnostics

Performance

Connection Limits

Memory Usage

CPU Usage

Security

Default Security

Production Security

Troubleshooting

Next Steps