Guide the user through migrating their OpenClaw installation into NanoClaw v2.\nThis is a conversation, not a batch job. Read OpenClaw state, discuss it with\nthe user, decide together what to bring over and where it belongs in v2's\nentity model, and show proposed changes before applying.
\nPrinciple: Never silently copy data. Read it, explain it, place it, then\napply. Credentials are masked when displayed (first 4 + ... + last 4). Make\njudgment calls about what's core vs. reference material.
UX: Use AskUserQuestion for multiple-choice only. Use plain text for\nfree-form input. Don't dump raw data — summarize and explain conversationally.
This skill drives existing NanoClaw entry points (setup/index.ts --step register, scripts/init-first-agent.ts, the onecli CLI) and copies a few\nfiles in (workspace markdown, OpenClaw skills, and its own transform module +\ntest). It makes no code-level reach-in into core. Its integration assumptions\nabout v2 are guarded by scripts/transform.test.ts, which is copied into the\nproject's scripts/ test tree on apply (Phase 8) so vitest runs it against the\ncomposed install. REMOVE.md reverses every file the skill copies.
OpenClaw and NanoClaw v2 differ structurally. Keep these in mind throughout:
\ndata/v2.db) holds users,\nuser_roles, agent_groups, messaging_groups, and the\nmessaging_group_agents wiring between them. There is no store/messages.db\nand no scheduled_tasks table.groups/<folder>/instructions.prepend.md. Durable facts\nlive under groups/<folder>/memory/. The provider project document is\ncomposed at spawn and must not be edited..env; the NanoClaw host process reads them to connect to the platform.unknown_sender_policy plus\nuser_roles (owner/admin) and agent_group_members — not a JSON allowlist\nfile.messages_in row (kind='task') in a\nsession's inbound.db, carrying a cron recurrence and a process_after\ntimestamp. The agent creates them via its schedule_task MCP tool.Create migration-state.md in the project root at the start of Phase 0. Update\nit after each phase. It's the single source of truth — if context is lost,\nre-read it to recover decisions and progress. Re-read it before starting any\nphase.
Sections to maintain:
\nKeep it factual and terse. Delete it at the end of Phase 8 (or offer to keep it\nas a record).
\nRun the discovery script to find and summarize the OpenClaw installation:
\npnpm exec tsx ${CLAUDE_SKILL_DIR}/scripts/discover-openclaw.ts\nIf the user specifies a custom path, pass --state-dir <path>.
Parse the status block. Key fields: STATUS, STATE_DIR, CHANNELS,\nWORKSPACE_FILES, DAILY_MEMORY_FILES, SKILL_COUNT, SKILLS, CRON_JOBS,\nMCP_SERVERS, IDENTITY_NAME, AGENT_COUNT, AGENT_IDS, GROUPS (each formatted\nchannel:id(name)=>v2_platform_id — the right-hand value is what to pass as\n--platform-id to register).
Sanity-check the output. The script detects known structures but can miss\ndata if OpenClaw's format changed. Check CONFIG_TOP_KEYS and\nCONFIG_CHANNEL_KEYS — if you see keys it didn't report on, read that section\nof the config with the Read tool. Check STATE_DIR_CONTENTS for directories it\ndoesn't scan.
If STATUS=not_found: Tell the user no OpenClaw install was detected at the\nstandard locations (~/.openclaw, ~/.clawdbot). Ask for a custom path; if\nnone, exit.
If STATUS=found: Present a human-readable summary (identity name, workspace\nfiles, channels and which v2 supports, daily memory count, skills, cron count,\nMCP servers, agent count). Then paraphrase the key architectural differences\nfrom the section above — don't dump it as a table.
\nAskUserQuestion: \"Ready to start migrating? I'll go through each area one at a\ntime.\"
\nDecide this before identity/memory — it determines where files go.
\nOpenClaw model: all groups routed to one agent share a workspace\n(SOUL/MEMORY/IDENTITY) and personality; only the session is per-group.
\nv2 model: each agent group is a separate container with its own filesystem,\nstanding instructions, and memory/ tree. Multiple messaging groups wired to\nthe same agent group share that state. There is no groups/global/.
AskUserQuestion: \"In OpenClaw your groups shared one personality and memory. In\nv2 each agent group is separate. How do you want to handle this?\"
\ninstructions.prepend.md; keep group\nfacts in each group's memory tree.Remember this choice for Phase 3.
\nIDENTITY_NAME from discovery is the OpenClaw name. Ask: \"Your OpenClaw\nassistant was named <IDENTITY_NAME>. Keep it in v2?\" If empty, ask them to\nchoose (default: \"Andy\"). The chosen name is passed as --assistant-name to\nregister/init.
The owner identity and the primary agent are created together by\nscripts/init-first-agent.ts. It upserts the user, grants the owner role,\ncreates the agent group + filesystem, wires a DM messaging group, and queues a\nwelcome DM over the running service's CLI socket — so the service must be\nrunning. 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\nown terminology). Then:
\npnpm exec tsx scripts/init-first-agent.ts \\\n --channel <channel> \\\n --user-id <channel>:<handle> \\\n --platform-id <channel>:<dm-id> \\\n --display-name \"<Owner Name>\" \\\n --agent-name \"<confirmed assistant name>\" \\\n [--role owner] # default: owner\nFor direct-addressable channels (telegram, whatsapp) the --platform-id is\nusually the same handle as --user-id with the channel prefix. --role\ndefaults to owner (global, cross-channel) — use admin (scoped to the agent\ngroup) or member only if intended.
For each additional OpenClaw group the user wants to bring over, register a\nmessaging group and wire it to an agent group:
\npnpm exec tsx setup/index.ts --step register -- \\\n --platform-id \"<v2_platform_id from discovery>\" \\\n --name \"<group name>\" \\\n --folder \"<channel>_<name-slug>\" \\\n --channel \"<channel>\" \\\n --session-mode \"<shared|agent-shared|per-thread>\" \\\n [--trigger \"@<assistant name>\"] \\\n [--no-trigger-required] \\\n --assistant-name \"<assistant name>\"\nNotes:
\nregister namespaces the --platform-id the same way the adapter will at\nruntime, so pass the => value discovery emitted (or the raw OpenClaw id).--folder to put a group on an existing agent (shared base/separate\nconversations); use a new --folder for a fully separate agent.--trigger to set an explicit\nregex, or --no-trigger-required for respond-to-everything.Folder naming: <channel>_<name-slug> (e.g. telegram_dev-team). Confirm each\nname and folder with the user.
Read the config (<STATE_DIR>/openclaw.json or clawdbot.json) for settings\nthat map to v2 setup.
Check agents.defaults.userTimezone. If it's a valid IANA zone, write it to\n.env as TZ=<timezone>. v2 reads TZ from .env (src/config.ts) and uses\nit for cron/recurrence evaluation, so this matters for scheduled tasks.
Check agents.defaults.timeoutSeconds. v2's equivalent is CONTAINER_TIMEOUT\n(env var, default 30 min) or per-group ncl groups config update. If the\nOpenClaw value differs notably, note it; the user can set\nCONTAINER_TIMEOUT=<ms> in .env.
OpenClaw per-channel allowFrom / dmPolicy / groupPolicy map onto v2's\nmodel, which is not a JSON file. Each messaging group has an\nunknown_sender_policy; access is granted via user_roles (owner/admin) and\nagent_group_members. Map:
dmPolicy/groupPolicy: \"open\" → leave the default; no extra grants.
allowFrom / groupAllowFrom lists → for each allowed sender, upsert the\nuser and add them as a member of the relevant agent group via ncl:
ncl users create --id \"<channel>:<handle>\" --kind <channel> --display-name \"<name>\"\nncl members add --user \"<channel>:<handle>\" --group \"<ag-id>\"\ndmPolicy: \"disabled\" → don't wire that chat (or leave it registered but\nunwired).
The messaging groups register / init-first-agent create default their\nunknown_sender_policy to whatever the channel adapter declares for that\ncontext (DM vs group) — strict when the channel has no declaration — so\nunknown senders are gated until you add them (or an admin approves the\nadapter-declared approval card). Pass --unknown-sender-policy to register\nto override. Show the user the OpenClaw allowlist and confirm who to grant\nbefore running the commands.
Fully conversational — read files directly and discuss. Placement depends on\nthe Phase 1 choice:
\ninstructions.prepend.md.instructions.prepend.md.Never edit a composed CLAUDE.md or AGENTS.md; it is regenerated each spawn.\nPut standing behavior in instructions.prepend.md and facts in memory/.
Find workspace files at <STATE_DIR>/workspace/. If AGENT_COUNT > 1, also\ncheck <STATE_DIR>/agents/*/workspace/ and ask which agent maps to which v2\nagent group.
Read them. Distinguish always-loaded vs reference:
\ninstructions.prepend.md.groups/<folder>/memory/, linked from that\nfolder's index.md and the root Map.Choose each memory folder based on which related information will be easiest to\nfind together; a folder may contain different concept types. Before writing the\nfirst concept into a new folder, create the folder and its index.md. Follow\nmemory/system/definition.md, including its YAML frontmatter rules, for every\nnew concept.
Show proposed edits before applying — this is a thoughtful merge, not a paste.
\nCreate a focused user-context concept in an appropriate memory folder and link\nit through that folder's index and the root Map. Put only facts relevant in\nnearly every conversation (for example name or timezone) into ## Core Memory;\nkeep all other details in the linked file.
Show MEMORY.md; keep relevant items in focused concepts under the chosen\nmemory folders, with links through each folder index and the root Map. For\ndaily files (workspace/memory/*.md, count = DAILY_MEMORY_FILES):
AskUserQuestion: \"You have N daily memory files. How to handle them?\"
\nindex.md,\nthen copy with cp <workspace>/memory/*.md <group_dir>/memory/<chosen-folder>/\nand link the retained files through its index and the root Map.If SKILL_COUNT > 0, the SKILL.md format is shared, so skills are portable.\nPresent each (name + description from the front matter) and let the user pick.\nFor each confirmed skill, copy the directory into the container skills tree:
cp -r <skill_source_dir> container/skills/<skill_name>\nA container rebuild is needed afterward — note it for Phase 8.
\nIf CONFIG_PLUGINS is non-empty, OpenClaw had plugins/skills carrying keys.\nFor each, read the config section and decide together:
ncl groups config add-mcp-server. Don't guess at packages.Don't install unknown packages or search for replacements — supply-chain risk.
\nTwo destinations, decided per credential. Channel tokens → .env (host\nreads them). Container-facing API credentials → the OneCLI vault (injected\nper request, never in container env).
Preview, then write to .env. The script emits only masked values:
pnpm exec tsx ${CLAUDE_SKILL_DIR}/scripts/extract-channel-credentials.ts \\\n --state-dir <STATE_DIR> --channel <name>\nParse the status block. DESTINATION: env confirms a host-side token. Show\nCREDENTIAL_MASKED (and CREDENTIAL_MASKED_2 for Slack's app token).
AskUserQuestion:
\n--write-env .env to save it..env yourself.pnpm exec tsx ${CLAUDE_SKILL_DIR}/scripts/extract-channel-credentials.ts \\\n --state-dir <STATE_DIR> --channel <name> --write-env .env\nCheck WRITTEN_TO / WRITTEN_COUNT. Slack writes both SLACK_BOT_TOKEN and\nSLACK_APP_TOKEN in one run.
If HAS_CREDENTIAL=false but a credential is expected: the config shape may\nbe unrecognized, or it uses a file/exec SecretRef (CREDENTIAL_SOURCE\nends in _ref with a NOTE) that can't be auto-extracted. Read the channel\nsection of the config directly and ask the user to confirm or paste the value.
WhatsApp: authenticates via QR/pairing code — there's no token. Don't copy\nBaileys auth state (stale encryption sessions break decryption).\nRe-authenticate during /setup via /add-whatsapp. The extraction script\nreports DESTINATION: none for it.
Find the agent's model credentials in OpenClaw. Check, in order:
\n<STATE_DIR>/auth-profiles.json (and\n<STATE_DIR>/agents/<id>/agent/auth-profiles.json) — a profiles map keyed\nprovider:identifier. For an anthropic provider profile the value depends\non type: api_key → key, token → token, oauth → access.<STATE_DIR>/.env — ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN.models.providers — Anthropic provider apiKey.These are container-facing, so they go to the OneCLI vault. Do not write\nthem to .env or thread them into a container. Register each in the vault:
onecli secrets create --name Anthropic --type anthropic \\\n --value <key-or-token> --host-pattern api.anthropic.com\nFor other container-facing keys discovered in plugins (e.g. OpenAI):
\nonecli secrets create --name OpenAI --type api_key \\\n --value <key> --host-pattern api.openai.com\nRun the command on the user's behalf so the value never lands in the chat\ntranscript; confirm with onecli secrets list.
Caveats: keyRef/tokenRef with source:\"exec\" or source:\"file\" can't\nbe auto-extracted — ask the user to paste it. For an oauth profile with a\npast expiry, warn that the token may need refreshing; the user can run\nclaude setup-token and register the fresh token.
If OneCLI isn't installed yet, defer this: tell the user that during /setup\n(or /init-onecli) they'll register the Anthropic credential, and note the\ndiscovered profile in migration-state.md so it isn't lost.
\n\nThere is no supported
\n.env-credentials opt-out anymore: the session spec's\nadmission rules refuse credential values in container env on every lane, by\ndesign (the retired/use-native-credential-proxyskill would be denied at\nevery spawn). Credentials go through the OneCLI vault; custom Anthropic\nendpoints useANTHROPIC_BASE_URLplus the placeholder-token pattern from\nsetup, with the gateway rewriting the header on the wire.
Read <STATE_DIR>/cron/jobs.json. If absent or empty, skip.
If jobs exist, read ${CLAUDE_SKILL_DIR}/MIGRATE_CRONS.md for the v2 task\nmodel, the mapCronToRecurrence transform, the full field mapping, and how\ntasks are created (the agent's schedule_task MCP tool, since tasks live in a\nper-session inbound.db the host owns). Follow it for each enabled job.
Read the relevant config sections directly. Conversational.
\nIf MCP_SERVERS is non-empty, v2 supports per-agent-group MCP servers via the\ncontainer config. Read each server's command/args/env/url from\nmcp.servers. For each one the user wants:
ncl groups config add-mcp-server --id <agent-group-id> \\\n --name <server-name> --command <cmd> \\\n [--args '<json-array>'] [--env '<json-object>']\nstdio servers must be runnable inside the container (Node/npx-based work;\ncustom binaries need a Dockerfile addition). Secrets referenced by a server's\nenv should go to the OneCLI vault (Phase 4), not be inlined. The config\nchange takes effect on restart: ncl groups restart --id <agent-group-id>\n(add --rebuild only if a custom binary was added to the Dockerfile).
OpenClaw cron.webhook / failureDestination / channel webhooks don't map to\na v2 primitive. For a notification webhook, fold it into a scheduled task's\nprompt or a pre-agent script that curls the endpoint. Discuss the use case.
init-first-agent (Phase 1) already queued a welcome DM for the primary owner\nagent. If the service was up, the owner should have received it. For groups\nregistered via setup --step register, the wiring also queues a /welcome\nonboarding message on first wiring.
Tell the user which agents are live now and which await channel installation\n(unsupported channels registered for the future).
\nCopy the transform module and its test into the project so vitest runs them\nagainst the composed install, then build and test:
\ncp ${CLAUDE_SKILL_DIR}/scripts/transform.ts scripts/openclaw-transform.ts\ncp ${CLAUDE_SKILL_DIR}/scripts/transform.test.ts scripts/openclaw-transform.test.ts\n# Point the copied test at the copied module name:\nsed -i.bak \"s#from './transform.js'#from './openclaw-transform.js'#\" scripts/openclaw-transform.test.ts && rm -f scripts/openclaw-transform.test.ts.bak\n\npnpm run build\npnpm exec vitest run scripts/openclaw-transform.test.ts\nThe test guards the skill's two v2 integration assumptions: credential routing\n(container-facing → vault, channel tokens → .env) and the cron → v2\nrecurrence mapping. It imports the real cron-parser (the same parser the host\nrecurrence sweep uses), so a missing/renamed dependency turns it red. build\ntypechecks the transform module against the project.
These copied files are the only files the skill installs into the project tree;\nREMOVE.md deletes them.
If OpenClaw skills were copied or MCP servers added: ./container/build.sh,\nthen restart the service.
Print what was migrated:
\nusers / user_roles / agent group + welcome DM.env TZ; container timeout → notedinstructions.prepend.md + linked memory conceptsmemory/container/skills/.env (list channels)Noted for later: channel installs during /setup; container rebuild if needed;\ntasks deferred until a session exists.
Not applicable: unsupported channels (registered for the future); OpenClaw-only\nfeatures (exec approvals, human delay, TTS, model/thinking config).
\nRemind: \"Run /setup next to finish your NanoClaw install. Channel tokens are\nin .env; container-facing credentials are in the OneCLI vault. Select the\nchannels we configured when setup asks.\"
Then delete migration-state.md (or offer to keep it as a record), and remove\nthe copied transform files if you don't want them lingering (see REMOVE.md).
file/exec SecretRef — ask the user to\npaste the value.init-first-agent can't reach the CLI socket: the service isn't running.\nStart it, then re-run.