@snap-protocol/openclaw-snap-bridge

An OpenClaw plugin that bridges enterprise IM identities (Slack, DingTalk, Teams) to SNAP P2TR addresses via the SNAP Bridge protocol. It handles identity binding, certificate lifecycle, and bidirectional message relay over a single WebSocket connection.

How It Works

Enterprise IM (DingTalk/Slack/Teams)
        │
        ▼
┌─────────────────┐     WebSocket      ┌────────────────────────┐
│  Bridge Server   │◄──────────────────►│  This Plugin (Agent)   │
│  (SNAP Bridge)   │  ca/bind           │  ┌──────────────────┐  │
│                  │  ca/cert_request    │  │ BridgeConnection │  │
│  Routes messages │  message/send      │  │ BindingManager   │  │
│  between IM and  │  message/stream    │  │ CertManager      │  │
│  SNAP agents     │  bridge/send       │  │ InboundRouter    │  │
│                  │  tasks/get|cancel   │  │ ResponseHandler  │  │
└─────────────────┘                     └────────────────────────┘
                                                    │
                                                    ▼
                                               OpenClaw Core

Installation

npm install @snap-protocol/openclaw-snap-bridge

Register the plugin in your OpenClaw configuration:

// ~/.openclaw/openclaw.json (plugins section)
{
  "plugins": {
    "entries": {
      "openclaw-snap-bridge": {
        "config": {
          "bridgeUrl": "wss://bridge.example.com/snap-bridge"
        }
      }
    }
  }
}

Local bridge: If you are running the bridge locally for development, use ws://127.0.0.1:9090 instead. See docs/development.md for the full local development workflow.

Configuration

| Field | Required | Default | Description | |-------|----------|---------|-------------| | bridgeUrl | Yes | — | WebSocket URL of the SNAP Bridge server | | privateKey | No | auto-generated | 64-character lowercase hex key for BIP-340 Schnorr signing | | privateKeyPath | No | — | Path to key file (takes precedence over privateKey) | | streamingEnabled | No | true | Advertise message/stream capability to the Bridge |

Private key resolution order:

1. privateKeyPath — reads key from file
2. privateKey — uses inline value
3. Neither set — auto-generates and stores at ~/.openclaw/openclaw-snap-bridge/key.hex

Quick Start

Option A: Run the demo (no Bridge Server needed)

The demo starts a local mock Bridge and walks through the full lifecycle:

npx tsx examples/demo.ts

You will see: connection → pairing → certificate issuance → inbound message handling → proactive outbound message. Wait ~45 seconds to observe automatic certificate renewal.

Option B: Connect to a real Bridge Server

1. Get your Bridge Server URL and a pairing code from your admin
2. Configure the plugin:

{
  "bridgeUrl": "wss://bridge.example.com/snap-bridge"
}

3. On first connection, pass the pairing code via the gateway start options. The plugin will:

   • Connect to the Bridge via WebSocket
   • Send ca/bind with the pairing code
   • Receive your identity binding (enterprise user ↔ SNAP address)
   • Request and cache a SNAP-IC certificate (auto-renews at 75% lifetime)

4. Once paired, the plugin automatically reconnects and re-binds on disconnection.

API Overview

The plugin exposes three adapters to OpenClaw:

Gateway — Manages the WebSocket lifecycle

• start({ config, pairingCode }) — Connect and pair with Bridge
• stop() — Disconnect and clean up
• isConnected() — Connection status

Outbound — Send messages to IM users

• sendText({ text, target }) — Send a proactive message via bridge/send

Config — Account management

• listAccountIds() — List bound identities
• resolveAccount(cfg, accountId) — Get binding details for an identity

Supported Protocol Methods

| Method | Direction | Description | |--------|-----------|-------------| | ca/bind | Agent → Bridge | Pair agent with enterprise identity | | ca/cert_request | Agent → Bridge | Request/renew SNAP-IC certificate | | message/send | Bridge → Agent | Deliver IM message for sync processing | | message/stream | Bridge → Agent | Deliver IM message for streaming response | | bridge/send | Agent → Bridge | Proactive outbound message to IM user | | tasks/get | Bridge → Agent | Query task status | | tasks/cancel | Bridge → Agent | Cancel a running task |

Guide

• docs/guide.md — Step-by-step walkthrough for end users connecting to a remote Bridge server
• docs/development.md — Local development setup with a local Bridge server

License

MIT