OpenClaw won’t start after I changed the config

You changed something in your OpenClaw config, the gateway stopped responding, and now you have no way back in. OpenClaw gives you no error message by default when the config fails to load. The gateway just stops, silently, and your agent goes with it. This is how to find out exactly what broke and get back online without losing your config.

Why OpenClaw goes silent when the config breaks

OpenClaw reads your entire config file when the gateway starts. If anything in that file is wrong: a syntax error, a field set to the wrong type, a required field missing. The gateway refuses to start. It does not start partially. It does not tell you in a pop-up or a chat message. It just does not start, because there is no running gateway to send you a message.

This is actually the correct behavior. A gateway that started with a broken config would behave unpredictably. Silent failure on bad config is a safety feature, not a bug. The problem is that OpenClaw does not surface what went wrong unless you specifically ask it to.

There are three distinct ways a config can be broken, and each has a different fix:

1. JSON syntax error. The config file is not valid JSON. A missing comma, an extra brace, a trailing comma: any of these prevents the file from being parsed at all. The validate command shows the exact line and character position where the syntax breaks.
2. Schema validation error. The JSON is valid but a field has the wrong type of value. For example, a text string where a number is expected, or a value that falls outside the allowed range. This is like filling out a form with the right handwriting but the wrong answer.
3. Permission error. The config file exists but OpenClaw cannot read it. Usually caused by file permission changes, running OpenClaw as a different user, or the file being owned by root. This is less common but produces the same symptom from the outside: gateway does not start.

The first thing to do: run the diagnostic before anything else

Before restarting the gateway, before editing anything, before trying anything else, run the config validator. One command tells you exactly what is wrong.

If you have another agent session running (Telegram, Discord, a secondary OpenClaw instance), paste this:

Run OpenClaw's config validator and show me the exact output. If it shows an error, copy the full error text exactly, including the field path and the error description.

Do not restart the gateway before you have run validate. Each failed restart attempt does not give you new information. The validate command does.

What the output looks like

There are two possible outputs from validate.

If the config is valid:

The most common error message you will see is openclaw.json error in some form — either a JSON parse error or a schema validation error. The exact wording varies but the root cause is always the same: something in the config file does not match what OpenClaw expects.

If there is a syntax error:

If there is a schema validation error:

Fixing a JSON syntax error

A JSON syntax error means the config file cannot be read at all. OpenClaw uses JSON5 internally. JSON5 is a variant of JSON (the standard format for config files) that allows comments and some flexible syntax. It is more forgiving than standard JSON in a few ways, but it still fails on common mistakes: trailing commas after the last item in a list, unclosed braces, unmatched brackets.

The most common causes:

• Trailing comma: {"key": "value",}: the comma after the last item in an object or array
• Missing comma: adding a new key-value pair without a comma after the previous one
• Missing closing brace or bracket from a nested section
• A text value containing a quote character that was not escaped

If you still have an active agent session, paste this and let it fix the problem:

Run OpenClaw's config validator. If it shows a JSON parse error with a line number, read that line of my openclaw.json and the lines around it. Show me what you find and what the fix is, but do not write anything yet. I will confirm before you make any change.

Fixing a schema validation error

A schema validation error means the JSON parsed correctly but a field has the wrong type of value. The error message tells you exactly which field and what type it expected.

Common causes:

• Setting a number field to a text string: "contextTokens": "200000" instead of "contextTokens": 200000 (no quotes around numbers)
• Setting a boolean field to a string: "enabled": "true" instead of "enabled": true
• Setting an enum field to a value not in the allowed list. For example, a model name that does not match the format OpenClaw expects
• Setting a required nested object to null or an empty string

Run validate the config. If it shows a schema validation error, read the field path it shows me. Look up what the valid values for that field are using openclaw config schema lookup [field path] or check the docs. Tell me what the correct value for that field is, and what it is currently set to. Do not change anything yet.

Using openclaw doctor to repair automatically

openclaw doctor is OpenClaw’s built-in health check and repair tool. When config validation fails, it can attempt to repair the specific field that failed without touching the rest of your config.

Run openclaw doctor --repair --non-interactive and show me the full output. Tell me what it found and what it changed. Do not restart the gateway until I confirm.

Using the config set command to correct a specific field

If validate tells you exactly which field has the wrong value, you can fix it with a single command without opening the config file at all. the config set command takes a dot-path to the field and the new value.

The validate output showed this error: [paste the exact error]. Use openclaw config set [field path] [correct value] to fix it. Show me the exact command before running it so I can confirm. After I confirm, run it, then run validate again to make sure the fix worked.

Fixing a permission error

If validate says the config is valid but the gateway still does not start, check whether OpenClaw can read its own config file. A permission error produces a different failure mode: validate itself may fail with a file access error, or the gateway may fail with a cryptic error that has nothing to do with your config content.

Run: ls -la ~/.openclaw/openclaw.json and show me the output. Also tell me which user OpenClaw is running as (run ps aux | grep openclaw | grep -v grep). I need to check whether the file is owned by the same user running OpenClaw.

Restoring from backup when the config is too broken to fix

If the config file is severely damaged (multiple interleaved errors, structure so broken that even the doctor cannot parse it): restoring from backup is faster and safer than editing by hand.

OpenClaw’s built-in backup system creates archives of your config, credentials, sessions, and workspaces. If you have run a backup before, this is the fastest path back to a known-good state.

Run openclaw backup verify to show me what backups exist and when they were taken. Tell me the most recent one and what it includes. Do not restore anything yet.

I want to restore from the most recent backup. Before you do anything: copy my current openclaw.json to ~/openclaw-broken-backup.json in my home directory so I have it if I need to reference what I had. Then restore the backup config. After restoring, run validate to confirm the restored config is valid. Tell me the result before starting the gateway.

Rebuilding the config from scratch with the setup wizard

If no backups exist and the config is too broken to repair, the setup wizard rebuilds a working config from scratch. You will lose your existing config values and need to re-enter credentials, model settings, and channel configurations.

I need to rebuild my OpenClaw config from scratch. First, save my broken config to ~/openclaw-broken-$(date +%Y%m%d).json in my home directory (not /tmp, which is cleared on reboot) so I can reference my old API keys and settings. Then tell me: does running openclaw configure overwrite my current config completely or merge with it? I need to know what I will lose before we start.

After you fix it: preventing this next time

Two habits prevent this from happening again.

Validate before restarting. Any time you edit the config, run validate before restarting the gateway. If validate fails, you still have a running gateway and an agent to help you fix it. Once you restart with a broken config, you lose the agent.

Any time I ask you to change something in openclaw.json, I want you to follow this sequence: (1) show me the exact change before writing it, (2) after I confirm, make the change, (3) run OpenClaw's config validator immediately, (4) show me the result, (5) only restart the gateway if validate passes. Do not restart until validate shows clean.

Use config set instead of direct edits. the config set command and openclaw config unset make targeted changes without opening the JSON file. They handle quoting and type conversion automatically. Direct edits to the JSON file are the most common source of syntax errors. If you edit the file directly and introduce a syntax error, the gateway goes down again.

From now on, when I want to change a config value, do not write to openclaw.json directly. Use openclaw config set [path] [value] instead. After setting it, run validate and show me the result. Only proceed to restart if validate passes.

Take a backup before significant changes. If you are about to change multiple config values or add a new plugin, take a backup first.

Before we make any config changes today, run openclaw backup create and tell me when it completes and where the backup file is stored.

Common config mistakes that break OpenClaw

These are the specific changes that most often cause OpenClaw to stop starting. If you recognize your change in this list, you know exactly what to fix.

Putting quotes around a number field: "contextTokens": "200000" instead of "contextTokens": 200000. JSON treats quoted numbers as strings. OpenClaw expects a number. The fix: remove the quotes.

Adding a new line without a comma after the previous line:

  "agents": {
    "defaults": {
      "contextTokens": 200000
      "model": "deepseek/deepseek-chat"  // missing comma after 200000
    }
  }

The fix: add a comma after 200000.

A comma after the last item in a list or object:

  "models": {
    "providers": {
      "openai": {
        "apiKey": "sk-..."
      },  // trailing comma - invalid in standard JSON (JSON5 allows it but some parsers reject)
    }
  }

The fix: remove the comma after the closing brace.

If your API key or token contains a quote character and you did not escape it:

  "apiKey": "sk-abc"123"def"  // the quote in the middle breaks the string

The fix: escape the quote with a backslash: "sk-abc"123"def" or use the config set command which handles escaping automatically.

When editing nested sections, it is easy to misplace a closing brace:

  "agents": {
    "defaults": {
      "contextTokens": 200000
    }  // missing closing brace for defaults
  }  // this closes agents, but defaults is still open

The fix: use a text editor with JSON syntax highlighting or bracket matching. Count opening and closing braces.

I think I made one of these mistakes. Run OpenClaw's config validator and tell me which one matches my error. Show me the exact fix before writing anything.

What to do if the gateway starts but behaves strangely after the fix

Occasionally, fixing a config error and restarting successfully will leave the gateway in a state where something is not working as expected. A model may be wrong, a channel is unresponsive, context limits feel off. This is usually caused by the session inheriting cached state from before the config fix.

The gateway is running after the config fix, but something seems off. Run the config get command agents and the config get command models and show me the current values. Tell me if anything looks wrong relative to what I intended to configure.

FAQ

It can be. Some plugins add entries to openclaw.json during installation. If a plugin installer writes malformed JSON or an invalid value, the config fails the same way as a manual edit. Run openclaw config validate first. If it shows an error in a plugin-related field (anything under plugins.entries), you have two options: fix the plugin config with the config set command, or remove the plugin entry from the config and reinstall. If validate passes but the gateway still fails, the problem is the plugin’s code rather than the config. Check the gateway logs.

If OpenClaw is running as a system service: journalctl -u openclaw --since "10 minutes ago". If it runs as a user service: journalctl --user -u openclaw --since "10 minutes ago". On macOS with launchd: log show --predicate 'processImagePath contains "openclaw"' --last 5m. If you started the gateway manually, it writes to stdout and stderr. Look at the terminal output where you ran openclaw gateway start.

Three possibilities: (1) permission error: the gateway process cannot read the file even though the contents are valid. Check file ownership with ls -la ~/.openclaw/openclaw.json and make sure it is owned by the user running OpenClaw. (2) port conflict: something else is already using the gateway port (default 18789). Check with ss -tlnp | grep 18789. (3) plugin startup error: a plugin fails to initialize and takes the gateway down with it. Check the gateway logs. Disable plugins one at a time to isolate the cause.

Run the config file command to see exactly which config file the current active profile is using. If you use named profiles (--profile flag), each profile has its own config directory. Validate only checks the currently active config. To check a specific profile’s config: openclaw --profile [name] config validate.

Yes. Use OpenClaw’s --dev flag to run against an isolated state directory: openclaw --dev gateway start. The dev profile uses ~/.openclaw-dev/ for all state including config, so changes there do not affect your production setup. This is the right way to test a config change before applying it to your live instance.

Use openclaw config unset [field path] to remove the value and let it fall back to the default. Or use the config set command [field path] [original value] to restore the previous setting. If you are not sure what the original value was, check the gateway logs from before your change. The startup sequence logs the effective config. If you have a recent backup, you can also check the config file in the backup archive without restoring it.

No. Validate checks that the config file is valid JSON and that all fields match the expected types and formats. It does not make network requests to verify that your API keys actually work. A config can validate cleanly and still fail when the gateway tries to use an expired or revoked key. If your config validates but the agent cannot reach a model, check the API key by running a test request independently.

No. A healthy openclaw.json is typically under 50KB. If your config file is very large, it likely contains a section that has grown unexpectedly. Often a plugin that is writing data into the config rather than into its own storage. Check the file size with ls -lh ~/.openclaw/openclaw.json and look for any unusually large sections by running openclaw config get plugins and comparing its output size to the overall file.

Yes. If you run OpenClaw in a Docker container, the config file is inside the container at ~/.openclaw/openclaw.json. To validate it, you need to run the validate command inside the container: docker exec [container-name] validate the config. The same error messages apply. If you mount a config file from the host into the container, validate checks the mounted file. Permission errors are more common in Docker setups because the container user may not have read access to the mounted file.

Each instance uses its own config file. The default instance uses ~/.openclaw/openclaw.json. Named profiles (--profile) use ~/.openclaw-[profile]/openclaw.json. The dev profile (--dev) uses ~/.openclaw-dev/openclaw.json. When you run validate, it checks the config for the currently active profile. To check a different profile’s config: openclaw --profile [name] config validate. If you have multiple instances failing to start, check each profile’s config separately.

Yes, but with limitations. A generic JSON validator (like jq . openclaw.json or an online JSON validator) will catch syntax errors but not schema validation errors. It will not tell you that "contextTokens": "200000" is wrong (string vs number). It also will not show you the OpenClaw-specific field path. Use OpenClaw's config validator for the complete check. If you cannot run OpenClaw at all because the gateway is down, a generic JSON validator is a good first step to rule out syntax errors.

If validate passes but the gateway logs show a plugin failing to load, the problem is plugin-specific. Disable plugins one at a time to isolate the culprit. In openclaw.json, find the plugins.entries section and set "enabled": false for each plugin, restart, and see if the gateway starts. Once you identify the broken plugin, check its documentation or reinstall it. Some plugins require specific versions of OpenClaw or have dependencies that may be missing.

Run the config get command [field path] after the gateway starts. For example, the config get command agents.defaults.contextTokens shows the current value. Compare it to what you set. If it does not match, either the config file was not saved correctly, or another config layer (environment variable, plugin override) is taking precedence. Also check the gateway startup logs: journalctl -u openclaw --since "1 minute ago" shows the effective config values as the gateway loads them.

Go deeper