fix: load shell via openclaw-shell:// instead of file:// (blank window)

Chromium/Electron often fail to run Vite ES-module bundles from file:// even
without crossorigin. Register a privileged custom protocol mapping to the
unpacked renderer directory, load index via openclaw-shell://renderer/.

Extend gateway CSP frame-ancestors for this origin. Release 0.2.7.

Made-with: Cursor

Author: agentkernel

package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-desktop",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Community-maintained Windows desktop app and installer for OpenClaw.",
   "type": "module",
   "main": "out/main/index.js",

resources/bundle-manifest.json

@@ -1,4 +1,4 @@
 {
-  "shellVersion": "0.2.6",
+  "shellVersion": "0.2.7",
   "bundledOpenClawVersion": "2026.3.23-1"
 }

scripts/smoke/gateway-response-headers-smoke.ts

@@ -24,12 +24,12 @@ function testFrameAncestorsRelaxation(): void {
   const replaced = relaxGatewayFrameAncestors("default-src 'self'; frame-ancestors 'none'; script-src 'self'")
   assert.match(replaced, /default-src 'self';/)
   assert.match(replaced, /script-src 'self'/)
-  assert.match(replaced, /frame-ancestors 'self' file: http:\/\/localhost:\*/)
+  assert.match(replaced, /frame-ancestors 'self' file:.*http:\/\/localhost:\*/)
 
   const appended = relaxGatewayFrameAncestors("default-src 'self'")
   assert.equal(
     appended,
-    "default-src 'self'; frame-ancestors 'self' file: http://localhost:* http://127.0.0.1:* http://[::1]:* https://localhost:* https://127.0.0.1:* https://[::1]:*",
+    "default-src 'self'; frame-ancestors 'self' file: openclaw-shell://renderer http://localhost:* http://127.0.0.1:* http://[::1]:* https://localhost:* https://127.0.0.1:* https://[::1]:*",
   )
 
   const fromEmpty = relaxGatewayFrameAncestors('')
@@ -47,7 +47,7 @@ function testHeaderPatchForLoopbackResponse(): void {
   assert.equal((patched as Record<string, unknown>)['X-Frame-Options'], undefined)
   assert.equal(
     patched?.['Content-Security-Policy']?.[0],
-    "default-src 'self'; frame-ancestors 'self' file: http://localhost:* http://127.0.0.1:* http://[::1]:* https://localhost:* https://127.0.0.1:* https://[::1]:*",
+    "default-src 'self'; frame-ancestors 'self' file: openclaw-shell://renderer http://localhost:* http://127.0.0.1:* http://[::1]:* https://localhost:* https://127.0.0.1:* https://[::1]:*",
   )
   assert.deepEqual(patched?.Server, ['openclaw'])
 }

src/main/index.ts

@@ -27,6 +27,10 @@ import { patchGatewayResponseHeaders } from './security/gateway-response-headers
 import { rewriteGatewayRequestUrlWithToken } from './security/gateway-request-auth.js'
 import { listPendingFeishuPairing } from './pairing/index.js'
 import { resolveTrayLocale, getFeishuPairingNotificationStrings, formatFeishuPairingBody } from './tray/tray-i18n.js'
+import { registerShellFileProtocol, registerShellPrivileges } from './shell-protocol.js'
+
+/** Must run before app 'ready' so the shell can use openclaw-shell:// instead of file:// */
+registerShellPrivileges()
 
 process.on('uncaughtException', (error) => {
   if ((error as NodeJS.ErrnoException).code === 'EPIPE') return
@@ -117,6 +121,7 @@ app.whenReady().then(() => {
 
   Menu.setApplicationMenu(null) // Remove View, File, etc. menu bar
   initShellLog()
+  registerShellFileProtocol()
 
   // Allow Control UI to be embedded in our Shell iframe: OpenClaw sets X-Frame-Options: DENY
   // and frame-ancestors 'none', which would block the iframe. We intercept and relax these

src/main/security/gateway-response-headers.ts

@@ -1,7 +1,7 @@
 export const LOOPBACK_GATEWAY_HOSTS = new Set(['127.0.0.1', 'localhost', '::1'])
 
 export const RELAXED_GATEWAY_FRAME_ANCESTORS =
-  "frame-ancestors 'self' file: http://localhost:* http://127.0.0.1:* http://[::1]:* https://localhost:* https://127.0.0.1:* https://[::1]:*"
+  "frame-ancestors 'self' file: openclaw-shell://renderer http://localhost:* http://127.0.0.1:* http://[::1]:* https://localhost:* https://127.0.0.1:* https://[::1]:*"
 
 export type GatewayResponseHeadersInput = Record<string, string[] | string | undefined>
 export type GatewayResponseHeaders = Record<string, string[]>

src/main/shell-protocol.ts

@@ -0,0 +1,100 @@
+import { app, protocol } from 'electron'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+/** Custom scheme so the shell is not loaded via file:// (module/CORS/CSP edge cases on Windows). */
+export const SHELL_CUSTOM_SCHEME = 'openclaw-shell' as const
+export const SHELL_CUSTOM_HOST = 'renderer' as const
+
+let rendererRootCache: string | null = null
+
+function getShellRendererRootDir(): string {
+  if (app.isPackaged) {
+    const unpacked = path.join(process.resourcesPath, 'app.asar.unpacked', 'out', 'renderer')
+    if (fs.existsSync(unpacked)) return unpacked
+    return path.join(app.getAppPath(), 'out', 'renderer')
+  }
+  return path.join(__dirname, '../renderer')
+}
+
+function getShellRendererRootCached(): string {
+  if (!rendererRootCache) {
+    rendererRootCache = path.resolve(getShellRendererRootDir())
+  }
+  return rendererRootCache
+}
+
+/** Call before app 'ready' (Electron requirement). */
+export function registerShellPrivileges(): void {
+  protocol.registerSchemesAsPrivileged([
+    {
+      scheme: SHELL_CUSTOM_SCHEME,
+      privileges: {
+        standard: true,
+        secure: true,
+        supportFetchAPI: true,
+        corsEnabled: true,
+        stream: true,
+      },
+    },
+  ])
+}
+
+export function getShellIndexPageUrl(hash?: string): string {
+  const base = `${SHELL_CUSTOM_SCHEME}://${SHELL_CUSTOM_HOST}/index.html`
+  if (!hash) return base
+  const h = hash.startsWith('#') ? hash : `#${hash}`
+  return `${base}${h}`
+}
+
+export function isShellCustomProtocolUrl(rawUrl: string): boolean {
+  try {
+    const u = new URL(rawUrl)
+    return u.protocol === `${SHELL_CUSTOM_SCHEME}:` && u.hostname.toLowerCase() === SHELL_CUSTOM_HOST
+  } catch {
+    return false
+  }
+}
+
+/** Register after app 'ready', before creating BrowserWindows that load the shell. */
+export function registerShellFileProtocol(): void {
+  protocol.registerFileProtocol(SHELL_CUSTOM_SCHEME, (request, callback) => {
+    try {
+      const parsed = new URL(request.url)
+      if (parsed.protocol !== `${SHELL_CUSTOM_SCHEME}:`) {
+        callback({ error: -2 })
+        return
+      }
+      if (parsed.hostname.toLowerCase() !== SHELL_CUSTOM_HOST) {
+        callback({ error: -10 })
+        return
+      }
+      let pathname = decodeURIComponent(parsed.pathname)
+      if (pathname === '/' || pathname === '') {
+        pathname = '/index.html'
+      }
+      const relative = pathname.replace(/^\/+/, '')
+      if (relative.includes('..')) {
+        callback({ error: -10 })
+        return
+      }
+      const root = getShellRendererRootCached()
+      const filePath = path.resolve(path.join(root, relative))
+      const relToRoot = path.relative(root, filePath)
+      if (relToRoot.startsWith('..') || path.isAbsolute(relToRoot)) {
+        callback({ error: -10 })
+        return
+      }
+      if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory()) {
+        callback({ error: -6 })
+        return
+      }
+      callback({ path: filePath })
+    } catch {
+      callback({ error: -2 })
+    }
+  })
+}

src/main/window/manager.ts

@@ -1,10 +1,11 @@
 import { app, BrowserWindow, shell, nativeImage } from 'electron'
 import path from 'node:path'
 import fs from 'node:fs'
-import { fileURLToPath, pathToFileURL } from 'node:url'
+import { fileURLToPath } from 'node:url'
 import type { ShellConfig } from '../../shared/types.js'
 import { getLocalizedShellWindowTitle, normalizeToShellLocale } from '../../shared/shell-locale.js'
 import { logError, logInfo, logWarn } from '../utils/logger.js'
+import { getShellIndexPageUrl, isShellCustomProtocolUrl } from '../shell-protocol.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
@@ -111,6 +112,10 @@ function isAllowedNavigation(url: string, port: number): boolean {
     return true
   }
 
+  if (isShellCustomProtocolUrl(url)) {
+    return true
+  }
+
   if (isControlUIUrl(url, port)) {
     return true
   }
@@ -191,8 +196,7 @@ export class WindowManager {
     if (!app.isPackaged) {
       window.once('ready-to-show', showWhenReady)
     }
-    // When packaged: do NOT show on ready-to-show (would show bootstrap/black screen).
-    // Show only after the actual renderer (index.html) has loaded.
+    // When packaged: show only after shell URL has finished loading (see loadURL().then).
 
     let loadErrorShown = false
     const showLoadError = (title: string, detail: string) => {
@@ -217,49 +221,35 @@ export class WindowManager {
 
     if (process.env.ELECTRON_RENDERER_URL) {
       void window.loadURL(process.env.ELECTRON_RENDERER_URL).then(openDevToolsIfRequested)
-    } else if (app.isPackaged) {
+    } else {
       const rendererPath = getRendererIndexPath()
-      const rendererCandidates = getPackagedRendererCandidates()
-      logInfo(
-        `[OpenClaw] Packaged: rendererPath=${rendererPath} candidates=${JSON.stringify(
-          rendererCandidates,
-        )} exists=${JSON.stringify(rendererCandidates.map((p) => fs.existsSync(p)))}`
-      )
-      const bootstrapHtml =
-        `<!DOCTYPE html><html><head><meta charset="utf-8"><title>${escapeHtml(initialTitle)}</title></head><body style="margin:0;background:transparent;"></body></html>`
+      const shellUrl = getShellIndexPageUrl()
+      if (app.isPackaged) {
+        const rendererCandidates = getPackagedRendererCandidates()
+        logInfo(
+          `[OpenClaw] Packaged: shellUrl=${shellUrl} rendererPath=${rendererPath} candidates=${JSON.stringify(
+            rendererCandidates,
+          )} exists=${JSON.stringify(rendererCandidates.map((p) => fs.existsSync(p)))}`
+        )
+      } else {
+        logInfo(`[OpenClaw] Dev build: shellUrl=${shellUrl} rendererPath=${rendererPath}`)
+      }
       void window
-        .loadURL('data:text/html;charset=utf-8,' + encodeURIComponent(bootstrapHtml))
+        .loadURL(shellUrl)
         .then(() => {
           openDevToolsIfRequested()
-          if (window.isDestroyed()) return
-          void window
-            .loadFile(rendererPath)
-            .then(() => {
-              if (!window.isDestroyed()) showWhenReady()
-            })
-            .catch((err) => {
-              logError(`[OpenClaw] Failed to load renderer: ${rendererPath} ${(err instanceof Error ? err.message : String(err))}`)
-              showLoadError(
-                'Renderer load failed',
-                `Path: ${rendererPath}\n\nError: ${err instanceof Error ? err.message : String(err)}\n\n` +
-                  `Check that dist\\win-unpacked\\resources\\app.asar.unpacked\\out\\renderer or resources\\app.asar\\out\\renderer exists.`,
-              )
-              if (!window.isDestroyed()) showWhenReady()
-            })
-        })
-        .catch(() => {
-          showLoadError('Bootstrap failed', 'Unable to load bootstrap page')
           if (!window.isDestroyed()) showWhenReady()
         })
-    } else {
-      const rendererPath = getRendererIndexPath()
-      void window
-        .loadFile(rendererPath)
-        .then(openDevToolsIfRequested)
         .catch((err) => {
-          logError(`[OpenClaw] Failed to load renderer: ${rendererPath} ${(err instanceof Error ? err.message : String(err))}`)
-          const msg = err instanceof Error ? err.message : String(err)
-          showLoadError('Renderer load failed', `Path: ${rendererPath}\nError: ${msg}`)
+          logError(
+            `[OpenClaw] Failed to load shell URL: ${shellUrl} ${err instanceof Error ? err.message : String(err)}`,
+          )
+          showLoadError(
+            'Renderer load failed',
+            `URL: ${shellUrl}\nPath: ${rendererPath}\n\nError: ${err instanceof Error ? err.message : String(err)}\n\n` +
+              `Check that out\\renderer (or app.asar.unpacked\\out\\renderer) contains index.html and assets.`,
+          )
+          if (!window.isDestroyed()) showWhenReady()
         })
     }
 
@@ -289,7 +279,12 @@ export class WindowManager {
         return
       }
 
-      if (validatedURL && (validatedURL.startsWith('file:') || validatedURL.startsWith('data:'))) {
+      if (
+        validatedURL &&
+        (validatedURL.startsWith('file:') ||
+          validatedURL.startsWith('data:') ||
+          isShellCustomProtocolUrl(validatedURL))
+      ) {
         const title = 'Page load failed (did-fail-load)'
         const detail = `code: ${errorCode}\ndescription: ${errorDescription}\nurl: ${url}`
         showLoadError(title, detail)
@@ -328,6 +323,7 @@ export class WindowManager {
     const currentUrl = window.webContents.getURL()
     const canPatchHash =
       (currentUrl.startsWith('file:') && !currentUrl.startsWith('data:')) ||
+      isShellCustomProtocolUrl(currentUrl) ||
       (!!process.env.ELECTRON_RENDERER_URL && currentUrl.startsWith('http'))
 
     if (canPatchHash) {
@@ -350,9 +346,7 @@ export class WindowManager {
       void window.loadURL(`${base}${safeHash}`)
       return
     }
-    const rendererPath = getRendererIndexPath()
-    const fileUrl = pathToFileURL(rendererPath).href + safeHash
-    void window.loadURL(fileUrl)
+    void window.loadURL(getShellIndexPageUrl(safeHash))
   }
 
   showErrorPage(title: string, detail: string): void {