openclaw-riverdesk

OpenClaw channel plugin for RiverDesk — chat with your OpenClaw agents from the RiverDesk app, with end-to-end encryption.

• Dial-out WebSocket — the plugin connects out to the RiverDesk server (wss://api.riverdesk.ai/plugin). No inbound ports, NAT/firewall friendly.
• E2EE — messages are encrypted with a locally minted keypair (libsodium). The server relays ciphertext only.
• Self-serve pairing — a one-time pairing code from the RiverDesk web app is exchanged for a persistent plugin token on first boot. No manual token handling.
• Managed lifecycle — runs inside the OpenClaw gateway; starts, stops, and reconnects with it.

Requirements / Compatibility

• OpenClaw gateway >= 2026.6.11 — the first release with the channel plugin SDK surface this plugin targets (including the current ChannelSetupAdapter shape). Check yours with:

  openclaw --version

  The same minimum is declared in three consistent places in package.json: peerDependencies.openclaw, openclaw.compat.minGatewayVersion, and openclaw.compat.pluginApi.

• Node.js 22+ — the plugin runs inside the OpenClaw gateway process, and the gateway itself requires Node 22 or newer.

• A RiverDesk account at web.riverdesk.ai.

Install

openclaw plugins install openclaw-riverdesk

Or from a local tarball:

openclaw plugins install npm-pack:/path/to/openclaw-riverdesk-0.1.0.tgz

Setup (pairing code — recommended)

1. Get a pairing code. Sign in at web.riverdesk.ai, open your agent's settings, and generate a pairing code. Codes are one-time and expire after ~10 minutes, so do this right before the next step.

2. Configure the channel. Add to your OpenClaw config (~/.openclaw/openclaw.json):

   {
     "channels": {
       "riverdesk": {
         "serverUrl": "wss://api.riverdesk.ai/plugin",
         "pairingCode": "<your one-time code>",
         "agents": ["youragent"],
         "agentMap": { "youragent": "main" }
       }
     }
   }

   • agents — the RiverDesk agent id(s) this gateway serves.
   • agentMap — maps each RiverDesk agent id to a local gateway agent id (most installs map to "main").

3. Restart the gateway.

   openclaw gateway restart

   On first boot the plugin mints an E2EE keypair (~/.riverdesk/plugin-keypair.json), exchanges the pairing code for a persistent plugin token, and stores it in a state file next to the keypair (chmod 600). The pairing code is ignored from then on — you can delete it from the config.

4. Verify it's online. In the RiverDesk app your agent should show as online; send it a message and it should reply. From the shell:

   curl -s https://api.riverdesk.ai/health
   # "agentsOnline" should list your agent as true

Configuration reference

| Key | Required | Description | | --- | --- | --- | | serverUrl | yes | RiverDesk /plugin WS endpoint. Production: wss://api.riverdesk.ai/plugin | | pairingCode | first boot | One-time code from the web app. Used only when no stored token exists. | | agents | yes | RiverDesk agent ids this plugin serves. | | agentMap | recommended | RiverDesk agent id → local gateway agent id, e.g. {"youragent":"main"}. | | apiUrl | no | REST base for media endpoints. Default derives from serverUrl. | | keyFile | no | Path to the plugin keypair JSON. Default ~/.riverdesk/plugin-keypair.json, auto-minted. | | stateFile | no | Where the issued plugin token persists. Default keyFile + ".rd-state.json". | | pluginToken | no | Legacy explicit token (pre-pairing deployments). Prefer the pairing flow. | | pubkeyId | no | E2EE pubkey id override. Derived from the keypair when omitted. | | stream | no | Typewriter streaming: {"mode":"typewriter","chunk":6,"delayMs":45} or {"mode":"off"}. | | allowFrom | no | DM allowlist (participant/pubkey ids). | | agentConcurrency | no | Max concurrent agent turns (default 2). | | agentQueueMax | no | Max queued turns before rejection (default 20). | | agentTurnTimeoutSec | no | Max seconds per agent turn (default 1800). | | mediaMaxMb | no | Media size cap in MB. | | tickMs | no | Reconnect tick interval in ms (default 20000). | | dmSecurity | no | DM policy override (default allowlist). |

Environment variable equivalents: RIVERDESK_SERVER, RIVERDESK_PLUGIN_TOKEN, RIVERDESK_PLUGIN_KEYFILE, RIVERDESK_PLUGIN_PUBKEY_ID, RIVERDESK_PLUGIN_AGENTS, RIVERDESK_LOCAL_AGENT_MAP.

Migrating from a standalone connector

If you previously ran the standalone RiverDesk connector process for the same agent, stop it after the plugin connects — two clients serving one agent will fight over the connection. Point keyFile (and pubkeyId) at the existing connector's keypair to keep your E2EE identity, or pair fresh with a new code.

Troubleshooting

• Agent not online after restart — check gateway logs for [rd-channel] lines. pairing failed usually means the code expired (10 min TTL); generate a new one.
• Paired before, offline now — the token persists in the state file; a stale pairingCode in config is ignored and harmless. Check network reachability to api.riverdesk.ai:443.
• Reset pairing — delete the state file (~/.riverdesk/plugin-keypair.json.rd-state.json), set a fresh pairingCode, restart the gateway.

License

MIT © RiverDesk