OpenClaw broken after an update? Every fix, in the order to try them

Triage: three commands before you change anything

Do not start editing config files yet. OpenClaw ships diagnostics that identify most post-update breakage on their own, and you want a clear picture before you make changes on top of a half-migrated install:

openclaw --version confirms the update actually applied. A surprising number of "broken after update" reports are updates that silently failed, leaving a half-old, half-new install. openclaw doctor checks the runtime environment (Node.js version, package manager, config health). openclaw config validate tells you whether your ~/.openclaw/openclaw.json still parses and matches the current schema.

Then look at the logs from the moment the gateway last tried to start:

The first error line after the restart usually names the failure directly. Everything below is the fix for each of the errors you are likely to see there.

Fix 1: config schema changed (the most common one)

OpenClaw updates frequently change the configuration schema. Keys get renamed, moved, or nested differently, and your existing openclaw.json no longer matches what the new version expects. The symptom is a gateway that refuses to start, or starts and ignores settings that worked yesterday.

The built-in migration handles most of it:

doctor --fix rewrites your config to the current schema where it can. Run config validate afterward to confirm nothing is left over, then restart the gateway and send the bot a test message.

If config validate still reports errors after doctor --fix, the remaining keys need manual attention. Check the release notes for the version you just installed, fix the named keys in ~/.openclaw/openclaw.json, and validate again. The config file is plain JSON, so one trailing comma or missing quote will keep OpenClaw from starting with a cryptic error. Validate after every manual edit.

Fix 2: the agent replies but cannot do anything

This one looks strange: the bot answers in Telegram, chats normally, but claims it cannot read files, write files, or run commands. Tasks it handled last week now come back with permission errors.

The cause is a known update behavior: tools.profile defaulting back to messaging, which strips read, write, and exec permissions from the agent. Your agent did not lose its abilities. Its permission profile got reset.

Open ~/.openclaw/openclaw.json, check what tools.profile is set to now, and set it back to the profile you were running before the update:

If you never changed it and do not know what it was, check the release notes for your previous version or your pre-upgrade backup of openclaw.json. After every future upgrade, verifying tools.profile should be part of your checklist, because this reset has bitten the community more than once.

Fix 3: the gateway will not start at all

If the process dies immediately on start, work through these in order:

• Config syntax. Run openclaw config validate. A JSON syntax error in openclaw.json prevents startup with an unhelpful message. Fix the syntax before anything else.
• Node.js version. OpenClaw requires Node.js 22 LTS or later, and an update can raise the floor. openclaw doctor flags this. If your system Node is older, upgrade it, then retry.
• Package manager. The official tooling assumes pnpm. If doctor reports missing or mismatched dependencies after an update, reinstall them with pnpm rather than npm.
• Service state. On native installs, a stale service definition can survive the update. openclaw gateway install refreshes it, then systemctl --user restart openclaw-gateway.

For Docker installs, a container that restarts in a loop usually means the new image cannot read the mounted config. Check docker compose logs for the parse error, fix the config in your mounted ./data directory, and bring it up again with docker compose up -d.

Fix 4: your custom skills broke

OpenClaw's skill API surface changes between releases. Functions get renamed or removed, and custom skills written against the old surface fail after the update. The log line typically names the missing function.

There is no automated fix for this one. You update the skill code to the new API, or you pin OpenClaw to the version the skill was written for until you have time to port it. Community skills from ClawHub often ship updates within days of a breaking release, so check for a newer version of the skill before rewriting anything yourself.

A separate Docker-specific trap looks like broken skills but is really lost skills: if your skills lived inside the container image instead of the mounted volume, the update wiped them. Skills and config must live in the mounted volume (./data), not in the image layer. Verify the mount:

If the mount is wrong, restore the skills from your backup into the volume, fix the docker-compose.yml volume mapping, and recreate the container.

Rolling back a bad release

Sometimes the right move is to get back to the version that worked and try again next week. On Docker this is clean. Pin the previous image tag in docker-compose.yml:

Then recreate:

If the update also migrated your config or data, restore the backup you made before upgrading over the current ~/.openclaw/ (or the mounted ./data directory), because a schema-migrated config may not run on the older version.

If you did not make a backup, that is the lesson for next time. The standard pre-upgrade ritual is 2 minutes:

One warning on staying pinned: rollback is a delay, not a strategy. CVE-2026-25253, the prompt injection vulnerability patched in 2026.2.8, is the standing example of why running weeks behind on OpenClaw releases carries real risk. Pin to recover, then plan the re-upgrade.

Preventing the next one

OpenClaw's release cadence is not going to slow down for you, so the practical defense is a repeatable upgrade routine. The full version is in our self-hosting OpenClaw guide, but the short list:

• Back up ~/.openclaw/ before every upgrade, without exception.
• Read the release notes before updating, not after the breakage.
• Run openclaw doctor --fix and openclaw config validate immediately after every update.
• Check tools.profile and send the bot one real task before you walk away.
• On Docker, pin exact version tags and upgrade deliberately instead of riding latest.

Budget roughly 20 minutes per upgrade done properly, times 2-4 upgrades per month. That number is the honest cost of self-hosting OpenClaw at production quality.

If you are tired of fixing this every month

Some people enjoy the maintenance. If you just want the agent to work, there are two ways out of the monthly breakage loop.

The first is letting someone else run OpenClaw for you. Hivra hosts OpenClaw on a private managed VM: the open-source agent unmodified, its Control UI behind an authenticated gateway, with the server, install, updates, and uptime handled for you. The daemon is kept running and restarted if it crashes, and your Telegram, WhatsApp, or Signal channels stay live. It needs the Pro plan at $9.99 a month, which covers up to 3 agents. Details on the pricing page.

The second is switching to an agent with a calmer release cadence. Hermes Agent is architecturally comparable (persistent agent, messaging gateway, skills) with fewer breaking changes, and it ships a migration tool (hermes claw migrate) that imports your OpenClaw config, memories, skills, and environment variables. The full comparison is in Hermes vs OpenClaw.

Either way, the fixes above will get today's breakage sorted first.