Tools
Migrate
By Spent weeks setting up your OpenClaw agent then got a new PC and had to start over? This fixes that. One command moves your entire agent — memory, persona, plugins — to any machine via USB or AirDrop. Also covers migrating to Hermes Agent.
Install
npm install -gREADME
# openclaw-migrate 🦞➡️
> One command to move your OpenClaw agent — settings, memory, personality and all — to a new machine. No reconfiguration. No starting over.
---
> ⚠️ **This project is untested on real hardware and a work in progress.**
> The core logic has been back-tested in a simulated environment (see [Test Results](#test-results) below) but has not been verified across real Mac-to-Mac migrations yet. Use it, break it, and tell us what went wrong. Every piece of feedback makes it safer for the next person.
>
> **If you've migrated successfully — or hit a problem — please [open an issue](../../issues) or submit a PR. Your experience directly helps the community.**
---
## The problem
You set up your OpenClaw agent exactly the way you want it. Custom persona, plugins configured, channels connected, API keys in place, months of memory built up. Then you get a new machine and have to do it all again from scratch.
This script fixes that.
---
## How it works
**On your old machine — export:**
```bash
bash openclaw-migrate.sh export
```
It bundles everything OpenClaw needs and asks how you want to transfer it:
```
How do you want to transfer to the new Mac?
1. 💾 USB Drive (auto-detects your drive)
2. 📡 AirDrop / LocalFiles (saves to Desktop — drag & drop from there)
3. 📁 Save locally (pick any folder)
```
**On your new machine — import:**
```bash
bash openclaw-migrate.sh import
```
It auto-searches Downloads, Desktop, and Documents for your bundle. One confirmation and everything is restored. Your agent starts up exactly where it left off.
---
## What gets moved
| File / Folder | What it contains |
|---|---|
| `~/.openclaw/openclaw.json` | Main config — models, plugins, channels, tools |
| `~/.openclaw/.env` | API keys (Anthropic, OpenAI, etc.) |
| `~/.openclaw/agents/` | Per-agent sessions and state |
| `~/.openclaw/workspace/MEMORY.md` | Long-term agent memory |
| `~/.openclaw/workspace/SOUL.md` | Agent persona and tone |
| `~/.openclaw/workspace/USER.md` | Your personal context |
| `~/.openclaw/workspace/IDENTITY.md` | Agent name and identity |
| `~/.openclaw/workspace/memory/` | Daily memory files |
---
## After import
```bash
# 1. Make sure OpenClaw is installed on the new machine
npm install -g openclaw
# 2. Start the gateway
openclaw gateway start
# 3. Verify everything looks good
openclaw doctor
# 4. Say hi — your agent remembers you 🦞
```
Plugin binaries will re-download automatically on first start. Your plugin settings and configuration are fully preserved.
---
## Switching to Hermes Agent?
[Hermes Agent](https://github.com/NousResearch/hermes-agent) by Nous Research has a built-in migration command specifically for OpenClaw users. You do **not** need this script for that — use their native tool instead.
> **This section is based on a tested dry-run and live execution against the actual Hermes migration script.** The behaviour below reflects what Hermes `v0.10.0` does in practice.
### How to migrate
```bash
# 1. Install Hermes
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
# 2. Preview what would be migrated (nothing changes)
hermes claw migrate --dry-run
# 3. Run the migration
hermes claw migrate
# 4. Also migrate API keys (skipped by default — see warning below)
hermes claw migrate --migrate-secrets
# 5. Clean up the old OpenClaw directory after you're happy
hermes claw cleanup
```
### What actually migrates ✓
These files are moved automatically and verified working:
| OpenClaw | Hermes destination |
|---|---|
| `workspace/SOUL.md` | `~/.hermes/SOUL.md` |
| `workspace/MEMORY.md` | `~/.hermes/memories/MEMORY.md` |
| `workspace/USER.md` | `~/.hermes/memories/USER.md` |
| `workspace/memory/*.md` | Merged into `~/.hermes/memories/MEMORY.md` |
### What gets archived for manual review ◆
These don't have a direct 1:1 equivalent in Hermes. Hermes copies them to `~/.hermes/migration/openclaw/<timestamp>/archive/` so nothing is lost, but you'll need to recreate them manually:
- `IDENTITY.md` — set your agent's name and vibe via `hermes setup` instead
- `memory/people/`, `memory/projects/` subfolders — review and paste relevant entries into Hermes memory manually
### What is skipped and needs fresh setup ⊘
In our test, **31 items were skipped** — these need to be configured fresh in Hermes after migration:
- Channel configs (WhatsApp, Telegram, Discord, Slack) — reconnect via `hermes setup`
- Plugin settings — Hermes uses a different plugin/skill system
- Cron jobs — recreate via `hermes cron`
- Hooks and webhooks — recreate manually
- MCP server definitions — re-add via `hermes config`
### ⚠️ API keys are NOT migrated by default
This is the most important thing to know. Running `hermes claw migrate` alone will **not** copy your API keys. You must explicitly add `--migrate-secrets`:
```bash
hermes claw migrate --migrate-secrets
```
Only a specific allowlist of keys is migrated even then:
`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `TELEGRAM_BOT_TOKEN`, `ELEVENLABS_API_KEY`
Any other custom keys in your `.env` must be added manually to `~/.hermes/.env`.
### ⚠️ Stop OpenClaw before migrating
If OpenClaw is still running (gateway active), Hermes will warn you before migrating. Messaging platforms like Telegram and Discord only allow one active session per bot token — both agents fighting for the same token causes disconnects. Stop OpenClaw first:
```bash
# macOS (launchd)
openclaw gateway stop
# Linux (systemd)
systemctl --user stop openclaw-gateway.service
```
Then run the migration, then start Hermes.
### Migration report
Hermes saves a full migration report to `~/.hermes/migration/openclaw/<timestamp>/` including:
- `MIGRATION_NOTES.md` — human-readable notes on what needs manual attention
- `summary.md` — full item-by-item summary
- `report.json` — machine-readable report
- `archive/` — copies of files that didn't have a direct Hermes destination
---
## Test results
The script has been back-tested in a simulated environment. Not on real hardware yet — that's where you come in.
**Core migration — 12/12 files ✓**
Every file transferred correctly in simulation: config, API keys, sessions, MEMORY.md, SOUL.md, USER.md, IDENTITY.md, daily memory files, and nested memory folders. Content verified intact after restore.
**Edge cases — 4/4 ✓**
| Scenario | Result |
|---|---|
| No `.env` file (API keys stored elsewhere) | ✓ Exports cleanly without it |
| Importing over an existing config | ✓ Auto-backup created before overwrite |
| Bundle corruption check | ✓ Passes `tar` integrity check |
| No `openclaw.json` (partial/fresh setup) | ✓ Exports workspace only, no crash |
**Security check ✓**
`.env` file permissions are automatically set to `600` on restore — readable by your user only.
---
## Known gaps (help wanted)
These have **not** been tested and are the most likely places things could break on real hardware. If you can test any of these, please open an issue with your findings:
- [ ] **Real USB drive on macOS** — auto-detect logic uses `df` and `/Volumes/`, untested with actual drives
- [ ] **AirDrop file naming** — received files sometimes get renamed by macOS, import auto-search may miss them
- [ ] **Very large workspaces** — memory folders over ~100MB, many session files
- [ ] **Custom `OPENCLAW_CONFIG_PATH`** — if you've overridden the default config location, the script won't find it
- [ ] **Multiple profiles** — `openclaw --profile work` style setups with separate state directories
- [ ] **Linux / WSL2** — paths are the same but shell differences may cause issues
- [ ] **Windows (native, non-WSL2)** — not supported yet
---
## Good to know
- **API keys are bundled unencrypted.** The `.tar.gz` is safe to move via USB or AirDrop to yourself — just don't upload the bundle file to a public location.
- **The import always backs up your existing `~/.openclaw`** before overwriting, so you can roll back if anything looks wrong.
- **API key file permissions** are automatically locked to `600` on restore (readable by your user only).
- **Sessions and conversation history** are included. If you have very long session files the bundle may be large — this is normal.
---
## Requirements
- macOS (tested on macOS Sequoia and later)
- Bash 3.2+ (ships with macOS by default)
- OpenClaw installed on the destination machine
> Linux support is untested but should work — the paths are the same (`~/.openclaw/`). Windows (WSL2) users would need minor path adjustments.
---
## Quick start
```bash
# Download the script
curl -O https://raw.githubusercontent.com/YOUR_USERNAME/openclaw-migrate/main/openclaw-migrate.sh
# Export from old machine
bash openclaw-migrate.sh export
# Import on new machine
bash openclaw-migrate.sh import
```
---
## Contributing
**This project is community-driven and needs your help to become reliable.**
It was built as a starting point — not a finished tool. Real-world migrations will surface edge cases, missing files, and platform quirks that no single person can anticipate alone.
**Ways to contribute:**
- 🧪 **Tested it?** Open an issue and tell us what worked and what didn't — even a "worked fine on macOS Sequoia M2" is valuable
- 🐛 **Hit a bug?** Please open an issue with your OS, OpenClaw version, and what happened
- 🔒 **Bundle encryption** — most important missing safety feature for anyone transferring over a network
- 🐧 **Linux / WSL2 testing** — paths should work but nobody's confirmed it yet
- 📦 **Edge cases** — custom `OPENCLAW_CONFIG_PATH`, multiple profiles, large memory folders, AirDrop renaming
- 💡 **Ideas** — anything that makes migration safer or less scary for non-technical users
If you've done a migration — successful or not — your experience is the most useful thing you can share. Open an issue and describe it. That's how this gets better.
---
## License
MIT
tools
Comments
Sign in to leave a comment