You try to start the OpenClaw gateway and it refuses with a message along the lines of Gateway start blocked: set gateway.mode=local, or the sibling variant existing config is missing gateway.mode. Nothing you try seems to get past it, and the block feels arbitrary because the gateway ran fine yesterday.
The message is a guard, not a bug. OpenClaw will not guess how you want the gateway to run, and when the config does not say, it stops and asks. Here is what the mode key means, why it can silently disappear, and the three ways to clear the block depending on how your config got into this state.
What the error means
gateway.mode tells the CLI which direction it faces. In local mode, the gateway runs on this machine and the CLI talks to it over the local socket. In remote mode, the CLI is supposed to connect outward to a gateway running somewhere else, and a config like gateway.remote.url points at that host.
The start command is blocked when the config says anything other than local. Two states produce the message:
- The mode is missing entirely. A config edit, a clobbered-file repair, or an interrupted onboarding can drop the key. OpenClaw treats an existing config without
gateway.modeas damaged or clobbered, and it refuses to guesslocalfor you. It will not silently assume; that is the point of the guard. - The mode says
remote. This usually means the config was copied or migrated from a remote setup, or an upgrade defaulted something you did not expect. In this state the CLI believes it should connect outward, so starting a local gateway is contradictory and gets blocked.
Why so strict? The failure mode the guard prevents is ambiguity with consequences. If OpenClaw guessed local on a machine whose config expects a remote gateway, the CLI could start binding a gateway where one was not wanted. If it guessed remote, it would silently try to reach another host while your local service sat idle. Either guess can strand messages or expose a listener in the wrong place, so the guard fails loud on uncertainty instead: it names the missing key and waits for an explicit answer. Post-upgrade drift is a common trigger, since updates can surface stricter defaults that older configs never satisfied; if this error appeared right after an update, the config was probably fine before and simply never carried the key the newer version requires.
Step 1: Check the mode and the surrounding config
Read the current value first, then look at the gateway block as a whole:
user@host:~$ openclaw config get gateway.mode :~$ openclaw config get gateway.remote.url
A healthy local setup returns local for the mode. This capture from a live host shows the full gateway block in its local shape:
Notice what a healthy local config carries: mode: "local", a loopback bind, and an auth token sourced from the environment, with no remote.url in sight. If your config instead shows mode: "remote" or a remote.url pointing at an old host, that is your state.
Step 2: Set the mode and restart
For the plain missing-mode case, one command clears the block:
user@host:~$ openclaw config set gateway.mode local :~$ openclaw gateway restart
In most cases that is the whole fix. The mode flag is the only thing blocking the start, and the service comes up with the config it now trusts.
Step 3: When the config set also fails, or the config was clobbered
If writing the key throws an error, or you suspect the config file was damaged (which is exactly how the mode key goes missing in the first place), use the repair path. Doctor detects and repairs config state, and onboarding restamps the expected local-mode shape:
Two notes on the repair tools. openclaw doctor --fix owns config repair, including restoring last-known-good copies when a write lost fields. openclaw onboard --mode local (same as openclaw setup) rewrites a complete, valid local-mode config from scratch, which is the right move when the file is too damaged to patch reliably. And --allow-unconfigured is the ad-hoc escape hatch: it bypasses the guard for a dev run without writing or repairing the config, which is useful for testing but is not a substitute for fixing the mode.
Step 4: After a migration from remote to local
If the config came from a remote gateway setup, setting the mode is only half the work. The old gateway.remote.url and any remote-mode service assumptions travel with the file, and a CLI in remote mode can silently target the old host while your local service sits idle. Update the mode, rebuild the service wrapper from the local install, and verify:
user@host:~$ openclaw config set gateway.mode local :~$ openclaw gateway install --force :~$ openclaw gateway restart
The forced reinstall rebuilds the LaunchAgent or systemd unit so the service metadata matches local operation instead of inheriting remote-mode assumptions. If the old host URL is still in the config, clear or repoint gateway.remote.url; a stale remote URL is the classic cause of a gateway that starts fine locally while CLI calls keep failing with gateway connect failed or unauthorized.
The diagram stacks the whole flow on one page:
One caution before you flip anything: only set gateway.mode=local when you actually want a local gateway. If you run OpenClaw against a remote gateway on purpose, the remote mode and gateway.remote.url are correct, and the block only appears when you try to start a local service on top of that setup. In that case the fix is not to change the mode; it is to stop starting a local gateway, or to run the local and remote setups with separate configs and state directories so they stop contradicting each other.
Verify the gateway is running
After the fix, confirm the two lines that define a healthy local gateway:
Runtime: running plus Connectivity probe: ok means the mode fix worked and the service is answering on its socket. If the service is installed but the runtime stays stopped, work the rest of the start-blocked checklist: port conflicts (EADDRINUSE), CLI vs service config mismatches, and clobbered config recovery cover the usual suspects.
Related fixes
This is the last entry in the gateway troubleshooting cluster. The full set now covers EADDRINUSE, config mismatches, clobbered config, approval prompts, Telegram identity, cron delivery, Anthropic 429, and memory search. New to OpenClaw? Start with The Complete OpenClaw Guide.
Not Ready to Self-Host? Try ClawTrust
Building agents locally is powerful, but managing infrastructure, security, and scaling takes effort. ClawTrust provides managed OpenClaw hosting: your agents run securely in the cloud with automatic scaling, no DevOps overhead, and 24/7 monitoring.
This post contains affiliate links. If you buy through them, I may earn a small commission at no extra cost to you.
About The Author
