migrate-from-openclaw skill

Migrate from OpenClaw

Guide the user through migrating their OpenClaw installation into NanoClaw v2. This is a conversation, not a batch job. Read OpenClaw state, discuss it with the user, decide together what to bring over and where it belongs in v2's entity model, and show proposed changes before applying.

Principle: Never silently copy data. Read it, explain it, place it, then apply. Credentials are masked when displayed (first 4 + ... + last 4). Make judgment calls about what's core vs. reference material.

UX: Use AskUserQuestion for multiple-choice only. Use plain text for free-form input. Don't dump raw data — summarize and explain conversationally.

What this skill changes (conformance)

This skill drives existing NanoClaw entry points (setup/index.ts --step register, scripts/init-first-agent.ts, the onecli CLI) and copies a few files in (workspace markdown, OpenClaw skills, and its own transform module + test). It makes no code-level reach-in into core. Its integration assumptions about v2 are guarded by scripts/transform.test.ts, which is copied into the project's scripts/ test tree on apply (Phase 8) so vitest runs it against the composed install. REMOVE.md reverses every file the skill copies.

v2 architecture the migration targets

OpenClaw and NanoClaw v2 differ structurally. Keep these in mind throughout:

userroles, agentgroups, messaginggroups, and the messaginggroupagents wiring between them. There is no store/messages.db and no scheduledtasks table.

• Entity model. v2's central DB (data/v2.db) holds users,

An OpenClaw "agent" maps to a v2 agent group (workspace + memory + CLAUDE.md); an OpenClaw chat/group maps to a v2 messaging group; the wiring row connects them.

• Container isolation. Each agent group runs in its own Linux container.

behavior live in groups//instructions.prepend.md. Durable facts live under groups//memory/. The provider project document is composed at spawn and must not be edited.

• Standing instructions vs memory. Per-group role, personality, and

held in the OneCLI Agent Vault and injected per request — never in container env vars. Host-side channel tokens (Telegram/Discord/Slack bot tokens) stay in .env; the NanoClaw host process reads them to connect to the platform.

• Credentials. Container-facing API credentials (Anthropic, OpenAI, …) are

userroles (owner/admin) and agentgroup_members — not a JSON allowlist file.

• Access control. Per messaging group unknownsenderpolicy plus

session's inbound.db, carrying a cron recurrence and a processafter timestamp. The agent creates them via its scheduletask MCP tool.

• Scheduled tasks. A task is a messages_in row (kind='task') in a

Migration State File

Create migration-state.md in the project root at the start of Phase 0. Update it after each phase. It's the single source of truth — if context is lost, re-read it to recover decisions and progress. Re-read it before starting any phase.

Sections to maintain:

platform_id mappings), workspace files, cron count, MCP servers

• Progress — checkbox list of phases (Phase 0–8)
• Discovery — STATEDIR, IDENTITYNAME, channels, groups (with v2

• Decisions — assistant_name, shared-vs-separate, primary owner agent
• Owner & Primary Agent — user id, role, agent group folder
• Registered Groups — table: folder, platformid, channel, sessionmode
• Credentials — table: credential, destination (vault / .env), status
• Settings Migrated — timezone, container timeout
• Identity & Memory — prepend and memory paths created for each group
• Scheduled Tasks — table: original_id, name, mapped schedule, status
• Deferred / Not Applicable — unsupported channels, OpenClaw-only features

Keep it factual and terse. Delete it at the end of Phase 8 (or offer to keep it as a record).

Phase 0: Discovery

Run the discovery script to find and summarize the OpenClaw installation:

pnpm exec tsx ${CLAUDE_SKILL_DIR}/scripts/discover-openclaw.ts

If the user specifies a custom path, pass --state-dir .

Parse the status block. Key fields: STATUS, STATEDIR, CHANNELS, WORKSPACEFILES, DAILYMEMORYFILES, SKILLCOUNT, SKILLS, CRONJOBS, MCPSERVERS, IDENTITYNAME, AGENTCOUNT, AGENTIDS, GROUPS (each formatted channel:id(name)=>v2platformid — the right-hand value is what to pass as --platform-id to register).

Sanity-check the output. The script detects known structures but can miss data if OpenClaw's format changed. Check CONFIGTOPKEYS and CONFIGCHANNELKEYS — if you see keys it didn't report on, read that section of the config with the Read tool. Check STATEDIRCONTENTS for directories it doesn't scan.

If STATUS=notfound:** Tell the user no OpenClaw install was detected at the standard locations (~/.openclaw, ~/.clawdbot). Ask for a custom path; if none, exit.

If STATUS=found: Present a human-readable summary (identity name, workspace files, channels and which v2 supports, daily memory count, skills, cron count, MCP servers, agent count). Then paraphrase the key architectural differences from the section above — don't dump it as a table.

AskUserQuestion: "Ready to start migrating? I'll go through each area one at a time."

1. Yes, let's go — proceed to Phase 1
2. Tell me more — explain any area they ask about
3. Skip migration — exit

Phase 1: Agents, Groups, and Shared vs Separate

Decide this before identity/memory — it determines where files go.

OpenClaw model: all groups routed to one agent share a workspace (SOUL/MEMORY/IDENTITY) and personality; only the session is per-group.

v2 model: each agent group is a separate container with its own filesystem, standing instructions, and memory/ tree. Multiple messaging groups wired to the same agent group share that state. There is no groups/global/.

AskUserQuestion: "In OpenClaw your groups shared one personality and memory. In v2 each agent group is separate. How do you want to handle this?"

identity to each selected group's instructions.prepend.md; keep group facts in each group's memory tree.

1. Shared identity (recommended if it was one bot) — apply the same core

shared base edit.

1. Fully separate — each group gets independent memory and instructions; no

1. Just the primary agent for now — set one agent up; add others later.

Remember this choice for Phase 3.

Confirm the assistant name

IDENTITY_NAME from discovery is the OpenClaw name. Ask: "Your OpenClaw assistant was named . Keep it in v2?" If empty, ask them to choose (default: "Andy"). The chosen name is passed as --assistant-name to register/init.

Seed the owner and the primary DM agent

The owner identity and the primary agent are created together by scripts/init-first-agent.ts. It upserts the user, grants the owner role, creates the agent group + filesystem, wires a DM messaging group, and queues a welcome DM over the running service's CLI socket — so the service must be running. If it isn't, tell the user to start it first.

Resolve the owner's channel identity and the DM platform id (use the channel's own terminology). Then:

pnpm exec tsx scripts/init-first-agent.ts \
  --channel <channel> \
  --user-id <channel>:<handle> \
  --platform-id <channel>:<dm-id> \
  --display-name "<Owner Name>" \
  --agent-name "<confirmed assistant name>" \
  [--role owner]      # default: owner

For direct-addressable channels (telegram, whatsapp) the --platform-id is usually the same handle as --user-id with the channel prefix. --role defaults to owner (global, cross-channel) — use admin (scoped to the agent group) or member only if intended.

Register the remaining groups

For each additional OpenClaw group the user wants to bring over, register a messaging group and wire it to an agent group:

pnpm exec tsx setup/index.ts --step register -- \
  --platform-id "<v2_platform_id from discovery>" \
  --name "<group name>" \
  --folder "<channel>_<name-slug>" \
  --channel "<channel>" \
  --session-mode "<shared|agent-shared|per-thread>" \
  [--trigger "@<assistant name>"] \
  [--no-trigger-required] \
  --assistant-name "<assistant name>"

Notes:

runtime, so pass the => value discovery emitted (or the raw OpenClaw id).