Migrating OpenClaw to a new machine

Setting up a new machine is always a bit of a headache. I usually spend a lot of time trying to remember which config files I need to move so I don’t lose my history or have to log in to every service again.

If you are moving your OpenClaw setup, you definitely don’t want to redo the onboarding process or lose your agent’s memory. This guide helps you move everything to a new machine while keeping your sessions and credentials intact.

What You’ll Need

• Access to your old machine to run commands and copy files.
• The path to your state directory (usually ~/.openclaw/).
• The path to your workspace directory (usually ~/.openclaw/workspace/).
• OpenClaw CLI installed on your new machine.

Quick Start

1. Locate your data: On your old machine, run openclaw status. Look for the OPENCLAW_STATE_DIR or profile name in the output so you know exactly which folders to copy.
2. Stop the gateway: Run openclaw gateway stop on the old machine. This prevents files from changing while you are trying to copy them.
3. Create backups: Archive your state and workspace directories.

   cd ~
   tar -czf openclaw-state.tgz .openclaw
   tar -czf openclaw-workspace.tgz .openclaw/workspace

4. Install on the new machine: Install the CLI on your new computer. It is fine if the installation process creates a fresh ~/.openclaw/ folder, as you will replace it in the next step.
5. Move and extract: Copy your archives to the new machine. Extract them to the correct locations, making sure you include hidden directories like .openclaw/.
6. Repair and start: Run openclaw doctor on the new machine to fix services and apply any needed migrations. Then, run openclaw gateway restart.

Troubleshooting

• Profile or state-dir mismatch: If you used a specific --profile on your old machine, you must use that same profile on the new one. If you don’t, you might see empty session histories or missing channels. Run openclaw doctor after you switch to the correct profile.
• Missing credentials: If you only copied the openclaw.json file, your logins will not work. You must copy the entire $OPENCLAW_STATE_DIR folder because that is where credentials and agent states are stored.
• Permissions and ownership: If you copied files using a different user or as root, the gateway might fail to read your data. Check the file ownership and ensure the user running the gateway has full access to the state and workspace folders.
• Remote vs Local mode: If your UI is pointing at a remote gateway, moving files on your local laptop won’t change anything. In this case, you need to migrate the actual host where the gateway is running.

Verification Checklist

Before you get back to work, check these four things on your new machine:

1. Run openclaw status to confirm the gateway is running.
2. Open the dashboard to see if your existing sessions are there.
3. Check that your channels (like WhatsApp) are still connected without needing to re-pair.
4. Verify that your workspace files, like memory and skills notes, are present.

If you run into any other issues during the move, check out the AI Setup Assistant.

What’s Next

• Doctor
• Gateway troubleshooting