Gateway won't start: config validation failed / JSON5 parse error

Symptoms

• Gateway refuses to start after editing ~/.openclaw/openclaw.json.
• The Control UI shows errors / gateway is down.
• CLI commands that require a running gateway fail, but diagnostic commands still work.

Cause

Two common failure modes:

A) JSON5 syntax error

OpenClaw reads JSON5 (comments + trailing commas allowed), but it still must be valid JSON5:

• missing commas
• unbalanced braces/brackets
• unterminated strings

B) Schema validation error

OpenClaw validates config strictly against the running schema:

• unknown keys
• wrong types (allowFrom must be an array, etc.)
• invalid enum values

Strict validation also rejects unsupported keys even when they came from an old doc, a beta build, or a plausible-looking community snippet. If your installed OpenClaw build does not recognize a field, treat that key as unsupported for your version until current docs, the generator, or openclaw config validate confirms the schema location.

C) Upgrade migration warning that did not rewrite your file yet

This is the subtle case that catches a lot of people after upgrades:

• OpenClaw prints an auto-migrated on load message,
• but your on-disk config still contains the old key,
• and strict validation still refuses to boot until the file is rewritten.

Typical example:

• session.threadBindings.ttlHours was renamed to session.threadBindings.idleHours

So the operator sees a migration warning and assumes “good, it handled it”, but the gateway still exits with Invalid config.

Fix

1) Run doctor to see exact errors

openclaw doctor

If the gateway is crash-looping and you want a fast “does the file validate” check without starting anything:

openclaw config validate

2) If doctor suggests a schema migration

openclaw doctor --fix

This is the right first move for upgrade-era key renames, especially when the logs mention:

• auto-migrated on load
• was renamed to
• run 'openclaw doctor --fix'

2.1 Example: ttlHours → idleHours

If your logs mention a legacy key like:

session.threadBindings.ttlHours was renamed to session.threadBindings.idleHours

then use one of these recovery paths:

openclaw doctor --fix

or, if you need to patch it manually, replace the old key in ~/.openclaw/openclaw.json and restart the gateway.

Practical rule:

• migration warning means OpenClaw recognized the old shape,
• migration success means your actual file is now aligned,
• if the gateway still refuses to start, treat it as an unresolved config-validation problem until proven otherwise.

2.2 If Control UI / config.patch bricked your gateway (crash loop + log spam)

The Control UI can change config via a gateway RPC called config.patch (a partial update merge).

If a patch writes an unknown key or wrong type, you can end up in a loop:

• gateway restarts,
• reads invalid config,
• fails validation,
• restarts again (and logs spam forever).

Recovery runbook:

1. Stop the gateway service so it stops re-reading the broken file.
2. Restore a known-good config backup:

ls -1 ~/.openclaw/openclaw.json.bak.* 2>/dev/null | tail -n 10
cp ~/.openclaw/openclaw.json.bak.<timestamp> ~/.openclaw/openclaw.json

3. Validate before restarting:

openclaw config validate

4. Restart the gateway:

openclaw gateway restart

Prevention tip: use openclaw config set for single-key edits and the config generator for multi-field edits. Treat ad-hoc JSON snippets from issue threads as untrusted until they validate on your version.

2.3 Regenerate instead of hand-patching June-era surfaces

If the failure involves newer starter fields around agents.defaults.models, tools.exec, tools.fs, plugins.*, gateway.nodes.browser, nodeHost.browserProxy, cron, or hooks, do not keep hand-patching guesses into a crash loop.

Instead:

1. keep the broken file stopped/backed up,
2. recreate the intended baseline in OpenClaw Config Generator,
3. compare only the supported starter fields against your file,
4. cross-check the refreshed /guides/openclaw-configuration page,
5. validate again with openclaw config validate before restart.

Use the surface hubs when the failing key belongs to a specific area: Providers for provider/model refs, Tools for tool and sandbox policy, Plugins for plugin trust, Nodes for browser node routing, and Automation for cron or hooks. The generator is a schema-aligned tie-breaker for supported starter fields, but the running schema still wins.

3) Revert to a known-good minimal config

Start from a schema-aligned example and re-apply changes incrementally.

Example minimal config (JSON5):

{
  agent: { workspace: '~/.openclaw/workspace' },
  channels: { whatsapp: { allowFrom: ['+15555550123'] } },
}

4) Prefer openclaw config for small edits

This avoids manual syntax mistakes:

openclaw config set agents.defaults.workspace "~/.openclaw/workspace"

5) When docs and validation seem to disagree, trust the running schema first

Sometimes a field can appear in examples, old docs, discussions, or issue comments, but your current build still rejects it.

When that happens:

1. trust openclaw doctor and openclaw config validate over stale snippets,
2. confirm the exact version you are running,
3. move the change to the closest schema-aligned location if a stable fallback exists,
4. and use the config generator or current configuration guide as the tie-breaker.

This is slower than copy-pasting a thread snippet, but much faster than a gateway crash loop.

Verify

openclaw status
openclaw logs --follow

Related

• Configuration overview (concepts + schema-aligned patterns): /guides/openclaw-configuration
• Generate a schema-aligned config visually: /openclaw-config-generator
• Upgrade workflow + rollback: /guides/updating-and-migration
• Backup before risky config surgery: /guides/openclaw-backup-and-rollback