Handling Strict Config Validation in OpenClaw

I have spent too many hours debugging services only to realize I had a typo in a configuration key that the system silently ignored. It is frustrating when a tool tries to be helpful by skipping over errors, leaving you to wonder why your changes aren’t working. I prefer a system that tells me exactly what is wrong the moment I start it up.

OpenClaw now uses strict validation to ensure your configuration is perfect. It rejects unknown keys and requires every plugin to have a clear schema. If something is wrong, the system blocks non-diagnostic commands until you fix the issue.

What You’ll Need

• A plugin manifest file named openclaw.plugin.json for every plugin.
• A strict JSON Schema defined inside each plugin manifest.
• The openclaw CLI.

Quick Start

You can fix configuration issues in about five minutes by following these steps.

1. Start the gateway: OpenClaw runs a doctor dry-run every time it starts. If your config is invalid, it will block startup and show you a summary of errors.
2. Review the errors: Look for grouped sections in the output. You will see unknown keys with their full paths and any plugin load failures.
3. Apply automatic fixes: Run the following command to migrate legacy keys and remove unrecognized settings:

   openclaw doctor --fix

4. Verify the results: Check the system status to ensure everything is running correctly:

   openclaw status

Troubleshooting

Plugin Load Blocked

If a plugin fails to load, it is usually because the openclaw.plugin.json is missing or the configuration does not match the provided schema. The error message will show the plugin ID and the specific path that failed validation. You must provide a valid schema in the manifest to resolve this.

Command Hard-Fail

When your configuration is invalid, OpenClaw restricts you to diagnostic commands. If you try to run a restricted command, you will see the message: “Config invalid. Run openclaw doctor --fix.” In this state, only these commands are allowed:

• openclaw doctor
• openclaw logs
• openclaw health
• openclaw status

If you need more help with your specific configuration, check out the AI Setup Assistant.

What’s Next

• Plugin Manifest Specifications
• CLI Command Reference