Updating OpenClaw is safe when you do it in the right order. The risk is not the update itself , it is running an update without knowing what it touches, or triggering a restart that silently reverts config changes you made manually. This article walks through the correct update sequence, what to back up beforehand, and how to recover if something goes wrong.
TL;DR
- Back up openclaw.json before any update. One command. Takes five seconds.
- Check what the update changes before applying it, especially if you have local source patches.
- Use update.run through the gateway tool, not manual git pulls or npm commands.
- Verify config after restart , a few key values confirm the update did not overwrite your settings.
Throughout this article you will see indented blocks like the ones below. Each one is a command you can paste directly into your OpenClaw chat. Your agent will run it and report back. You do not need to open a terminal or edit any files manually.
What the OpenClaw update actually changes
An OpenClaw update replaces the application code: the gateway binary, the built-in plugins, and the node modules the application depends on. It does not touch your openclaw.json config file, your workspace directory, your memory database, your LCM database, or your session history. All of those live in ~/.openclaw/ separately from the application code and are never overwritten by a standard openclaw update. Your data is safe. The risk is in config behavior changes, not data loss.
What can go wrong during an openclaw update is more subtle than data loss. A config migration runs during startup after certain updates, adding new config fields or changing the values of fields you never explicitly set. A plugin update may introduce new required config keys that your current config does not have, causing the plugin to use a different default behavior than what you configured before. Any source patches you applied directly to plugin files are silently overwritten when those files are replaced by the update.
What version of OpenClaw am I currently running? Check the installed version and compare it to the latest available. Are there any pending updates? Show me the version information.
Knowing your current version and the target version lets you review the release notes for that specific delta before committing to the update. A minor patch release is typically low risk. A major or minor version jump warrants more careful review, especially if you are running local source patches or non-default config values.
Step 1: Back up config before the update
The config backup is one command and takes under ten seconds. There is no reason to skip it before an openclaw update. Even in the common case where the update does not touch your config at all, having a clean timestamped backup means you can restore in under a minute if something unexpected happens. The five seconds the backup takes is cheap insurance against the time it would take to reconstruct config values from memory after a bad migration.
Create a timestamped backup of my openclaw.json before the update. Run: cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup-$(date +%Y%m%d-%H%M%S) and confirm the backup file was created. Show me its size and the timestamp in the filename.
While you have the config open, note the key values you care about most. These become your verification baseline after the update completes:
Before I update, read my openclaw.json and show me these specific values: agents.defaults.model, gateway.bind, channels.discord.dmPolicy, channels.telegram.dmPolicy, and plugins list (just the plugin names and enabled status). These are my baseline to verify against after the update.
Write those values down in a note, a scratch file, or anywhere that survives the gateway restart. The post-update verification step compares the live config against this baseline to catch any migration that changed a value you cared about.
Step 2: Check for local source patches
If you have applied any manual patches to plugin source files, those patches will be overwritten when the plugin files are updated. Common patches include timeout adjustments, config key additions, or bug fixes you applied before an upstream fix was available.
Check my AGENTS.md for any documented source patches. Are there any patches listed that apply to plugin source files? List each patched file, the location, and what was changed. I need to know which files to re-patch after the update.
If you have source patches, note the exact file path and the specific change for each one before running the update. After the openclaw update replaces those files, you will need to re-apply the patches manually before using any functionality that depends on them. The update unconditionally replaces plugin files and does not check for or preserve any manual edits in those files.
Source patches are silently overwritten
The update process does not warn you when it overwrites a patched file. If you have a critical patch (such as a timeout fix that prevents silent failures) and you run the update without re-applying it, the behavior regresses silently. You may not notice until a task fails in the same way it failed before you patched it. Always audit patches before and after any update.
Step 3: Run the update through the gateway tool
The correct way to run an openclaw update is through the update.run gateway action built into the tool. This triggers the built-in update mechanism which handles dependency resolution, file replacement, and the subsequent restart in the right order. Do not run manual git pull, npm install, or npx commands to update OpenClaw directly. Manual updates bypass the built-in update coordination and can leave the installation in a partially updated state where some files are new and others are old.
Run the OpenClaw update using the gateway update.run action. Before triggering it, confirm: my config is backed up, I have noted all local patches, and I have my baseline config values recorded. Then run the update and report the output.
The OpenClaw gateway will go offline briefly during the update and restart automatically. This is expected behavior. The update process installs the new application version, runs any pending config migrations, and brings the gateway back up. Most openclaw updates complete and have the gateway reconnected within one to three minutes on a typical VPS.
The gateway will go silent during restart
When the gateway restarts during an update, the Discord or Telegram connection drops momentarily. You will not receive a response to the update command until the gateway comes back up and reconnects. Wait two to three minutes before assuming something went wrong. If the gateway does not reconnect after five minutes, check the gateway logs via SSH.
Step 4: Re-apply source patches after the update
Once the openclaw gateway is back up and responding, re-apply any source patches before doing anything else that might trigger the patched code paths. The updated plugin files are now in place and need your patches applied to them before any functionality that depends on those patches is invoked.
The update is complete. Re-apply all documented source patches from AGENTS.md. For each patch: read the target file, apply the change, and confirm the patched line is present in the file. List each patch applied with a pass or fail confirmation.
After re-applying all patches, check the release notes for the new version to see whether any config changes upstream now covers behavior you were patching. If a timeout extension or behavior change you were patching in has been made configurable in the new version through openclaw.json, you can move it to config and retire the source patch entirely. This is worth checking after every openclaw update that touches plugins you have patched.
For each patch I re-applied, check the new version’s config schema to see if the patched behavior is now configurable through openclaw.json. If it is, show me the config key and the value I should set to replace the source patch.
Step 5: Verify config survived the update
With the openclaw gateway back up and all patches re-applied, verify the key config values match your pre-update baseline. This is a quick step that catches any migration-driven value changes before they cause unexpected behavior.
Post-update config verification. Read my openclaw.json and confirm these values match my pre-update baseline: agents.defaults.model, gateway.bind, channels.discord.dmPolicy, channels.telegram.dmPolicy, and the plugins list (names and enabled status). Flag any value that differs from what I noted before the update.
If any value differs from your pre-update baseline, compare it against the backup file to determine whether the change is intentional (a migration added a new field with a reasonable default) or a regression (an existing value you deliberately set was reset to default). The distinction matters: intentional changes from openclaw config migrations are fine, but regressions need to be corrected explicitly.
Compare my current openclaw.json against ~/.openclaw/openclaw.json.backup-[TIMESTAMP] and show me any differences. Focus on values that changed rather than new keys that were added. Did any of my deliberate config settings get reset to default?
New config keys added by a migration are expected and generally fine. Existing values that changed from what you had set are what require attention and correction. For any value that was reset to a default you did not intend, restore it with a config patch and restart the gateway. Then run the session replacement step to ensure the new session picks up the corrected value.
Step 6: Run a basic functional test
Config is verified and patches are re-applied. Before calling the openclaw update complete, run a quick functional test to confirm the core agent capabilities are all working correctly on the new version. A passing functional test is the final confirmation that the update is clean.
Run a post-update functional test. Check: (1) web search works, (2) file read works by reading a known workspace file, (3) memory recall returns results, (4) exec runs a simple command (echo “test”) and returns output, (5) at least one cron job is listed. Report pass or fail for each check.
Any failure on this test identifies a specific regression introduced by the openclaw update. A failing web search test suggests an API key was not preserved through the migration. A failing exec test suggests a tool permission configuration changed. Missing cron jobs suggest the cron store was affected by the update in an unexpected way. Each failure type points to a specific cause to investigate and resolve.
How to roll back if the update breaks something
If the update introduces a breaking change and you need to roll back, the config backup is your first resource. Restoring the config backup will not roll back the application code, but it will restore any config values that were changed by a migration.
I need to restore my pre-update config backup. Run: cp ~/.openclaw/openclaw.json.backup-[TIMESTAMP] ~/.openclaw/openclaw.json and confirm the restore. Then restart the gateway with the restored config. Show me the key config values after restore to confirm the rollback is correct.
Rolling back the application code itself (the OpenClaw binary) requires manual intervention at the server level. For most issues encountered after an update, restoring the config backup and re-applying patches resolves the problem without needing a code rollback. True code rollbacks are rare and indicate a regression in the upstream release rather than a config issue.
Deciding how often to update OpenClaw
There is no single right cadence. The tradeoffs are:
- Updating frequently keeps you current with security patches, bug fixes, and new features. The risk per update is low because each update is a small delta.
- Updating less frequently means fewer disruptions but larger deltas when you do update. More changes in one update means more to verify and more potential for something to break.
- Not updating leaves known security vulnerabilities unpatched. Given the ClawHub crisis and the rate of plugin security issues being discovered, running an outdated version is a meaningful risk for an agent with exec access and API keys configured.
Set up a monthly cron job that checks for available OpenClaw updates and sends me a Telegram notification listing the current version, the latest available version, and whether an update is recommended. Schedule it for the first of each month.
A monthly update check cron gives you visibility without committing to automatic updates. You see the delta, review the release notes if the update is significant, and apply it when you choose. This is a reasonable balance between staying current and maintaining control.
Updating plugins separately from OpenClaw
Plugins installed from npm or ClawhHub update independently from the OpenClaw core. A plugin update follows the same pre/post steps as a core update: backup config, note patches, run the update, re-apply patches, verify config.
Check whether any of my installed plugins have available updates. For each plugin that has an update available, show me: the current version, the latest version, and whether I have any source patches applied to that plugin’s files. I want to assess the risk of each plugin update before applying any of them.
Plugin updates warrant the same scrutiny as core updates, particularly for plugins with exec tool access, memory access, or external API connections. An update to a plugin that handles your memory database is higher risk than an update to a display formatting plugin. Assess each update on its own merits.
Understanding config migrations and what they do
When a new OpenClaw version introduces new config fields or changes the structure of existing ones, it runs a config migration on first startup. Migrations are additive by default: they add new fields with default values and do not remove or change fields you have explicitly set.
The risk is in defaults. If you have been relying on a default value that changes between versions, and you never explicitly set that value in your config, the new default applies after the migration. Your config file now has the new value, and it looks like it was always set that way. Without a pre-update baseline, you would not know the value changed.
After the openclaw update completed, did any config migrations run? Check the gateway startup logs for any mentions of migration, config update, or schema change. List any migration events and what fields they touched.
If a migration ran and changed a default you were relying on, you have two options. Set the value explicitly in config to the old default (so future migrations do not change it), or accept the new default if the change was intentional upstream. Check the release notes to understand whether the changed default is a deliberate improvement or a regression.
The long-term fix is to never rely on implicit defaults for settings you care about. If your agent depends on a specific model, set it explicitly. If your gateway bind address needs to be loopback, set it explicitly. Explicit config values survive migrations intact. Implicit defaults do not.
Pinning to a specific OpenClaw version
If you need to stay on a specific version, for example because you are mid-project and do not want to risk a regression, you can pin the version rather than running the latest. This requires understanding which version you are on and ensuring the update mechanism does not pull a newer version automatically.
What exact version of OpenClaw am I running right now? Show me the full version string including any patch or build identifiers. Is there a way to see the package.json version or the installed npm package version? I want to know the precise version before I decide whether to update.
Version pinning is a tradeoff. A pinned version gives you stability but accumulates unpatched vulnerabilities over time. Given the rate of plugin security issues in the OpenClaw ecosystem (the ClawHub crisis affected versions running outdated plugin code), staying current with security patches is more important than version stability for most personal deployments.
A better approach than pinning is running updates promptly when security-relevant releases ship, and doing so with the backup-and-verify workflow in this article. That gives you the protection of current security patches without the instability of running untested version jumps.
The complete pre-update checklist
Before running any OpenClaw update, run through this checklist:
- Config backup created and timestamped
- Key config values noted (model, gateway.bind, channel dmPolicy settings, plugin list)
- Source patches documented and their target files identified
- Release notes reviewed for breaking changes or behavior changes
- No active long-running tasks in progress (cron jobs idle, no multi-step operations mid-execution)
- Access to SSH as a fallback confirmed (in case the gateway does not come back up after restart)
Run the pre-update checklist. Verify each item above: confirm config backup exists with today’s timestamp, show me my key config baseline values, list any documented source patches, confirm no cron jobs are currently running, and verify SSH access is available as a fallback path.
All six items passing means you are ready to update. If any item fails, resolve it before running the update. The most commonly skipped item is number six: confirming SSH access. If the gateway does not come back up after the update, SSH is your only recovery path. Verifying SSH works before the update is much easier than discovering it does not work when you need it.
The complete post-update checklist
After the update completes and the gateway is back up:
- Version confirmed (new version is running, not the old one)
- Source patches re-applied and verified in files
- Key config values match pre-update baseline
- Functional test passes (web search, file read, memory, exec, cron list)
- Channel connections confirmed (Discord and Telegram responding)
- Any migration-added config fields reviewed and explicitly set if needed
Run the post-update checklist. Confirm each item: current version matches the expected update target, all source patches are present in their files, key config values match baseline, functional test passes, both Discord and Telegram channels are responding, and any new config fields from migrations are set to explicit values rather than left as defaults.
Why you need a new session after certain updates
OpenClaw caches some values in the session entry on first response. Context window size, compaction settings, and model config are among the values that get locked in at session start. After an update that changes any of these values (through a migration or a config change you made before restarting), the running session still has the old cached values.
A new session reads the current config fresh. The old session reads what was cached when it started, regardless of what the config file now says. This is not a bug, but it is a behavior that causes confusion when an update changes a setting that appears to have no effect.
After the update, does my current session need to be replaced with a new one for any config changes to take effect? Specifically: did the update change any context window settings, compaction config, or model defaults? If any of those changed, I need to start a new session before verifying the new values are active.
The rule is: if the update changed context window, compaction, or model settings, start a fresh session before verifying. Then run the post-update checklist in the new session to confirm the new values are what the session is actually using.
Managing config backup files over time
Each update creates a timestamped backup. After running updates for a few months, the ~/.openclaw/ directory accumulates backup files. These are small, but it is worth periodically cleaning up backups older than a few versions.
List all openclaw.json backup files in ~/.openclaw/ ordered by date. Run: ls -lt ~/.openclaw/openclaw.json.backup-* 2>/dev/null and show me the full list. How many backup files exist? I want to keep the three most recent and delete the rest.
Keeping the three most recent backups gives you openclaw config rollback coverage for the last three updates. More than that adds clutter without meaningful additional safety, since a backup older than three versions is unlikely to be useful if something goes wrong today.
When an update breaks a channel connection
A common post-update issue is a channel plugin that stops working. The Telegram or Discord connection was fine before the update and fails to connect after restart. This happens when a plugin update changes the authentication flow, the API version, or the expected config structure.
My [Discord/Telegram] channel is not responding after the update. Check the gateway logs for any channel plugin errors. Look for: authentication failures, API version errors, missing config keys, or webhook registration failures. Show me the relevant error messages.
The most common causes:
- New required config key: The plugin update added a mandatory field that was not in your config before the migration. Check the release notes for new required fields and add them.
- API version change: The plugin now targets a different version of the Discord or Telegram API. Usually this resolves automatically, but sometimes requires re-registering a webhook or resetting bot permissions.
- Token format change: Rare, but some updates change how tokens are stored or validated. If the token was working before the update and fails after, check whether the config value survived the migration correctly.
Show me the complete channels.discord config section and channels.telegram config section from my openclaw.json. Are there any new required fields that the post-update plugin expects but that are not set in my config? Compare against the schema for the current version.
Extra care for memory plugin updates
Memory plugins that store data in a local database (like LanceDB) require extra care during updates. The plugin update may change the database schema, requiring a migration that runs on first access. If the migration fails or the old database format is incompatible, memory recall may stop working or return empty results.
Before updating the memory plugin, back up the memory database. Run: cp -r ~/.openclaw/memory-lancedb/ ~/.openclaw/memory-lancedb-backup-$(date +%Y%m%d-%H%M%S)/ or equivalent for the database location. Confirm the backup exists before I proceed with any memory plugin update.
After a memory plugin update, test recall immediately:
Run a memory recall test. Search for something I have stored recently, for example my Cloudflare config or my Telegram chat ID. Do the results return correctly? If memory recall returns empty or errors, check the memory plugin logs for schema migration errors.
If memory recall fails after a plugin update, restoring the database backup and pinning the plugin to the previous version is the correct response. Memory data is irreplaceable in the sense that the agent’s accumulated knowledge lives there. Treat memory database backups with the same seriousness as the openclaw config backup: both are critical before any update that touches the respective data store.
Monitoring the agent for 24 hours post-update
Some issues only surface under real workload. A new session initialized clean, cron jobs that were idle during the update, and the first memory extraction of the day may all behave differently than during the immediate post-update test. Monitoring for the first 24 hours after an openclaw update catches these delayed issues before they accumulate.
Set a reminder for 24 hours from now to run a post-update health check. The check should: verify memory recall is still working, confirm the last 24 hours of cron jobs ran successfully, check that no new errors appeared in the gateway logs overnight, and confirm API spend is in the expected range (indicating no unexpected extra calls from a broken retry loop).
The 24-hour check is a lightweight insurance policy. Most updates are clean and the check takes two minutes. On the rare update that introduces a subtle issue, you catch it on day one rather than after it has been silently accumulating for a week.
Model provider changes and openclaw updates
OpenClaw model provider configs can be affected by updates when the provider API changes or when a new model is added to the provider list. The more common issue is when a provider the update assumes is available is not in your config, causing the agent to fall back to a different provider than intended.
After the openclaw update, verify my model provider configuration is intact. Show me the current models.providers config and compare it to what was in my pre-update baseline. Is my primary model still set correctly? Are all my API keys still present (shown as redacted)? Are any new providers added by the update that I should be aware of?
Pay particular attention to the fallback model chain. If the update added a new provider with a different cost profile to the default fallback list, and your primary model hits a rate limit, you might start getting charged at a different rate than expected. Review the fallback config explicitly after any update and confirm it matches your intent.
Frequently asked questions
Does the update overwrite my openclaw.json?
No. The openclaw update process replaces application code files but does not touch ~/.openclaw/openclaw.json. However, a config migration may run on first startup after the update, which can add new fields or change existing defaults for fields you never explicitly set. This is different from overwriting: your explicitly set values are preserved, but new default values for newly introduced config keys are added automatically. After every openclaw update, compare your config to the pre-update backup to confirm no values changed unexpectedly. Focus on values that matter to your deployment: model selection, gateway bind address, channel access control settings, and plugin enabled states.
Do I lose my cron jobs when I update?
No. Cron job definitions are stored in the OpenClaw database at ~/.openclaw/, separate from the application code that gets replaced during an update. Your scheduled jobs persist through the openclaw update and resume on the next scheduled interval after the gateway restarts. The only cron jobs that could be affected are ones whose logic depends on a specific plugin that was updated, and only if that plugin’s behavior changed in a way that breaks the job. After an update, verify your critical cron jobs ran on their next scheduled trigger and completed successfully.
Will the update reset my model config to defaults?
It should not, but verify it regardless. The model config, including which model is set as default, the fallback order, and your provider API keys, all live in openclaw.json and are not overwritten by the update process. What can happen is a config migration that changes the effective default if you never explicitly set the model in your config. If agents.defaults.model is set to a specific value in your config file, that value persists through the migration. If you relied on the implicit default (whatever value ships with the OpenClaw version you were on), a version change could alter what that default resolves to. The safe practice is to always explicitly set your preferred model in config so migrations cannot silently change it.
What happens to my LCM database and conversation history during an update?
Nothing. The LCM database at ~/.openclaw/lcm.db is stored in ~/.openclaw/ and is not touched by the openclaw update process. All summaries, message history, and compacted context survive the update unchanged. Your conversation continuity is fully maintained across the update. The agent reads the same context after the update as it had before, because all context data lives in the database, not in the application code that the update replaces. The only scenario where LCM data would be affected is if a migration changes the LCM database schema itself, which is rare and would be called out explicitly in the release notes if it occurred.
My update failed partway through. What do I do?
First, check whether the openclaw gateway is still running by attempting to interact with your agent through Discord or Telegram. An interrupted update sometimes leaves the old version running if the update failed before replacing the binary. If the gateway is up and responding normally, your old version is likely still running and the interrupted update left no damage. If the gateway is down and not reconnecting, SSH to the server and check the gateway service status and update logs. In most cases, you can either restart the old binary manually or rerun the update command from the terminal. The config backup you made before the update is valid regardless of what happened during the update process, so your config is recoverable even in a worst-case partial update scenario.
Can I update OpenClaw while tasks are running?
Technically yes, but not recommended. An openclaw update triggers a gateway restart that interrupts any task currently in progress. If a cron job is running mid-execution when the restart occurs, that execution is abandoned and does not resume. If you are mid-way through a multi-step operation in a chat session, the current turn context is lost, though LCM preserves whatever was compacted before the restart. The interruption is recoverable but inconvenient. The better practice is to schedule openclaw updates for a quiet period: no active cron jobs running, no complex multi-turn operations in flight, and ideally at a time when you are available to verify the post-update state promptly.
How do I know if an update includes security patches?
Check the OpenClaw release notes at github.com/openclaw/openclaw before applying any significant update. Security-related updates are typically called out explicitly in the release notes. If a release includes a CVE fix or a security hardening change, it will be noted. Treat any update that mentions authentication, access control, exec tool security, or plugin isolation as security-relevant and prioritize it.