feat: externalize dev runtime ownership

Author: PerishCode

TASK.md

@@ -0,0 +1,86 @@
+# Handoff Notes
+
+## Branch
+
+- Current branch: `feat/local-dev-workflow-optimization`
+- Branch pushed to: `origin/feat/local-dev-workflow-optimization`
+- Latest commit from before this session: `01bd29a` `refactor: clarify scripts dev module boundaries`
+- Workspace status at handoff: code changes for desktop/controller/scripts-dev integration plus this `TASK.md` update
+
+## What Changed In This Session
+
+### Desktop runtime ownership was split into `external | internal`
+
+- `apps/desktop/shared/runtime-config.ts` now exposes `runtimeMode: "external" | "internal"`
+- `apps/desktop/main/platforms/shared/runtime-common.ts` now has an external runtime adapter path
+- `apps/desktop/main/platforms/index.ts` selects an external adapter when desktop is launched in external mode
+- `apps/desktop/main/runtime/manifests.ts` marks `web`, `controller`, and `openclaw` runtime units as `external` when desktop is attaching instead of owning processes
+- `apps/desktop/main/runtime/daemon-supervisor.ts` now probes external runtime units by port and reports external availability state instead of trying to manage them
+- `apps/desktop/main/index.ts` logs the effective desktop runtime mode and the external runtime targets during cold start
+
+### Controller OpenClaw ownership was split into `external | internal`
+
+- `apps/controller/src/app/env.ts` now accepts:
+  - `NEXU_CONTROLLER_OPENCLAW_MODE=external|internal`
+  - `OPENCLAW_BASE_URL`
+  - `OPENCLAW_LOG_DIR`
+- Legacy `RUNTIME_MANAGE_OPENCLAW_PROCESS` is now treated as a compatibility input; the effective owner is derived from the explicit mode when present
+- `apps/controller/src/runtime/gateway-client.ts`, `apps/controller/src/runtime/runtime-health.ts`, and `apps/controller/src/runtime/openclaw-ws-client.ts` now connect through `OPENCLAW_BASE_URL` instead of hard-coded `127.0.0.1:${port}`
+- `apps/controller/src/app/bootstrap.ts` now logs the runtime contract and only starts OpenClaw when controller is in `internal` mode
+- `apps/controller/src/services/model-provider-service.ts` and `apps/controller/src/services/desktop-local-service.ts` now skip runtime restarts when controller is attached to an external OpenClaw instance
+- `apps/controller/src/runtime/openclaw-process.ts` now exposes `managesProcess()` so ownership checks are explicit at call sites
+
+### `scripts/dev` now owns OpenClaw local-dev startup
+
+- Added `scripts/dev/src/shared/dev-runtime-config.ts`
+  - reads `scripts/dev/.env` when present
+  - defines the cross-service local-dev contract for ports, URLs, state dirs, config path, log dir, and gateway token
+- Added `scripts/dev/.env.example` as the source-of-truth example for dev-only external injection
+- Added `scripts/dev/src/services/openclaw.ts`
+- Added `scripts/dev/src/supervisors/openclaw.ts`
+- Updated `scripts/dev/src/index.ts` so `pnpm dev start|restart|stop|status|logs` now includes `openclaw`
+- Updated existing `scripts/dev` controller/web assembly to consume injected values from `scripts/dev/.env` instead of assuming only hard-coded defaults
+
+### Small controller-chain robustness fix
+
+- `apps/controller/src/runtime/openclaw-config-writer.ts` now derives a fallback state dir from `openclawConfigPath` when the full env shape is not present, which fixed the related config-writer regression in tests
+
+## Validation Already Done
+
+- `pnpm --filter @nexu/desktop typecheck` passed
+- `pnpm --filter @nexu/desktop build` passed earlier in the session after the desktop external-runtime split
+- `pnpm --filter @nexu/controller typecheck` passed
+- `pnpm --filter @nexu/controller build` passed
+- `pnpm --dir ./scripts/dev exec tsc --noEmit` passed
+- Root-entrypoint local-dev acceptance for the current three-service flow passed:
+  - `pnpm dev status`
+  - `pnpm dev start`
+  - `pnpm dev status`
+  - `pnpm dev logs openclaw`
+  - `pnpm dev logs controller`
+  - `pnpm dev restart`
+  - `pnpm dev stop`
+  - `pnpm dev status`
+- Verified controller now boots in `external` OpenClaw mode and successfully reaches `openclaw_ws_connected` through the `scripts/dev`-managed OpenClaw process
+
+## Important Current Behavior
+
+- OpenClaw local dev is now expected to be orchestrated by `scripts/dev`, not by its own dedicated `.env`
+- `scripts/dev/.env` is intended to become the single dev-only source of truth for cross-service injected runtime values
+- Controller local dev is already consuming OpenClaw through that external contract when launched via `scripts/dev`
+- Desktop code is prepared for the same external-runtime shape, but desktop is not yet wired into `scripts/dev`
+
+## Known Existing Issues
+
+- `pnpm lint` still fails due to pre-existing repo-wide Biome formatting issues unrelated to this branch
+- `pnpm --filter @nexu/controller test` still has pre-existing failures not introduced by this session:
+  - `tests/nexu-config-store.test.ts`
+  - `tests/openclaw-sync.test.ts`
+  - `tests/openclaw-runtime-plugin-writer.test.ts` (Windows symlink permission issue)
+- Desktop is not yet started/stopped through `scripts/dev`; only `openclaw + controller + web` are wired today
+
+## Suggested Next Steps
+
+1. Wire `desktop` into `scripts/dev` using the same `scripts/dev/.env` contract and `NEXU_DESKTOP_RUNTIME_MODE=external`
+2. Decide whether to expand `pnpm dev` into explicit single-service targeting like `pnpm dev start openclaw` / `pnpm dev stop controller`
+3. Continue tightening the `scripts/dev/.env` contract so every external injection is documented, named consistently, and traced to a single owner

apps/controller/src/app/bootstrap.ts

@@ -1,8 +1,20 @@
+import { logger } from "../lib/logger.js";
 import type { ControllerContainer } from "./container.js";
 
 export async function bootstrapController(
   container: ControllerContainer,
 ): Promise<() => void> {
+  logger.info(
+    {
+      openclawOwnershipMode: container.env.openclawOwnershipMode,
+      openclawBaseUrl: container.env.openclawBaseUrl,
+      openclawConfigPath: container.env.openclawConfigPath,
+      openclawStateDir: container.env.openclawStateDir,
+      openclawLogDir: container.env.openclawLogDir,
+    },
+    "controller_bootstrap_runtime_contract",
+  );
+
   // Run independent prep tasks in parallel to shave off startup time.
   // All three are independent: process cleanup, plugin files, cloud model fetch.
   await Promise.all([
@@ -28,8 +40,12 @@ export async function bootstrapController(
   // restarts from async setup (cloud connect, model selection, bot creation).
   container.openclawSyncService.beginSettling();
 
-  container.openclawProcess.enableAutoRestart();
-  container.openclawProcess.start();
+  if (container.openclawProcess.managesProcess()) {
+    container.openclawProcess.enableAutoRestart();
+    container.openclawProcess.start();
+  } else {
+    logger.info({}, "controller_bootstrap_attaching_external_openclaw");
+  }
   container.channelFallbackService.start();
 
   // Start WS client — connects to OpenClaw gateway

apps/controller/src/app/container.ts

@@ -69,12 +69,10 @@ export interface ControllerContainer {
 export async function createContainer(): Promise<ControllerContainer> {
   const configStore = new NexuConfigStore(env);
   await configStore.reconcileConfiguredDesktopCloudState();
-  if (env.manageOpenclawProcess) {
-    await configStore.syncManagedRuntimeGateway({
-      port: env.openclawGatewayPort,
-      authMode: env.openclawGatewayToken ? "token" : "none",
-    });
-  }
+  await configStore.syncManagedRuntimeGateway({
+    port: env.openclawGatewayPort,
+    authMode: env.openclawGatewayToken ? "token" : "none",
+  });
   const artifactsStore = new ArtifactsStore(env);
   const compiledStore = new CompiledOpenClawStore(env);
   const configWriter = new OpenClawConfigWriter(env);

apps/controller/src/app/env.ts

@@ -36,15 +36,52 @@ const booleanSchema = z
   .enum(["true", "false", "1", "0"])
   .transform((value) => value === "true" || value === "1");
 
+const openclawOwnershipModeSchema = z.enum(["external", "internal"]);
+
+function parseUrlPort(value: string): number | null {
+  try {
+    const url = new URL(value);
+    if (url.port.length > 0) {
+      return Number.parseInt(url.port, 10);
+    }
+
+    if (url.protocol === "https:") {
+      return 443;
+    }
+
+    if (url.protocol === "http:") {
+      return 80;
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function readOpenclawOwnershipMode(input: {
+  explicitMode?: "external" | "internal";
+  legacyManageProcess: boolean;
+}): "external" | "internal" {
+  if (input.explicitMode) {
+    return input.explicitMode;
+  }
+
+  return input.legacyManageProcess ? "internal" : "external";
+}
+
 const envSchema = z.object({
   NODE_ENV: z
     .enum(["development", "test", "production"])
     .default("development"),
   PORT: z.coerce.number().int().positive().default(3010),
   HOST: z.string().default("127.0.0.1"),
   NEXU_HOME: z.string().default("~/.nexu"),
+  NEXU_CONTROLLER_OPENCLAW_MODE: openclawOwnershipModeSchema.optional(),
+  OPENCLAW_BASE_URL: z.string().url().optional(),
   OPENCLAW_STATE_DIR: z.string().optional(),
   OPENCLAW_CONFIG_PATH: z.string().optional(),
+  OPENCLAW_LOG_DIR: z.string().optional(),
   OPENCLAW_SKILLS_DIR: z.string().optional(),
   SKILLHUB_STATIC_SKILLS_DIR: z.string().optional(),
   PLATFORM_TEMPLATES_DIR: z.string().optional(),
@@ -64,6 +101,15 @@ const envSchema = z.object({
 });
 
 const parsed = envSchema.parse(process.env);
+const openclawOwnershipMode = readOpenclawOwnershipMode({
+  explicitMode: parsed.NEXU_CONTROLLER_OPENCLAW_MODE,
+  legacyManageProcess: parsed.RUNTIME_MANAGE_OPENCLAW_PROCESS,
+});
+const openclawBaseUrl =
+  parsed.OPENCLAW_BASE_URL ??
+  `http://127.0.0.1:${String(parsed.OPENCLAW_GATEWAY_PORT)}`;
+const openclawGatewayPort =
+  parseUrlPort(openclawBaseUrl) ?? parsed.OPENCLAW_GATEWAY_PORT;
 
 const nexuHomeDir = expandHomeDir(parsed.NEXU_HOME);
 const openclawStateDir = expandHomeDir(
@@ -119,12 +165,17 @@ export const env = {
     openclawStateDir,
     "workspace-templates",
   ),
+  openclawOwnershipMode,
+  openclawBaseUrl,
   openclawBin: parsed.OPENCLAW_BIN,
+  openclawLogDir: expandHomeDir(
+    parsed.OPENCLAW_LOG_DIR ?? path.join(nexuHomeDir, "logs", "openclaw"),
+  ),
   litellmBaseUrl: parsed.LITELLM_BASE_URL ?? null,
   litellmApiKey: parsed.LITELLM_API_KEY ?? null,
-  openclawGatewayPort: parsed.OPENCLAW_GATEWAY_PORT,
+  openclawGatewayPort,
   openclawGatewayToken: parsed.OPENCLAW_GATEWAY_TOKEN,
-  manageOpenclawProcess: parsed.RUNTIME_MANAGE_OPENCLAW_PROCESS,
+  manageOpenclawProcess: openclawOwnershipMode === "internal",
   gatewayProbeEnabled: parsed.RUNTIME_GATEWAY_PROBE_ENABLED,
   runtimeSyncIntervalMs: parsed.RUNTIME_SYNC_INTERVAL_MS,
   runtimeHealthIntervalMs: parsed.RUNTIME_HEALTH_INTERVAL_MS,

apps/controller/src/runtime/gateway-client.ts

@@ -4,10 +4,7 @@ export class GatewayClient {
   constructor(private readonly env: ControllerEnv) {}
 
   async fetchJson<T>(pathname: string): Promise<T> {
-    const url = new URL(
-      pathname,
-      `http://127.0.0.1:${this.env.openclawGatewayPort}`,
-    );
+    const url = new URL(pathname, this.env.openclawBaseUrl);
     const response = await fetch(url, {
       headers: this.env.openclawGatewayToken
         ? { Authorization: `Bearer ${this.env.openclawGatewayToken}` }

apps/controller/src/runtime/openclaw-config-writer.ts

@@ -51,6 +51,10 @@ async function syncWeixinAccountIndex(
   );
 }
 
+function resolveOpenclawStateDir(env: ControllerEnv): string {
+  return env.openclawStateDir ?? path.dirname(env.openclawConfigPath);
+}
+
 export class OpenClawConfigWriter {
   /** Last successfully written content — used to skip redundant writes. */
   private lastWrittenContent: string | null = null;
@@ -100,7 +104,7 @@ export class OpenClawConfigWriter {
     this.lastWrittenContent = content;
 
     // Sync weixin account index for openclaw-weixin plugin compatibility
-    await syncWeixinAccountIndex(this.env.openclawStateDir, config);
+    await syncWeixinAccountIndex(resolveOpenclawStateDir(this.env), config);
 
     const configStat = await stat(this.env.openclawConfigPath);
     logger.info(

apps/controller/src/runtime/openclaw-process.ts

@@ -36,6 +36,10 @@ export class OpenClawProcessManager {
 
   constructor(private readonly env: ControllerEnv) {}
 
+  managesProcess(): boolean {
+    return this.env.manageOpenclawProcess;
+  }
+
   async prepare(): Promise<void> {
     if (!this.env.manageOpenclawProcess) {
       return;

apps/controller/src/runtime/openclaw-ws-client.ts

@@ -141,6 +141,12 @@ function buildDeviceAuthPayloadV3(params: {
   ].join("|");
 }
 
+function toGatewayWsUrl(baseUrl: string): string {
+  const url = new URL(baseUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.toString().replace(/\/$/, "");
+}
+
 // ---------------------------------------------------------------------------
 // Protocol types (subset of openclaw/src/gateway/protocol)
 // ---------------------------------------------------------------------------
@@ -204,7 +210,7 @@ export class OpenClawWsClient {
   private readonly deviceIdentity: DeviceIdentity;
 
   constructor(env: ControllerEnv) {
-    this.url = `ws://127.0.0.1:${env.openclawGatewayPort}`;
+    this.url = toGatewayWsUrl(env.openclawBaseUrl);
     this.token = env.openclawGatewayToken ?? "";
     this.deviceIdentity = loadOrCreateDeviceIdentity(
       path.join(env.openclawStateDir, "identity", "device.json"),

apps/controller/src/runtime/runtime-health.ts

@@ -10,7 +10,7 @@ export class RuntimeHealth {
 
     try {
       const response = await fetch(
-        `http://127.0.0.1:${this.env.openclawGatewayPort}/health`,
+        new URL("/health", this.env.openclawBaseUrl),
       );
       return {
         ok: response.ok,

apps/controller/src/services/desktop-local-service.ts

@@ -1,3 +1,4 @@
+import { logger } from "../lib/logger.js";
 import type { OpenClawProcessManager } from "../runtime/openclaw-process.js";
 import type { NexuConfigStore } from "../store/nexu-config-store.js";
 import type { ModelProviderService } from "./model-provider-service.js";
@@ -87,6 +88,14 @@ export class DesktopLocalService {
   }
 
   async restartRuntime(): Promise<void> {
+    if (!this.openclawProcess.managesProcess()) {
+      logger.info(
+        {},
+        "desktop_local_runtime_restart_skipped_external_openclaw",
+      );
+      return;
+    }
+
     await this.openclawProcess.stop();
     this.openclawProcess.enableAutoRestart();
     this.openclawProcess.start();