How to Update OpenClaw: Complete Guide to Updates, Channels & Rollbacks (2026)

Why Updates Matter

OpenClaw is under active development, with new releases shipping multiple times per month. Here's what you miss when you skip updates:

Bottom line: If you haven't updated in more than 2–3 weeks, you're probably missing something meaningful. If it's been more than a month, update now.

• New model support. When providers like Anthropic, OpenAI, or Google release new models, OpenClaw adds support quickly. Running an old version means you can't use the latest Claude, GPT, or Gemini models.
• Security patches. Each release includes fixes for vulnerabilities in dependencies and OpenClaw itself. An unpatched gateway exposed to the internet is a real risk.
• Bug fixes. Memory leaks, channel disconnections, cron scheduling edge cases — these get fixed in point releases.
• New features. Multi-agent orchestration, ACP sessions, new channel integrations, and skill improvements land regularly.
• Config migrations. OpenClaw's config schema evolves. The openclaw doctor tool (which runs automatically during updates) migrates your config to the current format so you don't have to do it manually.

Check Your Current Version

Before updating, check what you're running:

The format is YYYY.M.D (year, month, day of the release build), followed by a short git commit hash.

To see the full update status including your channel and install method:

This outputs a table showing your install method (pnpm, npm, git, etc.), your channel (stable by default), and the latest available version.

For machine-readable output (useful in scripts):

To check what the latest published version is on npm:

openclaw --version

OpenClaw 2026.3.13 (61d171a)

openclaw update status

openclaw update status --json

npm view openclaw version

The Recommended Way: openclaw update

Regardless of how you installed OpenClaw, the universal update command is:

This command is smart. It detects your install type (npm global, pnpm global, or git checkout), fetches the latest version for your configured channel, installs dependencies and builds (for git installs), runs openclaw doctor to migrate config and check health, syncs plugins to match the new version, and restarts the gateway automatically.

That's it. One command handles everything. For most users, this is the only update workflow you'll ever need.

If you prefer, there's a shorthand: openclaw --update. This rewrites to openclaw update internally. Handy for launcher scripts.

openclaw update

# Preview what would happen without making changes
openclaw update --dry-run

# Update without restarting the gateway
openclaw update --no-restart

# Output results as JSON (for automation)
openclaw update --json

# Skip confirmation prompts (CI/automation)
openclaw update --yes

# Set a custom timeout (default: 1200 seconds)
openclaw update --timeout 300

Updating by Installation Method

The update process varies depending on how you originally installed OpenClaw. Here's how to update for each method.

npm / pnpm Global Install

This is the most common install method. OpenClaw was installed globally via a package manager.

Using openclaw update (recommended):

Manual npm update:

Manual pnpm update:

Using the installer script:

Add --no-onboard to skip the onboarding wizard if you've already configured everything:

openclaw update

npm i -g openclaw@latest
openclaw doctor
openclaw gateway restart

pnpm add -g openclaw@latest
openclaw doctor
openclaw gateway restart

curl -fsSL https://openclaw.ai/install.sh | bash

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Git Source Install

If you cloned the OpenClaw repository and run from source, openclaw update handles everything: checking for a clean working tree, fetching upstream, checking out the appropriate tag or rebasing on main, installing dependencies, building the project and Control UI, running doctor, syncing plugins, and restarting the gateway.

Manual git update:

Important: openclaw update won't proceed if your working directory has uncommitted changes. Commit or stash them first.

For the dev channel on git, OpenClaw has a clever safety mechanism: it runs a preflight lint + TypeScript build in a temporary worktree. If the tip of main fails to build, it walks back up to 10 commits to find the newest clean build. This means openclaw update --channel dev almost always succeeds, even when main is temporarily broken.

openclaw update

cd ~/openclaw
git fetch origin
git pull --rebase origin main
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart

Docker Install

If you run OpenClaw in Docker, the update process depends on your Docker setup.

Docker Compose (most common):

Plain Docker:

Docker with specific version:

For Docker users, your data persists in volumes, so pulling a new image is safe. Just make sure your volumes are properly mounted.

# Pull the latest image
docker compose pull

# Recreate the container with the new image
docker compose up -d

# Verify
docker compose exec openclaw openclaw --version

docker pull openclaw/openclaw:latest
docker stop openclaw
docker rm openclaw
docker run -d --name openclaw \
  -v openclaw-data:/data \
  -p 18789:18789 \
  openclaw/openclaw:latest

docker pull openclaw/openclaw:2026.3.13

Raspberry Pi

Updates on Raspberry Pi follow the same npm/pnpm path, but ARM builds can sometimes take longer:

If you hit memory issues during the build step (common on Pi 3 and older):

openclaw update

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=512"
openclaw update

Understanding Update Channels

OpenClaw ships three update channels: stable (npm latest tag, vetted releases, high stability, for most users), beta (beta tag, builds under test, medium stability, for early adopters), and dev (dev tag, main branch, low stability, for contributors).

Stable is what you want. Builds are promoted from beta after testing. Config migrations are tested. Breaking changes are documented in release notes.

Beta builds ship before stable. They're feature-complete but may have edge cases. The beta channel is great if you want new features 1–2 weeks before stable, and you're comfortable reporting bugs.

The dev channel tracks the main branch. This is active development — incomplete features, potential breaking changes, experimental code. Only use this if you're contributing to OpenClaw or testing something specific.

The --channel flag persists your choice in config (update.channel), so future openclaw update calls use the same channel.

One-off version targeting (without switching channels) is available with the --tag flag. It applies only to the current update and doesn't persist.

# Switch to beta
openclaw update --channel beta

# Switch to dev (creates a git checkout if needed)
openclaw update --channel dev

# Switch back to stable
openclaw update --channel stable

# Install a specific version (one-off, doesn't change your channel)
openclaw update --tag 2026.3.14

# Install from beta dist-tag (one-off)
openclaw update --tag beta

# Install from GitHub main (npm tarball)
openclaw update --tag main

openclaw update --channel beta --dry-run

Setting Up the Auto-Updater

Don't want to remember to run openclaw update? Enable the auto-updater. The auto-updater is off by default. Enable it in your config file (~/.openclaw/openclaw.json):

How it works per channel: For stable, it waits stableDelayHours (default: 6h) after a new version is published, then applies with a deterministic jitter spread across stableJitterHours (default: 12h). This spreads rollout so not everyone updates at the exact same time. For beta, it checks every betaCheckIntervalHours (default: 1h) and applies immediately when found. For dev, there is no automatic apply — you must run openclaw update manually since dev is too unstable for unattended updates.

By default, the gateway logs an update hint on startup if a new version is available. Disable this with checkOnStart: false in your update config.

• Start with stableDelayHours: 24 if you're cautious. This gives the community a full day to find issues before you auto-update.
• Never auto-update dev. It's experimental by definition.
• Monitor after enabling. Check openclaw update status periodically to confirm auto-updates are landing.
• Set up cron heartbeats to detect if an auto-update breaks something.

{
  "update": {
    "channel": "stable",
    "auto": {
      "enabled": true,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  }
}

How to Roll Back an Update

Sometimes an update breaks something. Here's how to go back.

For npm/pnpm installs, pin a specific version:

To find available versions:

Note: Downgrades require confirmation because older versions may not understand newer config formats. Use --yes to skip the prompt in scripts.

For git installs, find the commit you want and check it out:

To roll back to a specific date:

To return to latest after testing: git checkout main && git pull.

For Docker, pull and run a specific version:

After any rollback, always run openclaw doctor and openclaw health. Doctor checks config compatibility with the older version. If your config was auto-migrated to a newer format, doctor may flag warnings — this is expected.

# Roll back to a known good version
npm i -g [email protected]

# Run doctor to ensure config compatibility
openclaw doctor

# Restart the gateway
openclaw gateway restart

npm view openclaw versions --json | tail -20

cd ~/openclaw

# Find the commit you want
git log --oneline -20

# Check out that commit
git checkout <commit-hash>

# Rebuild
pnpm install && pnpm build

# Restart
openclaw gateway restart

git fetch origin
git checkout "$(git rev-list -n 1 --before="2026-03-01" origin/main)"
pnpm install && pnpm build
openclaw gateway restart

# Pull and run a specific version
docker pull openclaw/openclaw:2026.3.10
docker compose down
# Update docker-compose.yml to pin the version
docker compose up -d

Post-Update Checklist

After every update, run through this quick checklist:

1. Run Doctor: openclaw doctor runs automatically during openclaw update, but if you updated manually (npm/Docker), run it explicitly. Doctor handles config migration from legacy formats, state directory migration, cron job store migration, browser config normalization, service config audit, and gateway health check.

2. Restart the Gateway: openclaw update does this automatically (unless you passed --no-restart). For manual updates, always restart.

3. Verify Health: You should see a healthy response with the new version number.

4. Check Channel Connectivity: Verify your Telegram, Discord, WhatsApp, or other channels are connected and responding.

5. Test Your Agent: Send a quick test message through your preferred channel. Verify the agent responds, memory files are accessible, skills are loaded, and cron jobs are running.

openclaw doctor

openclaw gateway restart

openclaw health

openclaw channels status --probe

Troubleshooting Common Update Issues

Here are the most common problems you'll encounter during updates and how to fix them.

"Uncommitted changes" Error (Git Installs): Fix by committing or stashing your changes first:

Port Conflict After Update: The old gateway process didn't stop properly. Find and kill the old process, or use the force flag:

"Gateway start blocked: set gateway.mode=local": This happens when the config is missing the local gateway mode setting:

npm Permission Errors: Don't use sudo with npm. Fix npm permissions or use pnpm instead:

Config Migration Failures: If openclaw doctor reports config issues after an update, try repair:

Build Failures (Git Install): Clean and rebuild, or try the update wizard which guides you through recovery steps interactively:

Auto-Updater Not Working: Check that it's actually enabled with openclaw config get update, and verify the gateway logs for update-related messages.

Docker Container Won't Start After Pull: Check container logs, and recreate instead of just restart. If the issue is data volume related, check permissions.

cd ~/openclaw
git stash
openclaw update
git stash pop  # re-apply your changes after

# Find and kill the old process
lsof -ti:18789 | xargs kill -9

# Restart
openclaw gateway restart

openclaw config set gateway.mode local
openclaw gateway restart

# Fix npm permissions
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Or use pnpm instead (handles this better)
pnpm add -g openclaw@latest

# View your current config
cat ~/.openclaw/openclaw.json

# Run doctor with repair
openclaw doctor --repair

# If that doesn't work, try aggressive repair
openclaw doctor --repair --force

# Clean and rebuild
rm -rf node_modules
pnpm install
pnpm build

# If still failing, try the update wizard
openclaw update wizard

# Check container logs
docker logs openclaw

# Recreate instead of just restart
docker compose down
docker compose up -d

Update Frequency: How Often Should You Update?

Here's a practical guideline: Personal daily driver users should update every 1–2 weeks on stable. Business/production deployments should update monthly with testing on stable. Tinkerers and early adopters can update weekly on beta. Contributors and developers update as needed on dev. DoneClaw managed users get automatic updates.

Signs you need to update immediately: a security advisory was posted in the OpenClaw Discord, your agent can't use a new model you need, you're hitting a known bug that's been fixed, or openclaw doctor says "please update".

Signs you can wait: everything works fine, you're in the middle of a busy period, or the changelog only shows minor fixes.

DoneClaw Managed Users: Updates Are Handled for You

If you're using DoneClaw's managed service, you don't need to worry about any of this. Your agent gets the latest features and security fixes without downtime. This is one of the core benefits of managed hosting — you focus on using your agent, not maintaining it.

Want to check your DoneClaw instance version? Just ask your agent: "What version of OpenClaw are you running?" It can tell you directly.

• Automatic updates on the stable channel with a staggered rollout
• Config migrations applied automatically by doctor
• Health monitoring to detect and fix post-update issues
• Rollbacks if an update causes problems for your specific instance
• Docker image management including security patches for the base image

Advanced: Scripting Updates for Multiple Instances

If you manage several OpenClaw instances (homelab, multiple VPSes, team deployments), here's a script to update them all:

For Docker-based instances:

Combine this with an OpenClaw cron job to have your agent remind you about available updates.

#!/bin/bash
# update-all-openclaw.sh

HOSTS=(
  "[email protected]"
  "[email protected]"
  "[email protected]"
)

for host in "${HOSTS[@]}"; do
  echo "=== Updating $host ==="
  ssh "$host" "openclaw update --yes --json" 2>&1
  echo ""
done

#!/bin/bash
# update-docker-openclaw.sh

HOSTS=(
  "[email protected]"
  "[email protected]"
)

for host in "${HOSTS[@]}"; do
  echo "=== Updating $host ==="
  ssh "$host" "cd /opt/openclaw && docker compose pull && docker compose up -d" 2>&1
  echo ""
done

Conclusion

Updating OpenClaw is straightforward once you know your install method: 1. Check version: openclaw --version 2. Update: openclaw update (works for npm, pnpm, and git) 3. Verify: openclaw health For Docker, pull the new image and recreate the container. For DoneClaw managed, it's automatic. Set up the auto-updater if you want hands-off maintenance, or script it for multiple instances. Keep the troubleshooting section bookmarked for when things go sideways. The most important thing: don't let your agent fall too far behind. An up-to-date OpenClaw instance is a more capable, more secure, and more reliable AI agent.

Frequently asked questions