OpenClaw gateway failed to start: Invalid config after upgrade

You upgraded an OpenClaw instance to 2026.5.30 or newer (for example 2026.6.1), and now the gateway crash-loops at startup with the exact line Gateway failed to start: Invalid config. The config that worked yesterday suddenly fails validation. The fix is not a restart — it is a config rewrite. OpenClaw 2026.5.30 unified its OpenAI provider handling, and three concrete schema renames invalidate older configs: rename the provider openai-codex → openai (id and auth entry), rename the api openai-codex-responses → openai-chatgpt-responses, and move agentRuntime from per-agent scope to provider scope. Then validate against the real schema before you restart.

What "Gateway failed to start: Invalid config" actually means here

On 2026.5.30, OpenClaw consolidated how it handles OpenAI. Before that version, a Codex-on-OpenAI setup used a distinct openai-codex provider with its own auth entry, an api id of openai-codex-responses, and an agentRuntime setting attached per agent. The 2026.5.30 schema collapses all of that into a single openai provider and moves the runtime selector up to provider scope.

Your existing config still references the old names. The new validator does not recognize them, so it rejects the whole file before the gateway ever finishes booting. That is the entire mechanism. It is not your provider key, your network, or your auth — it is a schema mismatch introduced by the version bump.

Why restarting the gateway never fixes it

This is the part that wastes the most time. The invalid config persists on disk (on a managed PVC, or wherever your gateway config lives self-hosted). When the pod restarts, it re-reads the same file, fails the same validation, and goes straight back into CrashLoopBackOff. There is no transient state to clear, no cache to flush. A restart is a no-op against a config the validator already rejected.

The corollary: you must edit the config to the new schema first. The restart is the last step, not the first one. If you are reflexively restarting crash-looping pods, read recovering an OpenClaw CrashLoopBackOff without restart spam first — restart spam hides the real signal in the logs.

The three breaking renames from the unified-OpenAI migration

What it is	Old (pre-2026.5.30)	New (2026.5.30+)
Provider id + auth entry	openai-codex	openai
API id	openai-codex-responses	openai-chatgpt-responses
agentRuntime scope	per-agent	provider

All three have to be applied. Fixing one rename and missing another leaves the config invalid, and you get the same startup failure with no extra hint about which key is still wrong.

How to tell this apart from other startup failures

Symptom	Most likely cause
Invalid config appears right after a bump to 2026.5.30+, config was fine before	Unified-OpenAI schema renames (this guide)
Validation error mentions the network bind / interface, not OpenAI	A different post-upgrade config tightening — check your bind setting, not the provider
Gateway starts, then a coding turn fails with a model-not-supported harness error	Model reference mismatch downstream of the same migration, but config is valid
Crash loop with no "Invalid config" line at all	Not this issue — read the actual startup log line, don't assume

Stop babysitting your OpenClaw box

Fix it once — or stop fixing it for good.

Apply the checklist above and keep self-hosting, or skip the maintenance entirely: run your OpenClaw on managed hosting from $6.90/mo, starting with a 7-day free trial. We handle the stale locks, gateway restarts, version upgrades, and uptime — and you can import your existing instance in a couple of minutes. Cancel anytime.

Managed hosting — from $6.90/mo Your own hosted OpenClaw instance with automatic restarts and version upgrades. Starts with a 7-day free trial — import your current setup, keep your channels, cancel anytime.

$199 managed setup — optional Prefer we do it for you? One workspace configured end-to-end: first-run config, one 30-minute onboarding/debug session, and a 7-day follow-up. Limited weekly slots.

• Managed hosting handles stale .jsonl.lock files, gateway restarts, and version upgrades for you
• Import your existing OpenClaw setup in minutes — keep your channels and configuration
• The optional $199 setup is scoped: no custom development, enterprise/SRE support, or unsupported self-hosting repair

If you would rather compare options first, review OpenClaw cloud hosting or see the best OpenClaw hosting options before deciding.

Run it on managed hosting — from $6.90/mo Prefer we set it up? $199 managed setup See how managed OpenClaw hosting handles upgrades

Step-by-step fix

1) Back up the current config before you touch anything

Copy the gateway config somewhere safe. You want a clean rollback target, and if you decide to run openclaw doctor --fix later you will want the original to diff against.

2) Apply the three renames in the config

Open the gateway config and make every change from the table above:

• Rename the provider id openai-codex to openai, and rename its auth entry to openai as well.
• Rename the api id openai-codex-responses to openai-chatgpt-responses.
• Move agentRuntime off each agent and onto the openai provider (provider scope).

Search the whole file for the old strings — these names often appear in more than one place (provider definition, auth block, and per-agent runtime), and a stray reference keeps the config invalid.

3) Validate against the exact version's schema — before restarting

This is the step that turns one clean restart into a guaranteed one. Install the same version you upgraded to and let its real validator check your edited config:

npm i -g openclaw@2026.5.30   # or the exact version you upgraded to, e.g. 2026.6.1
openclaw doctor               # confirm the config parses against the real schema

You can also run openclaw gateway run against the config to confirm it boots locally. If doctor still flags something, you have a rename left to apply — fix it and re-run. Do not touch the live gateway until this is green.

4) Restart the gateway — now it's the last step

With a config that validates against the real schema, restart the gateway. This time it boots cleanly instead of crash-looping, because the file it re-reads is finally valid.

About openclaw doctor --fix

The generic advice across most search results is to run openclaw doctor --fix and walk away. It can rewrite the references for you, but in our experience the dependable path is the explicit one above: back up the config, apply the three renames yourself, and validate against the exact version's schema before you restart. If you do use --fix, treat its output as a starting draft — diff the result against your backup and validate it against the real schema before you restart, rather than blind-trusting it on a config you care about.

Result verification

• The startup log no longer prints Gateway failed to start: Invalid config.
• The pod leaves CrashLoopBackOff and reaches a running, ready state.
• openclaw doctor against the same version reports no config errors.
• A real coding turn through the openai provider completes — proving the renamed provider, api, and runtime all resolve.
• No old openai-codex or openai-codex-responses strings remain anywhere in the config.

Edge cases and judgment calls

You validated against the wrong version

Validating with a globally installed OpenClaw that is not the version you upgraded the instance to defeats the purpose. The schema is version-specific. Pin npm i -g openclaw@<version> to the exact target before running doctor.

You only renamed the provider, not the api or the runtime scope

Then the config is still invalid and you will see the same failure. The three renames are a set, not a menu. Re-check the table.

The gateway boots but a turn errors with a model harness message

That is a separate, downstream symptom of the same migration — the config is now valid, but a model reference elsewhere still points at the old shape. Fix the model reference; do not undo your config renames.

Typical mistakes

• Restarting the pod or gateway repeatedly instead of editing the config — the broken file is on disk and re-read every boot.
• Rolling back the whole upgrade when only three renames were needed.
• Applying one or two of the renames and missing the third.
• Skipping local validation and discovering the next missed key only after another crash-loop.
• Running doctor --fix blind on a production config without a backup or a post-diff.

FAQ

What changed about the OpenAI provider in 2026.5.30?

OpenClaw unified its OpenAI handling. The openai-codex provider (id and auth) collapsed into openai, the api openai-codex-responses became openai-chatgpt-responses, and agentRuntime moved from per-agent to provider scope. Any config still using the old names fails validation.

Will a plain pod restart ever clear this?

No. The invalid config is on disk and is re-read on every boot. You must rewrite it to the new schema; the restart only succeeds after the file validates.

Is openai-codex still valid?

Not on 2026.5.30+. Rename it — and its auth entry — to openai, rename the api to openai-chatgpt-responses, and move agentRuntime to provider scope.

How do I stop this happening on every upgrade?

Either keep a validate-before-restart discipline (install the target version, run openclaw doctor, restart only when green), or move to a managed host whose config generator emits the correct schema per version. On OpenClaw cloud hosting the version-gated generator handles the 2026.5.30 schema for you so the bump is uneventful.