Clawdbot Gateway

Clawdbot Gateway Overview

The Clawdbot Gateway is the always-on process that owns messaging connections (WhatsApp via Baileys, Telegram via grammY, Discord, Slack, and more) and the control/event plane. It's the core service that keeps your Clawdbot AI assistant running 24/7.

What is the Gateway?

The Gateway is a single long-lived daemon that:

• Maintains all messaging provider connections
• Exposes a typed WebSocket API for requests, responses, and server-push events
• Validates inbound frames against JSON Schema
• Emits events like agent, chat, presence, health, heartbeat, cron

Key principle: One Gateway per host; it is the only place that opens messaging sessions (like WhatsApp).

Quick Start

Start the Gateway

clawdbot gateway --port 18789

For full debug/trace logs:

clawdbot gateway --port 18789 --verbose

If the port is busy, terminate listeners then start:

clawdbot gateway --force

Development Mode

For development with auto-reload on TypeScript changes:

pnpm gateway:watch

Gateway Architecture

Components

Connection Flow

Client                    Gateway
  |                          |
  |---- req:connect -------->|
  |<------ res (ok) ---------|
  |                          |
  |<------ event:presence ---|
  |<------ event:tick -------|
  |                          |
  |------- req:agent ------->|
  |<------ res:agent --------|
  |<------ event:agent ------|

Gateway Configuration

Basic Configuration

Config file location: ~/.clawdbot/clawdbot.json

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token"
    },
    "reload": {
      "mode": "hybrid"
    }
  }
}

Port Configuration

Port precedence:

1. --port CLI flag
2. CLAWDBOT_GATEWAY_PORT environment variable
3. gateway.port in config
4. Default: 18789

Authentication

Gateway auth is required by default. Set via:

• gateway.auth.token in config
• CLAWDBOT_GATEWAY_TOKEN environment variable
• gateway.auth.password for password-based auth

Clients must send connect.params.auth.token or connect.params.auth.password.

Hot Reload

Config hot reload watches ~/.clawdbot/clawdbot.json:

Gateway Services

HTTP Endpoints

The Gateway serves multiple HTTP endpoints on the same port:

Canvas Host

Starts by default on port 18793, serving:

http://<gateway-host>:18793/__clawdbot__/canvas/

From ~/.clawdbot/workspace/canvas. Disable with:

• canvasHost.enabled: false
• CLAWDBOT_SKIP_CANVAS_HOST=1

Dashboard

Access the Control UI at:

http://127.0.0.1:18789/

Or run:

clawdbot dashboard

Remote Access

SSH Tunnel (Recommended)

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

Clients then connect to ws://127.0.0.1:18789 through the tunnel.

Tailscale/VPN

Preferred for production remote access. The same handshake + auth token apply.

Gateway Management

Service Commands

# Check status
clawdbot gateway status

# Health check
clawdbot health

# Security audit
clawdbot security audit --deep

# Stop gateway
clawdbot gateway stop

Supervision

macOS: Uses LaunchAgent (bot.molt.<profile>)

Linux: Uses systemd user service (clawdbot-gateway-<profile>.service)

Windows: Uses Windows Service (Clawdbot Gateway (<profile>))

Multiple Gateways

Usually unnecessary—one Gateway can serve multiple channels and agents. Use multiple Gateways only for:

• Redundancy
• Strict isolation (e.g., rescue bot)

Requirements:

• Isolate state + config
• Use unique ports

Wire Protocol

Transport

• WebSocket with text frames containing JSON payloads
• First frame must be connect

Message Types

Requests:

{"type": "req", "id": "...", "method": "...", "params": {...}}

Responses:

{"type": "res", "id": "...", "ok": true, "payload": {...}}

Events:

{"type": "event", "event": "...", "payload": {...}, "seq": 1}

Idempotency

Idempotency keys are required for side-effecting methods (send, agent) to safely retry.

Troubleshooting

Gateway Won't Start

1. Check if port is in use: lsof -i :18789
2. Review logs: cat /tmp/clawdbot/gateway.log
3. Use --force to terminate existing listeners

Connection Issues

1. Verify auth token matches
2. Check network connectivity
3. Review WebSocket handshake logs with --verbose

Channel Problems

1. Check channel status: clawdbot channels status
2. Re-authenticate channels: clawdbot channels login
3. Review channel-specific logs

Best Practices

1. Use Auth Tokens: Always configure gateway.auth.token for security
2. Monitor Health: Regularly check clawdbot health
3. Use Supervision: Let launchd/systemd manage restarts
4. Backup Config: Keep backups of ~/.clawdbot/clawdbot.json
5. Review Logs: Check logs regularly for issues

Next Steps

• Clawdbot Setup Guide - Complete installation guide
• Clawdbot WhatsApp Integration - Connect to WhatsApp
• Clawdbot Telegram Integration - Connect to Telegram