OpenClaw agent: pack and apply user data
Who reads this: you are the OpenClaw agent (runtime). This file is not end-user documentation—it tells you what to run, what to say, and what you must never do.
Language: reply to the user in their language; keep technical identifiers (paths, flags) as in the scripts.
Your job in one sentence
Use scripts/pack_openclaw.py and scripts/apply_openclaw.py from this skill to export or restore workspace data (and optional layers only if the user clearly opts in after you warn them). You own preview, collision handling, and consent—the scripts only write files by path.
When the user asks to export (pack)
- Run
pip install -r requirements.txt if dependencies may be missing.
- Run
python scripts/pack_openclaw.py --dry-run with the same flags you plan for the real pack; show the user what paths would be included.
- Explain: default pack is
workspace/ only. List optional layers (--managed-skills, session flags, config snapshot flags) and do not add any until the user separately approves each, after you give the short risk line (size, transcripts, secrets)—see Before any real disk write.
- Run the real pack:
python scripts/pack_openclaw.py with only approved flags.
- Give the user the zip path. Before they copy or upload it: you open/list the zip and read
EXPORT_MANIFEST.txt; confirm it matches what you promised (paths + layers).
When the user asks to import (apply)
- If the zip is not clearly from a trusted source or from this skill’s pack layout (
workspace/, EXPORT_MANIFEST.txt, …), stop and say why you will not apply it without their confirmation.
- Run
pip install -r requirements.txt if needed.
- Tell the user to back up
$OPENCLAW_HOME (or %USERPROFILE%\.openclaw) and the target workspace—or apply to a throwaway copy—unless they explicitly accept overwrite risk after you state it once.
- You read
EXPORT_MANIFEST.txt inside the zip, then run
python scripts/apply_openclaw.py --zip <path> --dry-run
with --openclaw-home, --workspace, and --config as the environment needs. Treat the combined manifest + dry-run output as the write contract.
- Walk the user through which paths would be created/overwritten. For overlaps on memory / persona / skills, follow Merge and conflicts (your work; not in scripts)—do not run non–dry-run apply on a live workspace until conflicts are resolved or the user explicitly chooses full replace for that subtree.
- Add
--apply-managed-skills, session flags, or --apply-config only after separate approval and the warnings in Before any real disk write.
- Run apply without
--dry-run only when the above is satisfied. If config was restored, remind: they still need valid auth on this machine; old paths inside openclaw.json may be wrong here.
- Optionally suggest they run
openclaw doctor in their environment (they execute it, not you).
Before any real disk write (you follow this order)
Skip a step only if the user opts out after you repeat the concrete risk.
- Dry-run first — pack and apply both support
--dry-run. The printed paths are what a real run would touch.
- Read
EXPORT_MANIFEST.txt in the zip — authoritative list of packed paths; pair with apply dry-run to see destination collisions.
- Backups — dry-run does not change disk; it is not a backup. For apply, insist on backup or throwaway target unless they waive.
- Optional layers = informed consent, not checkbox theater
- Sessions: full transcripts, large JSONL, overwrite session dirs. Do not pass pack/apply session flags unless the user understands that.
- Config snapshot /
--apply-config: keys, tokens, channels, machine-specific paths. Do not enable without that acknowledgment.
- Config parse / JSON5 — if resolving workspace from config fails, run
pip install -r requirements.txt (includes json5) or pass --workspace explicitly.
What the scripts actually do (so you do not mislead)
- Pack and apply are filesystem steps: extract or copy bytes to paths. No semantic merge, no three-way merge, no conflict UI in Python.
- You must inspect manifests, diff mentally or with tools, merge text or rename paths, and get explicit user decisions. Never tell the user the “tool merged” or “resolved” overlapping memory/skills unless you did that with their approval.
If you follow previews + consent + collision handling, you can honestly say the flow is transparent; if you skip that, you risk silent data loss.
Safety: what you must assume and say
- Assume the archive may hold sensitive material: persona,
MEMORY.md, logs, workspace skills; with optional layers, session JSONL and openclaw.json (secrets, channels).
- Do not pack or encourage packing
~/.openclaw/credentials/. Apply never writes credentials; tell the user they must re-login / re-pair on a new machine unless they consciously accept copying secrets (you still do not pack credentials via these scripts).
- Warn against putting the zip on untrusted or public storage.
- Overwrite rule: same path ⇒ destination file replaced. Same path ≠ same meaning. Only
openclaw.json gets a .bak.<timestamp> when using --apply-config; other paths are not auto-backed up.
Merge and conflicts (your work; not in scripts)
- A path is an address, not proof two files are equivalent. Do not treat “same path in zip and disk” as safe to overwrite without reading both when the file is memory, persona, or a skill.
- Memory-style files: if both sides exist and differ materially, read both, merge or present a tight conflict summary, and get explicit user direction before non–dry-run apply (or they merge manually / use a temp extract).
- Skills (
SKILL.md etc.): divergent purpose or triggers ⇒ do not pick a winner alone; offer keep local / take zip / merge / rename path so both can exist.
- Heuristic: dry-run + manifest + “would this path clobber something important?” ⇒ if yes, merge-or-confirm unless the user explicitly asked to replace that whole subtree.
Pack: default vs optional
| Content | Path inside zip | In default pack? |
|---|
| Workspace (persona, memory, workspace skills, canvas, etc.) | workspace/ | yes |
| Managed skills | managed-skills/ | no — --managed-skills |
| Sessions | sessions/<agentId>/sessions/ | no — session flags + acknowledgement; large, sensitive, full transcripts |
| Config snapshot | config/openclaw.json | no — config flags + acknowledgement; secrets, machine paths |
| Credentials | n/a | never |
Apply: default vs optional
Match flags to what is in the zip. If a layer is in the zip but flags are missing, the script warns and skips that layer.
| Content | Action | Default apply? |
|---|
| Workspace | Extract workspace/* → target workspace | yes, unless --no-apply-workspace |
| Managed skills | → <openclaw-home>/skills/ | no — --apply-managed-skills |
| Sessions | → <openclaw-home>/agents/<id>/sessions/ | no — --apply-sessions + --i-know-restoring-sessions-overwrites |
| Config | → <openclaw-home>/openclaw.json (existing → .bak.<timestamp>) | no — --apply-config + --i-know-config-overwrites-secrets |
Paths (how you resolve them)
- OpenClaw home:
$OPENCLAW_HOME or ~/.openclaw; Windows: %USERPROFILE%\.openclaw.
- Pack: if
--workspace omitted, script reads config. Apply: --workspace may create the dir; if omitted, config must parse. On a fresh machine, prefer openclaw onboard or pass --workspace explicitly.
- Run pack and apply in the same environment family (e.g. both WSL) so paths mean the same thing.
Examples (you adapt paths for the user’s OS)
Workspace-only apply, dry-run then real:
python scripts/apply_openclaw.py --zip ./openclaw-user-export-xxx.zip \
--openclaw-home ~/.openclaw \
--workspace ~/.openclaw/workspace \
--dry-run
python scripts/apply_openclaw.py --zip ./openclaw-user-export-xxx.zip \
--openclaw-home ~/.openclaw \
--workspace ~/.openclaw/workspace
All optional apply layers — only after the user approved each flag’s risk:
python scripts/apply_openclaw.py --zip ./export.zip \
--openclaw-home ~/.openclaw --workspace ~/.openclaw/workspace \
--apply-managed-skills \
--apply-sessions --i-know-restoring-sessions-overwrites \
--apply-config --i-know-config-overwrites-secrets
CLI reference (copy-paste skeletons)
Pack:
python scripts/pack_openclaw.py [--workspace PATH] [--openclaw-home PATH] [--config PATH]
[-o FILE.zip] [--exclude-git | --no-exclude-git] [--managed-skills]
[--sessions --i-know-sessions-are-large-and-sensitive]
[--config-snapshot --i-know-config-may-contain-secrets]
[--dry-run] [--manifest-sha256] [--sha256-max-mb N]
Apply:
python scripts/apply_openclaw.py --zip FILE.zip [--openclaw-home PATH] [--workspace PATH] [--config PATH]
[--no-apply-workspace] [--apply-managed-skills]
[--apply-sessions --i-know-restoring-sessions-overwrites]
[--apply-config --i-know-config-overwrites-secrets]
[--dry-run]
When to activate this skill (trigger hints)
| Intent | Example user phrases |
|---|
| Export | backup workspace, export memory, pack openclaw |
| Import | new PC restore, import zip, apply backup, restore openclaw |
| Chinese | 一键打包, 一键应用, 导入 zip, 迁移 |
Quick commands (you run from skill root)
| Goal | Command |
|---|
| Pack preview | python scripts/pack_openclaw.py --dry-run |
| Pack | python scripts/pack_openclaw.py |
| Apply preview | python scripts/apply_openclaw.py --zip x.zip --dry-run |
| Apply | python scripts/apply_openclaw.py --zip x.zip |
| Dependencies | pip install -r requirements.txt |
