Updating OpenClaw | OpenClaw AI

Check Current Version

openclaw --version
# OpenClaw AI v1.0.0

# Check if update is available
openclaw update --check

Update Methods

Method 1: Built-in Update Command

The easiest way — updates core and all installed packs:

openclaw update --yes

Method 2: pip

# Update to latest stable
pip install --upgrade openclaw

# Update within a virtual environment
source ~/.venvs/openclaw/bin/activate
pip install --upgrade openclaw

Method 3: conda

conda update -c conda-forge openclaw

Windows PowerShell

pip install --upgrade openclaw

After Updating

Verify the update was successful:

openclaw --version
# OpenClaw AI v1.1.0

# Run a quick smoke test
openclaw run "Say hello world" --provider openai

💡

Before Updating in Production

Always export your configuration first: openclaw config export ~/openclaw-backup.yaml and test in a staging environment if your workflows are business-critical.

Rolling Back

# Install a specific version
pip install openclaw==1.0.0

# Restore backed-up configuration
openclaw config import ~/openclaw-backup.yaml

Configuration Migration

OpenClaw automatically migrates configuration files when updating between minor versions. For major version updates, check the changelog for any manual migration steps:

# Force config migration
openclaw config migrate --version 1.1.0

💡

See Also

Automating Updates in CI/CD

For teams or servers, automate OpenClaw updates as part of your deployment pipeline:

# .github/workflows/update-openclaw.yml
name: Update OpenClaw Weekly
on:
  schedule:
    - cron: "0 3 * * 1"   # every Monday 03:00 UTC
  workflow_dispatch:        # allow manual trigger

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - name: Update OpenClaw
        run: pip install --upgrade openclaw

      - name: Verify version
        run: openclaw --version

      - name: Smoke test
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          openclaw run "Return the word PASS" --model gpt-4o-mini | grep PASS
          echo "Smoke test OK"

Pinning to a Specific Version in Production

For stability in production environments, pin the exact version in your requirements.txt:

# requirements.txt
openclaw==1.4.2          # exact pin — safest for prod
# openclaw~=1.4.0        # allow patch updates (1.4.x)
# openclaw>=1.4,<2.0     # allow minor updates

Pre-Update Checklist

Back up your current config: cp ~/.openclaw/config.yaml ~/.openclaw/config.yaml.bak
Check the release notes for breaking changes
Test in a staging environment first for production servers
After upgrade, run openclaw config validate to catch any deprecated keys

Migration Examples for Breaking Changes

Occasionally major versions introduce renamed config keys. Use the migration tool:

# Auto-migrate config.yaml to the new format
openclaw config migrate --from 1.x --to 2.0

# Preview what would change without applying
openclaw config migrate --dry-run

# Example manual migration: renamed key in v2.0
# OLD (v1.x):
# model: gpt-4-turbo
#
# NEW (v2.0):
# model: gpt-4o          # gpt-4-turbo is now gpt-4o

Exit Codes for Upgrade Scripts

Exit Code	Meaning
`0`	Upgrade successful
`1`	pip install error (network, permissions)
`2`	Config validation failed after upgrade
`3`	Smoke test failed — version may have broken changes

Rollback to a Previous Version

If a new version introduces a regression, roll back immediately:

# Install a specific previous version
pip install openclaw==1.3.9

# Or use pip's rollback shorthand (pip 23.1+)
pip install --force-reinstall openclaw==1.3.9

# Verify rollback
openclaw --version

# Prevent auto-upgrade until you are ready to re-test
pip install "openclaw==1.3.9"  # exact pin in requirements.txt

Using Virtual Environments to Safely Test Upgrades

# Create a test environment alongside your production one
python -m venv ~/.venv/openclaw-test
source ~/.venv/openclaw-test/bin/activate
pip install --upgrade openclaw

# Run your smoke tests in the test env
openclaw run "Return the word PASS" --model gpt-4o-mini

# If all good, update your production env:
deactivate
source ~/.venv/openclaw-prod/bin/activate
pip install --upgrade openclaw

Version History and Changelogs

GitHub Releases — full changelog for every version
CHANGELOG.md — curated list of breaking changes and major features
Subscribe to GitHub releases: Repository → Watch → Custom → Releases

Update Best Practices

Test in a venv first — create a separate venv, install the new version, run your task suite before updating production
Pin a version in requirements.txt — openclaw==1.4.2 prevents unexpected automatic upgrades in team environments
Read the changelog — always review openclaw update --check output; breaking changes are marked with ⚠️ in release notes
Back up your packs — community packs in ~/.openclaw/packs/ are not automatically restored after a rollback; copy them manually
Automated updates in CI — use openclaw update --dry-run in nightly CI jobs to get early warning of failing tests before updating production

Next: Managing API Keys or back to Configuration overview.

← Config Examples Configuration Overview →