Migrate from OpenClaw

How it works

The /migrate-from-openclaw skill brings an existing OpenClaw install into NanoClaw v2. It’s a conversation, not a batch job — the skill reads your OpenClaw state, explains what it found, and shows proposed changes before applying anything. Credentials are masked when displayed (first four characters, then ..., then the last four), and nothing is copied silently.

The two systems differ structurally, so most of the work is translation. In v2, an OpenClaw “agent” becomes an agent group — its own container with its own workspace, memory, and CLAUDE.local.md. An OpenClaw chat or group becomes a messaging group, and a wiring row connects the two. There is no shared groups/global/; shared instructions live in container/CLAUDE.md, mounted read-only into every container. Container-facing API credentials go to the OneCLI vault and are injected per request, while host-side channel tokens stay in .env. Scheduled tasks are no longer a table — they become inbound rows the agent creates through its schedule_task tool.

Throughout, the skill maintains a migration-state.md file in the project root. It’s the single source of truth: every discovered value and decision is recorded there, so if context is lost the skill can re-read it and pick up where it left off.

Setup

The migration runs in phases:

1. Discovery — runs discover-openclaw.ts to locate the install (standard paths are ~/.openclaw and ~/.clawdbot; pass --state-dir for a custom one) and summarize identity, channels, groups, workspace files, cron count, and MCP servers.
2. Agents and groups — decides shared-base versus fully-separate, confirms the assistant name, then seeds the owner and primary agent with scripts/init-first-agent.ts and registers additional groups via setup/index.ts --step register.
3. Settings — reads the OpenClaw config and maps timezone to TZ in .env and container timeout to CONTAINER_TIMEOUT, and translates access-control lists into v2 roles and members.
4. Identity and memory — merges IDENTITY, SOUL, USER, and memory files into the right v2 locations, and copies portable OpenClaw skills into container/skills/.
5. Credentials — extracts channel tokens to .env and registers container-facing keys (Anthropic, OpenAI, and the like) in the OneCLI vault.
6. Scheduled tasks, MCP, and other config — converts cron jobs to v2 recurrences and wires MCP servers per agent group.
7. Validate — copies the shipped transform test into scripts/, runs pnpm run build, and executes the test to confirm credential routing and cron mapping hold against your composed install.

Tips

• The service must be running before the primary agent is seeded — init-first-agent.ts queues the welcome DM over the running service’s CLI socket. If it can’t reach the socket, start the service and re-run.
• WhatsApp has no token to copy. Don’t migrate Baileys auth state; re-authenticate during /setup with /add-whatsapp.
• The skill never installs unknown packages or hunts for skill replacements — a deliberate supply-chain guardrail. Only the exact package a plugin already configured gets installed.
• Groups on channels v2 doesn’t support yet can still be registered; the wiring persists and activates when you install that channel.
• If OneCLI isn’t set up, container-facing credentials are noted in migration-state.md and registered later during /setup or /init-onecli so nothing is lost.
• Copied skills or added MCP servers require a container rebuild (./container/build.sh) before the changes take effect.