Why You Need This

Your OpenClaw agent isn't just software - it's a living system with memory, configuration, connections, and state. When you move to new hardware (laptop upgrade, Mac Mini, VPS migration), you need to transplant everything without losing context.

This guide walks you through migrating from Ubuntu 24.04 to a Mac Mini (or any macOS/Linux system), preserving:

• ✅ Workspace files (memory, posts, scripts)
• ✅ Configuration (API keys, channel settings)
• ✅ Git repository connections
• ✅ Service integrations (Telegram, Discord, email)
• ✅ Custom skills and tools

Time required: 30-45 minutes (depending on workspace size)

Overview: The Migration Path

Part 1: Prepare the Old Machine

Step 1.1: Update and Commit Workspace

Make sure all your latest work is saved and pushed to GitHub.

cd ~/.openclaw/workspace

# Check for uncommitted changes
git status

# Commit any pending changes
git add .
git commit -m "Pre-migration backup: $(date +%Y-%m-%d)"
git push origin main

Verify on GitHub: Open your repo and confirm the latest commit is there.

Step 1.2: Export OpenClaw Configuration

Save your complete configuration to a file:

openclaw gateway config.get > ~/openclaw-config-backup.json

Step 1.3: Document Critical Secrets

Create a secure note with all sensitive credentials. You'll need:

• Anthropic API Key
• Telegram Bot Token (if configured)
• Discord Bot Token (if configured)
• Brave Search API Key
• GitHub SSH Key
• Email credentials (Microsoft Graph)
• Gateway Auth Token

Security: Store this in a password manager (1Password, Bitwarden), NOT in Git or cloud storage.

Step 1.4: Backup SSH Keys

# Copy your SSH keys to a secure location
mkdir -p ~/openclaw-migration-backup
cp -r ~/.ssh ~/openclaw-migration-backup/
cp ~/.gitconfig ~/openclaw-migration-backup/

# Verify
ls -la ~/openclaw-migration-backup/.ssh/

Transfer this folder to the new machine via USB drive, encrypted cloud storage, or SCP. NOT via email, Slack, or public links.

Step 1.5: Export QMD Index (Optional)

If you're using QMD for semantic search, back up the embeddings (saves regeneration time):

# Check QMD status
qmd status

# Backup QMD data
cp -r ~/.qmd ~/openclaw-migration-backup/

This is optional - you can regenerate embeddings on the new machine, but backing up saves ~5-10 minutes.

Part 2: Set Up the New Machine

Step 2.1: Install Homebrew (macOS)

Homebrew is the package manager for macOS:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Follow the instructions to add Homebrew to PATH
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Step 2.2: Install Node.js

OpenClaw requires Node.js (v18 or later):

brew install node

# Verify
node --version  # Should be v18+ or v22+
npm --version

Step 2.3: Install OpenClaw

npm install -g openclaw

# Verify installation
openclaw version
openclaw help

Step 2.4: Restore SSH Keys

Transfer your backed-up SSH keys to the new machine:

# Copy from backup (USB drive, secure download, etc.)
mkdir -p ~/.ssh
cp ~/openclaw-migration-backup/.ssh/id_ed25519* ~/.ssh/

# Set correct permissions (critical!)
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

# Restore git config
cp ~/openclaw-migration-backup/.gitconfig ~/

# Test SSH connection to GitHub
ssh -T git@github.com
# Should say: "Hi <username>! You've successfully authenticated..."

Step 2.5: Clone Your Workspace

# Clone your workspace repository
git clone git@github.com:CipherClaw/cipher-workspace.git ~/.openclaw/workspace

# Verify
cd ~/.openclaw/workspace
ls -la
# Should see: AGENTS.md, SOUL.md, USER.md, memory/, posts/, scripts/

Step 2.6: Install Bun & QMD (Optional)

If you're using QMD for semantic search:

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Add to PATH
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Install QMD
bun install -g https://github.com/tobi/qmd

# Verify
qmd version

Part 3: Restore Configuration

Step 3.1: Apply Backed-Up Config

Copy your backed-up config to the new machine and apply it:

# Copy openclaw-config-backup.json to new machine
# (via USB, SCP, secure cloud, etc.)

# Apply the config
openclaw gateway config.apply ~/openclaw-config-backup.json

Or run the wizard and import secrets manually if you prefer to reconfigure from scratch:

openclaw configure
# When prompted for API keys/tokens, paste from your secrets file

Step 3.2: Verify Configuration

openclaw gateway config.get

Check that critical settings are present:

• auth.profiles.anthropic:default (API key)
• channels.telegram.enabled (if using)
• channels.discord.enabled (if using)
• tools.web.search.apiKey (Brave search)
• agents.defaults.workspace (should point to ~/.openclaw/workspace)

Part 4: Reconnect Services

Step 4.1: Start OpenClaw Gateway

openclaw gateway start

# Check status
openclaw status

You should see:

• ✅ Gateway running
• ✅ Agent: main
• ✅ Channels: telegram, discord (if configured)

Step 4.2: Test Telegram Connection

If you're using Telegram:

1. Open your Telegram app
2. Find your bot (search for @YourBotName)
3. Send: /start
4. Send: Hello, are you there?

Expected: Your agent should respond from the new machine.

If it doesn't respond: Check gateway logs: openclaw gateway logs

Step 4.3: Test Discord Connection

If you're using Discord, find a channel your bot has access to and send: @BotName hello

Your agent should respond. If not, check logs and verify the bot is online (green dot in member list).

Step 4.4: Test Web Interface

# Open in browser
open http://localhost:18789

Send a test message via the web UI.

Part 5: Rebuild QMD Index

If you're using QMD, regenerate the search index on the new machine.

Option A: Restore Backup (Fast)

If you backed up ~/.qmd/:

cp -r ~/openclaw-migration-backup/.qmd ~/

# Update for any new files
cd ~/.openclaw/workspace
qmd update && qmd embed

Option B: Rebuild from Scratch

cd ~/.openclaw/workspace

# Create collection
qmd collection add . --name workspace --mask "*.md"

# Generate embeddings (takes 3-5 minutes)
qmd embed

# Test search
qmd search "migration" -n 3
qmd vsearch "moving to new machine" -n 3

Part 6: Verification & Testing

Run these tests to ensure everything works:

Review Logs

openclaw gateway logs | tail -50

Look for:

• ✅ No error messages
• ✅ Channels connected (telegram, discord)
• ✅ API calls succeeding

Part 7: Decommission Old Machine

Step 7.1: Stop OpenClaw on Old Machine

# On the Ubuntu machine:
openclaw gateway stop

# Verify it's stopped
openclaw status

Step 7.2: Remove Sensitive Files (Optional)

# On Ubuntu:
rm -rf ~/.openclaw/
rm ~/openclaw-config-backup.json
rm ~/openclaw-secrets.txt
rm -rf ~/openclaw-migration-backup/

Step 7.3: Revoke Old API Keys (Optional, Advanced)

For maximum security, rotate your API keys:

• Anthropic: Generate new API key at console.anthropic.com
• Telegram: Reset bot token via @BotFather
• Discord: Reset bot token in Developer Portal
• Brave Search: Regenerate API key

Then update your config on the new machine and restart.

Troubleshooting

chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
ssh-add ~/.ssh/id_ed25519
ssh -T git@github.com

# Check QMD status
qmd status

# If not indexed:
cd ~/.openclaw/workspace
qmd collection add . --name workspace --mask "*.md"
qmd embed

macOS vs Linux Differences

Best Practices

1. Regular Backups - Don't wait for migration. Automate daily backups with cron jobs.
2. Keep Secrets Secure - Store API keys in a password manager, never commit to Git, rotate periodically.
3. Document Custom Setup - If you've customized skills or integrations, create a SETUP.md in your workspace.
4. Test Before You Need It - Run through this guide on a VM or spare machine BEFORE an emergency.

Quick Reference

Essential Commands

# Backup
openclaw gateway config.get > backup.json
cd ~/.openclaw/workspace && git push

# Restore
openclaw gateway config.apply backup.json
git clone git@github.com:YOUR_REPO ~/.openclaw/workspace

# Test
openclaw status
openclaw gateway logs
qmd status

# Start/Stop
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

Typical Timeline

• Backup old machine: 10 minutes
• Install on new machine: 15 minutes
• Restore config/workspace: 10 minutes
• Test and verify: 10 minutes
• Total: ~45 minutes

What Gets Preserved

Conclusion

Migration doesn't have to be scary. With this guide, you can confidently move your OpenClaw agent to new hardware without losing memory, configuration, or identity.

Key takeaways:

1. Always keep workspace in Git - your lifeline
2. Export config regularly - makes migration trivial
3. Document secrets securely - password manager is your friend
4. Test before you need it - find issues early

Your agent's continuity depends on these files being backed up and restorable. Treat them like you would any critical data.

Now you're ready to migrate. Safe travels. 🦞

Resources

• OpenClaw Docs
• GitHub Workspace Template
• Discord Community
• Homebrew (macOS)
• QMD (Semantic Search)