Workspace Backup

Manage these fixed core files from the OpenClaw workspace:

• AGENTS.md
• HEARTBEAT.md
• IDENTITY.md
• SOUL.md
• TOOLS.md
• USER.md
• MEMORY.md

Fixed repository name:

• openclaw-workspace-soul-undead

Repository visibility is always private.

What this skill does

This skill is for preserving and restoring the core markdown files that define an OpenClaw workspace identity and behavior. It is designed for these situations:

• First-time setup of a private backup repo for the six core files
• Restoring the six core files onto a new machine after reinstalling OpenClaw
• Manually syncing saved local changes back to the GitHub backup repo

This skill intentionally does not scan the whole workspace and does not back up every markdown file. It only manages this fixed core file set.

Rules

• Always check gh auth status first.
• If GitHub authentication is missing, stop and tell the user to run gh auth login.
• Do not scan the whole workspace.
• Do not ask the user to choose files unless they explicitly ask for a different scope.
• Treat the fixed GitHub repo as the authority during first-time initialization on a new machine.
• Before any remote restore overwrites local files, create a timestamped local backup snapshot under skills/workspace-backup/local-backups/.

Important behavior: first restore can overwrite local default files

On a new machine, OpenClaw may already have generated local default markdown files. This skill does not treat those default files as authoritative.

If all of the following are true:

• GitHub authentication succeeds
• The fixed repo openclaw-workspace-soul-undead exists
• The local state file does not yet say initialized: true

then this skill will treat that run as a first-time restore scenario and pull the remote six-file set down to the local workspace.

That means the remote files can overwrite local default files created by a fresh OpenClaw installation.

To reduce risk, this skill first saves a timestamped local backup snapshot under:

• ~/.openclaw/workspace/skills/workspace-backup/local-backups/<timestamp>/

That snapshot is the local fallback if the restore direction was wrong.

State file

Use a local state file to mark successful initialization:

• ~/.openclaw/workspace/.workspace-backup-state.json

Write:

{"initialized": true, "repo": "openclaw-workspace-soul-undead"}

Only after one of these succeeds:

1. Restore succeeds from the default GitHub repo
2. First-time repo creation and initial upload succeeds

Do not write initialized: true on failure.

Required dependencies

This skill assumes these tools are available:

• git
• gh (GitHub CLI)
• python3

Minimum expectations:

• gh auth status must succeed before any restore or sync
• The active GitHub account must have permission to read/create/push the private repo

If gh is installed but not authenticated, stop and tell the user to run:

gh auth login

If a dependency is missing, tell the user exactly which command/tool must be installed before continuing.

Required user-facing reminders before execution

Before executing restore, first-time init, or sync, explicitly remind the user of the relevant points below.

Always remind

• This skill only manages these six files: AGENTS.md, HEARTBEAT.md, IDENTITY.md, SOUL.md, TOOLS.md, USER.md
• The GitHub repository is private and fixed to openclaw-workspace-soul-undead
• gh auth login is required if GitHub CLI authentication is missing

If first-time restore may happen

Explicitly warn that:

• if the remote repo already exists, the skill may restore remote files onto the local workspace during first initialization
• this can overwrite local default markdown files created by a fresh OpenClaw install
• before overwrite, the skill will create a timestamped local backup snapshot under skills/workspace-backup/local-backups/

If sync/upload is the user's intent

Explicitly confirm the task as sync/upload intent and avoid accidentally running restore-first behavior.

Workflow

1. Check GitHub authentication

Run:

gh auth status

If authentication fails, stop and guide the user to run:

gh auth login

2. Initialization / restore decision

Use the bundled script:

bash <skill-dir>/scripts/init_or_sync.sh

Behavior:

• Uses the fixed repo name openclaw-workspace-soul-undead
• Uses the fixed core file set only
• If the state file is missing or not initialized:
  • If the GitHub repo exists, restore from it first, even if local default md files already exist
  • If the GitHub repo does not exist, create it as private and upload the local six files
  • On success, write initialized: true
• If already initialized, sync local saved changes to GitHub

3. Sync after saved changes

After initialization is complete, use the same script again whenever the six tracked files may have changed.

Behavior:

• Detects saved file changes via modification time
• Copies the fixed six-file set into the export repo
• Uses git to determine whether content actually changed
• If content changed, commits and pushes immediately
• If content did not actually change, exits quietly

Preview / dry-run design (not implemented yet)

If preview support is added later, it should report intent without making changes.

The preview should show these four things:

1. Planned path

   • restore from remote
   • first-time init + upload
   • sync upload
   • no-op

2. Affected files

   • Which of the fixed core files would be overwritten locally
   • Or which of the fixed core files would be committed and pushed

3. Safety actions

   • Whether a local timestamped snapshot would be created before remote restore
   • The expected backup path under skills/workspace-backup/local-backups/<timestamp>/

4. Precondition status

   • Whether gh auth status passes
   • Whether the default repo exists
   • Whether the state file is initialized
   • Whether real file changes are currently detected

Preview mode should never:

• overwrite local files
• create or update the GitHub repo
• commit or push
• write initialized: true

Failure handling

Use these failure rules:

GitHub auth failure

• Do not continue
• Tell the user to run gh auth login

Missing dependency

• Do not continue
• Tell the user which dependency is missing: git, gh, or python3

Repo does not exist during first use

• Treat it as first-time initialization
• Create the private repo
• Upload the six local files
• Only then write initialized: true

Remote restore fails

• Do not write initialized: true
• Keep the local backup snapshot that was created before overwrite
• Tell the user restore failed and where the local snapshot is stored

Sync/push fails

• Do not change initialization state
• Tell the user the push failed
• Leave the local files untouched so sync can be retried later

Defaults

• Workspace path: ~/.openclaw/workspace
• State file: ~/.openclaw/workspace/.workspace-backup-state.json
• Export path: ~/.openclaw/workspace-export/openclaw-workspace-soul-undead
• Local restore-safety backup path: ~/.openclaw/workspace/skills/workspace-backup/local-backups/<timestamp>/
• Repository visibility: private
• Repository name: openclaw-workspace-soul-undead
• Tracked files: fixed core file set only

Notes

• On a new machine, remote restore wins over freshly generated local default md files during first initialization.
• Use the generated restore.sh from the backup repo for manual recovery when needed.
• This skill is currently best suited for controlled/private use. If publishing publicly later, consider adding preview/dry-run support and configurable repo/file settings.