mateclaw-openclaw-plugin 0.1.0

package/src/cli.mjs

@@ -0,0 +1,2257 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { URL } from 'node:url';
+import qrcode from 'qrcode-terminal';
+import { WebSocket } from 'ws';
+
+const DEFAULT_OPENCLAW_URL = 'http://127.0.0.1:18789';
+const DEFAULT_CHAT_PATH = '/v1/chat/completions';
+const DEFAULT_CHAT_MODE = 'gateway-session';
+const DEFAULT_SESSION_KEY = 'agent:main:main';
+const CHAT_PATH_FALLBACKS = [
+  '/v1/chat/completions',
+  '/api/v1/chat/completions',
+  '/chat/completions',
+  '/v1/responses',
+];
+const DEFAULT_LISTEN_HOST = '0.0.0.0';
+const DEFAULT_PORT = 18890;
+const DEFAULT_AGENT_ID = 'main';
+const DEFAULT_EXPIRES_MINUTES = 720;
+const DEFAULT_UPSTREAM_TIMEOUT_MS = 180000;
+const PAYLOAD_TYPE = 'mateclaw_local_openclaw_demo';
+const DEFAULT_OPENCLAW_BIN = process.platform === 'win32' ? 'openclaw.cmd' : 'openclaw';
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  const resolved = resolveCommand(rawArgs);
+  const options = parseArgs(resolved.args);
+
+  switch (resolved.command) {
+    case 'connect': {
+      const config = buildConfig(options);
+      await startConnector(config);
+      return;
+    }
+    case 'install': {
+      await runInstall(options);
+      return;
+    }
+    case 'doctor': {
+      await runDoctor(options);
+      return;
+    }
+    case 'help':
+      printHelp();
+      return;
+    default:
+      printHelp();
+      process.exitCode = 1;
+  }
+}
+
+function resolveCommand(rawArgs) {
+  if (!rawArgs.length) {
+    return { command: 'help', args: [] };
+  }
+  const [first, second, ...rest] = rawArgs;
+  const normalizedFirst = `${first || ''}`.trim().toLowerCase();
+  const normalizedSecond = `${second || ''}`.trim().toLowerCase();
+  if (normalizedFirst === 'login' && normalizedSecond === 'install') {
+    return { command: 'install', args: rest };
+  }
+  if (normalizedFirst === 'help' || normalizedFirst === '--help' || normalizedFirst === '-h') {
+    return { command: 'help', args: [] };
+  }
+  return { command: normalizedFirst, args: [second, ...rest].filter((v) => v != null) };
+}
+
+function printHelp() {
+  console.log('Usage: node ./src/cli.mjs <command> [options]');
+  console.log('');
+  console.log('Commands:');
+  console.log('  install              One-command setup: check OpenClaw, auto-fix config, restart gateway, start connector');
+  console.log('  login install        Alias of install (for folotoy-like UX)');
+  console.log('  connect              Start connector directly (no config repair)');
+  console.log('  doctor               Check OpenClaw and local config health');
+  console.log('');
+  console.log('Shared options (connect/install):');
+  console.log('  --openclaw-url <url>    Upstream OpenClaw base URL');
+  console.log('  --chat-path <path>      Chat path on OpenClaw');
+  console.log('  --host <host>           Connector bind host');
+  console.log('  --port <port>           Connector bind port');
+  console.log('  --lan-host <host>       Override LAN host shown in QR payload');
+  console.log('  --agent-id <id>         Agent id attached to requests');
+  console.log('  --name <label>          Display name shown in the app');
+  console.log('  --token <token>         Fixed bearer token for the app');
+  console.log('  --expires-minutes <n>   QR/token expiration window');
+  console.log('  --upstream-token <t>    Bearer token forwarded to OpenClaw');
+  console.log('  --upstream-timeout-ms <ms>  Upstream OpenClaw request timeout');
+  console.log('  --chat-mode <mode>      gateway-session | http-proxy');
+  console.log('  --session-key <key>     Fixed Gateway session key (default: agent:<agent-id>:main)');
+  console.log('');
+  console.log('Install/Doctor options:');
+  console.log('  --openclaw-bin <cmd>    OpenClaw CLI command (default: openclaw/openclaw.cmd)');
+  console.log('  --config-path <path>    Override openclaw.json path');
+  console.log('  --skip-gateway-restart  Skip openclaw gateway restart after config updates');
+  console.log('  --skip-connector        Only setup config, do not start local connector');
+  console.log('  --dry-run               Validate and print changes without writing files');
+}
+
+function parseArgs(args) {
+  const parsed = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      continue;
+    }
+
+    const key = arg.slice(2);
+    const next = args[i + 1];
+    if (next == null || next.startsWith('--')) {
+      parsed[key] = 'true';
+      continue;
+    }
+
+    parsed[key] = next;
+    i += 1;
+  }
+  return parsed;
+}
+
+function optionEnabled(options, key) {
+  const raw = options?.[key];
+  if (raw == null) return false;
+  const normalized = `${raw}`.trim().toLowerCase();
+  return normalized === '' || normalized === 'true' || normalized === '1' || normalized === 'yes';
+}
+
+function resolveOpenClawBin(options) {
+  return `${options?.['openclaw-bin'] || process.env.OPENCLAW_BIN || DEFAULT_OPENCLAW_BIN}`.trim();
+}
+
+function resolveOpenClawConfigPath(options) {
+  const configured =
+    options?.['config-path'] ||
+    process.env.OPENCLAW_CONFIG_PATH ||
+    path.join(os.homedir(), '.openclaw', 'openclaw.json');
+  return path.resolve(configured);
+}
+
+function resolveIdentityPaths() {
+  const baseDir = path.join(os.homedir(), '.openclaw', 'identity');
+  return {
+    baseDir,
+    identityPath: path.join(baseDir, 'device.json'),
+    deviceAuthPath: path.join(baseDir, 'device-auth.json'),
+  };
+}
+
+function readJsonFileSafe(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {
+      exists: false,
+      valid: false,
+      value: null,
+      error: '',
+    };
+  }
+
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const value = JSON.parse(raw);
+    return {
+      exists: true,
+      valid: true,
+      value,
+      error: '',
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      valid: false,
+      value: null,
+      error: `${error?.message || error}`,
+    };
+  }
+}
+
+function writeJsonFile(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function deepClonePlain(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
+function timestampTagForFile() {
+  const now = new Date();
+  const yyyy = `${now.getFullYear()}`;
+  const mm = `${now.getMonth() + 1}`.padStart(2, '0');
+  const dd = `${now.getDate()}`.padStart(2, '0');
+  const hh = `${now.getHours()}`.padStart(2, '0');
+  const mi = `${now.getMinutes()}`.padStart(2, '0');
+  const ss = `${now.getSeconds()}`.padStart(2, '0');
+  return `${yyyy}${mm}${dd}-${hh}${mi}${ss}`;
+}
+
+function backupFile(filePath, dryRun) {
+  if (!fs.existsSync(filePath)) {
+    return '';
+  }
+  const backupPath = `${filePath}.bak.${timestampTagForFile()}`;
+  if (!dryRun) {
+    fs.copyFileSync(filePath, backupPath);
+  }
+  return backupPath;
+}
+
+function runOpenClawCommand(bin, args, timeoutMs = 20000) {
+  try {
+    const result = spawnSync(bin, args, {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      shell: process.platform === 'win32',
+    });
+    const stdout = `${result.stdout || ''}`.trim();
+    const stderr = `${result.stderr || ''}`.trim();
+    const status = typeof result.status === 'number' ? result.status : 1;
+    const error = result.error ? `${result.error?.message || result.error}` : '';
+    return {
+      ok: status === 0 && !error,
+      status,
+      stdout,
+      stderr,
+      error,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      status: 1,
+      stdout: '',
+      stderr: '',
+      error: `${error?.message || error}`,
+    };
+  }
+}
+
+function commandLooksMissing(result) {
+  const blob = `${result?.stderr || ''}\n${result?.error || ''}`.toLowerCase();
+  return (
+    blob.includes('not recognized') ||
+    blob.includes('not found') ||
+    blob.includes('enoent') ||
+    blob.includes('cannot find')
+  );
+}
+
+function summarizeCommandFailure(result) {
+  if (!result) return 'unknown error';
+  const detail = [result.error, result.stderr, result.stdout].filter((part) => part).join(' | ');
+  return detail || `exit code ${result.status}`;
+}
+
+function extractGatewayTokenFromConfig(config) {
+  const mode = `${config?.gateway?.auth?.mode || ''}`.trim().toLowerCase();
+  if (mode === 'password') {
+    return `${config?.gateway?.auth?.password || ''}`.trim();
+  }
+  return `${config?.gateway?.auth?.token || ''}`.trim();
+}
+
+function maskToken(token) {
+  const text = `${token || ''}`.trim();
+  if (!text) return '';
+  if (text.length <= 8) return `${text.slice(0, 2)}***`;
+  return `${text.slice(0, 4)}...${text.slice(-2)}`;
+}
+
+function parsePortOrDefault(raw, fallback) {
+  const parsed = Number.parseInt(`${raw ?? ''}`, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return parsed;
+}
+
+function createDoctorCheck(id, status, summary, detail = '') {
+  return { id, status, summary, detail };
+}
+
+function countDoctorFailures(checks) {
+  return checks.filter((item) => item.status === 'fail').length;
+}
+
+function countDoctorWarnings(checks) {
+  return checks.filter((item) => item.status === 'warn').length;
+}
+
+async function isPortAvailable(port, host) {
+  return await new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once('error', () => {
+      resolve(false);
+    });
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, host);
+  });
+}
+
+async function pickAvailablePort(preferredPort, host, window = 20) {
+  const tried = [];
+  for (let step = 0; step <= window; step += 1) {
+    const port = preferredPort + step;
+    const available = await isPortAvailable(port, host);
+    tried.push({ port, available });
+    if (available) {
+      return {
+        found: true,
+        selectedPort: port,
+        tried,
+      };
+    }
+  }
+  return {
+    found: false,
+    selectedPort: preferredPort,
+    tried,
+  };
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function probeGatewayHealth(openclawUrl, timeoutMs = 5000) {
+  const url = new URL('/health', `${stripTrailingSlash(openclawUrl)}/`);
+  try {
+    const result = await httpRequest({
+      url,
+      method: 'GET',
+      headers: {
+        accept: 'application/json',
+      },
+      timeoutMs,
+    });
+    const ok = result.statusCode >= 200 && result.statusCode < 300;
+    return {
+      ok,
+      statusCode: result.statusCode,
+      detail: ok ? 'reachable' : `http ${result.statusCode}`,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      statusCode: 0,
+      detail: `${error?.message || error}`,
+    };
+  }
+}
+
+async function waitForGatewayHealthy(openclawUrl, timeoutMs = 20000) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    const probe = await probeGatewayHealth(openclawUrl, 3000);
+    if (probe.ok) {
+      return probe;
+    }
+    await sleep(1000);
+  }
+  return {
+    ok: false,
+    statusCode: 0,
+    detail: `gateway health did not recover within ${timeoutMs}ms`,
+  };
+}
+
+async function startGatewayIfNeeded(openclawBin, openclawUrl) {
+  const health = await probeGatewayHealth(openclawUrl, 3000);
+  if (health.ok) {
+    return {
+      attempted: false,
+      ok: true,
+      detail: 'gateway already healthy',
+    };
+  }
+
+  const startResult = runOpenClawCommand(openclawBin, ['gateway', 'start'], 30000);
+  if (!startResult.ok) {
+    return {
+      attempted: true,
+      ok: false,
+      detail: summarizeCommandFailure(startResult),
+    };
+  }
+
+  const recovered = await waitForGatewayHealthy(openclawUrl, 20000);
+  return {
+    attempted: true,
+    ok: recovered.ok,
+    detail: recovered.ok ? 'gateway health recovered after start' : recovered.detail,
+  };
+}
+
+async function collectDoctorReport(options) {
+  const openclawBin = resolveOpenClawBin(options);
+  const configPath = resolveOpenClawConfigPath(options);
+  const openclawUrl = stripTrailingSlash(
+    options['openclaw-url'] ||
+      process.env.OPENCLAW_BASE_URL ||
+      DEFAULT_OPENCLAW_URL,
+  );
+  const configSnapshot = readJsonFileSafe(configPath);
+  const configValue = configSnapshot.valid ? configSnapshot.value : {};
+  const gatewayTokenFromConfig = extractGatewayTokenFromConfig(configValue);
+  const deviceAuthToken = detectLocalDeviceAuthToken();
+  const deviceIdentity = loadLocalDeviceIdentity();
+  const cliToken = `${options['upstream-token'] || ''}`.trim();
+  const envToken = `${process.env.OPENCLAW_UPSTREAM_TOKEN || ''}`.trim();
+  const effectiveToken = cliToken || deviceAuthToken || gatewayTokenFromConfig || envToken;
+  const { identityPath, deviceAuthPath } = resolveIdentityPaths();
+
+  const versionProbe = runOpenClawCommand(openclawBin, ['--version'], 10000);
+  const fallbackVersionProbe = !versionProbe.ok ?
+    runOpenClawCommand(openclawBin, ['version'], 10000) :
+    null;
+  const versionResult = versionProbe.ok ? versionProbe : (fallbackVersionProbe || versionProbe);
+
+  const gatewayStatusResult = runOpenClawCommand(openclawBin, ['gateway', 'status', '--json'], 45000);
+  const gatewayHealth = await waitForGatewayHealthy(openclawUrl, 8000);
+
+  const listenHost = options.host || process.env.MATECLAW_CONNECTOR_HOST || DEFAULT_LISTEN_HOST;
+  const preferredPort = parsePortOrDefault(
+    options.port || process.env.MATECLAW_CONNECTOR_PORT || `${DEFAULT_PORT}`,
+    DEFAULT_PORT,
+  );
+  const portAvailable = await isPortAvailable(preferredPort, listenHost);
+
+  const lanCandidates = listLanCandidates();
+  const lanHost = options['lan-host'] || process.env.MATECLAW_CONNECTOR_LAN_HOST || lanCandidates[0]?.address || '';
+
+  const checks = [];
+
+  if (!versionResult.ok && commandLooksMissing(versionResult)) {
+    checks.push(
+      createDoctorCheck(
+        'openclaw-bin',
+        'fail',
+        `OpenClaw CLI not found: ${openclawBin}`,
+        'Install OpenClaw first or pass --openclaw-bin with a valid command path.',
+      ),
+    );
+  } else if (!versionResult.ok) {
+    checks.push(
+      createDoctorCheck(
+        'openclaw-bin',
+        'warn',
+        `OpenClaw CLI execution failed: ${openclawBin}`,
+        summarizeCommandFailure(versionResult),
+      ),
+    );
+  } else {
+    checks.push(
+      createDoctorCheck(
+        'openclaw-bin',
+        'pass',
+        `OpenClaw CLI available: ${openclawBin}`,
+        '',
+      ),
+    );
+    checks.push(
+      createDoctorCheck(
+        'openclaw-version',
+        'pass',
+        `OpenClaw version: ${(versionResult.stdout || versionResult.stderr || 'unknown').split('\n')[0]}`,
+        '',
+      ),
+    );
+  }
+
+  if (!configSnapshot.exists) {
+    checks.push(
+      createDoctorCheck(
+        'config',
+        'warn',
+        `Config missing: ${configPath}`,
+        'Install will create a minimal openclaw.json.',
+      ),
+    );
+  } else if (!configSnapshot.valid) {
+    checks.push(
+      createDoctorCheck(
+        'config',
+        'fail',
+        `Config parse failed: ${configPath}`,
+        configSnapshot.error,
+      ),
+    );
+  } else {
+    checks.push(
+      createDoctorCheck(
+        'config',
+        'pass',
+        `Config loaded: ${configPath}`,
+        '',
+      ),
+    );
+  }
+
+  if (effectiveToken) {
+    const source = cliToken ?
+      'explicit --upstream-token' :
+      (deviceAuthToken ? 'device-auth.json' : (gatewayTokenFromConfig ? 'openclaw.json gateway.auth' : 'OPENCLAW_UPSTREAM_TOKEN'));
+    checks.push(
+      createDoctorCheck(
+        'token',
+        'pass',
+        `Gateway token available (${source}): ${maskToken(effectiveToken)}`,
+        '',
+      ),
+    );
+  } else {
+    checks.push(
+      createDoctorCheck(
+        'token',
+        'warn',
+        'No upstream auth token found.',
+        'Install will auto-generate gateway.auth.token and sync device-auth token.',
+      ),
+    );
+  }
+
+  if (deviceIdentity) {
+    checks.push(
+      createDoctorCheck(
+        'identity',
+        'pass',
+        `Device identity ready: ${identityPath}`,
+        '',
+      ),
+    );
+  } else {
+    checks.push(
+      createDoctorCheck(
+        'identity',
+        'warn',
+        `Device identity missing: ${identityPath}`,
+        'Install will auto-create device identity.',
+      ),
+    );
+  }
+
+  if (deviceAuthToken) {
+    checks.push(
+      createDoctorCheck(
+        'device-auth',
+        'pass',
+        `Device auth token ready: ${deviceAuthPath}`,
+        '',
+      ),
+    );
+  } else {
+    checks.push(
+      createDoctorCheck(
+        'device-auth',
+        'warn',
+        `Device auth token missing: ${deviceAuthPath}`,
+        'Install will sync operator token into device-auth store.',
+      ),
+    );
+  }
+
+  if (gatewayStatusResult.ok) {
+    checks.push(
+      createDoctorCheck(
+        'gateway-status',
+        'pass',
+        'OpenClaw gateway status command is healthy.',
+        '',
+      ),
+    );
+  } else {
+    checks.push(
+      createDoctorCheck(
+        'gateway-status',
+        'warn',
+        'OpenClaw gateway status command returned non-zero.',
+        summarizeCommandFailure(gatewayStatusResult),
+      ),
+    );
+  }
+
+  if (gatewayHealth.ok) {
+    checks.push(
+      createDoctorCheck(
+        'gateway-health',
+        'pass',
+        `Gateway health reachable: ${openclawUrl}/health`,
+        '',
+      ),
+    );
+  } else {
+    checks.push(
+      createDoctorCheck(
+        'gateway-health',
+        'fail',
+        `Gateway health check failed: ${openclawUrl}/health`,
+        gatewayHealth.detail,
+      ),
+    );
+  }
+
+  if (lanHost) {
+    checks.push(
+      createDoctorCheck(
+        'lan',
+        'pass',
+        `LAN host selected: ${lanHost}`,
+        '',
+      ),
+    );
+  } else {
+    checks.push(
+      createDoctorCheck(
+        'lan',
+        'fail',
+        'No LAN IPv4 address detected.',
+        'Pass --lan-host manually.',
+      ),
+    );
+  }
+
+  if (portAvailable) {
+    checks.push(
+      createDoctorCheck(
+        'port',
+        'pass',
+        `Connector port available: ${listenHost}:${preferredPort}`,
+        '',
+      ),
+    );
+  } else {
+    checks.push(
+      createDoctorCheck(
+        'port',
+        'warn',
+        `Connector port is busy: ${listenHost}:${preferredPort}`,
+        'Install will auto-select a nearby free port.',
+      ),
+    );
+  }
+
+  return {
+    checks,
+    openclawBin,
+    openclawUrl,
+    configPath,
+    preferredPort,
+    listenHost,
+  };
+}
+
+function printDoctorReport(report, title = 'OpenClaw Doctor') {
+  console.log('');
+  console.log(title);
+  console.log('='.repeat(title.length));
+  for (const check of report.checks) {
+    const prefix = check.status === 'pass' ? '[PASS]' : check.status === 'warn' ? '[WARN]' : '[FAIL]';
+    console.log(`${prefix} ${check.summary}`);
+    if (check.detail) {
+      console.log(`       ${check.detail}`);
+    }
+  }
+  const failures = countDoctorFailures(report.checks);
+  const warnings = countDoctorWarnings(report.checks);
+  console.log('');
+  console.log(`Doctor summary: ${failures} fail, ${warnings} warn`);
+  console.log('');
+}
+
+function ensureDeviceIdentity({ dryRun }) {
+  const { identityPath } = resolveIdentityPaths();
+  const existing = loadLocalDeviceIdentity();
+  if (existing) {
+    return {
+      changed: false,
+      created: false,
+      identityPath,
+      deviceId: existing.deviceId,
+      warning: '',
+    };
+  }
+
+  const keyPair = crypto.generateKeyPairSync('ed25519');
+  const nextIdentity = {
+    deviceId: crypto.randomUUID(),
+    publicKeyPem: keyPair.publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+    privateKeyPem: keyPair.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(),
+    createdAt: new Date().toISOString(),
+  };
+
+  if (!dryRun) {
+    writeJsonFile(identityPath, nextIdentity);
+  }
+  return {
+    changed: true,
+    created: true,
+    identityPath,
+    deviceId: nextIdentity.deviceId,
+    warning: '',
+  };
+}
+
+function ensureDeviceAuthToken({ dryRun, gatewayToken, deviceId }) {
+  const { deviceAuthPath } = resolveIdentityPaths();
+  const snapshot = readJsonFileSafe(deviceAuthPath);
+  const existingToken = detectLocalDeviceAuthToken();
+  if (existingToken) {
+    return {
+      changed: false,
+      created: false,
+      deviceAuthPath,
+      warning: '',
+    };
+  }
+
+  if (!gatewayToken) {
+    return {
+      changed: false,
+      created: false,
+      deviceAuthPath,
+      warning: 'Cannot backfill device-auth token because gateway token is missing.',
+    };
+  }
+
+  const now = new Date().toISOString();
+  const base = snapshot.valid ? deepClonePlain(snapshot.value) : {};
+  if (!base.version || typeof base.version !== 'number') {
+    base.version = 1;
+  }
+  if (!base.deviceId) {
+    base.deviceId = deviceId || crypto.randomUUID();
+  }
+  if (!base.tokens || typeof base.tokens !== 'object' || Array.isArray(base.tokens)) {
+    base.tokens = {};
+  }
+  if (!base.tokens.operator || typeof base.tokens.operator !== 'object' || Array.isArray(base.tokens.operator)) {
+    base.tokens.operator = {};
+  }
+  base.tokens.operator.token = gatewayToken;
+  if (!Array.isArray(base.tokens.operator.scopes) || base.tokens.operator.scopes.length === 0) {
+    base.tokens.operator.scopes = ['operator.admin'];
+  }
+  base.tokens.operator.updatedAt = now;
+
+  if (!dryRun) {
+    writeJsonFile(deviceAuthPath, base);
+  }
+  return {
+    changed: true,
+    created: !snapshot.exists,
+    deviceAuthPath,
+    warning: '',
+  };
+}
+
+function normalizeGatewayAuthMode(rawMode) {
+  const text = `${rawMode || ''}`.trim().toLowerCase();
+  if (text === 'token' || text === 'password') return text;
+  return '';
+}
+
+function ensureGatewayConfig({ config, options }) {
+  const nextConfig = deepClonePlain(config);
+  const changes = [];
+
+  if (!nextConfig.gateway || typeof nextConfig.gateway !== 'object' || Array.isArray(nextConfig.gateway)) {
+    nextConfig.gateway = {};
+    changes.push('Created gateway section in openclaw.json');
+  }
+  if (!nextConfig.gateway.mode) {
+    nextConfig.gateway.mode = 'local';
+    changes.push('Set gateway.mode=local');
+  }
+  if (!nextConfig.gateway.auth || typeof nextConfig.gateway.auth !== 'object' || Array.isArray(nextConfig.gateway.auth)) {
+    nextConfig.gateway.auth = {};
+    changes.push('Created gateway.auth section');
+  }
+
+  let authMode = normalizeGatewayAuthMode(nextConfig.gateway.auth.mode);
+  const tokenValue = `${nextConfig.gateway.auth.token || ''}`.trim();
+  const passwordValue = `${nextConfig.gateway.auth.password || ''}`.trim();
+  if (!authMode) {
+    authMode = tokenValue ? 'token' : (passwordValue ? 'password' : 'token');
+    nextConfig.gateway.auth.mode = authMode;
+    changes.push(`Set gateway.auth.mode=${authMode}`);
+  }
+
+  let generatedToken = '';
+  if (authMode === 'token') {
+    if (!tokenValue) {
+      generatedToken = `${options['upstream-token'] || crypto.randomBytes(16).toString('hex')}`;
+      nextConfig.gateway.auth.token = generatedToken;
+      changes.push('Generated and set gateway.auth.token');
+    }
+  } else if (!passwordValue) {
+    const generatedPassword = crypto.randomBytes(16).toString('hex');
+    nextConfig.gateway.auth.password = generatedPassword;
+    changes.push('Generated and set gateway.auth.password');
+  }
+
+  const effectiveGatewayToken =
+    `${options['upstream-token'] || ''}`.trim() ||
+    detectLocalDeviceAuthToken() ||
+    extractGatewayTokenFromConfig(nextConfig) ||
+    `${process.env.OPENCLAW_UPSTREAM_TOKEN || ''}`.trim() ||
+    generatedToken;
+
+  return {
+    nextConfig,
+    changes,
+    effectiveGatewayToken: `${effectiveGatewayToken || ''}`.trim(),
+  };
+}
+
+async function applyInstallFixes(options, dryRun) {
+  const configPath = resolveOpenClawConfigPath(options);
+  const configSnapshot = readJsonFileSafe(configPath);
+  const startingConfig = configSnapshot.valid ? configSnapshot.value : {};
+  const normalized = ensureGatewayConfig({
+    config: startingConfig,
+    options,
+  });
+
+  let backupPath = '';
+  if (normalized.changes.length > 0) {
+    backupPath = backupFile(configPath, dryRun);
+    if (!dryRun) {
+      writeJsonFile(configPath, normalized.nextConfig);
+    }
+  }
+
+  const identityResult = ensureDeviceIdentity({ dryRun });
+  const deviceAuthResult = ensureDeviceAuthToken({
+    dryRun,
+    gatewayToken: normalized.effectiveGatewayToken,
+    deviceId: identityResult.deviceId,
+  });
+
+  const changes = [...normalized.changes];
+  if (identityResult.changed) {
+    changes.push(`Created device identity: ${identityResult.identityPath}`);
+  }
+  if (deviceAuthResult.changed) {
+    changes.push(`Synced device-auth token: ${deviceAuthResult.deviceAuthPath}`);
+  }
+
+  const warnings = [];
+  if (!configSnapshot.valid && configSnapshot.exists) {
+    warnings.push(`Existing config was invalid JSON and has been replaced: ${configPath}`);
+  }
+  if (deviceAuthResult.warning) {
+    warnings.push(deviceAuthResult.warning);
+  }
+
+  return {
+    configPath,
+    backupPath,
+    changes,
+    warnings,
+    effectiveGatewayToken: normalized.effectiveGatewayToken,
+  };
+}
+
+function printInstallFixSummary(result, dryRun) {
+  console.log('');
+  console.log(dryRun ? 'Install Fix Plan (dry-run)' : 'Install Fixes');
+  console.log(dryRun ? '==========================' : '=============');
+  if (result.changes.length === 0) {
+    console.log('[PASS] No config repair needed.');
+  } else {
+    for (const item of result.changes) {
+      console.log(`[PASS] ${item}`);
+    }
+  }
+  if (result.backupPath) {
+    console.log(`[PASS] ${dryRun ? 'Would backup' : 'Backup'} openclaw.json -> ${result.backupPath}`);
+  }
+  for (const warning of result.warnings) {
+    console.log(`[WARN] ${warning}`);
+  }
+  console.log('');
+}
+
+async function runDoctor(options) {
+  const report = await collectDoctorReport(options);
+  printDoctorReport(report);
+  const failures = countDoctorFailures(report.checks);
+  if (failures > 0) {
+    process.exitCode = 1;
+  }
+}
+
+async function runInstall(options) {
+  const dryRun = optionEnabled(options, 'dry-run');
+  const skipGatewayRestart = optionEnabled(options, 'skip-gateway-restart');
+  const skipConnector = optionEnabled(options, 'skip-connector');
+  const openclawBin = resolveOpenClawBin(options);
+
+  console.log('');
+  console.log('MateClaw Local OpenClaw Installer');
+  console.log('=================================');
+
+  const before = await collectDoctorReport(options);
+  printDoctorReport(before, 'Preflight Doctor');
+
+  const fixResult = await applyInstallFixes(options, dryRun);
+  printInstallFixSummary(fixResult, dryRun);
+
+  const installOptions = { ...options };
+
+  const openclawUrl = stripTrailingSlash(
+    installOptions['openclaw-url'] ||
+      process.env.OPENCLAW_BASE_URL ||
+      DEFAULT_OPENCLAW_URL,
+  );
+
+  if (!skipGatewayRestart && !dryRun) {
+    const startResult = await startGatewayIfNeeded(openclawBin, openclawUrl);
+    if (startResult.attempted && startResult.ok) {
+      console.log('[PASS] OpenClaw gateway start triggered and healthy.');
+    } else if (startResult.attempted && !startResult.ok) {
+      console.log(`[WARN] OpenClaw gateway start failed: ${startResult.detail}`);
+    }
+
+    const restartResult = runOpenClawCommand(openclawBin, ['gateway', 'restart'], 30000);
+    if (restartResult.ok) {
+      console.log('[PASS] OpenClaw gateway restart triggered.');
+    } else {
+      console.log(`[WARN] OpenClaw gateway restart failed: ${summarizeCommandFailure(restartResult)}`);
+    }
+    const recovered = await waitForGatewayHealthy(openclawUrl, 20000);
+    if (recovered.ok) {
+      console.log('[PASS] Gateway health recovered after restart.');
+    } else {
+      console.log(`[WARN] Gateway health still unavailable: ${recovered.detail}`);
+    }
+  } else if (skipGatewayRestart) {
+    console.log('[WARN] Skipped gateway restart (--skip-gateway-restart).');
+  }
+
+  const connectorHost =
+    installOptions.host ||
+    process.env.MATECLAW_CONNECTOR_HOST ||
+    DEFAULT_LISTEN_HOST;
+  const preferredPort = parsePortOrDefault(
+    installOptions.port || process.env.MATECLAW_CONNECTOR_PORT || `${DEFAULT_PORT}`,
+    DEFAULT_PORT,
+  );
+  const portPlan = await pickAvailablePort(preferredPort, connectorHost, 20);
+  if (!portPlan.found) {
+    throw new Error(`No free connector port found near ${preferredPort}.`);
+  }
+  if (portPlan.selectedPort !== preferredPort) {
+    installOptions.port = `${portPlan.selectedPort}`;
+    console.log(`[WARN] Port ${preferredPort} is busy, switched to ${portPlan.selectedPort}.`);
+  }
+
+  if (!installOptions['lan-host']) {
+    const lanHost = detectLanAddress();
+    if (lanHost) {
+      installOptions['lan-host'] = lanHost;
+      console.log(`[PASS] Selected LAN host: ${lanHost}`);
+    }
+  }
+
+  const after = await collectDoctorReport(installOptions);
+  printDoctorReport(after, 'Post-fix Doctor');
+
+  const postFixFailures = countDoctorFailures(after.checks);
+  if (postFixFailures > 0) {
+    if (dryRun) {
+      console.log('[WARN] Dry-run detected blocking failures after auto-fix. Fix them before real install.');
+      return;
+    }
+    throw new Error('Doctor still reports blocking failures after auto-fix.');
+  }
+
+  if (dryRun) {
+    console.log('[PASS] Dry-run completed. Re-run without --dry-run to start connector.');
+    return;
+  }
+
+  if (skipConnector) {
+    console.log('[PASS] Install completed without starting connector (--skip-connector).');
+    return;
+  }
+
+  const config = buildConfig(installOptions);
+  await startConnector(config);
+}
+
+function buildConfig(options) {
+  const openclawUrl = stripTrailingSlash(
+    options['openclaw-url'] ||
+        process.env.OPENCLAW_BASE_URL ||
+        DEFAULT_OPENCLAW_URL,
+  );
+  const chatMode = normalizeChatMode(
+    options['chat-mode'] ||
+        process.env.MATECLAW_CHAT_MODE ||
+        DEFAULT_CHAT_MODE,
+  );
+  const chatPath = normalizePath(
+    options['chat-path'] ||
+        process.env.OPENCLAW_CHAT_PATH ||
+        DEFAULT_CHAT_PATH,
+  );
+  const acceptedChatPaths = dedupePaths([chatPath, ...CHAT_PATH_FALLBACKS]);
+  const listenHost =
+      options.host || process.env.MATECLAW_CONNECTOR_HOST || DEFAULT_LISTEN_HOST;
+  const port = Number.parseInt(
+    options.port || process.env.MATECLAW_CONNECTOR_PORT || `${DEFAULT_PORT}`,
+    10,
+  );
+  const lanCandidates = listLanCandidates();
+  const lanHost =
+      options['lan-host'] ||
+      process.env.MATECLAW_CONNECTOR_LAN_HOST ||
+      lanCandidates[0]?.address ||
+      '';
+  const agentId =
+      options['agent-id'] || process.env.MATECLAW_AGENT_ID || DEFAULT_AGENT_ID;
+  const sessionKey = normalizeSessionKey(
+    options['session-key'] ||
+        process.env.MATECLAW_SESSION_KEY ||
+        `agent:${normalizeSessionSegment(agentId)}:main`,
+  );
+  const name =
+      options.name || process.env.MATECLAW_CONNECTOR_NAME || `${os.hostname()} OpenClaw`;
+  const token =
+      options.token || process.env.MATECLAW_CONNECTOR_TOKEN || crypto.randomBytes(16).toString('hex');
+  const expiresMinutes = Number.parseInt(
+    options['expires-minutes'] ||
+        process.env.MATECLAW_CONNECTOR_EXPIRES_MINUTES ||
+        `${DEFAULT_EXPIRES_MINUTES}`,
+    10,
+  );
+  const upstreamTimeoutMs = Number.parseInt(
+    options['upstream-timeout-ms'] ||
+        process.env.OPENCLAW_UPSTREAM_TIMEOUT_MS ||
+        `${DEFAULT_UPSTREAM_TIMEOUT_MS}`,
+    10,
+  );
+  const upstreamToken =
+      options['upstream-token'] ||
+      process.env.OPENCLAW_UPSTREAM_TOKEN ||
+      detectLocalDeviceAuthToken() ||
+      detectLocalGatewayToken();
+
+  if (!Number.isFinite(port) || port <= 0) {
+    throw new Error('Invalid port.');
+  }
+  if (!Number.isFinite(expiresMinutes) || expiresMinutes <= 0) {
+    throw new Error('Invalid expires-minutes.');
+  }
+  if (!Number.isFinite(upstreamTimeoutMs) || upstreamTimeoutMs <= 0) {
+    throw new Error('Invalid upstream-timeout-ms.');
+  }
+  if (!lanHost) {
+    throw new Error(
+      'Unable to detect a LAN host automatically. Pass --lan-host or set MATECLAW_CONNECTOR_LAN_HOST.',
+    );
+  }
+
+  const expiresAt = new Date(Date.now() + expiresMinutes * 60 * 1000);
+  const baseUrl = `http://${lanHost}:${port}`;
+
+  return {
+    openclawUrl,
+    chatMode,
+    chatPath,
+    listenHost,
+    port,
+    lanHost,
+    agentId,
+    sessionKey,
+    name,
+    token,
+    expiresAt,
+    upstreamTimeoutMs,
+    upstreamToken,
+    lanCandidates,
+    baseUrl,
+    acceptedChatPaths,
+    qrPayload: {
+      type: PAYLOAD_TYPE,
+      name,
+      baseUrl,
+      chatPath,
+      token,
+      agentId,
+      sessionId: sessionKey,
+      expiresAt: expiresAt.toISOString(),
+    },
+  };
+}
+
+function detectLocalGatewayToken() {
+  try {
+    const configPath = process.env.OPENCLAW_CONFIG_PATH ||
+      path.join(os.homedir(), '.openclaw', 'openclaw.json');
+    if (!fs.existsSync(configPath)) return '';
+
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    const mode = `${parsed?.gateway?.auth?.mode || ''}`.trim().toLowerCase();
+    if (mode === 'token') {
+      return `${parsed?.gateway?.auth?.token || ''}`.trim();
+    }
+    if (mode === 'password') {
+      return `${parsed?.gateway?.auth?.password || ''}`.trim();
+    }
+    return '';
+  } catch {
+    return '';
+  }
+}
+
+function detectLocalDeviceAuthToken() {
+  try {
+    const filePath = path.join(os.homedir(), '.openclaw', 'identity', 'device-auth.json');
+    if (!fs.existsSync(filePath)) return '';
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    const token = `${parsed?.tokens?.operator?.token || ''}`.trim();
+    return token;
+  } catch {
+    return '';
+  }
+}
+
+function loadLocalDeviceIdentity() {
+  try {
+    const filePath = path.join(os.homedir(), '.openclaw', 'identity', 'device.json');
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    const deviceId = `${parsed?.deviceId || ''}`.trim();
+    const publicKeyPem = `${parsed?.publicKeyPem || ''}`.trim();
+    const privateKeyPem = `${parsed?.privateKeyPem || ''}`.trim();
+    if (!deviceId || !publicKeyPem || !privateKeyPem) return null;
+    return {
+      deviceId,
+      publicKeyPem,
+      privateKeyPem,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function startConnector(config) {
+  const server = http.createServer((req, res) => {
+    handleRequest(req, res, config).catch((error) => {
+      sendJson(res, error.statusCode || 500, {
+        error: 'connector_error',
+        message: error.message || 'Unexpected connector error.',
+      });
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(config.port, config.listenHost, resolve);
+  });
+
+  printBanner(config);
+
+  const shutdown = () => {
+    console.log('\nShutting down Local OpenClaw Demo Connector...');
+    server.close(() => process.exit(0));
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+async function handleRequest(req, res, config) {
+  const requestUrl = new URL(req.url || '/', config.baseUrl);
+
+  addCorsHeaders(res);
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  if (requestUrl.pathname === '/health' && req.method === 'GET') {
+    sendJson(res, 200, {
+      ok: true,
+      mode: 'mateclaw_local_openclaw_demo',
+      chatMode: config.chatMode,
+      sessionId: config.sessionKey,
+      upstream: config.openclawUrl,
+      chatPath: config.chatPath,
+      acceptedChatPaths: config.acceptedChatPaths,
+      expiresAt: config.expiresAt.toISOString(),
+    });
+    return;
+  }
+
+  if (requestUrl.pathname === '/binding' && req.method === 'GET') {
+    sendJson(res, 200, config.qrPayload);
+    return;
+  }
+
+  if (isChatPathRequest(requestUrl.pathname, req.method, config.acceptedChatPaths)) {
+    requireBearer(req, config.token);
+    const body = await readBody(req);
+    if (config.chatMode === 'gateway-session') {
+      const payload = parseChatPayload(body);
+      const userMessage = extractLatestUserMessage(payload);
+      const sessionId = config.sessionKey;
+      const gatewayResult = await chatViaGatewaySession({
+        openclawUrl: config.openclawUrl,
+        authToken: config.upstreamToken,
+        sessionKey: sessionId,
+        message: userMessage,
+        timeoutMs: config.upstreamTimeoutMs,
+      });
+      sendJson(res, 200, {
+        id: gatewayResult.runId || crypto.randomUUID(),
+        object: 'chat.completion',
+        created: Math.floor(Date.now() / 1000),
+        model: gatewayResult.model || 'openclaw/gateway-session',
+        provider: gatewayResult.provider || 'openclaw',
+        traceId: gatewayResult.runId || '',
+        sessionId,
+        chatMode: 'gateway-session',
+        reply: {
+          role: 'assistant',
+          text: gatewayResult.replyText,
+        },
+        choices: [
+          {
+            index: 0,
+            message: {
+              role: 'assistant',
+              content: gatewayResult.replyText,
+            },
+            finish_reason: 'stop',
+          },
+        ],
+      });
+      return;
+    }
+
+    const headers = {
+      'content-type': req.headers['content-type'] || 'application/json',
+    };
+
+    if (config.upstreamToken) {
+      headers.authorization = `Bearer ${config.upstreamToken}`;
+    }
+
+    const upstream = await forwardChatWithFallback({
+      openclawUrl: config.openclawUrl,
+      requestedPath: normalizePath(requestUrl.pathname),
+      preferredPath: config.chatPath,
+      candidatePaths: config.acceptedChatPaths,
+      upstreamTimeoutMs: config.upstreamTimeoutMs,
+      headers,
+      body,
+    });
+
+    res.writeHead(upstream.statusCode, {
+      ...upstream.headers,
+      'access-control-allow-origin': '*',
+      'x-openclaw-chat-path': upstream.chatPath,
+    });
+    res.end(upstream.body);
+    return;
+  }
+
+  sendJson(res, 404, {
+    error: 'not_found',
+    message: `Unsupported route: ${req.method || 'GET'} ${requestUrl.pathname}`,
+  });
+}
+
+function requireBearer(req, expectedToken) {
+  const header = req.headers.authorization || '';
+  const prefix = 'Bearer ';
+  if (!header.startsWith(prefix) || header.slice(prefix.length).trim() !== expectedToken) {
+    const error = new Error('Unauthorized');
+    error.statusCode = 401;
+    throw error;
+  }
+}
+
+function addCorsHeaders(res) {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+}
+
+function sendJson(res, statusCode, payload) {
+  res.writeHead(statusCode, {
+    'content-type': 'application/json; charset=utf-8',
+    'access-control-allow-origin': '*',
+  });
+  res.end(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+async function readBody(req) {
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+function parseChatPayload(body) {
+  try {
+    const text = body.toString('utf8').trim();
+    if (!text) {
+      throw createConnectorError(400, 'Empty chat payload.');
+    }
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw createConnectorError(400, 'Invalid chat payload object.');
+    }
+    return parsed;
+  } catch (error) {
+    if (error?.statusCode) {
+      throw error;
+    }
+    throw createConnectorError(400, 'Chat payload is not valid JSON.');
+  }
+}
+
+function extractLatestUserMessage(payload) {
+  const messages = Array.isArray(payload.messages) ? payload.messages : [];
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const item = messages[i];
+    if (!item || typeof item !== 'object') continue;
+    const role = `${item.role || ''}`.trim().toLowerCase();
+    if (role !== 'user') continue;
+    const text = toText(item.content).trim();
+    if (text) return text;
+  }
+
+  const fallbackText = toText(payload.input ?? payload.message ?? payload.prompt).trim();
+  if (fallbackText) return fallbackText;
+  throw createConnectorError(400, 'No user message found in request payload.');
+}
+
+async function chatViaGatewaySession({
+  openclawUrl,
+  authToken,
+  sessionKey,
+  message,
+  timeoutMs,
+}) {
+  if (!authToken || !authToken.trim()) {
+    throw createConnectorError(
+      401,
+      'Missing upstream gateway auth token. Set OPENCLAW_UPSTREAM_TOKEN or configure gateway.auth.token.',
+    );
+  }
+  const wsUrl = toWebSocketUrl(openclawUrl);
+  const client = await GatewaySessionClient.connect({
+    wsUrl,
+    authToken: authToken.trim(),
+    timeoutMs,
+  });
+
+  try {
+    const sendResult = await client.request(
+      'chat.send',
+      {
+        sessionKey,
+        message,
+        idempotencyKey: crypto.randomUUID(),
+      },
+      timeoutMs,
+    );
+    const runId = `${sendResult?.runId || ''}`.trim();
+
+    let finalEvent = null;
+    try {
+      finalEvent = await client.waitForEvent(
+        (evt) =>
+          evt?.event === 'chat' &&
+          evt?.payload?.sessionKey === sessionKey &&
+          (runId ? evt?.payload?.runId === runId : true) &&
+          (evt?.payload?.state === 'final' || evt?.payload?.state === 'error'),
+        timeoutMs,
+      );
+    } catch {
+      finalEvent = null;
+    }
+
+    if (finalEvent?.payload?.state === 'error') {
+      const errorMessage = `${finalEvent.payload.errorMessage || 'Gateway chat failed.'}`.trim();
+      throw createConnectorError(502, errorMessage || 'Gateway chat failed.');
+    }
+
+    let replyText = extractTextFromChatPayload(finalEvent?.payload?.message).trim();
+    if (!replyText) {
+      const history = await client.request(
+        'chat.history',
+        {
+          sessionKey,
+          limit: 30,
+        },
+        Math.min(timeoutMs, 30000),
+      );
+      replyText = extractLatestAssistantTextFromHistory(history?.messages).trim();
+    }
+
+    if (!replyText) {
+      throw createConnectorError(
+        502,
+        'Gateway chat completed but no assistant content was returned.',
+      );
+    }
+
+    return {
+      runId,
+      replyText,
+      provider: 'openclaw',
+      model: 'openclaw/gateway-session',
+    };
+  } catch (error) {
+    if (error?.statusCode) {
+      throw error;
+    }
+    const text = `${error?.message || error || ''}`;
+    if (text.toLowerCase().includes('timeout')) {
+      throw createConnectorError(504, `OpenClaw gateway timeout after ${timeoutMs}ms`);
+    }
+    if (text.toLowerCase().includes('unauthorized')) {
+      throw createConnectorError(401, text);
+    }
+    throw createConnectorError(502, `Gateway session error: ${text}`);
+  } finally {
+    client.close();
+  }
+}
+
+class GatewaySessionClient {
+  constructor(ws, timeoutMs) {
+    this.ws = ws;
+    this.timeoutMs = timeoutMs;
+    this.pendingById = new Map();
+    this.eventWaiters = new Set();
+    this.closed = false;
+
+    this.ws.on('message', (data) => {
+      this._handleFrame(data);
+    });
+    this.ws.on('error', () => {
+      // Error details are surfaced through pending request rejections.
+    });
+    this.ws.on('close', () => {
+      this.closed = true;
+      for (const pending of this.pendingById.values()) {
+        pending.reject(new Error('gateway websocket closed'));
+      }
+      this.pendingById.clear();
+      for (const waiter of this.eventWaiters.values()) {
+        waiter.reject(new Error('gateway websocket closed'));
+      }
+      this.eventWaiters.clear();
+    });
+  }
+
+  static async connect({ wsUrl, authToken, timeoutMs }) {
+    const ws = await openWebSocket(wsUrl, timeoutMs);
+    const client = new GatewaySessionClient(ws, timeoutMs);
+    const challengeEvent = await client.waitForEvent(
+      (evt) => evt?.event === 'connect.challenge',
+      timeoutMs,
+    );
+    const nonce = `${challengeEvent?.payload?.nonce || ''}`.trim();
+    if (!nonce) {
+      throw new Error('gateway connect challenge missing nonce');
+    }
+
+    const role = 'operator';
+    const scopes = ['operator.admin'];
+    const clientId = 'gateway-client';
+    const clientMode = 'backend';
+    const clientDisplayName = 'MateClaw Local Connector';
+    const platform = process.platform;
+    const deviceIdentity = loadLocalDeviceIdentity();
+    const signedAtMs = Date.now();
+    const device = deviceIdentity ? {
+      id: deviceIdentity.deviceId,
+      publicKey: publicKeyRawBase64UrlFromPem(deviceIdentity.publicKeyPem),
+      signature: signDevicePayload(
+        deviceIdentity.privateKeyPem,
+        buildDeviceAuthPayloadV3({
+          deviceId: deviceIdentity.deviceId,
+          clientId,
+          clientMode,
+          role,
+          scopes,
+          signedAtMs,
+          token: authToken,
+          nonce,
+          platform,
+          deviceFamily: '',
+        }),
+      ),
+      signedAt: signedAtMs,
+      nonce,
+    } : undefined;
+
+    const connectPayload = {
+      minProtocol: 3,
+      maxProtocol: 3,
+      role,
+      scopes,
+      auth: {
+        token: authToken,
+      },
+      client: {
+        id: clientId,
+        displayName: clientDisplayName,
+        version: '1.0.0',
+        mode: clientMode,
+        platform,
+      },
+      ...(device ? { device } : {}),
+    };
+
+    await client.request('connect', connectPayload, timeoutMs);
+    return client;
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    try {
+      this.ws.close();
+    } catch {
+      // no-op
+    }
+  }
+
+  async request(method, params, timeoutMs = this.timeoutMs) {
+    const id = crypto.randomUUID();
+    const frame = {
+      type: 'req',
+      id,
+      method,
+      params,
+    };
+
+    return await new Promise((resolve, reject) => {
+      if (this.closed) {
+        reject(new Error('gateway websocket already closed'));
+        return;
+      }
+
+      const timer = setTimeout(() => {
+        this.pendingById.delete(id);
+        reject(new Error(`gateway request timeout: ${method}`));
+      }, timeoutMs);
+
+      this.pendingById.set(id, {
+        resolve: (payload) => {
+          clearTimeout(timer);
+          resolve(payload);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+
+      try {
+        this.ws.send(JSON.stringify(frame));
+      } catch (error) {
+        clearTimeout(timer);
+        this.pendingById.delete(id);
+        reject(error);
+      }
+    });
+  }
+
+  async waitForEvent(predicate, timeoutMs = this.timeoutMs) {
+    return await new Promise((resolve, reject) => {
+      if (this.closed) {
+        reject(new Error('gateway websocket already closed'));
+        return;
+      }
+      const waiter = {
+        predicate,
+        resolve: (event) => {
+          clearTimeout(timer);
+          this.eventWaiters.delete(waiter);
+          resolve(event);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          this.eventWaiters.delete(waiter);
+          reject(error);
+        },
+      };
+      const timer = setTimeout(() => {
+        this.eventWaiters.delete(waiter);
+        reject(new Error('gateway event timeout'));
+      }, timeoutMs);
+      this.eventWaiters.add(waiter);
+    });
+  }
+
+  _handleFrame(data) {
+    let frame = null;
+    try {
+      const text = Buffer.isBuffer(data) ? data.toString('utf8') : `${data}`;
+      frame = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (!frame || typeof frame !== 'object') return;
+
+    if (frame.type === 'res') {
+      const id = `${frame.id || ''}`;
+      const pending = this.pendingById.get(id);
+      if (!pending) return;
+      this.pendingById.delete(id);
+      if (frame.ok) {
+        pending.resolve(frame.payload);
+      } else {
+        const detail = `${frame?.error?.message || 'gateway request failed'}`.trim();
+        pending.reject(new Error(detail || 'gateway request failed'));
+      }
+      return;
+    }
+
+    if (frame.type === 'event') {
+      for (const waiter of Array.from(this.eventWaiters)) {
+        let matched = false;
+        try {
+          matched = waiter.predicate(frame);
+        } catch {
+          matched = false;
+        }
+        if (matched) {
+          waiter.resolve(frame);
+        }
+      }
+    }
+  }
+}
+
+async function openWebSocket(wsUrl, timeoutMs) {
+  return await new Promise((resolve, reject) => {
+    const ws = new WebSocket(wsUrl);
+    const timer = setTimeout(() => {
+      try {
+        ws.close();
+      } catch {
+        // no-op
+      }
+      reject(new Error(`gateway websocket connect timeout: ${wsUrl}`));
+    }, Math.min(timeoutMs, 15000));
+
+    ws.once('open', () => {
+      clearTimeout(timer);
+      resolve(ws);
+    });
+    ws.once('error', (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+function toWebSocketUrl(baseUrl) {
+  const url = new URL(`${baseUrl}/`);
+  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+  if (!url.pathname || url.pathname === '') {
+    url.pathname = '/';
+  }
+  return url.toString();
+}
+
+function buildDeviceAuthPayloadV3({
+  deviceId,
+  clientId,
+  clientMode,
+  role,
+  scopes,
+  signedAtMs,
+  token,
+  nonce,
+  platform,
+  deviceFamily,
+}) {
+  const scopeText = Array.isArray(scopes) ? scopes.join(',') : '';
+  return [
+    'v3',
+    `${deviceId || ''}`.trim(),
+    `${clientId || ''}`.trim(),
+    `${clientMode || ''}`.trim(),
+    `${role || ''}`.trim(),
+    scopeText,
+    `${signedAtMs}`,
+    `${token || ''}`.trim(),
+    `${nonce || ''}`.trim(),
+    normalizeDeviceMetadataForAuth(platform),
+    normalizeDeviceMetadataForAuth(deviceFamily),
+  ].join('|');
+}
+
+function normalizeDeviceMetadataForAuth(value) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  if (!trimmed) return '';
+  return trimmed.replace(/[A-Z]/g, (char) =>
+    String.fromCharCode(char.charCodeAt(0) + 32),
+  );
+}
+
+function signDevicePayload(privateKeyPem, payload) {
+  const key = crypto.createPrivateKey(privateKeyPem);
+  const signature = crypto.sign(null, Buffer.from(payload, 'utf8'), key);
+  return base64UrlEncode(signature);
+}
+
+function publicKeyRawBase64UrlFromPem(publicKeyPem) {
+  const spki = crypto.createPublicKey(publicKeyPem).export({
+    type: 'spki',
+    format: 'der',
+  });
+  const ed25519SpkiPrefix = Buffer.from('302a300506032b6570032100', 'hex');
+  const raw =
+      spki.length === ed25519SpkiPrefix.length + 32 &&
+          spki.subarray(0, ed25519SpkiPrefix.length).equals(ed25519SpkiPrefix)
+        ? spki.subarray(ed25519SpkiPrefix.length)
+        : spki;
+  return base64UrlEncode(raw);
+}
+
+function base64UrlEncode(buf) {
+  return buf
+    .toString('base64')
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/=+$/g, '');
+}
+
+function extractTextFromChatPayload(message) {
+  if (!message || typeof message !== 'object') return '';
+  return toText(message.content ?? message.text ?? message.message ?? '').trim();
+}
+
+function extractLatestAssistantTextFromHistory(messages) {
+  const list = Array.isArray(messages) ? messages : [];
+  for (let i = list.length - 1; i >= 0; i -= 1) {
+    const item = list[i];
+    if (!item || typeof item !== 'object') continue;
+    const role = `${item.role || ''}`.trim().toLowerCase();
+    if (role !== 'assistant') continue;
+    const text = toText(item.content).trim();
+    if (text) return text;
+  }
+  return '';
+}
+
+function createConnectorError(statusCode, message) {
+  const error = new Error(message);
+  error.statusCode = statusCode;
+  return error;
+}
+
+function httpRequest({ url, method, headers, body, timeoutMs = DEFAULT_UPSTREAM_TIMEOUT_MS }) {
+  const transport = url.protocol === 'https:' ? https : http;
+
+  return new Promise((resolve, reject) => {
+    const request = transport.request(
+      url,
+      {
+        method,
+        headers,
+      },
+      (response) => {
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('end', () => {
+          resolve({
+            statusCode: response.statusCode || 502,
+            headers: sanitizeHeaders(response.headers),
+            body: Buffer.concat(chunks),
+          });
+        });
+      },
+    );
+
+    request.setTimeout(timeoutMs, () => {
+      const error = new Error(`upstream timeout after ${timeoutMs}ms`);
+      error.code = 'ETIMEDOUT';
+      request.destroy(error);
+    });
+
+    request.on('error', reject);
+    if (body?.length) {
+      request.write(body);
+    }
+    request.end();
+  });
+}
+
+async function forwardChatWithFallback({
+  openclawUrl,
+  requestedPath,
+  preferredPath,
+  candidatePaths,
+  upstreamTimeoutMs,
+  headers,
+  body,
+}) {
+  const paths = dedupePaths([
+    requestedPath,
+    preferredPath,
+    ...candidatePaths,
+    ...CHAT_PATH_FALLBACKS,
+  ]);
+  let lastResult = null;
+
+  for (const path of paths) {
+    const url = new URL(path, `${openclawUrl}/`);
+    const adaptedBody = adaptRequestBodyForPath(body, path);
+    let result;
+    try {
+      result = await httpRequest({
+        url,
+        method: 'POST',
+        headers,
+        body: adaptedBody,
+        timeoutMs: upstreamTimeoutMs,
+      });
+    } catch (error) {
+      if (isUpstreamTimeout(error)) {
+        return {
+          statusCode: 504,
+          headers: { 'content-type': 'application/json; charset=utf-8' },
+          body: Buffer.from(
+            JSON.stringify(
+              {
+                error: 'upstream_timeout',
+                message: `OpenClaw upstream timeout after ${upstreamTimeoutMs}ms`,
+                chatPath: path,
+              },
+              null,
+              2,
+            ),
+          ),
+          chatPath: path,
+        };
+      }
+      throw error;
+    }
+    if (result.statusCode !== 404) {
+      return { ...result, chatPath: path };
+    }
+    lastResult = { ...result, chatPath: path };
+  }
+
+  return (
+      lastResult || {
+        statusCode: 404,
+        headers: { 'content-type': 'application/json; charset=utf-8' },
+        body: Buffer.from(
+          JSON.stringify(
+            {
+              error: 'upstream_not_found',
+              message: 'No compatible upstream chat path was found.',
+            },
+            null,
+            2,
+          ),
+        ),
+        chatPath: requestedPath,
+      }
+  );
+}
+
+function isUpstreamTimeout(error) {
+  if (!error) return false;
+  const message = `${error.message || ''}`.toLowerCase();
+  return error.code === 'ETIMEDOUT' || message.includes('timeout');
+}
+
+function adaptRequestBodyForPath(body, path) {
+  if (normalizePath(path) !== '/v1/responses') {
+    return body;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body.toString('utf8'));
+  } catch {
+    return body;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return body;
+  }
+  if (parsed.input != null) {
+    return body;
+  }
+  return Buffer.from(JSON.stringify(toResponsesPayload(parsed)));
+}
+
+function toResponsesPayload(chatPayload) {
+  const messages = toMessageList(chatPayload.messages);
+  const instructions = firstSystemInstruction(messages);
+  const input = toResponsesInput(messages);
+  return {
+    model: chatPayload.model || 'openclaw',
+    stream: false,
+    ...(instructions ? { instructions } : {}),
+    input,
+    ...(chatPayload.metadata && typeof chatPayload.metadata === 'object' ?
+      { metadata: chatPayload.metadata } :
+      {}),
+  };
+}
+
+function toMessageList(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((item) => item && typeof item === 'object' && !Array.isArray(item));
+}
+
+function firstSystemInstruction(messages) {
+  for (const item of messages) {
+    const role = `${item.role || ''}`.trim().toLowerCase();
+    if (role !== 'system') continue;
+    const text = toText(item.content);
+    if (text) return text;
+  }
+  return '';
+}
+
+function toResponsesInput(messages) {
+  const list = [];
+  for (const item of messages) {
+    const role = `${item.role || ''}`.trim().toLowerCase();
+    if (role === 'system') continue;
+    const normalizedRole = role === 'assistant' ? 'assistant' : 'user';
+    const content = item.content;
+    if (Array.isArray(content)) {
+      list.push({
+        role: normalizedRole,
+        content,
+      });
+      continue;
+    }
+    const text = toText(content);
+    if (!text) continue;
+    list.push({
+      role: normalizedRole,
+      content: [
+        {
+          type: 'input_text',
+          text,
+        },
+      ],
+    });
+  }
+  if (list.length > 0) return list;
+  const fallback = messages.length ? toText(messages[messages.length - 1].content) : '';
+  return fallback;
+}
+
+function toText(value) {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) {
+    return value.map((part) => toText(part)).filter((part) => part.trim()).join('\n');
+  }
+  if (typeof value === 'object') {
+    return toText(value.text ?? value.content ?? value.value ?? value.output_text);
+  }
+  return `${value}`;
+}
+
+function sanitizeHeaders(headers) {
+  const next = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (value == null) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      next[key] = value.join(', ');
+    } else {
+      next[key] = value;
+    }
+  }
+  return next;
+}
+
+function normalizeChatMode(value) {
+  const mode = `${value || ''}`.trim().toLowerCase();
+  if (!mode) return DEFAULT_CHAT_MODE;
+  if (mode === 'gateway-session' || mode === 'http-proxy') {
+    return mode;
+  }
+  throw new Error(`Invalid chat-mode: ${value}. Use gateway-session or http-proxy.`);
+}
+
+function normalizeSessionSegment(value) {
+  const trimmed = `${value || ''}`.trim();
+  if (!trimmed) return 'main';
+  return trimmed.replace(/[^a-zA-Z0-9_-]/g, '-') || 'main';
+}
+
+function normalizeSessionKey(value) {
+  const trimmed = `${value || ''}`.trim();
+  if (!trimmed) return DEFAULT_SESSION_KEY;
+  return trimmed;
+}
+
+function stripTrailingSlash(value) {
+  return value.replace(/\/+$/, '');
+}
+
+function normalizePath(value) {
+  if (!value) {
+    return DEFAULT_CHAT_PATH;
+  }
+  const withLeading = value.startsWith('/') ? value : `/${value}`;
+  if (withLeading.length > 1 && withLeading.endsWith('/')) {
+    return withLeading.slice(0, -1);
+  }
+  return withLeading;
+}
+
+function dedupePaths(paths) {
+  const result = [];
+  const seen = new Set();
+  for (const path of paths) {
+    const normalized = normalizePath(path);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
+function isChatPathRequest(pathname, method, acceptedChatPaths) {
+  if (method !== 'POST') return false;
+  const normalized = normalizePath(pathname || '/');
+  return acceptedChatPaths.includes(normalized);
+}
+
+function detectLanAddress() {
+  return listLanCandidates()[0]?.address || '';
+}
+
+function listLanCandidates() {
+  const interfaces = os.networkInterfaces();
+  const candidates = [];
+
+  for (const [iface, addresses] of Object.entries(interfaces)) {
+    for (const item of addresses || []) {
+      if (item.family !== 'IPv4' || item.internal) {
+        continue;
+      }
+
+      const score = scoreLanCandidate(iface, item.address);
+      candidates.push({
+        iface,
+        address: item.address,
+        score,
+      });
+    }
+  }
+
+  candidates.sort((a, b) => b.score - a.score);
+  return candidates;
+}
+
+function scoreLanCandidate(iface, address) {
+  const name = iface.toLowerCase();
+  let score = 0;
+
+  if (isPrivateIpv4(address)) {
+    score += 60;
+  } else {
+    score += 5;
+  }
+
+  if (isSpecialUseIpv4(address)) {
+    score -= 180;
+  }
+
+  if (isBenchmarkOrDocumentationIpv4(address)) {
+    score -= 120;
+  }
+
+  if (
+    name.includes('wi-fi') ||
+    name.includes('wifi') ||
+    name.includes('wlan') ||
+    name.includes('wireless') ||
+    name.startsWith('en') ||
+    name.startsWith('wl')
+  ) {
+    score += 30;
+  }
+
+  if (name.includes('ethernet') || name.startsWith('eth')) {
+    score += 20;
+  }
+
+  if (
+    name.includes('virtual') ||
+    name.includes('vmware') ||
+    name.includes('vbox') ||
+    name.includes('hyper-v') ||
+    name.includes('docker') ||
+    name.includes('tailscale') ||
+    name.includes('zerotier') ||
+    name.includes('hamachi') ||
+    name.includes('clash') ||
+    name.includes('tun') ||
+    name.includes('tap') ||
+    name.includes('vpn') ||
+    name.includes('proxy') ||
+    name.includes('wireguard') ||
+    name.includes('wg') ||
+    name.includes('loopback') ||
+    name.includes('utun') ||
+    name.includes('veth')
+  ) {
+    score -= 100;
+  }
+
+  return score;
+}
+
+function isPrivateIpv4(address) {
+  if (address.startsWith('10.')) return true;
+  if (address.startsWith('192.168.')) return true;
+  if (/^172\.(1[6-9]|2\d|3[0-1])\./.test(address)) return true;
+  return false;
+}
+
+function parseIpv4(address) {
+  const parts = `${address || ''}`.trim().split('.');
+  if (parts.length !== 4) return null;
+  const octets = parts.map((part) => Number.parseInt(part, 10));
+  if (octets.some((part) => !Number.isFinite(part) || part < 0 || part > 255)) {
+    return null;
+  }
+  return octets;
+}
+
+function ipv4ToUInt32(octets) {
+  return (
+    (((octets[0] << 24) >>> 0) |
+      (octets[1] << 16) |
+      (octets[2] << 8) |
+      octets[3]) >>> 0
+  );
+}
+
+function isIpv4InCidr(address, baseAddress, prefixLength) {
+  const ip = parseIpv4(address);
+  const base = parseIpv4(baseAddress);
+  if (!ip || !base) return false;
+  if (prefixLength <= 0) return true;
+  if (prefixLength >= 32) return ipv4ToUInt32(ip) === ipv4ToUInt32(base);
+
+  const shift = 32 - prefixLength;
+  const mask = ((0xFFFFFFFF << shift) >>> 0);
+  return (
+    (ipv4ToUInt32(ip) & mask) === (ipv4ToUInt32(base) & mask)
+  );
+}
+
+function isBenchmarkOrDocumentationIpv4(address) {
+  return (
+    isIpv4InCidr(address, '198.18.0.0', 15) ||
+    isIpv4InCidr(address, '192.0.2.0', 24) ||
+    isIpv4InCidr(address, '198.51.100.0', 24) ||
+    isIpv4InCidr(address, '203.0.113.0', 24)
+  );
+}
+
+function isSpecialUseIpv4(address) {
+  return (
+    isBenchmarkOrDocumentationIpv4(address) ||
+    isIpv4InCidr(address, '100.64.0.0', 10) ||
+    isIpv4InCidr(address, '127.0.0.0', 8) ||
+    isIpv4InCidr(address, '169.254.0.0', 16) ||
+    isIpv4InCidr(address, '224.0.0.0', 4) ||
+    isIpv4InCidr(address, '240.0.0.0', 4) ||
+    isIpv4InCidr(address, '0.0.0.0', 8)
+  );
+}
+
+function printBanner(config) {
+  console.log('');
+  console.log('MateClaw Local OpenClaw Demo Connector');
+  console.log('======================================');
+  console.log(`Upstream OpenClaw : ${config.openclawUrl}`);
+  console.log(`Chat Mode         : ${config.chatMode}`);
+  console.log(`Session ID        : ${config.sessionKey}`);
+  console.log(`Chat Path         : ${config.chatPath}`);
+  console.log(`Accepted Paths    : ${config.acceptedChatPaths.join(', ')}`);
+  console.log(`Desktop Bind Host : ${config.listenHost}:${config.port}`);
+  console.log(`Mobile Access URL : ${config.baseUrl}`);
+  console.log(`Agent ID          : ${config.agentId}`);
+  console.log(`Token             : ${config.token}`);
+  console.log(`Expires At        : ${config.expiresAt.toISOString()}`);
+  console.log(`Upstream Timeout  : ${config.upstreamTimeoutMs}ms`);
+  console.log(
+    `Upstream Auth     : ${
+      config.upstreamToken ? `enabled (${config.upstreamToken.slice(0, 6)}...)` : 'disabled'
+    }`,
+  );
+  if (config.lanCandidates?.length) {
+    console.log('Detected IPv4 NICs:');
+    for (const item of config.lanCandidates) {
+      console.log(`  - ${item.address} (${item.iface}, score=${item.score})`);
+    }
+  }
+  console.log('');
+  console.log('FoloToy-style bind flow: install once -> scan the QR shown here -> chat.');
+  console.log('If binding fails, pin the LAN IP manually:');
+  console.log(
+    `  node ./src/cli.mjs install --lan-host ${config.lanHost || '<your-lan-ip>'} --port ${config.port}`,
+  );
+  console.log(`Quick health URL: ${config.baseUrl}/health`);
+  console.log('');
+  console.log('Scan this QR code in the MateClaw app (this is the OpenClaw-side bind QR):');
+  console.log('');
+  qrcode.generate(JSON.stringify(config.qrPayload), { small: true });
+  console.log('');
+  console.log('If QR scanning is inconvenient, copy this payload instead:');
+  console.log(JSON.stringify(config.qrPayload));
+  console.log('');
+}
+
+main().catch((error) => {
+  console.error(error.message || error);
+  process.exitCode = 1;
+});