clawrelay 0.1.0 → 0.3.0

package/README.md

@@ -1,13 +1,14 @@
 # clawrelay
 
-OpenClaw channel plugin that receives forwarded messages from an always-on relay proxy (ClawRelay), dispatches them through the agent pipeline, and sends responses back over WebSocket.
+OpenClaw channel plugin that receives forwarded messages from an always-on relay proxy (ClawRelay), dispatches them through the agent pipeline, and sends responses back via the gateway protocol.
 
 ## How it works
 
-1. Plugin starts an HTTP + WebSocket server on a configurable port (default `7600`)
-2. The relay service connects via WebSocket at `/relay/ws` with Bearer token auth
-3. Inbound messages are dispatched through the OpenClaw agent pipeline
-4. Agent responses are sent back to the relay service over the same WebSocket connection
+1. Plugin registers a `relay.inbound` gateway method and a `/relay/health` HTTP route on the gateway's existing server
+2. The relay service connects to the gateway via WebSocket and authenticates using the gateway protocol
+3. Inbound messages arrive as `relay.inbound` method calls
+4. Messages are dispatched through the OpenClaw agent pipeline
+5. Agent responses are returned in the gateway method response
 
 ## Installation
 
@@ -27,7 +28,7 @@ Or install from a tarball:
 
 ```bash
 cd packages/relay-channel && npm pack
-openclaw plugins install clawrelay-0.1.0.tgz
+openclaw plugins install clawrelay-0.3.0.tgz
 ```
 
 ## Gateway configuration
@@ -40,8 +41,7 @@ Add to `~/.openclaw/openclaw.json`:
     "relay": {
       "accounts": {
         "default": {
-          "authToken": "shared-secret",
-          "port": 7600
+          "authToken": "optional-per-account-token"
         }
       }
     }
@@ -55,7 +55,7 @@ Add to `~/.openclaw/openclaw.json`:
 }
 ```
 
-The `authToken` must match the relay service's `SANDBOX_AUTH_TOKEN`.
+The gateway's own auth token (in `gateway.auth.token`) is used for authentication. The relay account `authToken` is an optional per-account verification token.
 
 ## Verify installation
 
@@ -67,18 +67,20 @@ openclaw plugins doctor
 
 ## Endpoints
 
-| Method | Path | Description |
+| Type | Path/Method | Description |
 |---|---|---|
-| GET | `/relay/health` | Health check — returns `{"status":"ok","ready":true}` |
-| WS | `/relay/ws` | WebSocket endpoint for relay communication (Bearer auth required) |
+| HTTP | `GET /relay/health` | Health check — returns `{"status":"ok","ready":true}` |
+| Gateway | `relay.inbound` | Gateway method for receiving relay messages |
 
 ## Source files
 
 | File | Purpose |
 |---|---|
-| `src/index.ts` | Plugin entry point and registration |
-| `src/channel.ts` | Channel definition, account lifecycle, inbound message handler |
-| `src/inbound-server.ts` | HTTP + WebSocket server |
+| `src/index.ts` | Plugin entry point, gateway method + HTTP route registration |
+| `src/channel.ts` | Channel definition, config resolution, onboarding |
+| `src/gateway-handler.ts` | `relay.inbound` gateway method handler |
+| `src/health-handler.ts` | HTTP health route handler |
+| `src/onboarding.ts` | Setup wizard (auth token, sprite service) |
 | `src/runtime.ts` | OpenClaw runtime accessor |
 | `src/types.ts` | Protocol and config types |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawrelay",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Channel relay plugin for OpenClaw — receives messages from an always-on relay proxy",
   "main": "src/index.ts",
   "type": "module",
@@ -38,9 +38,6 @@
   ],
   "author": "Snowy Road",
   "license": "MIT",
-  "dependencies": {
-    "ws": "^8.18.0"
-  },
   "devDependencies": {
     "typescript": "^5.3.0"
   },

package/src/channel.ts

@@ -1,14 +1,14 @@
 // Relay Channel Plugin Definition
+//
+// The relay channel no longer runs its own server. Inbound messages arrive via
+// the `relay.inbound` gateway method registered in index.ts. This file defines
+// the channel metadata, config resolution, and onboarding adapter.
 
-import type { RelayAccount, RelayInboundMessage, RelayOutboundMessage, ReplyFn } from './types.js';
-import { InboundServer } from './inbound-server.js';
-import { getRelayRuntime } from './runtime.js';
+import type { RelayAccount } from './types.js';
+import { relayOnboardingAdapter } from './onboarding.js';
 
 const CHANNEL_ID = 'relay' as const;
 
-// Store active inbound servers per account
-const servers = new Map<string, InboundServer>();
-
 export function createRelayChannel(api: any) {
   const logger = api.logger;
 
@@ -24,6 +24,8 @@ export function createRelayChannel(api: any) {
       aliases: ['relay'],
     },
 
+    onboarding: relayOnboardingAdapter,
+
     capabilities: {
       chatTypes: ['direct', 'group'],
       media: {
@@ -51,7 +53,6 @@ export function createRelayChannel(api: any) {
         return {
           accountId: id,
           authToken: account.authToken,
-          port: account.port ?? 7600,
           enabled: account.enabled !== false,
         };
       },
@@ -61,74 +62,12 @@ export function createRelayChannel(api: any) {
       startAccount: async (ctx: any) => {
         const account = ctx.account as RelayAccount;
         const accountId = account.accountId ?? 'default';
-
-        logger.info(`[clawrelay] startAccount called for ${accountId}`);
-
-        if (!account.enabled) {
-          logger.info(`[clawrelay] Account ${accountId} not enabled, skipping`);
-          return;
-        }
-
-        if (servers.has(accountId)) {
-          logger.warn(`[clawrelay] Server already running for ${accountId}, skipping`);
-          return;
-        }
-
-        const server = new InboundServer({
-          port: account.port,
-          authToken: account.authToken,
-          logger: ctx.log ?? logger,
-          onMessage: (message: RelayInboundMessage, reply: ReplyFn) => {
-            handleRelayInbound({
-              message,
-              reply,
-              account,
-              config: ctx.cfg,
-              log: ctx.log ?? logger,
-            }).catch((err) => {
-              const errMsg = err instanceof Error ? err.message : String(err);
-              (ctx.log ?? logger).error(`[clawrelay] Failed to process inbound: ${errMsg}`);
-              // Best-effort error response over WS
-              reply({
-                messageId: message.messageId,
-                content: `[Relay Plugin] Error processing message: ${errMsg}`,
-                replyToMessageId: message.messageId,
-              });
-            });
-          },
-        });
-
-        servers.set(accountId, server);
-
-        // Listen for abort signal
-        if (ctx.abortSignal) {
-          ctx.abortSignal.addEventListener('abort', () => {
-            (ctx.log ?? logger).info(`[clawrelay] Received abort signal for ${accountId}`);
-            const srv = servers.get(accountId);
-            if (srv) {
-              srv.stop();
-              servers.delete(accountId);
-            }
-          }, { once: true });
-        }
-
-        try {
-          await server.start();
-          (ctx.log ?? logger).info(`[clawrelay] Server started for ${accountId} on port ${account.port}`);
-        } catch (err) {
-          (ctx.log ?? logger).error(`[clawrelay] Failed to start server for ${accountId}: ${err}`);
-          servers.delete(accountId);
-        }
+        logger.info(`[clawrelay] Account ${accountId} started (relay.inbound via gateway)`);
       },
 
       stopAccount: async (ctx: any) => {
         const accountId = ctx.account?.accountId ?? 'default';
-        const server = servers.get(accountId);
-        if (server) {
-          await server.stop();
-          servers.delete(accountId);
-          (ctx.log ?? logger).info(`[clawrelay] Server stopped for ${accountId}`);
-        }
+        logger.info(`[clawrelay] Account ${accountId} stopped`);
       },
     },
 
@@ -146,149 +85,17 @@ export function createRelayChannel(api: any) {
         accountId?: string;
         cfg: any;
       }) => {
-        // Outbound via sendText is not the primary path for relay-channel.
-        // The main response path is via WebSocket reply.
-        // This exists for completeness if OpenClaw core needs to send proactively.
-        logger.warn(`[clawrelay] sendText called for chatId=${chatId} — relay-channel uses WS for responses`);
-        return { ok: false, error: 'Relay channel uses WebSocket for responses, not sendText' };
+        logger.warn(`[clawrelay] sendText called for chatId=${chatId} — relay-channel uses gateway method for responses`);
+        return { ok: false, error: 'Relay channel uses gateway method for responses, not sendText' };
       },
     },
 
     status: {
       getHealth: (accountId: string) => {
-        const server = servers.get(accountId);
-        if (!server) {
-          return { status: 'disconnected', message: 'Server not running' };
-        }
-        return { status: 'connected', message: 'Server listening (HTTP + WS)' };
+        return { status: 'connected', message: 'Listening via gateway method (relay.inbound)' };
       },
     },
   };
 
   return channel;
 }
-
-
-// --- Inbound message handler using OpenClaw runtime ---
-
-function resolveSessionKey(message: RelayInboundMessage): string {
-  if (message.chatType === 'direct') {
-    return `relay:${message.platform}:dm:${message.senderId}`;
-  }
-  return `relay:${message.platform}:${message.guildId ?? 'unknown'}:${message.channelId}`;
-}
-
-function resolvePeerId(message: RelayInboundMessage): string {
-  if (message.chatType === 'direct') {
-    return `relay:${message.platform}:dm:${message.senderId}`;
-  }
-  return `relay:${message.platform}:${message.guildId ?? 'unknown'}:${message.channelId}`;
-}
-
-async function handleRelayInbound(params: {
-  message: RelayInboundMessage;
-  reply: ReplyFn;
-  account: RelayAccount;
-  config: any;
-  log: any;
-}): Promise<void> {
-  const { message, reply, account, config, log } = params;
-
-  let core;
-  try {
-    core = getRelayRuntime();
-  } catch (err) {
-    log?.error(`[clawrelay] Runtime not initialized: ${err}`);
-    return;
-  }
-
-  const peerId = resolvePeerId(message);
-
-  // Resolve agent route
-  const route = core.channel.routing.resolveAgentRoute({
-    cfg: config,
-    channel: CHANNEL_ID,
-    accountId: account.accountId,
-    peer: {
-      kind: message.chatType === 'direct' ? 'direct' : 'group',
-      id: peerId,
-    },
-  });
-
-  // Resolve session store path
-  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
-    agentId: route.agentId,
-  });
-
-  // Format envelope
-  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
-  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
-    storePath,
-    sessionKey: route.sessionKey,
-  });
-
-  const fromLabel = `${message.platform}:${message.senderName}`;
-  const body = core.channel.reply.formatAgentEnvelope({
-    channel: `relay:${message.platform}`,
-    from: fromLabel,
-    timestamp: message.timestamp,
-    previousTimestamp,
-    envelope: envelopeOptions,
-    body: message.content,
-  });
-
-  // Build finalized message context
-  const ctxPayload = core.channel.reply.finalizeInboundContext({
-    Body: body,
-    BodyForAgent: body,
-    RawBody: message.content,
-    CommandBody: message.content,
-    From: peerId,
-    To: peerId,
-    SessionKey: route.sessionKey,
-    AccountId: route.accountId,
-    ChatType: message.chatType,
-    ConversationLabel: fromLabel,
-    SenderName: message.senderName,
-    SenderId: message.senderId,
-    GroupSubject: message.groupName ?? message.channelId,
-    Provider: CHANNEL_ID,
-    Surface: CHANNEL_ID,
-    Timestamp: message.timestamp,
-    OriginatingChannel: CHANNEL_ID,
-    OriginatingTo: peerId,
-  });
-
-  // Record inbound session
-  await core.channel.session.recordInboundSession({
-    storePath,
-    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
-    ctx: ctxPayload,
-    onRecordError: (err: unknown) => {
-      log?.error(`[clawrelay] Failed updating session meta: ${String(err)}`);
-    },
-  });
-
-  // Dispatch reply — triggers agent processing and delivers response via WS
-  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-    ctx: ctxPayload,
-    cfg: config,
-    dispatcherOptions: {
-      deliver: async (payload: { text?: string }) => {
-        const text = payload.text ?? '';
-        if (!text.trim()) return;
-
-        reply({
-          messageId: message.messageId,
-          content: text,
-          replyToMessageId: message.messageId,
-        });
-      },
-      onError: (err: unknown, info: { kind: string }) => {
-        log?.error(`[clawrelay] ${info.kind} reply failed: ${String(err)}`);
-      },
-    },
-  });
-
-  log?.info(`[clawrelay] Processed message ${message.messageId} from ${message.senderName}`);
-}

package/src/gateway-handler.ts

@@ -0,0 +1,204 @@
+// Gateway method handler for relay.inbound
+//
+// Registered as a gateway method so the relay service can call it via the
+// gateway WS protocol instead of needing a standalone HTTP+WS server.
+
+import type { RelayAccount, RelayInboundMessage } from './types.js';
+import { getRelayRuntime } from './runtime.js';
+
+const CHANNEL_ID = 'relay' as const;
+
+/**
+ * Creates the `relay.inbound` gateway method handler.
+ * The handler receives params `{ accountId?, message }`, processes the message
+ * through the agent pipeline, and responds with the agent's reply.
+ */
+export function createRelayInboundHandler(api: any) {
+  const logger = api.logger;
+
+  return async (opts: {
+    req: any;
+    params: Record<string, unknown>;
+    client: any;
+    respond: (ok: boolean, payload?: unknown, error?: unknown) => void;
+    context: any;
+  }) => {
+    const { params, respond } = opts;
+
+    const message = params.message as RelayInboundMessage | undefined;
+    if (!message || !message.messageId || !message.content) {
+      respond(false, undefined, {
+        code: 'INVALID_PARAMS',
+        message: 'Missing or invalid "message" in params',
+      });
+      return;
+    }
+
+    // Resolve the account — use accountId from params or fall back to default
+    const accountId = (params.accountId as string) ?? 'default';
+    const config = api.runtime.config.load();
+    const accounts = config.channels?.relay?.accounts ?? {};
+    const accountData = accounts[accountId] ?? config.channels?.relay;
+
+    if (!accountData) {
+      respond(false, undefined, {
+        code: 'NOT_FOUND',
+        message: `Relay account "${accountId}" not configured`,
+      });
+      return;
+    }
+
+    const account: RelayAccount = {
+      accountId,
+      authToken: accountData.authToken ?? '',
+      enabled: accountData.enabled !== false,
+    };
+
+    if (!account.enabled) {
+      respond(false, undefined, {
+        code: 'UNAVAILABLE',
+        message: `Relay account "${accountId}" is not enabled`,
+      });
+      return;
+    }
+
+    try {
+      const responseContent = await processRelayMessage({
+        message,
+        account,
+        config,
+        log: logger,
+      });
+
+      respond(true, {
+        messageId: message.messageId,
+        content: responseContent,
+        replyToMessageId: message.messageId,
+      });
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      logger.error(`[clawrelay] Failed to process inbound: ${errMsg}`);
+      respond(false, undefined, {
+        code: 'INTERNAL_ERROR',
+        message: `Error processing message: ${errMsg}`,
+      });
+    }
+  };
+}
+
+
+// --- Inbound message processing (extracted from channel.ts) ---
+
+function resolveSessionKey(message: RelayInboundMessage): string {
+  if (message.chatType === 'direct') {
+    return `relay:${message.platform}:dm:${message.senderId}`;
+  }
+  return `relay:${message.platform}:${message.guildId ?? 'unknown'}:${message.channelId}`;
+}
+
+function resolvePeerId(message: RelayInboundMessage): string {
+  if (message.chatType === 'direct') {
+    return `relay:${message.platform}:dm:${message.senderId}`;
+  }
+  return `relay:${message.platform}:${message.guildId ?? 'unknown'}:${message.channelId}`;
+}
+
+async function processRelayMessage(params: {
+  message: RelayInboundMessage;
+  account: RelayAccount;
+  config: any;
+  log: any;
+}): Promise<string> {
+  const { message, account, config, log } = params;
+
+  const core = getRelayRuntime();
+  const peerId = resolvePeerId(message);
+
+  // Resolve agent route
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+    peer: {
+      kind: message.chatType === 'direct' ? 'direct' : 'group',
+      id: peerId,
+    },
+  });
+
+  // Resolve session store path
+  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+    agentId: route.agentId,
+  });
+
+  // Format envelope
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+
+  const fromLabel = `${message.platform}:${message.senderName}`;
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: `relay:${message.platform}`,
+    from: fromLabel,
+    timestamp: message.timestamp,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: message.content,
+  });
+
+  // Build finalized message context
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    BodyForAgent: body,
+    RawBody: message.content,
+    CommandBody: message.content,
+    From: peerId,
+    To: peerId,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: message.chatType,
+    ConversationLabel: fromLabel,
+    SenderName: message.senderName,
+    SenderId: message.senderId,
+    GroupSubject: message.groupName ?? message.channelId,
+    Provider: CHANNEL_ID,
+    Surface: CHANNEL_ID,
+    Timestamp: message.timestamp,
+    OriginatingChannel: CHANNEL_ID,
+    OriginatingTo: peerId,
+  });
+
+  // Record inbound session
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err: unknown) => {
+      log?.error(`[clawrelay] Failed updating session meta: ${String(err)}`);
+    },
+  });
+
+  // Dispatch reply — collect all deliver() calls into a single buffer
+  const parts: string[] = [];
+
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: config,
+    dispatcherOptions: {
+      deliver: async (payload: { text?: string }) => {
+        const text = payload.text ?? '';
+        if (text.trim()) {
+          parts.push(text);
+        }
+      },
+      onError: (err: unknown, info: { kind: string }) => {
+        log?.error(`[clawrelay] ${info.kind} reply failed: ${String(err)}`);
+      },
+    },
+  });
+
+  log?.info(`[clawrelay] Processed message ${message.messageId} from ${message.senderName}`);
+
+  return parts.join('\n');
+}

package/src/health-handler.ts

@@ -0,0 +1,10 @@
+// HTTP health route handler for /relay/health
+//
+// Registered on the gateway's HTTP server via api.registerHttpRoute.
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+export function relayHealthHandler(_req: IncomingMessage, res: ServerResponse): void {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ status: 'ok', ready: true }));
+}

package/src/index.ts

@@ -2,11 +2,17 @@
 //
 // Receives forwarded messages from an always-on relay service and processes
 // them through the standard OpenClaw channel pipeline.
+//
+// Instead of running a standalone HTTP+WS server, this plugin registers a
+// gateway method (`relay.inbound`) and an HTTP health route (`/relay/health`)
+// on the gateway's existing server.
 
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { createRelayChannel } from './channel.js';
 import { setRelayRuntime } from './runtime.js';
+import { createRelayInboundHandler } from './gateway-handler.js';
+import { relayHealthHandler } from './health-handler.js';
 
 const plugin = {
   id: 'clawrelay',
@@ -26,7 +32,14 @@ const plugin = {
     const channel = createRelayChannel(api);
     api.registerChannel({ plugin: channel });
 
-    logger.info('[clawrelay] Relay channel plugin registered');
+    // Register gateway method for relay.inbound calls
+    const relayInboundHandler = createRelayInboundHandler(api);
+    api.registerGatewayMethod('relay.inbound', relayInboundHandler);
+
+    // Register HTTP health route on the gateway's HTTP server
+    api.registerHttpRoute({ path: '/relay/health', handler: relayHealthHandler });
+
+    logger.info('[clawrelay] Relay channel plugin registered (gateway method + HTTP health)');
   },
 };
 

package/src/onboarding.ts

@@ -0,0 +1,271 @@
+import type {
+  ChannelOnboardingAdapter,
+  OpenClawConfig,
+  WizardPrompter,
+} from "openclaw/plugin-sdk";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  promptAccountId,
+} from "openclaw/plugin-sdk";
+import crypto from "node:crypto";
+import { execSync } from "node:child_process";
+
+const channel = "relay" as const;
+
+function generateAuthToken(): string {
+  const bytes = crypto.randomBytes(24);
+  return `crly_${bytes.toString("base64url")}`;
+}
+
+function setRelayAccountConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+  defaultPatch: Record<string, unknown>,
+  accountPatch: Record<string, unknown> = defaultPatch,
+): OpenClawConfig {
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        relay: {
+          ...cfg.channels?.relay,
+          enabled: true,
+          ...defaultPatch,
+        },
+      },
+    } as OpenClawConfig;
+  }
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      relay: {
+        ...cfg.channels?.relay,
+        enabled: true,
+        accounts: {
+          ...cfg.channels?.relay?.accounts,
+          [accountId]: {
+            ...cfg.channels?.relay?.accounts?.[accountId],
+            enabled: cfg.channels?.relay?.accounts?.[accountId]?.enabled ?? true,
+            ...accountPatch,
+          },
+        },
+      },
+    },
+  } as OpenClawConfig;
+}
+
+function listRelayAccountIds(cfg: OpenClawConfig): string[] {
+  return Object.keys((cfg.channels as any)?.relay?.accounts ?? {});
+}
+
+function resolveDefaultRelayAccountId(cfg: OpenClawConfig): string {
+  const ids = listRelayAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function getExistingToken(cfg: OpenClawConfig, accountId: string): string | undefined {
+  const relay = (cfg.channels as any)?.relay;
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return relay?.authToken;
+  }
+  return relay?.accounts?.[accountId]?.authToken;
+}
+
+function isSpriteEnv(): boolean {
+  try {
+    execSync('which sprite-env', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function setupSpriteService(prompter: WizardPrompter): Promise<void> {
+  if (!isSpriteEnv()) return;
+
+  const setup = await prompter.confirm({
+    message: 'Sprite environment detected. Set up service to expose the gateway?',
+    initialValue: true,
+  });
+  if (!setup) return;
+
+  try {
+    // Check if a service already exists
+    const existing = execSync('sprite-env services list', { encoding: 'utf-8' });
+    if (existing.includes('openclaw')) {
+      await prompter.note(
+        'An openclaw service already exists on this sprite.',
+        'Sprite Service',
+      );
+    } else {
+      execSync('sprite-env services create openclaw-gateway --cmd openclaw --args start --http-port 18789');
+      await prompter.note(
+        'Created sprite service: openclaw-gateway (port 18789)',
+        'Sprite Service',
+      );
+    }
+
+    // Check URL auth
+    const setPublic = await prompter.confirm({
+      message: 'Set sprite URL auth to public? (required for relay to connect without org token)',
+      initialValue: true,
+    });
+    if (setPublic) {
+      execSync('sprite url update --auth public');
+    }
+  } catch (err) {
+    await prompter.note(
+      `Failed to configure sprite service: ${err}\nYou can set it up manually later.`,
+      'Sprite Service',
+    );
+  }
+}
+
+export const relayOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+
+  getStatus: async ({ cfg }) => {
+    const ids = listRelayAccountIds(cfg);
+    const relay = (cfg.channels as any)?.relay;
+
+    // Check default account (top-level authToken) or any named account
+    let configured = Boolean(relay?.authToken);
+    if (!configured) {
+      for (const id of ids) {
+        if (relay?.accounts?.[id]?.authToken) {
+          configured = true;
+          break;
+        }
+      }
+    }
+
+    return {
+      channel,
+      configured,
+      statusLines: [
+        `Channel Relay: ${configured ? "configured" : "needs setup"}`,
+      ],
+      selectionHint: configured
+        ? "configured"
+        : "proxy for Discord/Telegram",
+      quickstartScore: configured ? 1 : 20,
+    };
+  },
+
+  configure: async ({
+    cfg,
+    prompter,
+    accountOverrides,
+    shouldPromptAccountIds,
+  }) => {
+    await prompter.note(
+      [
+        "ClawRelay bridges Discord/Telegram to OpenClaw via a",
+        "lightweight always-on relay service. This wizard configures",
+        "the channel plugin side (auth token).",
+        "",
+        "The relay service connects to the OpenClaw gateway via WS",
+        "and calls the relay.inbound method. No separate port needed.",
+        "",
+        "You'll deploy the relay service separately afterwards.",
+      ].join("\n"),
+      "Channel Relay Setup",
+    );
+
+    // --- Account ID ---
+    const relayOverride = (accountOverrides as any).relay?.trim();
+    const defaultAccountId = resolveDefaultRelayAccountId(cfg);
+    let accountId = relayOverride
+      ? normalizeAccountId(relayOverride)
+      : defaultAccountId;
+
+    if (shouldPromptAccountIds && !relayOverride) {
+      accountId = await promptAccountId({
+        cfg,
+        prompter,
+        label: "Channel Relay",
+        currentId: accountId,
+        listAccountIds: listRelayAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    let next = cfg;
+
+    // --- Auth Token (optional per-account verification token) ---
+    const existingToken = getExistingToken(next, accountId);
+    let authToken: string;
+
+    if (existingToken) {
+      const keepToken = await prompter.confirm({
+        message: `Auth token already set (${existingToken.slice(0, 12)}...). Keep it?`,
+        initialValue: true,
+      });
+      if (keepToken) {
+        authToken = existingToken;
+      } else {
+        authToken = await promptAuthToken(prompter);
+      }
+    } else {
+      authToken = await promptAuthToken(prompter);
+    }
+
+    // --- Write config ---
+    next = setRelayAccountConfig(next, accountId, {
+      authToken,
+    });
+
+    // --- Sprite service setup ---
+    await setupSpriteService(prompter);
+
+    // --- Next steps ---
+    await prompter.note(
+      [
+        "Plugin configured! Now deploy the relay service.",
+        "",
+        "The relay connects to your OpenClaw gateway via WebSocket.",
+        "",
+        "Required env vars for the relay service:",
+        `  DISCORD_TOKEN=<your-bot-token>`,
+        `  GATEWAY_URL=<your-sprite-or-gateway-url>`,
+        `  GATEWAY_AUTH_TOKEN=<gateway-auth-token-from-openclaw-config>`,
+        "",
+        "The gateway auth token is in your OpenClaw config under",
+        "gateway.auth.token (not the relay auth token above).",
+        "",
+        "Quick start:",
+        `  docker run -e DISCORD_TOKEN=... -e GATEWAY_URL=https://my-sprite.sprites.dev -e GATEWAY_AUTH_TOKEN=... ghcr.io/kylemclaren/clawrelay:latest`,
+        "",
+        "Docs: https://github.com/kylemclaren/clawrelay",
+      ].join("\n"),
+      "Next Steps",
+    );
+
+    return { cfg: next, accountId };
+  },
+};
+
+async function promptAuthToken(prompter: WizardPrompter): Promise<string> {
+  const generated = generateAuthToken();
+  const useGenerated = await prompter.confirm({
+    message: `Use auto-generated token? (${generated})`,
+    initialValue: true,
+  });
+
+  if (useGenerated) {
+    return generated;
+  }
+
+  const custom = await prompter.text({
+    message: "Enter your auth token",
+    validate: (value) =>
+      String(value ?? "").trim().length >= 8
+        ? undefined
+        : "Token must be at least 8 characters",
+  });
+  return String(custom).trim();
+}

package/src/types.ts

@@ -3,7 +3,6 @@
 export interface RelayAccount {
   accountId: string;
   authToken: string;
-  port: number;
   enabled?: boolean;
 }
 
@@ -27,11 +26,3 @@ export interface RelayOutboundMessage {
   content: string;
   replyToMessageId?: string;
 }
-
-// WebSocket protocol envelope
-export type WsEnvelope =
-  | { type: 'message'; payload: RelayInboundMessage }
-  | { type: 'response'; payload: RelayOutboundMessage };
-
-// Reply function passed to message handlers
-export type ReplyFn = (response: RelayOutboundMessage) => void;

package/src/inbound-server.ts

@@ -1,144 +0,0 @@
-// Relay Server - HTTP health + WebSocket server for relay communication
-
-import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http';
-import { WebSocketServer, WebSocket } from 'ws';
-import type { RelayInboundMessage, RelayOutboundMessage, WsEnvelope, ReplyFn } from './types.js';
-
-export interface InboundServerOptions {
-  port: number;
-  authToken: string;
-  onMessage: (message: RelayInboundMessage, reply: ReplyFn) => void;
-  logger?: any;
-}
-
-export class InboundServer {
-  private server: Server | null = null;
-  private wss: WebSocketServer | null = null;
-  private options: InboundServerOptions;
-
-  constructor(options: InboundServerOptions) {
-    this.options = options;
-  }
-
-  start(): Promise<void> {
-    return new Promise((resolve, reject) => {
-      const server = createServer((req, res) => this.handleRequest(req, res));
-
-      // Create WebSocket server attached to the HTTP server
-      const wss = new WebSocketServer({ noServer: true });
-
-      wss.on('connection', (ws) => {
-        this.options.logger?.info('[clawrelay] WebSocket client connected');
-
-        ws.on('message', (data) => {
-          try {
-            const envelope: WsEnvelope = JSON.parse(data.toString());
-
-            if (envelope.type === 'message') {
-              const message = envelope.payload as RelayInboundMessage;
-
-              if (!message.messageId || !message.content) {
-                this.options.logger?.warn('[clawrelay] WS message missing required fields');
-                return;
-              }
-
-              // Create reply function that sends response back over this WS connection
-              const reply: ReplyFn = (response: RelayOutboundMessage) => {
-                if (ws.readyState === WebSocket.OPEN) {
-                  const responseEnvelope: WsEnvelope = { type: 'response', payload: response };
-                  ws.send(JSON.stringify(responseEnvelope));
-                } else {
-                  this.options.logger?.error(`[clawrelay] Cannot reply — WS not open (state=${ws.readyState})`);
-                }
-              };
-
-              this.options.onMessage(message, reply);
-            } else {
-              this.options.logger?.warn(`[clawrelay] Unexpected WS message type: ${(envelope as any).type}`);
-            }
-          } catch (err) {
-            this.options.logger?.error(`[clawrelay] Failed to parse WS message: ${err}`);
-          }
-        });
-
-        ws.on('close', (code, reason) => {
-          this.options.logger?.info(`[clawrelay] WebSocket client disconnected: ${code} ${reason.toString()}`);
-        });
-
-        ws.on('error', (err) => {
-          this.options.logger?.error(`[clawrelay] WebSocket error: ${err.message}`);
-        });
-      });
-
-      // Handle HTTP upgrade for WebSocket connections
-      server.on('upgrade', (req, socket, head) => {
-        const url = req.url ?? '';
-
-        if (url !== '/relay/ws') {
-          socket.destroy();
-          return;
-        }
-
-        // Verify auth token
-        const authHeader = req.headers['authorization'];
-        const expected = `Bearer ${this.options.authToken}`;
-        if (authHeader !== expected) {
-          this.options.logger?.warn('[clawrelay] WS upgrade rejected: invalid auth');
-          socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
-          socket.destroy();
-          return;
-        }
-
-        wss.handleUpgrade(req, socket, head, (ws) => {
-          wss.emit('connection', ws, req);
-        });
-      });
-
-      server.on('error', reject);
-      server.listen(this.options.port, () => {
-        this.server = server;
-        this.wss = wss;
-        this.options.logger?.info(`[clawrelay] Server listening on port ${this.options.port} (HTTP + WS)`);
-        resolve();
-      });
-    });
-  }
-
-  stop(): Promise<void> {
-    return new Promise((resolve) => {
-      // Close all WebSocket connections
-      if (this.wss) {
-        for (const client of this.wss.clients) {
-          client.close();
-        }
-        this.wss.close();
-        this.wss = null;
-      }
-
-      if (!this.server) {
-        resolve();
-        return;
-      }
-      this.server.close(() => {
-        this.server = null;
-        this.options.logger?.info('[clawrelay] Server stopped');
-        resolve();
-      });
-    });
-  }
-
-  private handleRequest(req: IncomingMessage, res: ServerResponse) {
-    if (req.method === 'GET' && req.url === '/relay/health') {
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({
-        status: 'ok',
-        ready: true,
-        wsClients: this.wss?.clients.size ?? 0,
-      }));
-      return;
-    }
-
-    res.writeHead(404, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ error: 'Not found' }));
-  }
-}