TL;DR: OpenClaw’s
Gateway start blocked: existing config is missing gateway.mode. Treat this as suspicious or clobbered config.means your config file exists and parses, but thegateway.modekey is absent from it. That is the middle of three states the start guard can report, and the only one that says your file lost something. The guard also prints aConfig write auditpath, which is the line that tells you what wrote the file last. Setgateway.modetolocalor restamp the config with onboarding to clear the error; read the audit path first if you want to know why the key went missing. If your message starts withMissing config. Run openclaw setupinstead, there is no config file at the path the gateway checked, and the fix is different.
Contents
- The Error
- What the Guard Actually Checks
- Why “Suspicious” Is the Right Word
- The Line Everyone Scrolls Past
- The Fix
- What Does “Missing Config. Run openclaw setup” Mean?
- How to Prevent This
- Key Takeaways
- Frequently Asked Questions
The Error: Gateway Start Blocked, Existing Config Is Missing gateway.mode
You start the gateway and it refuses:
Gateway start blocked: existing config is missing gateway.mode. Treat this as
suspicious or clobbered config. Re-run `openclaw onboard --mode local` or
`openclaw setup`, set gateway.mode=local manually, or pass --allow-unconfigured.
Config write audit: <path>
Nothing crashed. The gateway declined to start, which is a different thing, and the message is unusually specific about why. If you are working through several startup failures at once, the OpenClaw errors reference covers the other signatures you are likely to hit alongside this one.
What the Guard Actually Checks
The start guard runs before the gateway binds anything, and it asks three questions in a fixed order. Each has its own message, and knowing which one you got is most of the diagnosis.
One: does a config exist at all? If not, the start path prints this, and it is the one people paste into a search box most often:
Missing config. Run `openclaw setup` or set gateway.mode=local (or pass --allow-unconfigured).
Your file is absent. Not corrupt, not missing a key: there is nothing at the config path to read. That matters because the fix below for a file that lost a key does not apply to you (this section covers yours), and the two messages are close enough in wording to be mistaken for each other.
The health check prints a shorter variant of the same condition, with a colon and no flag:
Missing config: run `openclaw setup` first.
Same cause, different caller. If you have both in a terminal, you have one problem.
Two: is gateway.mode present? If the config was read but that key is undefined, you get the “missing gateway.mode” message above. Your file is present, valid enough to parse, and missing the key that decides how the gateway runs.
Three: is the value one it can start in? If the key is present but holds something the gateway will not start on, you get a message that quotes it back, in the form set gateway.mode=local (current: <value>). Your file is present and complete, and you have configured a mode this start path does not accept.
Two of those three are ordinary configuration states. Only the middle one describes a file that lost something.
The official troubleshooting docs list the second and third signatures together on one line with a shared fix. As a fix hint that is reasonable, since setting the mode resolves both. As a diagnosis it hides the distinction that matters, because one of them is telling you the file changed underneath you.
Why “Suspicious” Is the Right Word
The wording reads as dramatic until you work out what the state implies.
A config that OpenClaw wrote during setup or onboarding carries gateway.mode. That is what those commands stamp. So a config file that exists, parses, and has no gateway.mode is not a config that OpenClaw finished writing. Something else produced it, or something rewrote it afterwards and dropped the key.
That narrows the causes to a short list worth checking in order:
- A hand edit that removed or renamed the key. The most common and the easiest to confirm.
- A restore from an older or trimmed copy. A backup taken before the key existed, or a config copied from another machine and pruned on the way.
- A partial write. A write interrupted part-way can leave a file that parses and is incomplete.
- A writer running as a different user than the gateway. If one process writes the config as one user and the gateway runs as another, you can end up reading a file that is not the one you think you edited. This is the classic self-hosting footgun, and it is worth ruling out early because every other fix on this list will appear to work and then quietly undo itself.
The guard cannot tell which of these happened. It can tell that the file is in a state its own writers do not produce, and it says so rather than starting anyway on a default. That is the correct behaviour for a process that is about to bind a port and start accepting work. Refusing to start on an incomplete config is the same instinct behind several of the production gotchas that catch self-hosted deployments.
The Line Everyone Scrolls Past
Both blocked-start messages print a second line:
Config write audit: <path>
That path points at OpenClaw’s own record of writes to the config. It is emitted precisely because “the config lost a key” is a question about history rather than contents, and the file itself cannot answer it.
If you only want the gateway running, you can ignore it. If you want to know why the key went missing, and you do if this is a machine you intend to leave running, that record is the difference between fixing the config and fixing the cause. A hand edit, a restore, and a process writing as the wrong user all leave the same empty space in the file and very different traces in the audit. The doctor command is worth a run at this point too, since it checks a set of config and permission conditions that overlap with the causes below.
The Fix
If this machine should run its own gateway, set the mode to local. Either set gateway.mode to local in the config directly, or re-run onboarding with the local mode flag to restamp a complete config. Restamping is the better choice when you do not know what else the file may be missing, since a config that lost one key may have lost others.
If this machine should talk to a gateway somewhere else, set the mode to remote and set the remote URL alongside it. Remote mode without that URL is a separate failure with its own message, so setting one without the other trades this error for the next one.
The unconfigured-start override, --allow-unconfigured, is a diagnostic, not a fix. Its own help text says so: it allows gateway start without enforcing gateway.mode=local in config, and it does not repair config. It skips the guard rather than satisfying it. That is useful when you want a running process to inspect while you work out what happened, and it is a poor thing to leave in a startup command, because it converts a loud refusal into a silent start on an incomplete config.
Do not delete the config as a first move. It is tempting, it usually works, and it destroys the only local evidence of how the file got into this state. If the cause is something that rewrites the config, a fresh config gets rewritten the same way and you are back within a boot or two, this time without the audit trail.
What Does “Missing Config. Run openclaw setup” Mean?
It means the gateway found no config file at the path it resolved, so there was nothing to read, check or repair.
Missing config. Run `openclaw setup` or set gateway.mode=local (or pass --allow-unconfigured).
Start by asking OpenClaw where it looked. Run openclaw config file in the same environment that starts the gateway: the same user, the same shell or service unit, the same environment variables. It prints the active config path, resolved from OPENCLAW_CONFIG_PATH or the default location under the account’s home directory.
If nothing is at that path, this is a fresh install. Run openclaw setup. On a system with no config it falls through to guided onboarding, which writes a complete config, gateway.mode included.
For scripts, openclaw setup --baseline creates the config and workspace folders without the wizard.
If you already have a config somewhere else, the gateway is looking in the wrong place, and running setup would create a second config instead of finding yours. The usual causes:
- A different account. A service unit, a container or a
sudocall runs as another user, so it resolves a different home directory and a different default path. - A different environment.
OPENCLAW_CONFIG_PATH,OPENCLAW_STATE_DIRorOPENCLAW_HOMEis set in your shell but not in the service, or the other way round. Each one moves where OpenClaw reads its state.
Make the gateway’s environment resolve the path your config is at, then start it again. Only use --allow-unconfigured to get a running process to inspect. It starts without a config rather than finding one.
How to Prevent This
Most recurrences come down to one question: is anything other than OpenClaw writing this file?
Decide which user owns the config and make sure the process that starts the gateway is that user. Keep configuration changes going through setup or onboarding where you can, since those write complete configs by construction. If you do edit by hand, edit a copy and swap it in, so a half-finished edit never becomes the live file. And if you restore configs from backup, restore from one taken after the machine was fully onboarded.
None of that is exotic. It is the ordinary discipline of a file that two things might write, applied to the one file that decides whether your agents run. If you would rather not be the person who finds this at 2am, that is what FleetHelp is for: your agents message ours when a gateway refuses to start, and the fix comes back production-tested.
Key Takeaways
existing config is missing gateway.modemeans the file was found and read, and the key is absent. It is one of three distinct states the start guard reports, and the only one that implies the file changed.- A message quoting a current value is a different branch: the key is present and the value is not startable. The published troubleshooting docs list both together, which merges a diagnosis with a fix hint.
- The
Config write auditpath is the most informative line in the output, because the question is what wrote the file, and the file cannot answer it. - Set the mode to
local, or restamp the config through onboarding. Use the unconfigured-start override to look around, not to run. - If the config lost a key once with nothing to explain it, find the writer before you trust the machine.
Related: OpenClaw Errors Explained · OpenClaw doctor --fix · OpenClaw Production Gotchas
Frequently Asked Questions
What does "existing config is missing gateway.mode" mean in OpenClaw?
It means your config file was found and read, but the gateway.mode key is not in it. That is a narrower complaint than it first appears. OpenClaw's start guard checks three things in order: whether a config exists at all, whether gateway.mode is present, and whether its value is one the gateway can start in. This message is the middle case only. The file is there and parses, and the one key that decides how the gateway runs is absent from it.
Why does OpenClaw call my config "suspicious or clobbered"?
Because of what the state implies rather than what it proves. A config that OpenClaw wrote during setup or onboarding always carries gateway.mode. A config that exists without it is therefore not a config OpenClaw finished writing, so something else produced or rewrote the file: a partial write, a hand edit that dropped the key, a restore from an older or trimmed copy, or a process writing the file as a different user than the one the gateway runs as. The wording is a deliberate signal that the file's history is the thing to check, not just its contents.
How is this different from "Gateway start blocked: set gateway.mode=local"?
They are two different branches of the same guard and they mean opposite things about your file. The message naming a current value, in the form set gateway.mode=local (current: remote), means the key is present and OpenClaw read a value it cannot start in. The missing gateway.mode message means there is no value to read. The official troubleshooting docs list both signatures on one line, which is fine as a fix hint and misleading as a diagnosis, because only one of the two says your file lost something.
What is the "Config write audit" line printed underneath the error?
It is a path, emitted alongside both blocked-start messages, pointing at OpenClaw's record of writes to the config. It is the most useful line in the output and the one most people scroll past. If the config genuinely lost a key, that record is where you look to see what last wrote the file and when, which separates a hand edit or a restore from a partial write by the tool itself.
What is the fastest correct fix?
If you know the machine should run its own gateway, set gateway.mode to local in the config, or re-run onboarding with the local mode flag to restamp a complete config. If the gateway should talk to a remote one, set the mode to remote and supply the remote URL, because remote mode without that URL is its own separate failure. Reach for the unconfigured-start override only to get a look at a running process while you diagnose. It skips the guard rather than satisfying it, so it turns a clear refusal into a silent one.
What does "Missing config. Run `openclaw setup` or set gateway.mode=local (or pass --allow-unconfigured)." mean?
It means there is no config file at the path OpenClaw looked in, which is a different problem from the missing gateway.mode error even though the wording overlaps. This is the first of the start guard's three checks: the file is absent, so there is nothing to read and nothing to repair. Run setup to create one. The health check reports the same condition in a shorter form, Missing config: run openclaw setup first, with a colon and no flag suggestion. If a config does exist and the gateway still refuses to start, you are looking at one of the other two branches instead.
What does --allow-unconfigured actually do?
Its help text is explicit: it allows gateway start without enforcing gateway.mode=local in config, and it does not repair config. That second clause is the part worth reading twice. The flag suppresses the guard for one start; it writes nothing, fixes nothing, and the next start without it blocks again on the same condition. It earns its place when you want a running process to inspect while you work out what happened to the file. It is a poor thing to leave in a startup command, because it converts a loud refusal into a silent start on an incomplete config.
Should I just delete the config and start over?
Not as a first move, and not before reading the write-audit path. Deleting the file destroys the only local evidence of how it lost the key, and if the cause is a process rewriting the config as the wrong user, a fresh config will be rewritten the same way and you will be back within a boot or two. Restamping the config is the right fix once you know what wrote it; it is a guess before then.
Stop Googling OpenClaw errors.
Your agents message ours on Telegram. Production-tested OpenClaw fixes. $99/mo.