​

Gateway service runbook

​

What it is

• The always-on process that owns the single Baileys/Telegram connection and the control/event plane.
• Replaces the legacy gateway command. CLI entry point: clawdia gateway.
• Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.

​

How to run (local)

clawdia gateway --port 18789
# for full debug/trace logs in stdio:
clawdia gateway --port 18789 --verbose
# if the port is busy, terminate listeners then start:
clawdia gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch

• Config hot reload watches ~/.nelsonmuntz-c/clawdia.json (or CLAWDIA_CONFIG_PATH).
  • Default mode: gateway.reload.mode="hybrid" (hot-apply safe changes, restart on critical).
  • Hot reload uses in-process restart via SIGUSR1 when needed.
  • Disable with gateway.reload.mode="off".
• Binds WebSocket control plane to 127.0.0.1:<port> (default 18789).
• The same port also serves HTTP (control UI, hooks, A2UI). Single-port multiplex.
  • OpenAI Chat Completions (HTTP): /v1/chat/completions.
  • OpenResponses (HTTP): /v1/responses.
  • Tools Invoke (HTTP): /tools/invoke.
• Starts a Canvas file server by default on canvasHost.port (default 18793), serving http://<gateway-host>:18793/__clawdia__/canvas/ from ~/clawd/canvas. Disable with canvasHost.enabled=false or CLAWDIA_SKIP_CANVAS_HOST=1.
• Logs to stdout; use launchd/systemd to keep it alive and rotate logs.
• Pass --verbose to mirror debug logging (handshakes, req/res, events) from the log file into stdio when troubleshooting.
• --force uses lsof to find listeners on the chosen port, sends SIGTERM, logs what it killed, then starts the gateway (fails fast if lsof is missing).
• If you run under a supervisor (launchd/systemd/mac app child-process mode), a stop/restart typically sends SIGTERM; older builds may surface this as pnpm ELIFECYCLE exit code 143 (SIGTERM), which is a normal shutdown, not a crash.
• SIGUSR1 triggers an in-process restart when authorized (gateway tool/config apply/update, or enable commands.restart for manual restarts).
• Gateway auth: set gateway.auth.mode=token + gateway.auth.token (or pass --token <value> / CLAWDIA_GATEWAY_TOKEN) to require clients to send connect.params.auth.token.
• The wizard now generates a token by default, even on loopback.
• Port precedence: --port > CLAWDIA_GATEWAY_PORT > gateway.port > default 18789.

​

Remote access

• Tailscale/VPN preferred; otherwise SSH tunnel:
  Copy

  ssh -N -L 18789:127.0.0.1:18789 user@host
  
• Clients then connect to ws://127.0.0.1:18789 through the tunnel.
• If a token is configured, clients must include it in connect.params.auth.token even over the tunnel.

​

Multiple gateways (same host)

• macOS: com.clawdia.<profile>
• Linux: clawdia-gateway-<profile>.service
• Windows: Clawdia Gateway (<profile>)

• CLAWDIA_SERVICE_MARKER=clawdia
• CLAWDIA_SERVICE_KIND=gateway
• CLAWDIA_SERVICE_VERSION=<version>

​

Dev profile (--dev)

clawdia --dev setup
clawdia --dev gateway --allow-unconfigured
# then target the dev instance:
clawdia --dev status
clawdia --dev health

• CLAWDIA_STATE_DIR=~/.clawdia-dev
• CLAWDIA_CONFIG_PATH=~/.clawdia-dev/clawdia.json
• CLAWDIA_GATEWAY_PORT=19001 (Gateway WS + HTTP)
• browser.controlUrl=http://127.0.0.1:19003 (derived: gateway.port+2)
• canvasHost.port=19005 (derived: gateway.port+4)
• agents.defaults.workspace default becomes ~/clawd-dev when you run setup/onboard under --dev.

• Base port = gateway.port (or CLAWDIA_GATEWAY_PORT / --port)
• browser.controlUrl port = base + 2 (or CLAWDIA_BROWSER_CONTROL_URL / config override)
• canvasHost.port = base + 4 (or CLAWDIA_CANVAS_HOST_PORT / config override)
• Browser profile CDP ports auto-allocate from browser.controlPort + 9 .. + 108 (persisted per profile).

• unique gateway.port
• unique CLAWDIA_CONFIG_PATH
• unique CLAWDIA_STATE_DIR
• unique agents.defaults.workspace
• separate WhatsApp numbers (if using WA)

clawdia --profile main gateway install
clawdia --profile rescue gateway install

CLAWDIA_CONFIG_PATH=~/.clawdia/a.json CLAWDIA_STATE_DIR=~/.clawdia-a clawdia gateway --port 19001
CLAWDIA_CONFIG_PATH=~/.clawdia/b.json CLAWDIA_STATE_DIR=~/.clawdia-b clawdia gateway --port 19002

​

Protocol (operator view)

• Full docs: Gateway protocol and Bridge protocol (legacy).
• Mandatory first frame from client: 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 an error, then closes).
• 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 comes from connect.client.instanceId).
• agent responses are two-stage: first res ack {runId,status:"accepted"}, then a final res {runId,status:"ok"|"error",summary} after the run finishes; streamed output arrives as event:"agent".

​

Methods (initial set)

• health — full health snapshot (same shape as clawdia health --json).
• status — short summary.
• system-presence — current presence list.
• system-event — post a presence/system note (structured).
• send — send a message via the active channel(s).
• agent — run an agent turn (streams events back on same connection).
• node.list — list paired + currently-connected nodes (includes caps, deviceFamily, modelIdentifier, paired, connected, and advertised commands).
• node.describe — describe a node (capabilities + supported node.invoke commands; works for paired nodes and for currently-connected unpaired nodes).
• node.invoke — invoke a command on a node (e.g. canvas.*, camera.*).
• node.pair.* — pairing lifecycle (request, list, approve, reject, verify).

​

Events

• agent — streamed tool/output events from the agent run (seq-tagged).
• presence — presence updates (deltas with stateVersion) pushed to all connected clients.
• tick — periodic keepalive/no-op to confirm liveness.
• shutdown — Gateway is exiting; payload includes reason and optional restartExpectedMs. Clients should reconnect.

​

WebChat integration

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

​

Typing and validation

• Server validates every inbound frame with AJV against JSON Schema emitted from the protocol definitions.
• Clients (TS/Swift) consume generated types (TS directly; Swift via the repo’s generator).
• Protocol definitions are the source of truth; regenerate schema/models with:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift

​

Connection snapshot

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

​

Error codes (res.error shape)

• Errors use { code, message, details?, retryable?, retryAfterMs? }.
• Standard codes:
  • NOT_LINKED — WhatsApp not authenticated.
  • AGENT_TIMEOUT — agent did not respond within the configured deadline.
  • INVALID_REQUEST — schema/param validation failed.
  • UNAVAILABLE — Gateway is shutting down or a dependency is unavailable.

​

Keepalive behavior

• tick events (or WS ping/pong) are emitted periodically so clients know the Gateway is alive even when no traffic occurs.
• Send/agent acknowledgements remain separate responses; do not overload ticks 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 gap.

​

Supervision (macOS example)

• Use launchd to keep the service alive:
  • Program: path to clawdia
  • Arguments: gateway
  • KeepAlive: true
  • StandardOut/Err: file paths or syslog
• On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
• LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped).
  • clawdia gateway install writes ~/Library/LaunchAgents/com.clawdia.gateway.plist (or com.clawdia.<profile>.plist).
  • clawdia doctor audits the LaunchAgent config and can update it to current defaults.

​

Gateway service management (CLI)

clawdia gateway status
clawdia gateway install
clawdia gateway stop
clawdia gateway restart
clawdia logs --follow

• gateway status probes the Gateway RPC by default using the service’s resolved port/config (override with --url).
• gateway status --deep adds system-level scans (LaunchDaemons/system units).
• gateway status --no-probe skips the RPC probe (useful when networking is down).
• gateway status --json is stable for scripts.
• gateway status reports supervisor runtime (launchd/systemd running) separately from RPC reachability (WS connect + status RPC).
• gateway status prints config path + probe target to avoid “localhost vs LAN bind” confusion and profile mismatches.
• gateway status includes the last gateway error line when the service looks running but the port is closed.
• logs tails the Gateway file log via RPC (no manual tail/grep needed).
• If other gateway-like services are detected, the CLI warns unless they are Clawdia profile services. We still recommend one gateway per machine for most setups; use isolated profiles/ports for redundancy or a rescue bot. See Multiple gateways.
  • Cleanup: clawdia gateway uninstall (current service) and clawdia doctor (legacy migrations).
• gateway install is a no-op when already installed; use clawdia gateway install --force to reinstall (profile/env/path changes).

• Clawdia.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled com.clawdia.gateway (or com.clawdia.<profile>).
• To stop it cleanly, use clawdia gateway stop (or launchctl bootout gui/$UID/com.clawdia.gateway).
• To restart, use clawdia gateway restart (or launchctl kickstart -k gui/$UID/com.clawdia.gateway).
  • launchctl only works if the LaunchAgent is installed; otherwise use clawdia gateway install first.
  • Replace the label with com.clawdia.<profile> when running a named profile.

​

Supervision (systemd user unit)

[Unit]
Description=Clawdia Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/clawdia gateway --port 18789
Restart=always
RestartSec=5
Environment=CLAWDIA_GATEWAY_TOKEN=
WorkingDirectory=/home/youruser

[Install]
WantedBy=default.target

sudo loginctl enable-linger youruser

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

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

​

Windows (WSL2)

​

Operational checks

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

​

Safety guarantees

• Assume one Gateway per host by default; if you run multiple profiles, isolate ports/state and target the right instance.
• No fallback to direct Baileys connections; if the Gateway is down, sends fail fast.
• Non-connect first frames or malformed JSON are rejected and the socket is closed.
• Graceful shutdown: emit shutdown event before closing; clients must handle close + reconnect.

​

CLI helpers

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

​

Migration guidance

• Retire uses of clawdia gateway and the legacy TCP control port.
• Update clients to speak the WS protocol with mandatory connect and structured presence.