# Agent Migration

> Safely rename or migrate an OpenClaw agent by updating config and naming, migrating session content, fixing session metadata, restarting, verifying, and asking separately before deleting the old agent.

- Skill: `lord1egypt/agent-migration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lord1egypt/agent-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lord1egypt/agent-migration/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Lord1Egypt (https://skillmd.com/u/lord1egypt)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/lord1egypt/agent-migration

---


# Agent Migration

Use this skill when the user wants to rename or migrate an OpenClaw agent safely.

## Scope
This skill handles:
- agent id rename
- workspace rename
- config/path updates
- prior session content migration
- session display metadata updates
- restart and verification
- separate deletion confirmation for the old agent

## Defaults and boundaries
- Confirm old id, new id, new workspace, and whether model also changes.
- Migrate prior session content by default unless the user explicitly says not to.
- Do not skip migration just because a session does not look active.
- Do not hard-edit active lock files or force-rewrite a live session shell.
- Restart is required after migration.
- Never delete the old agent without a separate user confirmation.

## Files involved
- config: `~/.openclaw/openclaw.json`
- agent dirs: `~/.openclaw/agents/<id>/...`
- workspace: `/home/yln/claw-workspace/<name>`
- session metadata such as `sessions.json`

## Use the included files
- `references/checklist.md`
- `references/cleanup.md`
- `scripts/inspect_agent_migration.sh`
- `scripts/copy_session_content.sh`
- `scripts/verify_agent_migration.sh`

## Recommended commands
```bash
bash skills/agent-migration/scripts/inspect_agent_migration.sh <old-id> <new-id>
bash skills/agent-migration/scripts/copy_session_content.sh <old-id> <new-id>
bash skills/agent-migration/scripts/verify_agent_migration.sh <old-id> <new-id>
```

## Guardrails
- Keep config, workspace, and naming changes consistent.
- Update session display-layer metadata as part of the migration.
- Verify the new agent before offering deletion of the old one.
- Use `references/cleanup.md` only after the user separately confirms deletion.