ClawdBotAI

What is the Gateway

The ClawdBot 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 ClawdBot system:

WhatsApp / Telegram / Discord / iMessage
        │
        ▼
┌───────────────────────────┐
│         Gateway           │  ws://127.0.0.1:18789
│    (Single Source of      │
│         Truth)            │
└───────────┬───────────────┘
            │
            ├─ Pi Agent (RPC)
            ├─ CLI (clawdbot …)
            ├─ 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:

clawdbot onboard --install-daemon

Manual Start

Run the gateway manually:

clawdbot gateway --port 18789

Check Status

clawdbot 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 ~/.clawdbot/clawdbot.json

Default Behavior

Without any configuration, ClawdBot 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 ClawdBot
`groups.requireMention`	Only respond in groups when @mentioned
`mentionPatterns`	Patterns that trigger ClawdBot in groups
`canvasHost.port`	Canvas host port (default: 18793)

See Configuration Reference for all options.

Security

Access Control

Lock down who can control your ClawdBot:

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

Group Mention Rules

Prevent ClawdBot from responding to every message in groups:

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

Remote Access

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

clawdbot 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
clawdbot doctor

# Check logs
clawdbot logs

WhatsApp Disconnected

# Re-pair WhatsApp
clawdbot channels login

# Check session status
clawdbot channels status

Messages Not Received

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

Multiple Instances

Run multiple gateways on different ports:

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

See Troubleshooting Guide for more solutions.

Gateway Setup