Related Issues

This is a continuation of a known problem that has been partially fixed but not fully resolved:

• Issue #5533 (Jan 2026) — Reported that config modifications unconditionally trigger SIGUSR1 even when restart is disabled. Fixed by PR #13408 (fix(gateway): skip SIGUSR1 restart in config.patch for noop reload rules), which skipped SIGUSR1 for no-op changes.
• Issue #20245 (Feb 2026) — Reported that agent-initiated config.patch calls bypass restart protection. Fixed by PR #20355 (fix(gateway): respect commands.restart guard in config.patch and config.apply), which added guard checks.

Despite these fixes, the March 2026 release still crashes the gateway when config.patch modifies paths that are explicitly hot-reloadable per BASE_RELOAD_RULES (e.g., browser.profiles.*). The previous PRs addressed no-op changes and commands.restart guards, but did not address the case where changedPaths match hot-reload rules — the RPC handler still unconditionally calls scheduleGatewaySigusr1Restart() regardless of whether the reload system can handle the change without a restart.

Context

We are building a sandbox skill (novita-sandbox) that runs browser operations and untrusted code in isolated Firecracker microVMs. For browser use cases, the ideal workflow is:

1. Create a browser-chromium sandbox (Chromium + CDP on port 9223)
2. Use config.patch to set browser.profiles.sandbox.cdpUrl pointing to the sandbox's CDP endpoint
3. Use OpenClaw's native browser tool with the sandbox profile — full interactive capabilities (snapshot, click, fill, navigate) running safely inside the isolated VM

This pattern is powerful because it gives OpenClaw's browser tool full functionality while completely isolating it from the user's local network (preventing SSRF, local file access, etc.).

The Problem

Every config.patch call crashes the gateway, regardless of what config path is changed and regardless of the gateway.reload setting.

Root Cause

In gateway-cli-C2ZZYgwu.js, the config.patch RPC handler unconditionally calls scheduleGatewaySigusr1Restart() after writing the config:

// Line 12912-12922 in gateway-cli-C2ZZYgwu.js
const sentinelPath = await tryWriteRestartSentinelPayload(payload);
const restart = scheduleGatewaySigusr1Restart({
    delayMs: restartDelayMs,
    reason: "config.patch",
    audit: {
        actor: actor.actor,
        deviceId: actor.deviceId,
        clientIp: actor.clientIp,
        changedPaths
    }
});

This triggers the following chain in restart-C7ane9OU.js:

scheduleGatewaySigusr1Restart()
  → authorizeGatewaySigusr1Restart()    // sets sigusr1AuthorizedCount += 1
  → (delay ~8-10s)
  → emitGatewayRestart()
    → process.emit("SIGUSR1")

onSigusr1 handler:
  → consumeGatewaySigusr1RestartAuthorization()  // finds authorized count > 0, returns true
  → request("restart", "SIGUSR1")                // gateway dies

This path is completely independent of the reload mode system. The reload logic (BASE_RELOAD_RULES) correctly classifies browser.* as kind: "hot" with action restart-browser-control — and in fact the hot reload succeeds before the SIGUSR1 kills the process:

14:55:52 [reload] config hot reload applied (browser.profiles.sandbox.cdpUrl)   ← SUCCESS
14:56:00 [gateway] signal SIGUSR1 received                                       ← KILLED
14:56:01 [gateway] restart mode: full process restart (supervisor restart)

What we tried

We initially assumed gateway.reload: "hot" would prevent the restart (since the reload rules correctly handle browser.* as hot-reloadable). Through multiple iterations we discovered:

1. Default "hybrid" mode — gateway crashes after config.patch ❌
2. Setting gateway.reload: "hot" via config.patch — the config.patch itself crashes the gateway before the setting takes effect ❌
3. Manually editing openclaw.json to set gateway.reload: "hot", then using config.patch for browser.profiles.* — hot reload succeeds, but SIGUSR1 still fires 8 seconds later and kills the process ❌

The SIGUSR1 restart is a completely separate code path from the reload mode evaluation. gateway.reload: "hot" only affects the config file watcher's reload plan (plan.restartGateway is logged but ignored in hot mode) — it does NOT affect the scheduleGatewaySigusr1Restart called explicitly by the config.patch handler.

Impact

• Any skill or tool that uses config.patch will crash the gateway when run without a supervisor (e.g., openclaw gateway run in foreground/nohup)
• Even with a supervisor, every config.patch causes an unnecessary full restart, disrupting active agent sessions
• This makes it impossible for skills to dynamically configure browser profiles, which is a key use case for sandbox-based browsing

Proposal

PR #13408 skipped SIGUSR1 for no-op changes, and PR #20355 added commands.restart guards. The missing piece is: config.patch should also skip SIGUSR1 when all changed paths are hot-reloadable per BASE_RELOAD_RULES. The reload system already handles these changes correctly — the SIGUSR1 is redundant and destructive.

Suggested approaches:

Option A: Check reload rules before scheduling restart

// After writing config, evaluate if restart is actually needed
const plan = evaluateReloadPlan(changedPaths); // uses BASE_RELOAD_RULES
if (plan.restartGateway) {
    scheduleGatewaySigusr1Restart({ ... });
} else {
    // Hot reload already handled by the config watcher / reload system
    // No SIGUSR1 needed
}

Option B: Skip SIGUSR1 for hot-reloadable paths

const hotReloadablePrefixes = ['browser.', 'meta.'];  // from BASE_RELOAD_RULES
const allHot = changedPaths.every(p => hotReloadablePrefixes.some(prefix => p.startsWith(prefix)));
if (!allHot) {
    scheduleGatewaySigusr1Restart({ ... });
}

Option C: Honor gateway.reload mode in the SIGUSR1 path

If gateway.reload is "hot", the scheduleGatewaySigusr1Restart should check whether the changed paths actually require a restart (per BASE_RELOAD_RULES) and skip the SIGUSR1 if all changes are hot-reloadable.

Environment

• OpenClaw version: installed via npm install -g openclaw (March 2026)
• Gateway file: gateway-cli-C2ZZYgwu.js
• Restart module: restart-C7ane9OU.js
• OS: macOS Darwin 25.2.0
• Run mode: openclaw gateway run --token xxx (no supervisor)

Workaround

Our sandbox skill (novita-sandbox) currently disables CDP mode entirely and uses Exec mode only — running curl/puppeteer/playwright inside the sandbox VM and returning results as text. This works but loses the native browser tool's interactive capabilities (snapshot, click, fill, navigate).