nullclaw gateway

Start the long-running gateway runtime with HTTP webhook support

The nullclaw gateway command starts the long-running runtime that includes:

• HTTP gateway for webhook endpoints
• All configured channels
• Heartbeat scheduler
• Cron job execution
• Pairing server for authentication

Usage

# Start with default port (3000)
nullclaw gateway

# Start with custom port
nullclaw gateway --port 8080

Options

--port · number · default: "3000"

HTTP port to bind to

What Gets Started

When you run nullclaw gateway, the following components start:

1. HTTP Gateway

Binds to 127.0.0.1:3000 (or custom port) and exposes:

• /health - Health check endpoint
• /pair - Pairing code exchange for authentication
• /webhook - Generic webhook for authenticated messages
• /whatsapp - WhatsApp webhook
• /telegram - Telegram webhook (if configured)

2. Configured Channels

All channels with accounts in config.json are started:

• Telegram bots (long-polling)
• Discord bots (WebSocket gateway)
• Signal listeners
• Nostr relays
• IRC connections
• And more…

3. Background Services

• Heartbeat: Periodic health checks
• Cron scheduler: Executes scheduled tasks
• Channel managers: Route messages to agent

Configuration

Gateway configuration in ~/.nullclaw/config.json:

{
  "gateway": {
    "port": 3000,
    "host": "127.0.0.1",
    "require_pairing": true,
    "allow_public_bind": false
  }
}

By default, the gateway binds to 127.0.0.1 (localhost only) for security. To expose publicly, you must:

1. Set allow_public_bind: true in config
2. Configure a tunnel (Cloudflare, ngrok, Tailscale)

Pairing

On first startup, the gateway generates a 6-digit pairing code:

$ nullclaw gateway
Gateway starting on 127.0.0.1:3000
Pairing code: 123456

Exchange this code for a bearer token:
  curl -X POST http://localhost:3000/pair \
    -H "X-Pairing-Code: 123456"

Exchange the pairing code for a bearer token:

$ curl -X POST http://localhost:3000/pair \
  -H "X-Pairing-Code: 123456"

{"token": "eyJ0eXAiOiJKV1QiLCJhbGc..."}

Use this token for all subsequent API calls:

curl -X POST http://localhost:3000/webhook \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, nullclaw!"}'

Webhook Endpoints

POST /webhook

Send messages to the agent:

curl -X POST http://localhost:3000/webhook \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What time is it?"
  }'

GET /health

Health check (no authentication required):

curl http://localhost:3000/health
{"status": "ok"}

Tunnels

For webhook-based channels (WhatsApp, Telegram webhooks), you need a public URL. Configure a tunnel:

{
  "tunnel": {
    "provider": "cloudflared",
    "cloudflared": {
      "hostname": "nullclaw.example.com"
    }
  }
}

See Tunnels for full configuration.

Examples

Start Gateway with Telegram

# 1. Configure Telegram in config.json
# 2. Start gateway
nullclaw gateway

# Gateway starts Telegram bot automatically
# Messages sent to the bot are routed to the agent

Start Gateway as Background Service

# Install as system service
nullclaw service install

# Start service
nullclaw service start

# Check status
nullclaw service status

Logs

Gateway logs are written to:

• macOS/Linux: ~/.nullclaw/logs/gateway.log
• systemd: journalctl -u nullclaw -f

See Also

• Agent - Interactive agent mode
• Service - Background service management
• Channels - Channel configuration
• Tunnels - Tunnel configuration