Gateway service runbook

Scope

The Gateway is the always-on process that owns channel connections and serves the control/event plane (WebSocket + HTTP Control UI).

Gateway Core Functions

The Clawdbot Gateway is the central component of the system, providing:

Function	Description
Message Routing	Connects channels and provides unified message entry/exit points
Control Plane	Web console and WebSocket interface for management
State Management	Maintains sessions, configuration, and runtime state
Security & Auth	Device pairing, permission control, and access management
Tool Execution	Tool calls and execution in sandboxed environments

Run locally

clawdbot gateway --port 18789
clawdbot gateway --port 18789 --verbose

Service install (recommended)

clawdbot onboard --install-daemon
clawdbot gateway status

Basic Operations

Start Gateway

# Development mode (foreground)
clawdbot start

# Production mode (daemon service)
clawdbot start --daemon

# With custom config
clawdbot start --config /path/to/config.yaml

Health Check

# Check gateway status
clawdbot status

# Run diagnostics
clawdbot doctor

# Check health endpoint
curl http://localhost:3983/health

Config Management

# View current config
clawdbot config show

# Set config value
clawdbot config set agents.defaults.model.primary "anthropic/claude-opus-4-5"

# Edit config file
clawdbot config edit

Config + auth basics

Default config path: ~/.clawdbot/clawdbot.json (override via env in advanced setups).
Default port: 18789 (WebSocket + HTTP Control UI on the same port).
When you bind beyond loopback, require a token/password (see /en/docs/gateway/security/).

Profiles (isolate state)

--dev: uses ~/.clawdbot-dev and shifted ports for a safe dev instance.
--profile <name>: uses ~/.clawdbot-<name> for isolation (multiple gateways on one host).

Remote access (safe defaults)

SSH tunnel: ssh -N -L 18789:127.0.0.1:18789 user@host
Tailscale access: /en/docs/gateway/tailscale/

Related Concepts

Session Management - Session lifecycle and state
Message Routing - How messages flow between channels
Device Pairing - How new devices connect to the gateway

Common operator pages

Configuration: /en/docs/gateway/configuration/
Security: /en/docs/gateway/security/
Logging: /en/docs/gateway/logging/
Troubleshooting: /en/docs/gateway/troubleshooting/
Protocol: /en/docs/gateway/protocol/