npm package: @storkagent/chat-gateway
Description: **Bridge between Stork Relay and OpenClaw.** Runs on the user's VPS.
Latest version: 2.2.2

# 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

```bash
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

```bash
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

```bash
# 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](../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:

```bash
bun run test:fast
```

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

```bash
bun run test:room-sync
```

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

---

## Related

- [Stork Relay](../server/) — Central message relay
- [Mobile App](../mobile-app/) — User's phone interface
- [Stork Hatch](../stork-hatch/) — VPS provisioning tool (installs this)