Migrate from OpenClaw to NanoClaw: Full Guide

NanoClaw runs on Raspberry Pis, edge boxes, and tiny VPS plans where OpenClaw cannot. If you have an OpenClaw agent that has outgrown its current host but does not need OpenClaw's full feature set, NanoClaw is the obvious destination. The migration is mostly straightforward — NanoClaw deliberately mirrors OpenClaw's skill manifest format — but there are sharp edges around memory size, network-bound skills, and UI components that catch most teams off guard.

This guide walks through every step of moving an OpenClaw agent to NanoClaw, what transfers automatically, what needs manual work, and how to verify the migrated agent behaves the same way at the destination.

Why move from OpenClaw to NanoClaw

OpenClaw is a heavy framework. It assumes a server with a few gigabytes of RAM, persistent storage, and a network connection that does not flicker. NanoClaw is the opposite: built for constrained environments where the host might have 512MB of RAM, intermittent connectivity, and a 50MB cap on agent memory.

Three reasons teams typically switch:

• Cost. A NanoClaw agent runs comfortably on a $5/month VPS or a Raspberry Pi 4. Running OpenClaw at the same scale costs 10-20x more.
• Edge deployment. If your agent needs to run on a device near where the data lives — a warehouse robot, a kiosk, a delivery truck — OpenClaw is too large. NanoClaw fits.
• Reliability under low resources. OpenClaw assumes plenty of headroom. NanoClaw is engineered to degrade gracefully when memory or network is tight.

The trade-offs are real. NanoClaw's 50MB memory ceiling means agents with deep conversation history or large knowledge bases need to be pruned. Skills that depend on heavyweight runtime libraries may need lighter equivalents. If your agent makes constant external API calls, NanoClaw's connection-pooling model is different and may need tuning.

What transfers automatically

NanoClaw shares OpenClaw's manifest format, so most of the heavy lifting is just file copies. Here is what comes across without manual intervention.

• Personality configs. SOUL.md, AGENTS.md, and HEARTBEAT.md transfer one-to-one. NanoClaw reads the same fields.
• Memory files. Memory transfers automatically, but it is compressed during transit to fit NanoClaw's storage model. If the source memory directory is under 50MB, every entry survives.
• Basic skills. Any skill whose manifest declares standard capabilities (file access, HTTP, lightweight compute) installs on NanoClaw without changes.
• Environment variables. Your .env file copies as-is. NanoClaw reads the same variable names.
• Skill permissions. OpenClaw's allow/deny model maps to NanoClaw directly.

In practice, this covers 70-80% of a typical migration. The remaining 20-30% is where the work lives.

What needs manual work

Three categories need attention before you cut over.

Memory over 50MB

NanoClaw enforces a hard 50MB cap on the agent's memory directory. Most agents that have been running for less than three months are nowhere near this. Agents that have been processing thousands of conversations a month for over a year often blow through it.

Before you migrate, run a size audit on your memory directory. If you are over the cap, you have three options:

• Prune. Drop conversation summaries older than a chosen window (90 days is reasonable for most use cases). If you have not referenced something in three months, NanoClaw probably does not need to either.
• Archive. Move older memories to cold storage (S3, an off-host SQLite file) and configure your skills to reach in only when needed. The agent's working memory stays under the cap.
• Split. Run two agents — one full-fidelity OpenClaw instance for deep history, one NanoClaw instance for live operations. They can share state through a small API.

Most teams end up pruning. It is the simplest path and rarely costs anything you actually miss.

Skills with external API dependencies

A skill that calls a third-party API every few seconds works fine on OpenClaw. On NanoClaw — especially at the edge, where the network may be intermittent — that pattern breaks. NanoClaw can survive a flaky network, but skills that assume always-on connectivity will not.

For each skill that hits an external service:

• Add a local cache so repeated calls do not require fresh network round trips.
• Implement graceful degradation. If the API is unreachable, return a sensible fallback instead of throwing.
• Move time-sensitive operations to the device. If a skill's only job is to wait for a webhook, that webhook needs to reach the edge box.

Custom UI components

OpenClaw skills can ship UI manifests that render rich interfaces in the OpenClaw dashboard. NanoClaw has no equivalent — it ships a much smaller status interface that does not render skill UIs. Skills that depend on custom UI need to be reworked to expose data through standard channels (logs, status fields, an HTTP endpoint) instead.

This is the most common reason teams keep one OpenClaw instance after switching most workloads to NanoClaw. Internal-tool agents that need rich UI stay on OpenClaw; production agents that just need to function move to NanoClaw.

Step-by-step migration

Step 1: Audit the source

Run a full inventory before you touch anything. List every file in the workspace, every environment variable, every installed skill with its version, and the total size of the memory directory.

This is the inventory you will check the destination against. If it shows you are over the 50MB memory cap, deal with that first — pruning is much easier on the source side, where everything is still in OpenClaw's native format.

Step 2: Provision the destination

Stand up your NanoClaw host with the correct version. Install NanoClaw on the device, confirm nanoclaw --version returns the expected output, and configure storage and networking. NanoClaw's installer is a single binary, but the host needs to be reachable from any external services that send the agent webhooks.

Match runtime versions precisely. NanoClaw and OpenClaw share most of the same skill manifest format, but minor version differences in the runtime can cause skills to fail at startup. If your source is OpenClaw 2.4, install NanoClaw at the same minor version to minimize surprises.

Step 3: Export the workspace

If you are using ClawSail, run clawsail export --target nanoclaw --source ./your-workspace. The export produces a .clawsail-export archive with everything packaged for NanoClaw's storage format.

If you are doing it manually, copy the workspace directory, dump environment variables to a .env file, and gather any skill state that lives outside the workspace root. Compress the bundle so the destination receives a single archive.

Step 4: Restore on NanoClaw

Restore in order: configs first, then memory, then skills.

• Place SOUL.md, AGENTS.md, and HEARTBEAT.md at the workspace root.
• Restore the memory directory under NanoClaw's storage path. The destination should report the same memory entry count as the source — if it does not, find what is missing before continuing.
• Install skills one at a time. NanoClaw's manifest reader catches incompatibilities at install time, so issues surface early.

After every restore step, run the agent's self-check command to confirm that step succeeded. Catching a missing config file at step 1 is much easier than catching it at step 5 when everything else is already in place.

Step 5: Update integrations

Every webhook URL that pointed to the OpenClaw server needs updating. This is the most tedious step and the one most likely to leave something broken. Make a list during the audit step (Step 1) of every external service that has a webhook configured, and walk through it now updating each one to the new endpoint.

OAuth tokens may also need refreshing depending on how they were issued. Test every authenticated outbound call before considering the migration done.

Step 6: Verify behavior

Send the same set of prompts to both the source (still running) and the destination NanoClaw instance. Compare responses. They will not be identical — agents have inherent randomness — but they should reflect the same knowledge, the same personality, and the same skills.

Run for 24-48 hours in parallel before decommissioning OpenClaw. Subtle issues often only surface under sustained operation. A scheduled task that fires once a day, a memory entry that is only referenced by one specific user query, an integration that retries quietly until it gives up — these surface in real usage, not in synthetic tests.

Quick comparison: OpenClaw vs NanoClaw

A few of the differences worth keeping in mind during planning:

• Memory cap. OpenClaw has none enforced by the runtime; NanoClaw enforces a 50MB ceiling.
• Skill manifests. OpenClaw's format is native; NanoClaw is fully compatible and reads the same files.
• External API skills. OpenClaw assumes always-on connectivity; NanoClaw expects you to cache and degrade gracefully.
• Custom UI. OpenClaw renders skill UIs in its dashboard; NanoClaw has no UI surface for skills.
• Minimum host RAM. OpenClaw wants ~2GB; NanoClaw runs on ~512MB.
• Edge deployment. OpenClaw was not designed for it; NanoClaw treats it as a first-class use case.

Common pitfalls

• Skipping the memory audit. Discovering you are over the 50MB cap halfway through restore wastes hours. Audit first.
• Assuming UI skills will "just work without UI." They do not — the skill manifest references the UI manifest, and an unresolved reference fails at install. Either rework the skill or leave it on OpenClaw.
• Forgetting webhook updates. The new agent works fine for outbound traffic, but inbound webhooks silently fail. Map every webhook before you cut over.
• Decommissioning the source too early. Keep OpenClaw running for at least 48 hours of overlap. Migrations fail in subtle ways.

When to migrate vs stay on OpenClaw

NanoClaw is the right destination when:

• You need the agent at the edge, on hardware with constrained resources.
• Your hosting bill on OpenClaw is the limiting factor.
• The agent's memory and skill set fit comfortably under NanoClaw's caps.
• You can live without custom UI components.

OpenClaw is the right place to stay when:

• The agent needs deep conversation history (multi-year recall, large knowledge bases).
• It runs many heavyweight skills (LLM-backed reasoning chains, video processing).
• It serves an internal team that depends on the dashboard UI.
• You have no resource pressure on the current host.

For mixed cases — a NanoClaw fleet at the edge with one OpenClaw "control plane" — both can run side by side. ClawSail handles syncing state between them.

Getting started

If you are sizing up a NanoClaw migration, start with the memory audit on your source. Most decisions follow from there. When you are ready to move, try ClawSail's audit — it tells you in minutes which parts of your agent will transfer automatically and which need attention. You can also read the broader OpenClaw portability guide for the patterns that make any future migration easier, or check the NanoClaw platform overview for the high-level summary.

The migration is rarely as scary as it looks on the first read. Most agents transfer cleanly with a handful of manual touch-ups. NanoClaw is built to make the destination side easy. The hard part is the same as every migration: knowing exactly what you have before you move it.

Related posts