feat: add openclaw_gateway adapter

New adapter type for invoking OpenClaw agents via the gateway protocol.
Registers in server, CLI, and UI adapter registries. Adds onboarding
wizard support with gateway URL field and e2e smoke test script.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

packages/adapters/openclaw-gateway/src/cli/format-event.ts

@@ -0,0 +1,23 @@
+import pc from "picocolors";
+
+export function printOpenClawGatewayStreamEvent(raw: string, debug: boolean): void {
+  const line = raw.trim();
+  if (!line) return;
+
+  if (!debug) {
+    console.log(line);
+    return;
+  }
+
+  if (line.startsWith("[openclaw-gateway:event]")) {
+    console.log(pc.cyan(line));
+    return;
+  }
+
+  if (line.startsWith("[openclaw-gateway]")) {
+    console.log(pc.blue(line));
+    return;
+  }
+
+  console.log(pc.gray(line));
+}

packages/adapters/openclaw-gateway/src/cli/index.ts

@@ -0,0 +1 @@
+export { printOpenClawGatewayStreamEvent } from "./format-event.js";

packages/adapters/openclaw-gateway/src/index.ts

@@ -0,0 +1,41 @@
+export const type = "openclaw_gateway";
+export const label = "OpenClaw Gateway";
+
+export const models: { id: string; label: string }[] = [];
+
+export const agentConfigurationDoc = `# openclaw_gateway agent configuration
+
+Adapter: openclaw_gateway
+
+Use when:
+- You want Paperclip to invoke OpenClaw over the Gateway WebSocket protocol.
+- You want native gateway auth/connect semantics instead of HTTP /v1/responses or /hooks/*.
+
+Don't use when:
+- You only expose OpenClaw HTTP endpoints (use openclaw adapter with sse/webhook transport).
+- Your deployment does not permit outbound WebSocket access from the Paperclip server.
+
+Core fields:
+- url (string, required): OpenClaw gateway WebSocket URL (ws:// or wss://)
+- headers (object, optional): handshake headers; supports x-openclaw-token / x-openclaw-auth
+- authToken (string, optional): shared gateway token override
+- password (string, optional): gateway shared password, if configured
+
+Gateway connect identity fields:
+- clientId (string, optional): gateway client id (default gateway-client)
+- clientMode (string, optional): gateway client mode (default backend)
+- clientVersion (string, optional): client version string
+- role (string, optional): gateway role (default operator)
+- scopes (string[] | comma string, optional): gateway scopes (default ["operator.admin"])
+- disableDeviceAuth (boolean, optional): disable signed device payload in connect params (default false)
+
+Request behavior fields:
+- payloadTemplate (object, optional): additional fields merged into gateway agent params
+- timeoutSec (number, optional): adapter timeout in seconds (default 120)
+- waitTimeoutMs (number, optional): agent.wait timeout override (default timeoutSec * 1000)
+- paperclipApiUrl (string, optional): absolute Paperclip base URL advertised in wake text
+
+Session routing fields:
+- sessionKeyStrategy (string, optional): fixed (default), issue, or run
+- sessionKey (string, optional): fixed session key when strategy=fixed (default paperclip)
+`;

packages/adapters/openclaw-gateway/src/server/index.ts

@@ -0,0 +1,2 @@
+export { execute } from "./execute.js";
+export { testEnvironment } from "./test.js";

packages/adapters/openclaw-gateway/src/server/test.ts

@@ -0,0 +1,317 @@
+import type {
+  AdapterEnvironmentCheck,
+  AdapterEnvironmentTestContext,
+  AdapterEnvironmentTestResult,
+} from "@paperclipai/adapter-utils";
+import { asString, parseObject } from "@paperclipai/adapter-utils/server-utils";
+import { randomUUID } from "node:crypto";
+import { WebSocket } from "ws";
+
+function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
+  if (checks.some((check) => check.level === "error")) return "fail";
+  if (checks.some((check) => check.level === "warn")) return "warn";
+  return "pass";
+}
+
+function nonEmpty(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  const value = hostname.trim().toLowerCase();
+  return value === "localhost" || value === "127.0.0.1" || value === "::1";
+}
+
+function toStringRecord(value: unknown): Record<string, string> {
+  const parsed = parseObject(value);
+  const out: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(parsed)) {
+    if (typeof entry === "string") out[key] = entry;
+  }
+  return out;
+}
+
+function toStringArray(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value
+      .filter((entry): entry is string => typeof entry === "string")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+function headerMapGetIgnoreCase(headers: Record<string, string>, key: string): string | null {
+  const match = Object.entries(headers).find(([entryKey]) => entryKey.toLowerCase() === key.toLowerCase());
+  return match ? match[1] : null;
+}
+
+function tokenFromAuthHeader(rawHeader: string | null): string | null {
+  if (!rawHeader) return null;
+  const trimmed = rawHeader.trim();
+  if (!trimmed) return null;
+  const match = trimmed.match(/^bearer\s+(.+)$/i);
+  return match ? nonEmpty(match[1]) : trimmed;
+}
+
+function resolveAuthToken(config: Record<string, unknown>, headers: Record<string, string>): string | null {
+  const explicit = nonEmpty(config.authToken) ?? nonEmpty(config.token);
+  if (explicit) return explicit;
+
+  const tokenHeader = headerMapGetIgnoreCase(headers, "x-openclaw-token");
+  if (nonEmpty(tokenHeader)) return nonEmpty(tokenHeader);
+
+  const authHeader =
+    headerMapGetIgnoreCase(headers, "x-openclaw-auth") ??
+    headerMapGetIgnoreCase(headers, "authorization");
+  return tokenFromAuthHeader(authHeader);
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function rawDataToString(data: unknown): string {
+  if (typeof data === "string") return data;
+  if (Buffer.isBuffer(data)) return data.toString("utf8");
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString("utf8");
+  if (Array.isArray(data)) {
+    return Buffer.concat(
+      data.map((entry) => (Buffer.isBuffer(entry) ? entry : Buffer.from(String(entry), "utf8"))),
+    ).toString("utf8");
+  }
+  return String(data ?? "");
+}
+
+async function probeGateway(input: {
+  url: string;
+  headers: Record<string, string>;
+  authToken: string | null;
+  role: string;
+  scopes: string[];
+  timeoutMs: number;
+}): Promise<"ok" | "challenge_only" | "failed"> {
+  return await new Promise((resolve) => {
+    const ws = new WebSocket(input.url, { headers: input.headers, maxPayload: 2 * 1024 * 1024 });
+    const timeout = setTimeout(() => {
+      try {
+        ws.close();
+      } catch {
+        // ignore
+      }
+      resolve("failed");
+    }, input.timeoutMs);
+
+    let completed = false;
+
+    const finish = (status: "ok" | "challenge_only" | "failed") => {
+      if (completed) return;
+      completed = true;
+      clearTimeout(timeout);
+      try {
+        ws.close();
+      } catch {
+        // ignore
+      }
+      resolve(status);
+    };
+
+    ws.on("message", (raw) => {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(rawDataToString(raw));
+      } catch {
+        return;
+      }
+      const event = asRecord(parsed);
+      if (event?.type === "event" && event.event === "connect.challenge") {
+        const nonce = nonEmpty(asRecord(event.payload)?.nonce);
+        if (!nonce) {
+          finish("failed");
+          return;
+        }
+
+        const connectId = randomUUID();
+        ws.send(
+          JSON.stringify({
+            type: "req",
+            id: connectId,
+            method: "connect",
+            params: {
+              minProtocol: 3,
+              maxProtocol: 3,
+              client: {
+                id: "gateway-client",
+                version: "paperclip-probe",
+                platform: process.platform,
+                mode: "probe",
+              },
+              role: input.role,
+              scopes: input.scopes,
+              ...(input.authToken
+                ? {
+                    auth: {
+                      token: input.authToken,
+                    },
+                  }
+                : {}),
+            },
+          }),
+        );
+        return;
+      }
+
+      if (event?.type === "res") {
+        if (event.ok === true) {
+          finish("ok");
+        } else {
+          finish("challenge_only");
+        }
+      }
+    });
+
+    ws.on("error", () => {
+      finish("failed");
+    });
+
+    ws.on("close", () => {
+      if (!completed) finish("failed");
+    });
+  });
+}
+
+export async function testEnvironment(
+  ctx: AdapterEnvironmentTestContext,
+): Promise<AdapterEnvironmentTestResult> {
+  const checks: AdapterEnvironmentCheck[] = [];
+  const config = parseObject(ctx.config);
+  const urlValue = asString(config.url, "").trim();
+
+  if (!urlValue) {
+    checks.push({
+      code: "openclaw_gateway_url_missing",
+      level: "error",
+      message: "OpenClaw gateway adapter requires a WebSocket URL.",
+      hint: "Set adapterConfig.url to ws://host:port (or wss://).",
+    });
+    return {
+      adapterType: ctx.adapterType,
+      status: summarizeStatus(checks),
+      checks,
+      testedAt: new Date().toISOString(),
+    };
+  }
+
+  let url: URL | null = null;
+  try {
+    url = new URL(urlValue);
+  } catch {
+    checks.push({
+      code: "openclaw_gateway_url_invalid",
+      level: "error",
+      message: `Invalid URL: ${urlValue}`,
+    });
+  }
+
+  if (url && url.protocol !== "ws:" && url.protocol !== "wss:") {
+    checks.push({
+      code: "openclaw_gateway_url_protocol_invalid",
+      level: "error",
+      message: `Unsupported URL protocol: ${url.protocol}`,
+      hint: "Use ws:// or wss://.",
+    });
+  }
+
+  if (url) {
+    checks.push({
+      code: "openclaw_gateway_url_valid",
+      level: "info",
+      message: `Configured gateway URL: ${url.toString()}`,
+    });
+
+    if (url.protocol === "ws:" && !isLoopbackHost(url.hostname)) {
+      checks.push({
+        code: "openclaw_gateway_plaintext_remote_ws",
+        level: "warn",
+        message: "Gateway URL uses plaintext ws:// on a non-loopback host.",
+        hint: "Prefer wss:// for remote gateways.",
+      });
+    }
+  }
+
+  const headers = toStringRecord(config.headers);
+  const authToken = resolveAuthToken(config, headers);
+  const password = nonEmpty(config.password);
+  const role = nonEmpty(config.role) ?? "operator";
+  const scopes = toStringArray(config.scopes);
+
+  if (authToken || password) {
+    checks.push({
+      code: "openclaw_gateway_auth_present",
+      level: "info",
+      message: "Gateway credentials are configured.",
+    });
+  } else {
+    checks.push({
+      code: "openclaw_gateway_auth_missing",
+      level: "warn",
+      message: "No gateway credentials detected in adapter config.",
+      hint: "Set authToken/password or headers.x-openclaw-token for authenticated gateways.",
+    });
+  }
+
+  if (url && (url.protocol === "ws:" || url.protocol === "wss:")) {
+    try {
+      const probeResult = await probeGateway({
+        url: url.toString(),
+        headers,
+        authToken,
+        role,
+        scopes: scopes.length > 0 ? scopes : ["operator.admin"],
+        timeoutMs: 3_000,
+      });
+
+      if (probeResult === "ok") {
+        checks.push({
+          code: "openclaw_gateway_probe_ok",
+          level: "info",
+          message: "Gateway connect probe succeeded.",
+        });
+      } else if (probeResult === "challenge_only") {
+        checks.push({
+          code: "openclaw_gateway_probe_challenge_only",
+          level: "warn",
+          message: "Gateway challenge was received, but connect probe was rejected.",
+          hint: "Check gateway credentials, scopes, role, and device-auth requirements.",
+        });
+      } else {
+        checks.push({
+          code: "openclaw_gateway_probe_failed",
+          level: "warn",
+          message: "Gateway probe failed.",
+          hint: "Verify network reachability and gateway URL from the Paperclip server host.",
+        });
+      }
+    } catch (err) {
+      checks.push({
+        code: "openclaw_gateway_probe_error",
+        level: "warn",
+        message: err instanceof Error ? err.message : "Gateway probe failed",
+      });
+    }
+  }
+
+  return {
+    adapterType: ctx.adapterType,
+    status: summarizeStatus(checks),
+    checks,
+    testedAt: new Date().toISOString(),
+  };
+}

packages/adapters/openclaw-gateway/src/shared/stream.ts

@@ -0,0 +1,16 @@
+export function normalizeOpenClawGatewayStreamLine(rawLine: string): {
+  stream: "stdout" | "stderr" | null;
+  line: string;
+} {
+  const trimmed = rawLine.trim();
+  if (!trimmed) return { stream: null, line: "" };
+
+  const prefixed = trimmed.match(/^(stdout|stderr)\s*[:=]?\s*(.*)$/i);
+  if (!prefixed) {
+    return { stream: null, line: trimmed };
+  }
+
+  const stream = prefixed[1]?.toLowerCase() === "stderr" ? "stderr" : "stdout";
+  const line = (prefixed[2] ?? "").trim();
+  return { stream, line };
+}

packages/adapters/openclaw-gateway/src/ui/build-config.ts

@@ -0,0 +1,13 @@
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+
+export function buildOpenClawGatewayConfig(v: CreateConfigValues): Record<string, unknown> {
+  const ac: Record<string, unknown> = {};
+  if (v.url) ac.url = v.url;
+  ac.timeoutSec = 120;
+  ac.waitTimeoutMs = 120000;
+  ac.sessionKeyStrategy = "fixed";
+  ac.sessionKey = "paperclip";
+  ac.role = "operator";
+  ac.scopes = ["operator.admin"];
+  return ac;
+}

packages/adapters/openclaw-gateway/src/ui/index.ts

@@ -0,0 +1,2 @@
+export { parseOpenClawGatewayStdoutLine } from "./parse-stdout.js";
+export { buildOpenClawGatewayConfig } from "./build-config.js";

packages/adapters/openclaw-gateway/src/ui/parse-stdout.ts

@@ -0,0 +1,75 @@
+import type { TranscriptEntry } from "@paperclipai/adapter-utils";
+import { normalizeOpenClawGatewayStreamLine } from "../shared/stream.js";
+
+function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function parseAgentEventLine(line: string, ts: string): TranscriptEntry[] {
+  const match = line.match(/^\[openclaw-gateway:event\]\s+run=([^\s]+)\s+stream=([^\s]+)\s+data=(.*)$/s);
+  if (!match) return [{ kind: "stdout", ts, text: line }];
+
+  const stream = asString(match[2]).toLowerCase();
+  const data = asRecord(safeJsonParse(asString(match[3]).trim()));
+
+  if (stream === "assistant") {
+    const delta = asString(data?.delta);
+    if (delta.length > 0) {
+      return [{ kind: "assistant", ts, text: delta, delta: true }];
+    }
+
+    const text = asString(data?.text);
+    if (text.length > 0) {
+      return [{ kind: "assistant", ts, text }];
+    }
+    return [];
+  }
+
+  if (stream === "error") {
+    const message = asString(data?.error) || asString(data?.message);
+    return message ? [{ kind: "stderr", ts, text: message }] : [];
+  }
+
+  if (stream === "lifecycle") {
+    const phase = asString(data?.phase).toLowerCase();
+    const message = asString(data?.error) || asString(data?.message);
+    if ((phase === "error" || phase === "failed" || phase === "cancelled") && message) {
+      return [{ kind: "stderr", ts, text: message }];
+    }
+  }
+
+  return [];
+}
+
+export function parseOpenClawGatewayStdoutLine(line: string, ts: string): TranscriptEntry[] {
+  const normalized = normalizeOpenClawGatewayStreamLine(line);
+  if (normalized.stream === "stderr") {
+    return [{ kind: "stderr", ts, text: normalized.line }];
+  }
+
+  const trimmed = normalized.line.trim();
+  if (!trimmed) return [];
+
+  if (trimmed.startsWith("[openclaw-gateway:event]")) {
+    return parseAgentEventLine(trimmed, ts);
+  }
+
+  if (trimmed.startsWith("[openclaw-gateway]")) {
+    return [{ kind: "system", ts, text: trimmed.replace(/^\[openclaw-gateway\]\s*/, "") }];
+  }
+
+  return [{ kind: "stdout", ts, text: normalized.line }];
+}