Until v2026.3.28, OpenClaw would silently rewrite legacy config keys every time it started up. Old key? It would quietly migrate it to the new format and keep going. You'd never know.

That behavior is gone.

Starting with 3.28, the gateway no longer auto-repairs deprecated config. If you have old keys sitting in your openclaw.json — and if your install predates January 2026, you probably do — they'll stop working silently on the next update that drops support for them.

From the v2026.3.28 release notes: "Config repair behavior changed: The gateway no longer auto-repairs deprecated config keys at startup. If your install predates January 2026 and you haven't run openclaw doctor since, run it to see what was quietly fixed."

Step 1: Run openclaw doctor

This is a built-in diagnostic tool. Run it now:

openclaw doctor

It scans your config files, workspace structure, and plugin settings for known issues. Output looks something like this:

OpenClaw Doctor — v2026.4.2
Scanning config...

⚠  Deprecated key: tts.provider → use tts.engine (legacy support ends v2026.5)
⚠  Deprecated key: gateway.bindAddress → use gateway.bind
✓  Auth token: present
✓  Gateway: reachable
⚠  exec-approvals.json: missing (defaults to block-all on v2026.4.1+)
✓  Workspace: found at ~/.openclaw/workspace
⚠  Channels: telegram plugin config missing webhookUrl
✓  Node: v22.22.0 (supported)

3 warnings, 0 errors.
Run `openclaw doctor --fix` to auto-resolve warnings where possible.

Step 2: Run --fix for Auto-Resolvable Issues

openclaw doctor --fix

This handles the easy migrations automatically — renamed keys, moved config sections, deprecated aliases. It creates a backup of your config before making changes.

After running it, run openclaw doctor again to confirm the warnings are cleared.

Step 3: Fix the Remaining Warnings Manually

Some warnings require manual intervention. Here are the most common ones and exactly how to fix them:

Warning
exec-approvals.json: missing (defaults to block-all on v2026.4.1+)
Create the file at ~/.openclaw/exec-approvals.json. Minimal config to restore pre-4.1 behavior: 
{
  "version": 1,
  "rules": [
    {
      "match": "*",
      "ask": "on-miss",
      "security": "allowlist"
    }
  ]
}
Or for fully trusted local installs: "ask": "off". See the approvals docs for full reference.
Warning
Channels: telegram plugin config missing webhookUrl
Your Telegram plugin has a token but no registered webhook. Fix:

openclaw channels telegram setup

This re-registers your bot's webhook URL with Telegram's API. Required after any domain/IP change or if you migrated servers.
Warning
Deprecated key: tts.provider → use tts.engine
In your openclaw.json, rename the key:
"tts": {"provider": "..."} → "tts": {"engine": "..."}

The value stays the same. Just the key name changed. openclaw doctor --fix usually handles this automatically.
Warning
Deprecated key: gateway.bindAddress → use gateway.bind
In openclaw.json:
"gateway": {"bindAddress": "127.0.0.1"} → "gateway": {"bind": "127.0.0.1"}

Again, value is unchanged — just the key name. Doctor --fix handles this.
Warning
MiniMax plugin: API shape changed, reconfigure required
MiniMax changed their API in v2026.3.28. If you use MiniMax, you need to re-enter credentials:
openclaw channels minimax setup

If you don't use MiniMax, remove the plugin config entirely to suppress the warning.

How to Check if You're Affected

Quick check — when was your OpenClaw first installed?

# Check your oldest config file timestamp
ls -la ~/.openclaw/openclaw.json

# Check git history if your workspace is version controlled
cd ~/.openclaw/workspace && git log --oneline | tail -1

If your install is older than January 2026, there's a near-100% chance you have at least one deprecated key. Run doctor.

Make This Part of Your Update Routine

Going forward, add openclaw doctor to your update process — run it after every major version bump:

# Before updating: back up
cp -r ~/.openclaw ~/.openclaw-backup-$(date +%Y%m%d)

# Update
npm update -g openclaw

# After updating: check config health
openclaw doctor

# Auto-fix where possible
openclaw doctor --fix

# Verify
openclaw doctor

Takes 2 minutes. Prevents the kind of silent config drift that leads to a mysterious broken channel three updates later.

ClawReady includes config health checks on every managed care plan update. We run doctor before and after every version bump and fix any warnings before they become problems. If you'd rather not think about this — book a call.