Relay

Name: Relay
Rating: 3.5 (1 reviews)
Author: AskLeeHQ

By AskLeeHQ 👁 7 views ▲ 0 votes

Multi-tenant OpenClaw architecture: relay plugin + Cloudflare worker proxy for Fly.io deployments

GitHub

Install

openclaw plugins install @askleehq/openclaw-relay

Configuration Example

{
  "ok": true,
  "reply": "Hi! How can I help?",
  "messageId": "relay-1707750001234"
}

README

# OpenClaw Relay Plugin

HTTP relay channel for OpenClaw. Enables external systems to send messages into OpenClaw sessions via a simple REST API.

## Use Cases

- Integrate OpenClaw with custom webhooks
- Build multi-tenant architectures
- Route messages from external chat platforms
- Create custom ingress points for your OpenClaw instance

## Installation

### Option 1: Copy to Extensions

```bash
# Clone the repo
git clone https://github.com/AskLeeHQ/openclaw-relay.git

# Copy plugin to OpenClaw extensions
cp -r openclaw-relay/plugin ~/.openclaw/extensions/relay

# Restart gateway
openclaw gateway restart
```

### Option 2: Install via OpenClaw CLI

```bash
openclaw plugins install @askleehq/openclaw-relay
```

## Configuration

Add to your `~/.openclaw/openclaw.json`:

```json5
{
  "channels": {
    "relay": {
      "enabled": true,
      "secret": "your-secret-here",
      "path": "/relay",
      "responseMode": "sync",
      "timeoutMs": 120000
    }
  }
}
```

### Config Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable/disable the relay endpoint |
| `secret` | string | required | Shared secret for authentication |
| `path` | string | `/relay` | HTTP endpoint path |
| `responseMode` | string | `sync` | `sync` (wait for response) or `callback` (async) |
| `timeoutMs` | number | `120000` | Max wait time for agent response (sync mode) |

## API

### Health Check

```http
GET /relay/health
```

### Send Message

```http
POST /relay
Content-Type: application/json
X-Relay-Secret: your-secret-here

{
  "channel": "telegram",
  "chatId": "123456",
  "sender": "user123",
  "text": "Hello!",
  "messageId": "msg-001",
  "timestamp": 1707750000000
}
```

#### Request Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `channel` | string | yes | Source channel identifier |
| `chatId` | string | yes | Chat/conversation ID |
| `sender` | string | yes | Sender identifier |
| `text` | string | yes | Message text |
| `messageId` | string | no | Original message ID |
| `replyToId` | string | no | ID of message being replied to |
| `replyToText` | string | no | Text of quoted message |
| `timestamp` | number | no | Unix timestamp (ms) |
| `callbackUrl` | string | no | URL for async response delivery |
| `metadata` | object | no | Additional metadata |

#### Response (Sync Mode)

```json
{
  "ok": true,
  "reply": "Hi! How can I help?",
  "messageId": "relay-1707750001234"
}
```

#### Response (Callback Mode)

```json
{
  "ok": true,
  "status": "accepted",
  "sessionKey": "agent:main:telegram:dm:123456"
}
```

The response will be POSTed to `callbackUrl`.

## Security

- Always use HTTPS in production
- Use a strong, random secret
- Consider IP allowlisting for additional security

## License

MIT

integration