Stork Chat Gateway

Bridge between Stork Relay and OpenClaw. Runs on the user's VPS.

What It Does

Stork Relay (cloud)          Your VPS
      │                         │
      │◄── WebSocket ──────────►│ Chat Gateway
      │                         │      │
      │                         │      │ Local WebSocket
      │                         │      ▼
      │                         │  OpenClaw
      │                         │

The Chat Gateway:

1. Connects to the central Stork Relay
2. Receives encrypted messages from Mobile App (via Relay)
3. Decrypts and forwards to OpenClaw
4. Encrypts OpenClaw responses and sends back
5. Handles streaming (typing indicators, chunk-by-chunk delivery)

Quick Start

bun install
bun run stork.ts init

The setup wizard will:

• Generate a BIP39 passphrase (your master identity)
• Register with the relay server
• Create an encrypted room
• Show a QR code for mobile pairing

Save your passphrase! You'll need it to add more agents or recover your identity.

Commands

stork init         # First-time setup (generates passphrase)
stork pair         # Show QR code for mobile app pairing
stork add-agent    # Generate a new agent token (requires passphrase)
stork start        # Connect to relay and start bridging
stork status       # Show current configuration

Running as a Service

# Copy service file
cp stork-gateway.service ~/.config/systemd/user/

# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now stork-gateway

# Check logs
journalctl --user -u stork-gateway -f

Configuration

Config saved to ~/.stork/config.json (mode 0600).

Environment variables: | Variable | Default | Description | |----------|---------|-------------| | OPENCLAW_GATEWAY_URL | ws://127.0.0.1:18789 | OpenClaw Gateway WebSocket | | OPENCLAW_GATEWAY_TOKEN | — | OpenClaw auth token | | STORK_RELAY_URL | wss://relay.stork.sh | Stork Relay server |

Architecture

See ARCHITECTURE.md for the full picture.

Current state:

• One gateway instance supports multiple rooms
• Each room maps to its own OpenClaw session
• Runtime room sync is supported (rooms created outside the process are picked up)

Planned:

• Room-level model preferences
• Multi-agent support

Files

| File | Purpose | |------|---------| | stork.ts | Main CLI and connection logic | | gateway.ts | OpenClaw Gateway WebSocket client | | identity.ts | BIP39 passphrase and key derivation | | stork-gateway.service | systemd unit file |

Change Validation Policy

Before confirming any gateway change as "working", run:

bun run test:fast

For room-sync related changes (especially mobile-created room behavior), also run:

bun run test:room-sync

This is mandatory for agents and humans touching routing/sync logic.

Related

• Stork Relay — Central message relay
• Mobile App — User's phone interface
• Stork Hatch — VPS provisioning tool (installs this)