> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nullclaw/nullclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
# Start with default port (3000)
nullclaw gateway

# Start with custom port
nullclaw gateway --port 8080
```

## Options

<ParamField path="--port" type="number" default="3000">
  HTTP port to bind to
</ParamField>

## 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`:

```json theme={null}
{
  "gateway": {
    "port": 3000,
    "host": "127.0.0.1",
    "require_pairing": true,
    "allow_public_bind": false
  }
}
```

<Warning>
  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)
</Warning>

## Pairing

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

```bash theme={null}
$ 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:

```bash theme={null}
$ curl -X POST http://localhost:3000/pair \
  -H "X-Pairing-Code: 123456"

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

Use this token for all subsequent API calls:

```bash theme={null}
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:

```bash theme={null}
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):

```bash theme={null}
curl http://localhost:3000/health
{"status": "ok"}
```

## Tunnels

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

```json theme={null}
{
  "tunnel": {
    "provider": "cloudflared",
    "cloudflared": {
      "hostname": "nullclaw.example.com"
    }
  }
}
```

See [Tunnels](/deployment/tunnels) for full configuration.

## Examples

### Start Gateway with Telegram

```bash theme={null}
# 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

```bash theme={null}
# 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](/cli/agent) - Interactive agent mode
* [Service](/cli/service) - Background service management
* [Channels](/configuration/channels) - Channel configuration
* [Tunnels](/deployment/tunnels) - Tunnel configuration