ClawdBotAI LogoClawdBotAI
HomeDocsGateway & OpsGateway

Gateway

Clawdbot's WebSocket server for channels, nodes, sessions, and hooks

The Gateway is Clawdbot's WebSocket server (channels, nodes, sessions, hooks). Subcommands in this page live under clawdbot gateway ….

Run the Gateway

Run a local Gateway process:

clawdbot gateway

Foreground alias:

clawdbot gateway run

Notes:

  • By default, the Gateway refuses to start unless gateway.mode=local is set in ~/.clawdbot/clawdbot.json.
  • Use --allow-unconfigured for ad-hoc/dev runs.
  • Binding beyond loopback without auth is blocked (safety guardrail).
  • SIGUSR1 triggers an in-process restart when authorized.
  • SIGINT / SIGTERM handlers stop the gateway process.

Options

OptionDescription
--port <port>WebSocket port (default: 18789)
--bind <mode>loopback|lan|tailnet|auto|custom
--auth <mode>token|password
--token <token>Token override
--password <password>Password override
--tailscale <mode>off|serve|funnel
--allow-unconfiguredAllow start without gateway.mode=local
--devCreate dev config + workspace if missing
--resetReset dev config + credentials + sessions
--forceKill existing listener on selected port
--verboseVerbose logs

Query a running Gateway

All query commands use WebSocket RPC.

Output modes:

  • Default: human-readable (colored in TTY)
  • --json: machine-readable JSON (no styling/spinner)
  • --no-color (or NO_COLOR=1): disable ANSI

Shared options:

  • --url <url>: Gateway WebSocket URL
  • --token <token>: Gateway token
  • --password <password>: Gateway password
  • --timeout <ms>: timeout/budget

gateway health

clawdbot gateway health --url ws://127.0.0.1:18789

gateway status

Shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe.

clawdbot gateway status
clawdbot gateway status --json

Options:

  • --url <url>: override the probe URL
  • --token <token>: token auth for the probe
  • --timeout <ms>: probe timeout (default 10000)
  • --no-probe: skip the RPC probe (service-only view)
  • --deep: scan system-level services too

gateway probe

The "debug everything" command. It always probes:

  • Your configured remote gateway (if set)
  • localhost (loopback) even if remote is configured
clawdbot gateway probe
clawdbot gateway probe --json

Manage the Gateway service

# Install as service
clawdbot gateway install

# Uninstall service
clawdbot gateway uninstall

# Restart service
clawdbot gateway restart

Discover gateways (Bonjour)

clawdbot gateway discover

Discovers gateways on the local network using Bonjour/mDNS.

Gateway & OpsProtocol