Gateway Runtime Manual

Last updated: 2025-12-09

What It Is

• A resident process with a single Baileys/Telegram connection and control/event plane.
• Replaces the old gateway command. CLI entry point: openclaw gateway.
• Runs until stopped; exits with non-zero exit code on fatal errors so supervisor can restart it.

How to Run (Local)

openclaw gateway --port 18789
# Get full debug/trace logs in stdio:
openclaw gateway --port 18789 --verbose
# If port is occupied, terminate listener then start:
openclaw gateway --force
# Development loop (auto-reload on TS changes):
pnpm gateway:watch

• Configuration hot reload watches ~/.openclaw/openclaw.json (or OPENCLAW_CONFIG_PATH).

  • Default mode: gateway.reload.mode="hybrid" (hot-applies safe changes, restarts on critical changes).
  • Hot reload uses SIGUSR1 for in-process restart when needed.
  • Use gateway.reload.mode="off" to disable.

• Binds WebSocket control plane to 127.0.0.1:<port> (default 18789).

• Same port also serves HTTP (control interface, hooks, A2UI). Single port multiplexing.

  • OpenAI Chat Completions (HTTP): /v1/chat/completions.
  • OpenResponses (HTTP): /v1/responses.
  • Tools Invoke (HTTP): /tools/invoke.

• By default starts Canvas file server on canvasHost.port (default 18793), serving http://<gateway-host>:18793/__openclaw__/canvas/ from ~/.openclaw/workspace/canvas. Use canvasHost.enabled=false or OPENCLAW_SKIP_CANVAS_HOST=1 to disable.

• Logs to stdout; use launchd/systemd to keep running and rotate logs.

• Pass --verbose for troubleshooting to mirror debug logs (handshakes, requests/responses, events) from log file to stdio.

• --force uses lsof to find listener on selected port, sends SIGTERM, logs what it terminated, then starts Gateway (fails fast if lsof missing).

• If you're running under a supervisor (launchd/systemd/mac app subprocess mode), stop/restart usually sends SIGTERM; old versions may show this as pnpm ELIFECYCLE exit code 143 (SIGTERM), which is normal shutdown, not a crash.

• SIGUSR1 triggers in-process restart when authorized (Gateway tools/config apply/update, or enable commands.restart for manual restart).

• By default requires Gateway authentication: set gateway.auth.token (or OPENCLAW_GATEWAY_TOKEN) or gateway.auth.password. Clients must send connect.params.auth.token/password unless using Tailscale Serve identity.

• Wizard now generates tokens by default, even on loopback.

• Port priority: --port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789.

Remote Access

• Prefer Tailscale/VPN; otherwise use SSH tunnel:

  xxxxxxxxxx
  ssh -N -L 18789:127.0.0.1:18789 user@host
  

• Then clients connect to ws://127.0.0.1:18789 through the tunnel.

• If token is configured, clients must include it in connect.params.auth.token even through tunnel.

Multiple Gateways (Same Host)

Usually not needed: one Gateway can serve multiple message channels and agents. Use multiple Gateways only when you need redundancy or strict isolation (e.g., rescue bot). Supported if you isolate state + configuration and use unique ports. Full guide: Multiple Gateways. Service names are profile-aware:

• macOS: bot.molt.<profile> (legacy com.openclaw.* may still exist)
• Linux: openclaw-gateway-<profile>.service
• Windows: OpenClaw Gateway (<profile>)

Installation metadata is embedded in service configuration:

• OPENCLAW_SERVICE_MARKER=openclaw
• OPENCLAW_SERVICE_KIND=gateway
• OPENCLAW_SERVICE_VERSION=<version>

Rescue bot mode: Keep a second Gateway isolated with its own profile, state directory, workspace, and base port offset. Full guide: Rescue Bot Guide.

Dev Profile (--dev)

Quick path: Run completely isolated dev instance (config/state/workspace) without touching your main setup.

xxxxxxxxxx
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
# Then target dev instance:
openclaw --dev status
openclaw --dev health

Defaults (overridable via env/flags/config):

• OPENCLAW_STATE_DIR=~/.openclaw-dev
• OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
• OPENCLAW_GATEWAY_PORT=19001 (Gateway WS + HTTP)
• Browser control service port = 19003 (derived: gateway.port+2, loopback only)
• canvasHost.port=19005 (derived: gateway.port+4)
• When you run setup/onboard under --dev, agents.defaults.workspace defaults to ~/.openclaw/workspace-dev.

Derived ports (rule of thumb):

• Base port = gateway.port (or OPENCLAW_GATEWAY_PORT / --port)
• Browser control service port = base + 2 (loopback only)
• canvasHost.port = base + 4 (or OPENCLAW_CANVAS_HOST_PORT / config override)
• Browser profile CDP ports auto-allocated from browser.controlPort + 9 .. + 108 (persisted per profile).

Per-instance checklist:

• Unique gateway.port
• Unique OPENCLAW_CONFIG_PATH
• Unique OPENCLAW_STATE_DIR
• Unique agents.defaults.workspace
• Separate WhatsApp number (if using WA)

Install services by profile:

xxxxxxxxxx
openclaw --profile main gateway install
openclaw --profile rescue gateway install

Example:

xxxxxxxxxx
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Protocol (Operations View)

• Full documentation: Gateway Protocol and Bridge Protocol (Legacy).

• First frame clients must send: req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId?}, caps, auth?, locale?, userAgent? } }.

• Gateway replies res {type:"res", id, ok:true, payload:hello-ok } (or ok:false with error, then close).

• After handshake:

  • Requests: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • Events: {type:"event", event, payload, seq?, stateVersion?}

• Structured presence entries: {host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? } (for WS clients, instanceId from connect.client.instanceId).

• agent responses are two-phase: first res acknowledges {runId,status:"accepted"}, then final res {runId,status:"ok"|"error",summary} sent after run completes; streaming output arrives as event:"agent".

Methods (Initial Set)

• health — Full health snapshot (same shape as openclaw health --json).
• status — Brief summary.
• system-presence — Current presence list.
• system-event — Publish presence/system annotation (structured).
• send — Send message via active channel.
• agent — Run agent turn (streams events back on same connection).
• node.list — List paired + currently connected nodes (including caps, deviceFamily, modelIdentifier, paired, connected, and broadcasted commands).
• node.describe — Describe node (capabilities + supported node.invoke commands; works for paired nodes and currently connected unpaired nodes).
• node.invoke — Invoke command on node (e.g., canvas.*, camera.*).
• node.pair.* — Pairing lifecycle (request, list, approve, reject, verify).

See also: Presence for how presence is generated/deduplicated and why stable client.instanceId is important.

Events

• agent — Streaming tool/output events from agent runs (with seq markers).
• presence — Presence updates (deltas with stateVersion) pushed to all connected clients.
• tick — Periodic keepalive/noop to confirm liveness.
• shutdown — Gateway is exiting; payload includes reason and optional restartExpectedMs. Clients should reconnect.

WebChat Integration

• WebChat is native SwiftUI UI that talks directly to Gateway WebSocket for history, send, abort, and events.
• Remote use works through same SSH/Tailscale tunnel; if Gateway token is configured, client includes it during connect.
• macOS app uses single WS connection (shared connection); it populates presence from initial snapshot and listens to presence events to update UI.

Types and Validation

• Server validates each inbound frame using AJV against JSON Schema emitted from protocol definition.

• Clients (TS/Swift) consume generated types (TS directly; Swift via repo's generator).

• Protocol definition is source of truth; regenerate schema/models with:

  • pnpm protocol:gen
  • pnpm protocol:gen:swift

Connection Snapshot

• hello-ok contains snapshot with presence, health, stateVersion, and uptimeMs, plus policy {maxPayload,maxBufferedBytes,tickIntervalMs}, so clients can render immediately without extra requests.
• health/system-presence still available for manual refresh but not required on connect.

Error Codes (res.error shape)

• Errors use `{ code, message, details?, retryable?, retryAfterMs? }".

• Standard codes:

  • NOT_LINKED — WhatsApp not authenticated.
  • AGENT_TIMEOUT — Agent didn't respond within configured deadline.
  • INVALID_REQUEST — schema/parameter validation failed.
  • UNAVAILABLE — Gateway is shutting down or dependency unavailable.

Keepalive Behavior

• tick events (or WS ping/pong) are sent periodically so clients know Gateway is alive even when there's no traffic.
• Send/agent acknowledgments remain separate responses; don't overload tick for sends.

Replay / Gaps

Events are not replayed. Clients detect seq gaps and should refresh (health + system-presence) before continuing. WebChat and macOS clients now auto-refresh on gaps.

Supervision (macOS Example)

• Use launchd to keep service alive:

  • Program: path to openclaw
  • Arguments: gateway
  • KeepAlive: true
  • StandardOut/Err: file paths or syslog

• On failure, launchd restarts; fatal configuration errors should stay exited so ops notice.

• LaunchAgents are per-user and require logged-in session; for headless setups, use custom LaunchDaemon (not bundled).

  • openclaw gateway install writes ~/Library/LaunchAgents/bot.molt.gateway.plist (or bot.molt.<profile>.plist; legacy com.openclaw.* will be cleaned up).
  • openclaw doctor audits LaunchAgent config and can update it to current defaults.

Gateway Service Management (CLI)

Use Gateway CLI for install/start/stop/restart/status:

xxxxxxxxxx
openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow

Notes:

• gateway status by default probes Gateway RPC using service-resolved port/config (override with --url).

• gateway status --deep adds system-level scan (LaunchDaemons/system units).

• gateway status --no-probe skips RPC probe (useful when network is down).

• gateway status --json is stable for scripting.

• gateway status reports supervisor runtime (launchd/systemd running) separate from RPC reachability (WS connection + status RPC).

• gateway status prints config path + probe target to avoid "localhost vs LAN bind" confusion and profile mismatches.

• gateway status includes last Gateway error line when service appears running but port is closed.

• logs tails Gateway file logs via RPC (no manual tail/grep needed).

• CLI warns if it detects other Gateway-like services, unless they are OpenClaw profile services. We still recommend most setups have one Gateway per machine; use isolated profiles/ports for redundancy or rescue bots. See Multiple Gateways.

  • Cleanup: openclaw gateway uninstall (current service) and openclaw doctor (legacy migration).

• gateway install is no-op when already installed; use openclaw gateway install --force to reinstall (profile/env/path changes).

Bundled mac app:

• OpenClaw.app can bundle Node-based Gateway relay and install per-user LaunchAgent labeled bot.molt.gateway (or bot.molt.<profile>; legacy com.openclaw.* labels still clean uninstall).

• To stop it cleanly, use openclaw gateway stop (or launchctl bootout gui/$UID/bot.molt.gateway).

• To restart, use openclaw gateway restart (or launchctl kickstart -k gui/$UID/bot.molt.gateway).

  • launchctl only works if LaunchAgent is installed; otherwise use openclaw gateway install first.
  • When running named profile, replace label with bot.molt.<profile>.

Supervision (systemd user units)

OpenClaw defaults to systemd user services on Linux/WSL2. We recommend user services for single-user machines (simpler env, per-user config). For multi-user or always-on servers use system services (no lingering needed, shared supervision). openclaw gateway install writes user unit. openclaw doctor audits unit and can update it to match current recommended defaults. Creates ~/.config/systemd/user/openclaw-gateway[-<profile>].service:

​x
[Unit]
Description=OpenClaw Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target
​
[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
Environment=OPENCLAW_GATEWAY_TOKEN=
WorkingDirectory=/home/youruser
​
[Install]
WantedBy=default.target

Enable lingering (required for user services to survive logout/idle):

xxxxxxxxxx
sudo loginctl enable-linger youruser

Onboarding runs this on Linux/WSL2 (may prompt for sudo; writes /var/lib/systemd/linger). Then enable service:

xxxxxxxxxx
systemctl --user enable --now openclaw-gateway[-<profile>].service

Alternative (system service) - For always-on or multi-user servers, you can install systemd system unit instead of user unit (no lingering needed). Create /etc/systemd/system/openclaw-gateway[-<profile>].service (copy unit above, switch WantedBy=multi-user.target, set User= + WorkingDirectory=), then:

xxxxxxxxxx
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service

Windows (WSL2)

Windows installations should use WSL2 and follow the Linux systemd section above.

Operations Checks

• Liveness check: Open WS and send req:connect → expect res with payload.type="hello-ok" (with snapshot).
• Readiness check: Call health → expect ok: true and linked channel in linkChannel (when applicable).
• Debug: Subscribe to tick and presence events; ensure status shows linked/auth time; presence entries show Gateway host and connected clients.

Security Guarantees

• Default assumes one Gateway per host; if you run multiple profiles, isolate ports/state and target the correct instance.
• Won't fall back to direct Baileys connection; if Gateway is down, sends fail fast.
• Non-connect first frame or malformed JSON is rejected and socket closed.
• Graceful shutdown: emits shutdown event before close; clients must handle close + reconnect.

CLI Helpers

• openclaw gateway health|status — Request health/status via Gateway WS.
• openclaw message send --target <num> --message "hi" [--media ...] — Send via Gateway (idempotent for WhatsApp).
• openclaw agent --message "hi" --to <num> — Run agent turn (waits for final result by default).
• openclaw gateway call <method> --params '{"k":"v"}' — Raw method invoker for debugging.
• openclaw gateway stop|restart — Stop/restart supervised Gateway service (launchd/systemd).
• Gateway helper subcommands assume running Gateway on --url; they no longer auto-spawn one.

Migration Guide

• Deprecate use of openclaw gateway and legacy TCP control port.
• Update clients to use WS protocol with mandatory connect and structured presence.

For more Gateway content, refer to: Gateway Runtime Manual - OpenClaw