fix: default gateway.mode to 'local' when unset (#54801) by BradGroux · Pull Request #60085 · openclaw/openclaw

BradGroux · 2026-04-03T05:12:17Z

After v2026.3.24 introduced a gateway.mode guard in the gateway run command, startup fails on Windows (and other platforms) when the config file exists but doesn't contain an explicit gateway.mode value. This happens after openclaw onboard writes a minimal config without gateway settings — the DOS window opens and immediately closes.

Root cause: effectiveCfg.gateway?.mode evaluates to undefined when the config has no gateway section, causing the mode !== "local" guard to block startup with exit code 1.

Fix: Default mode to "local" when unset, restoring pre-3.24 behavior where the gateway started without requiring an explicit mode.

One-line change in src/cli/gateway-cli/run.ts.

Fixes #54801

After v2026.3.24 introduced a gateway.mode guard, startup fails on Windows (and other platforms) when the config file exists but doesn't contain an explicit gateway.mode value. This happens after 'openclaw onboard' writes a minimal config without gateway settings. Default to 'local' when the mode is unset, restoring pre-3.24 behavior where the gateway started without requiring an explicit mode. Fixes openclaw#54801

greptile-apps · 2026-04-03T05:13:18Z

Greptile Summary

Fixes a Windows startup regression introduced in v2026.3.24 by defaulting mode to "local" when effectiveCfg.gateway?.mode is undefined. The one-line change correctly restores pre-3.24 behavior where a minimal config (written by openclaw onboard without a gateway section) no longer causes an immediate exit-1.

Confidence Score: 5/5

Safe to merge — minimal, targeted fix with no functional regressions.

Single-line logic change with a clear root cause and accurate fix. The only finding is a P2 dead-code nit (?? "unset") that has no runtime impact.

No files require special attention.

Comments Outside Diff (1)

src/cli/gateway-cli/run.ts, line 364 (link)

Dead ?? "unset" fallback

Since mode now defaults to "local" on line 356, it can never be undefined at this point. The ?? "unset" fallback is unreachable — this branch only runs when mode !== "local", so mode is always a non-undefined string here.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/cli/gateway-cli/run.ts
Line: 364

Comment:
**Dead `?? "unset"` fallback**

Since `mode` now defaults to `"local"` on line 356, it can never be `undefined` at this point. The `?? "unset"` fallback is unreachable — this branch only runs when `mode !== "local"`, so `mode` is always a non-`undefined` string here.



How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/cli/gateway-cli/run.ts
Line: 364

Comment:
**Dead `?? "unset"` fallback**

Since `mode` now defaults to `"local"` on line 356, it can never be `undefined` at this point. The `?? "unset"` fallback is unreachable — this branch only runs when `mode !== "local"`, so `mode` is always a non-`undefined` string here.

```suggestion
        `Gateway start blocked: set gateway.mode=local (current: ${mode}) or pass --allow-unconfigured.`,
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "fix: default gateway.mode to 'local' whe..." | Re-trigger Greptile}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 28bdeb6552

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-04-03T05:15:56Z

src/cli/gateway-cli/run.ts

+  // regressed startup on Windows (and other platforms) when the config file
+  // exists but doesn't contain gateway.mode — e.g. after `openclaw onboard`
+  // writes a minimal config. (#54801)
+  const mode = effectiveCfg.gateway?.mode ?? "local";


Keep missing-config startup blocked by default

In runGatewayCommand, defaulting mode with ?? "local" makes the guard treat an entirely missing config as configured local mode (loadConfig() returns {} when no file exists). That means openclaw gateway run now bypasses the --allow-unconfigured gate on fresh installs, and the !configExists error path is no longer reachable in that case. This changes the CLI contract (“Allow gateway start without gateway.mode=local in config”) and removes the intended explicit opt-in for unconfigured environments.

Useful? React with 👍 / 👎.

Copilot

Pull request overview

Adjusts the openclaw gateway run startup guard to avoid failing when the config exists but does not explicitly set gateway.mode, restoring the expected default behavior after a regression introduced in v2026.3.24.

Changes:

Default gateway.mode to "local" when it is unset in the effective config used by gateway run.
Add an inline comment explaining the regression scenario and rationale (issue #54801).
Minor import reordering in run.ts.

Copilot · 2026-04-03T05:16:28Z

src/cli/gateway-cli/run.ts

+  // Default to "local" when gateway.mode is unset. Prior to v2026.3.24 the
+  // gateway started without an explicit mode; the guard added in 3.24
+  // regressed startup on Windows (and other platforms) when the config file
+  // exists but doesn't contain gateway.mode — e.g. after `openclaw onboard`
+  // writes a minimal config. (#54801)
+  const mode = effectiveCfg.gateway?.mode ?? "local";
  if (!opts.allowUnconfigured && mode !== "local") {


mode is now defaulted to "local" unconditionally when gateway.mode is unset. That also changes behavior for the missing config file case: loadConfig() returns {} when the config path doesn’t exist, so mode becomes "local" and the !configExists error/exit path is bypassed. This effectively makes --allow-unconfigured meaningless for the no-config scenario and allows gateway run to proceed without any config.

Consider keeping the original fail-closed behavior when configExists is false (e.g., compute rawMode = effectiveCfg.gateway?.mode and only default to "local" when configExists is true, or incorporate configExists into the guard).

Suggested change

// Default to "local" when gateway.mode is unset. Prior to v2026.3.24 the

// gateway started without an explicit mode; the guard added in 3.24

// regressed startup on Windows (and other platforms) when the config file

// exists but doesn't contain gateway.mode — e.g. after `openclaw onboard`

// writes a minimal config. (#54801)

const mode = effectiveCfg.gateway?.mode ?? "local";

if (!opts.allowUnconfigured && mode !== "local") {

// Default to "local" when gateway.mode is unset, but only if a config file

// actually exists. Prior to v2026.3.24 the gateway started without an

// explicit mode; the guard added in 3.24 regressed startup on Windows (and

// other platforms) when the config file exists but doesn't contain

// gateway.mode — e.g. after `openclaw onboard` writes a minimal config.

// Keep the original fail-closed behavior when the config file is missing.

const rawMode = effectiveCfg.gateway?.mode;

const mode = rawMode ?? (configExists ? "local" : undefined);

if (!opts.allowUnconfigured && (!configExists || mode !== "local")) {

Copilot · 2026-04-03T05:16:29Z

src/cli/gateway-cli/run.ts

+  // Default to "local" when gateway.mode is unset. Prior to v2026.3.24 the
+  // gateway started without an explicit mode; the guard added in 3.24
+  // regressed startup on Windows (and other platforms) when the config file
+  // exists but doesn't contain gateway.mode — e.g. after `openclaw onboard`
+  // writes a minimal config. (#54801)
+  const mode = effectiveCfg.gateway?.mode ?? "local";
  if (!opts.allowUnconfigured && mode !== "local") {


This change alters the semantics of the startup guard when gateway.mode is absent in the observed config snapshot. There is an existing unit test (src/cli/gateway-cli/run.option-collisions.test.ts, “blocks startup when the observed snapshot loses gateway.mode…”) that currently asserts gateway run exits with current: unset when the snapshot omits gateway.mode. With the new default-to-local behavior, that test (and potentially related expectations) will need to be updated/removed, and it would be good to add/adjust coverage for the intended regression case (config exists, no gateway section/mode → gateway starts).

After v2026.3.24 introduced a gateway.mode guard, startup fails on Windows (and other platforms) when the config file exists but doesn't contain an explicit gateway.mode value. This happens after 'openclaw onboard' writes a minimal config without gateway settings. Default to 'local' when the mode is unset, restoring pre-3.24 behavior where the gateway started without requiring an explicit mode. Fixes #54801 Co-authored-by: Brad Groux <[email protected]>

…nclaw#60085) After v2026.3.24 introduced a gateway.mode guard, startup fails on Windows (and other platforms) when the config file exists but doesn't contain an explicit gateway.mode value. This happens after 'openclaw onboard' writes a minimal config without gateway settings. Default to 'local' when the mode is unset, restoring pre-3.24 behavior where the gateway started without requiring an explicit mode. Fixes openclaw#54801 Co-authored-by: Brad Groux <[email protected]>

Copilot AI review requested due to automatic review settings April 3, 2026 05:12

openclaw-barnacle bot added cli CLI command changes size: XS maintainer Maintainer-authored PR labels Apr 3, 2026

Copilot started reviewing on behalf of BradGroux April 3, 2026 05:12 View session

chatgpt-codex-connector bot reviewed Apr 3, 2026

View reviewed changes

Copilot AI reviewed Apr 3, 2026

View reviewed changes

BradGroux merged commit 9978d22 into openclaw:main Apr 3, 2026
45 of 49 checks passed

This was referenced Apr 3, 2026

test: update gateway.mode test to match default-to-local behavior (#54801) #60094

Merged

WORKING: All Microsoft Issues and PRs #49126

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: default gateway.mode to 'local' when unset (#54801)#60085

fix: default gateway.mode to 'local' when unset (#54801)#60085
BradGroux merged 1 commit intoopenclaw:mainfrom
BradGroux:bgod/fix-54801-windows-gateway-start

BradGroux commented Apr 3, 2026

Uh oh!

greptile-apps bot commented Apr 3, 2026 •

edited

Loading

Comments Outside Diff (1)

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Apr 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-  // Default to "local" when gateway.mode is unset. Prior to v2026.3.24 the
-  // gateway started without an explicit mode; the guard added in 3.24
-  // regressed startup on Windows (and other platforms) when the config file
-  // exists but doesn't contain gateway.mode — e.g. after `openclaw onboard`
-  // writes a minimal config. (#54801)
-  const mode = effectiveCfg.gateway?.mode ?? "local";
-  if (!opts.allowUnconfigured && mode !== "local") {
+  // Default to "local" when gateway.mode is unset, but only if a config file
+  // actually exists. Prior to v2026.3.24 the gateway started without an
+  // explicit mode; the guard added in 3.24 regressed startup on Windows (and
+  // other platforms) when the config file exists but doesn't contain
+  // gateway.mode — e.g. after `openclaw onboard` writes a minimal config.
+  // Keep the original fail-closed behavior when the config file is missing.
+  const rawMode = effectiveCfg.gateway?.mode;
+  const mode = rawMode ?? (configExists ? "local" : undefined);
+  if (!opts.allowUnconfigured && (!configExists || mode !== "local")) {

Uh oh!

Conversation

BradGroux commented Apr 3, 2026

Uh oh!

greptile-apps bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Comments Outside Diff (1)

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

greptile-apps bot commented Apr 3, 2026 •

edited

Loading