Skip to Content
👋 Welcome to HowToUseMoltbot Quick Start
GatewayGateway Overview

Gateway Overview

The Gateway is the heart of your Moltbot setup—an always-on service that owns your messaging connections (WhatsApp, Telegram, etc.) and handles all the orchestration between chat channels and your agents.

Think of it as the conductor: it listens for incoming messages, routes them to the right agent session, streams responses back, and keeps everything connected even when you’re not actively chatting.

What it does

  • Maintains persistent connections to messaging platforms (Baileys for WhatsApp, Bot API for Telegram, etc.)
  • Exposes a WebSocket control plane for CLI, apps, and remote nodes
  • Serves HTTP endpoints for OpenAI-compatible APIs, webhooks, and the control UI
  • Manages agent sessions, message queues, and delivery
  • Handles config hot-reload and in-process restarts (no downtime for most changes)

Entry point: moltbot gateway

Running it locally

Simple start:

moltbot gateway

That’s it. The gateway binds to 127.0.0.1:18789 by default and runs until you stop it.

With options:

# Use a different port
moltbot gateway --port 19000
 
# Debug mode (mirror all log events to console)
moltbot gateway --verbose
 
# Force-kill anything on the port first, then start
moltbot gateway --force
 
# Dev mode (auto-reload on code changes)
pnpm gateway:watch

The gateway watches your config file (~/.clawdbot/moltbot.json by default) and hot-reloads safe changes. Critical changes trigger an in-process restart via SIGUSR1.

Turn off hot-reload with gateway.reload.mode="off" if you prefer manual control.

Authentication

By default, the gateway requires authentication even on localhost. Set a token or password:

# Generate a token during setup
moltbot setup
 
# Or set it manually
export CLAWDBOT_GATEWAY_TOKEN="your-secret-token"

Then configure your clients (CLI, apps, nodes) to include auth.token in the WebSocket handshake.

Tailscale users: If you’re using Tailscale Serve with gateway.auth.allowTailscale: true, requests from your tailnet can authenticate via Tailscale identity headers instead of tokens.

Remote access

Recommended: Tailscale or VPN

Keep your gateway private. Use Tailscale to access it from anywhere without exposing ports to the internet.

See Tailscale setup for the full guide.

Alternative: SSH tunnel

If you can’t use Tailscale, tunnel through SSH:

ssh -N -L 18789:127.0.0.1:18789 user@remote-host

Then connect your CLI to ws://127.0.0.1:18789 as if the gateway were local.

Multiple gateways (usually not needed)

One gateway can handle multiple messaging channels and agents just fine. You only need multiple gateways for:

  • Redundancy (a rescue bot that stays up when your main setup breaks)
  • Strict isolation (separate production and development environments)

If you go this route, isolate state directories, config files, and ports.

See Multiple gateways for patterns and examples.

Dev profile (isolated testing)

Want to test changes without touching your production setup? Use --dev:

moltbot --dev setup
moltbot --dev gateway --allow-unconfigured
moltbot --dev status

The dev profile uses isolated directories and ports:

  • Config: ~/.clawdbot-dev/moltbot.json
  • State: ~/.clawdbot-dev/
  • Workspace: ~/clawd-dev/
  • Port: 19001 (vs. 18789 for main)

No conflicts with your main gateway.

Service management

Install as a system service:

# macOS (launchd)
moltbot gateway install
 
# Linux (systemd user service)
moltbot gateway install
sudo loginctl enable-linger $USER
 
# Check status
moltbot gateway status

Control it:

moltbot gateway start
moltbot gateway stop
moltbot gateway restart
moltbot logs --follow

The gateway runs as a supervised service (launchd on macOS, systemd on Linux). If it crashes, the supervisor restarts it automatically.

Service names

Services use profile-aware naming:

  • macOS: bot.molt.gateway (or bot.molt.<profile>)
  • Linux: moltbot-gateway.service (or moltbot-gateway-<profile>.service)

systemd (Linux/WSL2)

By default, Moltbot installs a user service (simpler for single-user machines). For always-on servers, use a system service instead.

User service (default):

moltbot gateway install
sudo loginctl enable-linger $USER
systemctl --user enable --now moltbot-gateway.service

System service (multi-user/always-on):

Create /etc/systemd/system/moltbot-gateway.service with appropriate User= and WorkingDirectory=, then:

sudo systemctl daemon-reload
sudo systemctl enable --now moltbot-gateway.service

See Background process for unit file examples.

Endpoints and ports

The gateway multiplexes everything on a single port (default 18789):

  • WebSocket (/)—main control plane for CLI, apps, and nodes
  • HTTP APIs:
    • /v1/chat/completions—OpenAI-compatible chat API
    • /v1/responses—OpenResponses API
    • /tools/invoke—direct tool invocation
  • Control UI (web dashboard, if enabled)
  • Canvas file server (18793 by default, separate port)—serves ~/clawd/canvas at /__moltbot__/canvas/

Browser control uses derived ports:

  • Control service: gateway port + 2 (e.g., 18791)
  • Extension relay: gateway port + 3 (e.g., 18792)
  • Browser profiles auto-allocate CDP ports in the 18800–18899 range

Change the base port with --port, CLAWDBOT_GATEWAY_PORT, or gateway.port in config.

Protocol basics

Clients connect via WebSocket and must send a connect request first:

{
  "type": "req",
  "id": "1",
  "method": "connect",
  "params": {
    "minProtocol": 7,
    "maxProtocol": 7,
    "client": {
      "id": "cli-abc123",
      "version": "1.0.0",
      "platform": "darwin",
      "mode": "operator"
    },
    "auth": {
      "token": "your-gateway-token"
    }
  }
}

The gateway responds with a hello-ok payload that includes presence, health, and config snapshots—everything you need to render state without extra requests.

After handshake:

  • Requests follow the {type:"req", id, method, params} → {type:"res", id, ok, payload} pattern
  • Events are pushed as {type:"event", event, payload}

Common events: agent (streamed tool output), presence (who’s connected), tick (keepalive), shutdown (gateway restarting).

See Gateway protocol for the full spec.

Key methods

  • health—full system health snapshot
  • status—quick summary
  • agent—run an agent turn (streams events back)
  • send—send a message via a channel
  • system-presence—list connected clients
  • node.*—discover, pair, and control remote nodes
  • cron.*—manage scheduled jobs

Config hot-reload

The gateway watches moltbot.json for changes. When you save:

  • Safe changes (allowlists, thresholds, feature flags) apply immediately
  • Critical changes (channel credentials, bind address) trigger an automatic restart

Default mode is "hybrid". Set gateway.reload.mode="off" to disable entirely.

In-process restart

Send SIGUSR1 to restart without stopping:

kill -USR1 $(pgrep -f "moltbot gateway")

Or use the gateway tool from an agent:

{
  "tool": "gateway",
  "action": "restart",
  "delayMs": 2000
}

The restart finishes the current agent run first, broadcasts a shutdown event, reloads everything, and comes back up in seconds.

Operational health checks

Liveness:

  • Can you open a WebSocket to the gateway port?
  • Does a connect request get a hello-ok response?

Readiness:

  • Does health return ok: true?
  • Is your main messaging channel linked? (check linkChannel in health payload)

Monitoring:

  • Subscribe to presence events—if you stop getting updates, something’s wrong
  • Watch for shutdown events (planned restarts vs. crashes)
  • Check status for agent queue depth and error counts

Security posture

  • Bind to localhost by default (127.0.0.1:18789)—only local processes can connect
  • Auth required even on loopback—no unauthenticated access
  • Use Tailscale Serve for remote access (identity-based auth, encrypted tunnel)
  • Avoid public exposure—don’t bind to 0.0.0.0 without strong auth and a firewall

When you do need remote access:

  • Tailscale Serve/Funnel (preferred)
  • SSH tunnel (fallback)
  • VPN (wireguard, etc.)

Never expose the gateway port directly to the internet.

See Security for threat models and hardening checklists.

Troubleshooting

Gateway won’t start:

  • Check if the port is already in use: lsof -i :18789
  • Use moltbot gateway --force to kill existing listeners
  • Check logs: moltbot logs or ~/.clawdbot/logs/gateway.log

Can’t connect from CLI:

  • Verify the gateway is running: moltbot gateway status
  • Check auth token matches: echo $CLAWDBOT_GATEWAY_TOKEN
  • Try connecting with explicit URL: moltbot --url ws://127.0.0.1:18789 status

Channel not linked:

  • WhatsApp: run moltbot setup and scan the QR code
  • Telegram: check channels.telegram.accounts and verify the bot token
  • Run moltbot doctor for a health audit

See Troubleshooting for the full runbook.

What’s next

Last updated on:
Authentication