openclaw update

Update OpenClaw and inspect update channel status

openclaw update

Update OpenClaw to the latest version and manage update channels.

Usage

openclaw update [options]

Or use the shorthand:

openclaw --update

Options

--channel <name> · string

Persist update channel: stable, beta, or dev

• stable: Tagged releases (recommended)
• beta: Pre-release versions
• dev: Latest development branch

--tag <dist-tag|version> · string

Override npm dist-tag or version for this update (one-time, not persisted)

--no-restart · boolean

Skip restarting the gateway service after a successful update

--timeout <seconds> · number

Timeout for each update step in seconds (default: 1200)

--yes · boolean

Skip confirmation prompts (non-interactive, accept downgrade prompts)

--json · boolean

Output result as JSON

Commands

wizard

Interactive update wizard with guided prompts.

openclaw update wizard [options]

--timeout <seconds> · number

Timeout for each update step in seconds (default: 1200)

status

Show update channel and version status.

openclaw update status [options]

--json · boolean

Output result as JSON

--timeout <seconds> · number

Timeout for update checks in seconds (default: 3)

Update Channels

stable

Recommended for production use:

• Tagged releases only (e.g., v2026.2.19)
• npm dist-tag: latest
• Thoroughly tested
• Includes macOS app releases

openclaw update --channel stable

beta

Early access to new features:

• Pre-release tags (e.g., v2026.2.19-beta.1)
• npm dist-tag: beta
• Less tested than stable
• May not include macOS app

openclaw update --channel beta

dev

Latest development code:

• Moving head on main branch
• No npm dist-tag (git only)
• Bleeding edge features
• Requires source checkout

openclaw update --channel dev

Update Process

The update process varies by installation method:

Git Checkout

For source installations:

1. Fetch latest changes from remote
2. Rebase onto target branch/tag
3. Install dependencies (pnpm install)
4. Build the project (pnpm build)
5. Run diagnostics (openclaw doctor)
6. Restart gateway (unless --no-restart)

npm Install

For global npm installations:

1. Detect package manager (npm, pnpm, yarn, bun)
2. Update via package manager
3. Restart gateway (unless --no-restart)

For Homebrew:

brew upgrade openclaw

Examples

Basic Updates

# Update to latest stable
openclaw update

# Update without restart
openclaw update --no-restart

# Check for updates
openclaw update status

Downgrades require confirmation (use --yes to auto-accept). Downgrading can break configuration compatibility.

Channel Persistence

The --channel flag persists the channel preference to config:

{
  update: {
    channel: "beta"
  }
}

Subsequent openclaw update commands use the saved channel.

The --tag flag is not persisted (one-time override).

Update Status

Check update channel and version:

openclaw update status

Output:

Update Status

Current version: 2026.2.19
Update channel: stable
Source: git
Branch: main
Tag: v2026.2.19
SHA: abc123def

Upstream: origin/main
Local ahead: 0
Local behind: 2

Update available: 2026.2.20

JSON output:

openclaw update status --json

{
  "currentVersion": "2026.2.19",
  "updateChannel": "stable",
  "source": "git",
  "branch": "main",
  "tag": "v2026.2.19",
  "sha": "abc123def",
  "updateAvailable": true,
  "latestVersion": "2026.2.20"
}

Automatic Updates

OpenClaw does not auto-update by default.

To enable automatic updates:

Cron (Linux/macOS)

# Daily update check at 3 AM
0 3 * * * /usr/local/bin/openclaw update --yes --no-restart

systemd Timer (Linux)

Create ~/.config/systemd/user/openclaw-update.timer:

[Unit]
Description=OpenClaw Update Timer

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

And ~/.config/systemd/user/openclaw-update.service:

[Unit]
Description=OpenClaw Update

[Service]
Type=oneshot
ExecStart=/usr/local/bin/openclaw update --yes

Enable:

systemctl --user enable openclaw-update.timer
systemctl --user start openclaw-update.timer

Troubleshooting

Update Fails

1. Check for uncommitted changes (git installs):

   git status
   

2. Check network connectivity:

   curl -I https://registry.npmjs.org/openclaw
   

3. Check disk space:

   df -h
   

4. Try manual update:

   # Git
   git pull --rebase
   pnpm install
   pnpm build
   
   # npm
   npm update -g openclaw@latest
   

Downgrade Required

If a config change requires a specific version:

# Downgrade to specific version
openclaw update --tag 2026.2.18 --yes

Gateway Won’t Restart

If the gateway fails to restart after update:

# Check status
openclaw gateway status

# Manual restart
openclaw gateway restart

# Run diagnostics
openclaw doctor

Stuck in Beta/Dev

To return to stable:

openclaw update --channel stable

Update Notifications

The CLI checks for updates periodically and shows a banner:

┌─────────────────────────────┐
│ Update available: 2026.2.20 │
│ Run: openclaw update        │
└─────────────────────────────┘

To disable:

openclaw config set update.checkForUpdates false

Release Notes

View release notes on GitHub:

open https://github.com/openclaw/openclaw/releases

Or check the changelog:

cat ~/path/to/openclaw/CHANGELOG.md

Related Commands

• doctor - Run diagnostics after update
• gateway - Restart gateway after update
• daemon - Manage gateway service