@parall/openclaw-agent 1.28.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// Bootstrap wrapper for daemon-mode OpenClaw agents.
+// Sets up a per-agent OpenClaw state dir, writes openclaw.json with the
+// agent's credentials, installs the bundled plugin, then execs
+// `openclaw gateway run`. The daemon supervisor spawns one of these per
+// attached OpenClaw agent.
+import { execFileSync, spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ---------------------------------------------------------------------------
+// 1. Read + validate ENV
+// ---------------------------------------------------------------------------
+const PRLL_API_URL = env("PRLL_API_URL");
+const PRLL_API_KEY = env("PRLL_API_KEY");
+const PRLL_ORG_ID = env("PRLL_ORG_ID");
+const stateDir = env("PRLL_OPENCLAW_STATE_DIR");
+const PRLL_WS_URL = process.env.PRLL_WS_URL?.trim() || "";
+const PRLL_SWIMLANE_NAME = process.env.PRLL_SWIMLANE_NAME?.trim() || "";
+const gatewayPort = process.env.OPENCLAW_GATEWAY_PORT?.trim() || "0";
+const pluginArchive = process.env.PRLL_OPENCLAW_PLUGIN_ARCHIVE?.trim()
+    || "/opt/parall-plugin/parall-plugin.tgz";
+function env(name) {
+    const v = process.env[name]?.trim();
+    if (!v) {
+        console.error(`ERROR: Missing required environment variable: ${name}`);
+        process.exit(1);
+    }
+    return v;
+}
+// ---------------------------------------------------------------------------
+// 2. Create per-agent state directory
+// ---------------------------------------------------------------------------
+const openclawStateDir = path.join(stateDir, ".openclaw");
+const configPath = path.join(openclawStateDir, "openclaw.json");
+fs.mkdirSync(path.join(openclawStateDir, "sessions"), { recursive: true });
+fs.mkdirSync(path.join(openclawStateDir, "workspace"), { recursive: true });
+// ---------------------------------------------------------------------------
+// 3. Install plugin from bundled archive
+// ---------------------------------------------------------------------------
+if (fs.existsSync(pluginArchive)) {
+    // Clean legacy extension dir before install (only when we have an archive
+    // to replace it — otherwise the existing install is the only copy).
+    const legacyExtDir = path.join(openclawStateDir, "extensions", "parall");
+    fs.rmSync(legacyExtDir, { recursive: true, force: true });
+    console.log(`Installing Parall plugin from ${pluginArchive}...`);
+    try {
+        execFileSync("openclaw", [
+            "plugins", "install", pluginArchive,
+            "--force", "--dangerously-force-unsafe-install",
+        ], {
+            env: { ...process.env, OPENCLAW_STATE_DIR: openclawStateDir },
+            stdio: "inherit",
+            timeout: 60_000,
+        });
+    }
+    catch (err) {
+        console.error(`ERROR: Failed to install Parall plugin: ${String(err)}`);
+        process.exit(1);
+    }
+}
+else {
+    console.warn(`Plugin archive not found at ${pluginArchive} — assuming plugin is already installed.`);
+}
+// ---------------------------------------------------------------------------
+// 4. Write openclaw.json
+// ---------------------------------------------------------------------------
+writeOpenclawConfig();
+function writeOpenclawConfig() {
+    let cfg = {};
+    try {
+        cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    catch { /* fresh config */ }
+    const gateway = (cfg.gateway && typeof cfg.gateway === "object") ? cfg.gateway : {};
+    gateway.mode = "local";
+    cfg.gateway = gateway;
+    const channels = (cfg.channels && typeof cfg.channels === "object") ? cfg.channels : {};
+    const parallChannel = {
+        parall_url: PRLL_API_URL,
+        api_key: PRLL_API_KEY,
+        org_id: PRLL_ORG_ID,
+    };
+    if (PRLL_WS_URL)
+        parallChannel.ws_url = PRLL_WS_URL;
+    channels.parall = parallChannel;
+    cfg.channels = channels;
+    const plugins = (cfg.plugins && typeof cfg.plugins === "object") ? cfg.plugins : {};
+    const entries = (plugins.entries && typeof plugins.entries === "object") ? plugins.entries : {};
+    const parallPluginConfig = {
+        parall_url: PRLL_API_URL,
+        api_key: PRLL_API_KEY,
+        org_id: PRLL_ORG_ID,
+    };
+    if (PRLL_WS_URL)
+        parallPluginConfig.ws_url = PRLL_WS_URL;
+    const existingParall = (entries.parall && typeof entries.parall === "object") ? entries.parall : {};
+    entries.parall = {
+        ...existingParall,
+        enabled: true,
+        hooks: { allowPromptInjection: true, allowConversationAccess: true },
+        config: parallPluginConfig,
+    };
+    plugins.entries = entries;
+    cfg.plugins = plugins;
+    // sqlite-vec vector index guard
+    const agents = (cfg.agents && typeof cfg.agents === "object") ? cfg.agents : {};
+    const defaults = (agents.defaults && typeof agents.defaults === "object") ? agents.defaults : {};
+    const ms = (defaults.memorySearch && typeof defaults.memorySearch === "object") ? defaults.memorySearch : {};
+    const store = (ms.store && typeof ms.store === "object") ? ms.store : {};
+    const vector = (store.vector && typeof store.vector === "object") ? store.vector : {};
+    if (vector.enabled === undefined)
+        vector.enabled = true;
+    store.vector = vector;
+    ms.store = store;
+    defaults.memorySearch = ms;
+    agents.defaults = defaults;
+    cfg.agents = agents;
+    // Seed tools.alsoAllow
+    const tools = (cfg.tools && typeof cfg.tools === "object") ? cfg.tools : {};
+    const alsoAllow = new Set(Array.isArray(tools.alsoAllow) ? tools.alsoAllow : []);
+    alsoAllow.add("group:plugins");
+    tools.alsoAllow = Array.from(alsoAllow);
+    cfg.tools = tools;
+    const tmp = configPath + ".tmp";
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2));
+    fs.renameSync(tmp, configPath);
+}
+// ---------------------------------------------------------------------------
+// 5. Pre-seed platform config (model + provider) before gateway reads it
+// ---------------------------------------------------------------------------
+// On first boot openclaw.json has no agents.defaults.model. Without this,
+// OpenClaw uses its built-in default which may lack credentials through the
+// Parall proxy. The plugin refreshes this during startAccount but OpenClaw's
+// hot reload only reloads the model catalog, not the active model.
+await preseedPlatformConfig();
+async function preseedPlatformConfig() {
+    try {
+        const headers = { Authorization: `Bearer ${PRLL_API_KEY}` };
+        if (PRLL_SWIMLANE_NAME)
+            headers["X-Prll-Swimlane"] = PRLL_SWIMLANE_NAME;
+        const resp = await fetch(`${PRLL_API_URL}/api/v1/agents/platform-config`, {
+            headers,
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!resp.ok)
+            throw new Error(`platform-config ${resp.status}`);
+        const data = (await resp.json());
+        const pc = (data.config ?? data);
+        let cfg = {};
+        try {
+            cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        }
+        catch { /* fresh */ }
+        const ALLOWED_DEFAULTS = new Set(["model", "compaction", "memorySearch"]);
+        const platformDefaults = pc.agents?.defaults;
+        if (platformDefaults && typeof platformDefaults === "object") {
+            const agents = (cfg.agents && typeof cfg.agents === "object") ? cfg.agents : {};
+            const existing = (agents.defaults && typeof agents.defaults === "object") ? agents.defaults : {};
+            for (const [k, v] of Object.entries(platformDefaults)) {
+                if (ALLOWED_DEFAULTS.has(k))
+                    existing[k] = v;
+            }
+            agents.defaults = existing;
+            cfg.agents = agents;
+        }
+        const ALLOWED_MODEL_KEYS = new Set(["id", "name", "contextWindow", "maxTokens"]);
+        const platformModels = pc.models?.providers;
+        const platformParall = platformModels?.parall;
+        if (platformParall && typeof platformParall === "object") {
+            const models = (cfg.models && typeof cfg.models === "object") ? cfg.models : {};
+            const providers = (models.providers && typeof models.providers === "object") ? models.providers : {};
+            const existingParall = (providers.parall && typeof providers.parall === "object") ? providers.parall : {};
+            const merged = { ...existingParall, ...platformParall };
+            if (Array.isArray(merged.models)) {
+                merged.models = merged.models
+                    .filter((m) => m && typeof m === "object")
+                    .map((m) => {
+                    const clean = {};
+                    for (const [k, v] of Object.entries(m)) {
+                        if (ALLOWED_MODEL_KEYS.has(k))
+                            clean[k] = v;
+                    }
+                    return clean;
+                });
+            }
+            merged.apiKey = PRLL_API_KEY;
+            providers.parall = merged;
+            models.providers = providers;
+            cfg.models = models;
+        }
+        const tmp = configPath + ".tmp";
+        fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2));
+        fs.renameSync(tmp, configPath);
+        const model = cfg.agents?.defaults?.model ?? "none";
+        console.log(`Platform config pre-seeded (model: ${String(model)}).`);
+    }
+    catch (err) {
+        console.warn(`Platform config pre-seed skipped: ${String(err)}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// 6. openclaw doctor --fix (non-fatal)
+// ---------------------------------------------------------------------------
+try {
+    execFileSync("openclaw", ["doctor", "--fix"], {
+        env: { ...process.env, OPENCLAW_STATE_DIR: openclawStateDir },
+        stdio: "inherit",
+        timeout: 30_000,
+    });
+}
+catch { /* non-fatal */ }
+// ---------------------------------------------------------------------------
+// 7. Spawn openclaw gateway run with signal forwarding
+// ---------------------------------------------------------------------------
+console.log("Starting OpenClaw gateway...");
+const workspaceDir = process.env.PRLL_OPENCLAW_WORKSPACE_DIR?.trim() || "";
+const gatewayEnv = {
+    ...process.env,
+    OPENCLAW_STATE_DIR: openclawStateDir,
+};
+if (workspaceDir) {
+    gatewayEnv.PRLL_WIKI_MOUNT_ROOT = workspaceDir;
+}
+if (PRLL_SWIMLANE_NAME) {
+    gatewayEnv.PRLL_SWIMLANE_NAME = PRLL_SWIMLANE_NAME;
+}
+const gatewayArgs = ["gateway", "run"];
+if (gatewayPort !== "0") {
+    gatewayArgs.push("--port", gatewayPort);
+    gatewayEnv.OPENCLAW_GATEWAY_PORT = gatewayPort;
+}
+const cwd = workspaceDir || path.join(openclawStateDir, "workspace");
+fs.mkdirSync(cwd, { recursive: true });
+const child = spawn("openclaw", gatewayArgs, {
+    env: gatewayEnv,
+    cwd,
+    stdio: "inherit",
+    detached: false,
+});
+function forwardSignal(sig) {
+    try {
+        child.kill(sig);
+    }
+    catch { /* already gone */ }
+}
+process.on("SIGTERM", () => forwardSignal("SIGTERM"));
+process.on("SIGINT", () => forwardSignal("SIGINT"));
+child.on("close", (code, signal) => {
+    if (signal === "SIGTERM")
+        process.exit(143);
+    if (signal === "SIGINT")
+        process.exit(130);
+    process.exit(code ?? 1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@parall/openclaw-agent",
+  "version": "1.28.0",
+  "description": "OpenClaw bootstrap wrapper for daemon-mode Parall agents — sets up per-agent OpenClaw state and execs openclaw gateway run",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parall-hq/parall-mono",
+    "directory": "ts/openclaw-agent"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "parall-openclaw-agent": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "start": "node dist/index.js"
+  }
+}

package/src/index.ts

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+// Bootstrap wrapper for daemon-mode OpenClaw agents.
+// Sets up a per-agent OpenClaw state dir, writes openclaw.json with the
+// agent's credentials, installs the bundled plugin, then execs
+// `openclaw gateway run`. The daemon supervisor spawns one of these per
+// attached OpenClaw agent.
+
+import { execFileSync, spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// 1. Read + validate ENV
+// ---------------------------------------------------------------------------
+
+const PRLL_API_URL = env("PRLL_API_URL");
+const PRLL_API_KEY = env("PRLL_API_KEY");
+const PRLL_ORG_ID = env("PRLL_ORG_ID");
+const stateDir = env("PRLL_OPENCLAW_STATE_DIR");
+
+const PRLL_WS_URL = process.env.PRLL_WS_URL?.trim() || "";
+const PRLL_SWIMLANE_NAME = process.env.PRLL_SWIMLANE_NAME?.trim() || "";
+const gatewayPort = process.env.OPENCLAW_GATEWAY_PORT?.trim() || "0";
+const pluginArchive = process.env.PRLL_OPENCLAW_PLUGIN_ARCHIVE?.trim()
+  || "/opt/parall-plugin/parall-plugin.tgz";
+
+function env(name: string): string {
+  const v = process.env[name]?.trim();
+  if (!v) {
+    console.error(`ERROR: Missing required environment variable: ${name}`);
+    process.exit(1);
+  }
+  return v;
+}
+
+// ---------------------------------------------------------------------------
+// 2. Create per-agent state directory
+// ---------------------------------------------------------------------------
+
+const openclawStateDir = path.join(stateDir, ".openclaw");
+const configPath = path.join(openclawStateDir, "openclaw.json");
+
+fs.mkdirSync(path.join(openclawStateDir, "sessions"), { recursive: true });
+fs.mkdirSync(path.join(openclawStateDir, "workspace"), { recursive: true });
+
+// ---------------------------------------------------------------------------
+// 3. Install plugin from bundled archive
+// ---------------------------------------------------------------------------
+
+if (fs.existsSync(pluginArchive)) {
+  // Clean legacy extension dir before install (only when we have an archive
+  // to replace it — otherwise the existing install is the only copy).
+  const legacyExtDir = path.join(openclawStateDir, "extensions", "parall");
+  fs.rmSync(legacyExtDir, { recursive: true, force: true });
+
+  console.log(`Installing Parall plugin from ${pluginArchive}...`);
+  try {
+    execFileSync("openclaw", [
+      "plugins", "install", pluginArchive,
+      "--force", "--dangerously-force-unsafe-install",
+    ], {
+      env: { ...process.env, OPENCLAW_STATE_DIR: openclawStateDir },
+      stdio: "inherit",
+      timeout: 60_000,
+    });
+  } catch (err) {
+    console.error(`ERROR: Failed to install Parall plugin: ${String(err)}`);
+    process.exit(1);
+  }
+} else {
+  console.warn(
+    `Plugin archive not found at ${pluginArchive} — assuming plugin is already installed.`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 4. Write openclaw.json
+// ---------------------------------------------------------------------------
+
+writeOpenclawConfig();
+
+function writeOpenclawConfig(): void {
+  let cfg: Record<string, unknown> = {};
+  try {
+    cfg = JSON.parse(fs.readFileSync(configPath, "utf8")) as Record<string, unknown>;
+  } catch { /* fresh config */ }
+
+  const gateway = (cfg.gateway && typeof cfg.gateway === "object") ? cfg.gateway as Record<string, unknown> : {};
+  gateway.mode = "local";
+  cfg.gateway = gateway;
+
+  const channels = (cfg.channels && typeof cfg.channels === "object") ? cfg.channels as Record<string, unknown> : {};
+  const parallChannel: Record<string, unknown> = {
+    parall_url: PRLL_API_URL,
+    api_key: PRLL_API_KEY,
+    org_id: PRLL_ORG_ID,
+  };
+  if (PRLL_WS_URL) parallChannel.ws_url = PRLL_WS_URL;
+  channels.parall = parallChannel;
+  cfg.channels = channels;
+
+  const plugins = (cfg.plugins && typeof cfg.plugins === "object") ? cfg.plugins as Record<string, unknown> : {};
+  const entries = (plugins.entries && typeof plugins.entries === "object") ? plugins.entries as Record<string, unknown> : {};
+  const parallPluginConfig: Record<string, unknown> = {
+    parall_url: PRLL_API_URL,
+    api_key: PRLL_API_KEY,
+    org_id: PRLL_ORG_ID,
+  };
+  if (PRLL_WS_URL) parallPluginConfig.ws_url = PRLL_WS_URL;
+  const existingParall = (entries.parall && typeof entries.parall === "object") ? entries.parall as Record<string, unknown> : {};
+  entries.parall = {
+    ...existingParall,
+    enabled: true,
+    hooks: { allowPromptInjection: true, allowConversationAccess: true },
+    config: parallPluginConfig,
+  };
+  plugins.entries = entries;
+  cfg.plugins = plugins;
+
+  // sqlite-vec vector index guard
+  const agents = (cfg.agents && typeof cfg.agents === "object") ? cfg.agents as Record<string, unknown> : {};
+  const defaults = (agents.defaults && typeof agents.defaults === "object") ? agents.defaults as Record<string, unknown> : {};
+  const ms = (defaults.memorySearch && typeof defaults.memorySearch === "object") ? defaults.memorySearch as Record<string, unknown> : {};
+  const store = (ms.store && typeof ms.store === "object") ? ms.store as Record<string, unknown> : {};
+  const vector = (store.vector && typeof store.vector === "object") ? store.vector as Record<string, unknown> : {};
+  if (vector.enabled === undefined) vector.enabled = true;
+  store.vector = vector;
+  ms.store = store;
+  defaults.memorySearch = ms;
+  agents.defaults = defaults;
+  cfg.agents = agents;
+
+  // Seed tools.alsoAllow
+  const tools = (cfg.tools && typeof cfg.tools === "object") ? cfg.tools as Record<string, unknown> : {};
+  const alsoAllow = new Set<string>(
+    Array.isArray(tools.alsoAllow) ? (tools.alsoAllow as string[]) : [],
+  );
+  alsoAllow.add("group:plugins");
+  tools.alsoAllow = Array.from(alsoAllow);
+  cfg.tools = tools;
+
+  const tmp = configPath + ".tmp";
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2));
+  fs.renameSync(tmp, configPath);
+}
+
+// ---------------------------------------------------------------------------
+// 5. Pre-seed platform config (model + provider) before gateway reads it
+// ---------------------------------------------------------------------------
+// On first boot openclaw.json has no agents.defaults.model. Without this,
+// OpenClaw uses its built-in default which may lack credentials through the
+// Parall proxy. The plugin refreshes this during startAccount but OpenClaw's
+// hot reload only reloads the model catalog, not the active model.
+
+await preseedPlatformConfig();
+
+async function preseedPlatformConfig(): Promise<void> {
+  try {
+    const headers: Record<string, string> = { Authorization: `Bearer ${PRLL_API_KEY}` };
+    if (PRLL_SWIMLANE_NAME) headers["X-Prll-Swimlane"] = PRLL_SWIMLANE_NAME;
+
+    const resp = await fetch(`${PRLL_API_URL}/api/v1/agents/platform-config`, {
+      headers,
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!resp.ok) throw new Error(`platform-config ${resp.status}`);
+    const data = (await resp.json()) as Record<string, unknown>;
+    const pc = (data.config ?? data) as Record<string, unknown>;
+
+    let cfg: Record<string, unknown> = {};
+    try { cfg = JSON.parse(fs.readFileSync(configPath, "utf8")) as Record<string, unknown>; } catch { /* fresh */ }
+
+    const ALLOWED_DEFAULTS = new Set(["model", "compaction", "memorySearch"]);
+    const platformDefaults = (pc.agents as Record<string, unknown> | undefined)?.defaults;
+    if (platformDefaults && typeof platformDefaults === "object") {
+      const agents = (cfg.agents && typeof cfg.agents === "object") ? cfg.agents as Record<string, unknown> : {};
+      const existing = (agents.defaults && typeof agents.defaults === "object") ? agents.defaults as Record<string, unknown> : {};
+      for (const [k, v] of Object.entries(platformDefaults as Record<string, unknown>)) {
+        if (ALLOWED_DEFAULTS.has(k)) existing[k] = v;
+      }
+      agents.defaults = existing;
+      cfg.agents = agents;
+    }
+
+    const ALLOWED_MODEL_KEYS = new Set(["id", "name", "contextWindow", "maxTokens"]);
+    const platformModels = (pc.models as Record<string, unknown> | undefined)?.providers as Record<string, unknown> | undefined;
+    const platformParall = platformModels?.parall;
+    if (platformParall && typeof platformParall === "object") {
+      const models = (cfg.models && typeof cfg.models === "object") ? cfg.models as Record<string, unknown> : {};
+      const providers = (models.providers && typeof models.providers === "object") ? models.providers as Record<string, unknown> : {};
+      const existingParall = (providers.parall && typeof providers.parall === "object") ? providers.parall as Record<string, unknown> : {};
+      const merged = { ...existingParall, ...(platformParall as Record<string, unknown>) };
+      if (Array.isArray(merged.models)) {
+        merged.models = (merged.models as Record<string, unknown>[])
+          .filter((m) => m && typeof m === "object")
+          .map((m) => {
+            const clean: Record<string, unknown> = {};
+            for (const [k, v] of Object.entries(m)) {
+              if (ALLOWED_MODEL_KEYS.has(k)) clean[k] = v;
+            }
+            return clean;
+          });
+      }
+      merged.apiKey = PRLL_API_KEY;
+      providers.parall = merged;
+      models.providers = providers;
+      cfg.models = models;
+    }
+
+    const tmp = configPath + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2));
+    fs.renameSync(tmp, configPath);
+    const model = ((cfg.agents as Record<string, unknown> | undefined)?.defaults as Record<string, unknown> | undefined)?.model ?? "none";
+    console.log(`Platform config pre-seeded (model: ${String(model)}).`);
+  } catch (err) {
+    console.warn(`Platform config pre-seed skipped: ${String(err)}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 6. openclaw doctor --fix (non-fatal)
+// ---------------------------------------------------------------------------
+
+try {
+  execFileSync("openclaw", ["doctor", "--fix"], {
+    env: { ...process.env, OPENCLAW_STATE_DIR: openclawStateDir },
+    stdio: "inherit",
+    timeout: 30_000,
+  });
+} catch { /* non-fatal */ }
+
+// ---------------------------------------------------------------------------
+// 7. Spawn openclaw gateway run with signal forwarding
+
+// ---------------------------------------------------------------------------
+
+console.log("Starting OpenClaw gateway...");
+
+const workspaceDir = process.env.PRLL_OPENCLAW_WORKSPACE_DIR?.trim() || "";
+
+const gatewayEnv: NodeJS.ProcessEnv = {
+  ...process.env,
+  OPENCLAW_STATE_DIR: openclawStateDir,
+};
+if (workspaceDir) {
+  gatewayEnv.PRLL_WIKI_MOUNT_ROOT = workspaceDir;
+}
+if (PRLL_SWIMLANE_NAME) {
+  gatewayEnv.PRLL_SWIMLANE_NAME = PRLL_SWIMLANE_NAME;
+}
+
+const gatewayArgs = ["gateway", "run"];
+if (gatewayPort !== "0") {
+  gatewayArgs.push("--port", gatewayPort);
+  gatewayEnv.OPENCLAW_GATEWAY_PORT = gatewayPort;
+}
+
+const cwd = workspaceDir || path.join(openclawStateDir, "workspace");
+fs.mkdirSync(cwd, { recursive: true });
+
+const child = spawn("openclaw", gatewayArgs, {
+  env: gatewayEnv,
+  cwd,
+  stdio: "inherit",
+  detached: false,
+});
+
+function forwardSignal(sig: NodeJS.Signals): void {
+  try { child.kill(sig); } catch { /* already gone */ }
+}
+process.on("SIGTERM", () => forwardSignal("SIGTERM"));
+process.on("SIGINT", () => forwardSignal("SIGINT"));
+
+child.on("close", (code, signal) => {
+  if (signal === "SIGTERM") process.exit(143);
+  if (signal === "SIGINT") process.exit(130);
+  process.exit(code ?? 1);
+});