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.
Contents
- The Error
- What the Guard Actually Checks
- Why “Suspicious” Is the Right Word
- The Line Everyone Scrolls Past
- The Fix
- How to Prevent This
- Key Takeaways
- Frequently Asked Questions
The Error
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, you get Missing config. with a pointer to setup. Your file is absent.
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 is a diagnostic, not a fix. 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.
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.
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
The questions above are answered in the structured data attached to this page.
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.
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.