When upgrading the OpenClaw application image, back up and restore workspace data to retain personalized data such as the AI assistant's memory, identity configuration, and Skills.-Simple Application Server(SAS)-阿里云帮助中心

Upgrade path overview

You can upgrade OpenClaw by using one of the following two methods:

Method	Process
Method 1: Upgrade by local backup and restoration	Back up locally → system reset → Restore from backup
Method 2: Upgrade by snapshot rollback	Create snapshot → Upgrade software → Roll back using snapshot if issues occur

Background

The default OpenClaw workspace directory, /home/admin/.openclaw/workspace, stores the core personalized data for your AI assistant, including:

IDENTITY.md: Identity definition.
SOUL.md: Values definition.
AGENTS.md: Work style definition.
memory/: Conversation history and work records.
skills/: Installed extension skills.

Important

The steps in this topic assume the default workspace directory is /home/admin/.openclaw/workspace. If you have changed the default workspace, use your actual path.
The OpenClaw configuration file is located at /home/admin/.openclaw/openclaw.json. You can back up this file as needed.

Procedure

Method 1: Local backup and restoration

Warning

A system reset erases all data on the system disk (including configurations, logs, and databases) and stops your services. You must back up critical data before you proceed. To ensure data integrity, we recommend that you stop the gateway and pause the OpenClaw service before creating the backup.

Step 1: Back up the workspace data

Package the workspace directory and download the archive to your local computer.

In the Simple Application Server console, select the target server and click Connect. In the Workbench One-click Connection section, click Log on Now.

Package the workspace data.

cd /home/admin
tar -zcvf workspace.tar.gz -C /home/admin/.openclaw/ workspace

Download the compressed archive to your local computer. For more information, see Download files by using Workbench.

Workbench limits single-file downloads to 1,200 MB. If your archive file is larger than 1,200 MB, see Transfer files to a Linux instance by using scp, rsync, or sftp.

Step 2: Reset the system and upgrade the image

In the Simple Application Server console, find your server and choose More > Server Resetting.
Under Reset to Other image, select the latest version of the OpenClaw image and click Confirm Reset.
After the system is reset, follow Step 2 in Deploy the OpenClaw application image to reconfigure your instance.

Step 3: Restore the backup data

Upload the backup file to the reset instance and restore the data to the workspace directory.

Upload the backup file to the /home/admin directory on the instance. For more information, see Upload files by using Workbench.

Workbench limits single-file uploads to 1,200 MB. If your archive is larger than 1,200 MB, see Transfer files to a Linux instance by using scp, rsync, or sftp.

Connect to the instance and extract the archive to restore the workspace data.

cd  /home/admin
tar -xzvf workspace.tar.gz
mv /home/admin/.openclaw/workspace /home/admin/.openclaw/workspace.bak # Rename the current workspace directory as a backup in case the restoration fails.
mv workspace /home/admin/.openclaw/ # Move the extracted workspace directory to the application path to complete the restoration.

Restart the gateway to apply the changes.
```
openclaw gateway restart
```
Open the WebUI, run the /new command, and confirm with the AI assistant that your memory and identity configurations are restored.

Method 2: Snapshot rollback

Before upgrading, create an instance snapshot to use as a recovery point. If an issue occurs after you upgrade the OpenClaw software, you can use the snapshot to roll back the instance to its pre-upgrade state.

Step 1: Create snapshot

Create a snapshot of the instance before the upgrade to serve as a rollback point.

In the Simple Application Server console, find the target server and choose Snapshot > Create Snapshot.
Set a snapshot name, such as openclaw-pre-upgrade, click Create, and wait for the snapshot to be created.

Step 2: Upgrade OpenClaw software

Establish a remote connection to the instance. In the Workbench One-click Connection section, click Log on Now.
In the terminal, run the following commands to check the current version and upgrade OpenClaw:
```
openclaw --version
sudo openclaw update
```
In the terminal, run the following command to restart the gateway:
```
openclaw gateway restart
```
Verify that the upgrade was successful.
```
openclaw --version
```

Important

After you upgrade by using the openclaw update command, you may encounter the following known issues in the console:

Gateway appears offline: Although the console indicates that the restart operation is successful, the gateway does not actually restart. You must run openclaw gateway restart in the terminal to restart the gateway.
The "Get Address" button is grayed out: This button is available only when the gateway is online. You can run sh /opt/.swas/run-cmd.sh get-url in the terminal to get the WebUI access URL and then open it in your browser.

For a detailed explanation, see What do I do if the gateway appears offline in the console after an upgrade using openclaw update?

Step 3: Roll back snapshot (optional)

If OpenClaw runs abnormally after the upgrade, use the snapshot to roll back to the pre-upgrade state.

Perform this step only if the upgrade causes issues. A rollback is unnecessary if the application runs as expected.

In the Simple Application Server console, go to the Snapshot page.
Find the snapshot that you created before the upgrade and click Rollback. Confirm the rollback operation.
After the rollback is complete, click Start and verify that OpenClaw is running correctly.

Restore only configuration files

Simple Application Server snapshots do not support direct mounting or individual file restoration. If you need to restore specific configuration files from a snapshot without a full rollback, create a temporary instance from the snapshot. Then, extract the required files and transfer them to your current instance.

In the Simple Application Server console, go to the Snapshot page of the server where the target snapshot is located. Select the snapshot and click Create Server to create a temporary instance.
After the temporary instance is created, go to the instance details page and click Connect. In the Workbench One-click Connection section, click Log on Now.

Locate the configuration files you need to restore. For example:

ls /home/admin/.openclaw/workspace/
ls /home/admin/.openclaw/openclaw.json

Download the configuration files to your local computer. For more information, see Download files by using Workbench.
On your current instance, upload the configuration files to the corresponding directory. For more information, see Upload files by using Workbench.
After you verify that the file paths and permissions are correct, restart the gateway to apply the configuration.
```
openclaw gateway restart
```
When you are finished, release the temporary instance promptly to avoid incurring additional charges.

FAQ

How do I stop the gateway?

Run the openclaw gateway stop command in the terminal or enter the command to stop the gateway in the WebUI.

Why does the console still show the old image version after an upgrade using `openclaw update`?

After you successfully upgrade the software by using the openclaw update command, the image information in the Simple Application Server console may still show an older version. This is expected behavior. The console displays the version of the image that was used to create the instance and does not affect the actual OpenClaw software version. The output of the openclaw --version command provides the definitive version number.

What to do if the gateway is offline after upgrading with `openclaw update`?

After you upgrade by using the openclaw update command, scripts delivered by Cloud Assistant may be incompatible with the new version, which can cause the following issues in the console:

Gateway appears offline: The gateway service is running correctly on the server, but its status in the console shows as offline.
The Restart button does not work: Although the console indicates that the restart operation is successful, the gateway does not actually restart.
The "Get Address" button is grayed out: This button is disabled when the gateway is shown as offline.

Solution:

To restart the gateway, run the following command in the terminal:
```
openclaw gateway restart
```
To access the WebUI, run the following command in the terminal to obtain the access URL:
```
sh /opt/.swas/run-cmd.sh get-url
```
Copy the URL from the command output and open it in a browser to access the WebUI.