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.

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 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.