How to Upgrade DenchClaw: Zero-Downtime Updates

DenchClaw ships updates regularly — bug fixes, new features, security patches, and improvements to the agent system. Because it installs via npx and runs as an OpenClaw profile, upgrades are designed to be smooth. But there are steps worth taking before any upgrade to protect your data and minimize disruption.

This guide covers the full upgrade workflow for both personal and team deployments.

Before You Upgrade#

1. Check Your Current Version#

npx denchclaw --version

Or ask the agent:

"What version of DenchClaw am I running?"

2. Read the Changelog#

Before upgrading, check what's changing. The DenchClaw changelog is at github.com/DenchHQ/denchclaw/CHANGELOG.md. Look for:

• Breaking changes: Any changes to object YAML format, API endpoints, or skill structure that might require you to update your configuration
• Database migrations: Schema changes to the DuckDB structure (these are handled automatically but worth knowing about)
• Deprecated features: Things that will be removed in a future version — plan to migrate away from them

3. Back Up Your Workspace#

Always back up before upgrading. The DuckDB file is the most critical:

cp ~/.openclaw-dench/workspace/workspace.duckdb \
   ~/.openclaw-dench/workspace/workspace-backup-$(date +%Y%m%d).duckdb

For a full workspace backup:

tar -czf ~/denchclaw-backup-$(date +%Y%m%d).tar.gz \
  --exclude="$HOME/.openclaw-dench/workspace/browser-profile" \
  --exclude="$HOME/.openclaw-dench/workspace/.openclaw/logs" \
  ~/.openclaw-dench/workspace/

See the full backup guide for more detail.

Personal Upgrade (Single User, Local)#

Standard Upgrade#

The standard upgrade is a single command:

npx denchclaw@latest

This:

1. Downloads the latest DenchClaw version
2. Stops the current gateway
3. Runs any database migrations
4. Starts the new version
5. Verifies the gateway is running

The whole process takes 30-60 seconds on a typical internet connection.

After Upgrading#

Verify everything is working:

# Check the gateway status
openclaw gateway status
 
# Verify DuckDB is accessible
duckdb ~/.openclaw-dench/workspace/workspace.duckdb "SELECT COUNT(*) FROM entries;"

Then ask the agent: "Is everything working after the upgrade?" — the agent will confirm the database connection and basic functionality.

Pinning to a Specific Version#

If the latest version has a breaking change you're not ready for:

npx denchclaw@1.2.3  # Replace with specific version

Check available versions: npm show denchclaw versions --json

Team Deployment Upgrade (VPS/Server)#

For team deployments on a shared server, upgrades require more care:

Zero-Downtime Upgrade Procedure#

Step 1: Schedule the maintenance window

For a team CRM, pick a low-traffic time (e.g., 2am local team time). Notify the team:

"Send a Telegram message to the team: 'DenchClaw maintenance window tonight 2am-2:15am. Brief interruption possible. Backup taken.'"

Step 2: Back up on the server

ssh your-server
cp ~/.openclaw-dench/workspace/workspace.duckdb \
   ~/backups/workspace-pre-upgrade-$(date +%Y%m%d%H%M).duckdb

Step 3: Run the upgrade

# The gateway will briefly stop and restart
npx denchclaw@latest

Step 4: Verify

openclaw gateway status
# Expected: running on port 19001
 
curl -s https://crm.yourcompany.com/api/health | jq .status
# Expected: "ok"

Step 5: Confirm with the team

"Send a Telegram message: 'Maintenance complete. DenchClaw is back up and running on version X.X.X.'"

Handling Breaking Changes#

Some upgrades require you to update your configuration before or after the upgrade. Common scenarios:

Object YAML Format Changes#

If an upgrade changes the .object.yaml format:

1. The upgrade script attempts automatic migration — check the migration log
2. Verify your objects display correctly in the UI after upgrade
3. If a view or field configuration looks wrong, check the changelog for the new format

The agent can help: "Check if any of my object YAML files need to be updated for the new version format."

Database Schema Migrations#

DenchClaw manages its own schema migrations in workspace.duckdb. These run automatically during upgrade. If a migration fails:

1. Check the migration log: ~/.openclaw-dench/workspace/.openclaw/migrations.log
2. The backup you took before upgrading is your recovery point
3. File a GitHub issue with the migration log output

Skill Compatibility#

If a skill was written for an older version of DenchClaw's agent system, it might need updates. After upgrading:

1. Test the skills you use most frequently by asking the agent to perform a task they handle
2. If a skill fails, check if a newer version is available on clawhub.ai: "Check if there's a newer version of the [skill name] skill"
3. For workspace skills you wrote yourself, the agent can help update them to the new format

Rollback Procedure#

If an upgrade introduces a critical bug:

Step 1: Stop the new version

openclaw gateway stop

Step 2: Restore the database backup

cp ~/backups/workspace-pre-upgrade-YYYYMMDD.duckdb \
   ~/.openclaw-dench/workspace/workspace.duckdb

Step 3: Install the previous version

# Install the specific version you were on
npx denchclaw@1.X.Y  # Replace with your previous version

Step 4: Verify

openclaw gateway status

Step 5: Report the issue

File a GitHub issue with:

• Your previous version
• The version you upgraded to
• What broke
• Relevant error logs from ~/.openclaw-dench/workspace/.openclaw/logs/

Keeping Up with Releases#

Subscribe to GitHub releases: Go to github.com/DenchHQ/denchclaw → Watch → Custom → Releases. You'll get an email for each new release.

Set up an automatic upgrade reminder:

"Every week on Sunday, check if there's a newer version of DenchClaw available and message me on Telegram if there is."

The agent compares npx denchclaw --version with the latest on npm and notifies you.

Join the Discord #releases channel: The team announces releases with changelogs and highlights.

Upgrade Cadence Recommendations#

• Security patches: Upgrade immediately
• Minor releases (bug fixes, small features): Upgrade within a week
• Major releases: Read the changelog carefully, test in a personal workspace before team deployment, upgrade within 2-4 weeks

For team deployments: test major upgrades on a personal local installation first before pushing to the shared server.

Frequently Asked Questions#

Will upgrading delete my data?#

No. Upgrades never touch your DuckDB data. The upgrade process updates the application code; your workspace.duckdb file is preserved. Database schema migrations (when needed) only add new columns or tables — they never delete data.

How do I upgrade if I don't have internet access?#

You can't use npx denchclaw@latest without internet. For air-gapped environments, download the package tarball on a connected machine, transfer it, and install offline:

# On connected machine:
npm pack denchclaw@latest
# Transfer the .tgz file
# On offline machine:
npm install -g ./denchclaw-1.x.x.tgz

Can I be on a different version from my teammates on a shared server?#

On a shared server, there's only one version — whatever is running on the server. Individual team members connect via Telegram/WhatsApp and don't have a separate version. The upgrade affects everyone simultaneously.

How long does the maintenance window need to be?#

For personal upgrades: <2 minutes. For team server upgrades: plan for 10-15 minutes to handle backup, upgrade, verification, and any post-upgrade checks. In practice, most upgrades complete in under 5 minutes.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →