Skip to content

fix: preserve user workspace files and prefs across upgrades#11

Closed
helix-nine wants to merge 1 commit into
masterfrom
fix/preserve-workspace-files-on-upgrade
Closed

fix: preserve user workspace files and prefs across upgrades#11
helix-nine wants to merge 1 commit into
masterfrom
fix/preserve-workspace-files-on-upgrade

Conversation

@helix-nine

Copy link
Copy Markdown
Contributor

Problem

Reports of OpenClaw settings being wiped on update. Root cause is in startos/init/initializeService.ts, which setupOnInit runs on every install and upgrade. Three things there clobber user data on each update:

  1. Workspace files overwritten. cp SOUL.md IDENTITY.md HEARTBEAT.md copied the image's defaults over the user's files every update — only MEMORY.md was guarded with a test -f. These are exactly the files the Instructions tell users to edit to shape their agent's personality/identity.
  2. Heartbeat reset. agents.defaults.heartbeat.every was re-forced to 24h on every update, discarding a user's chosen interval.
  3. Skill dirs dropped. skills.load.extraDirs was replaced with ['/opt/skills'] every update (arrays aren't deep-merged), so any user-added skill directories were lost.

This regressed in the gateway-auth redesign (21310b8), which moved the config seeding out of its original if (kind === 'install') guard so it now runs on every init.

Note: the openclaw.json zod schema itself is not the culprit — start-sdk ≥ this version patches z.object to be loose by default, so unknown keys already survive the read→merge→write round-trip (verified empirically).

Fix

  • Seed all four workspace files (SOUL, IDENTITY, HEARTBEAT, MEMORY) only when missing, so user edits persist across upgrades.
  • Still enforce the gateway/proxy settings StartOS requires on every init — deep-merge leaves the user's auth.password and other keys intact.
  • Union /opt/skills into extraDirs instead of replacing, preserving user-added dirs while keeping bundled skills loadable.
  • Seed the heartbeat.every default on first install only.
  • Update README.md and instructions.md to describe the seed-when-missing behavior.

Testing

  • npm run check (tsc) passes.
  • make builds openclaw_x86_64.s9pk cleanly.

Already-lost data can't be recovered; this prevents future overwrites.

initializeService ran on every install AND upgrade, so it:
- overwrote SOUL.md, IDENTITY.md, HEARTBEAT.md from the image on every
  update (only MEMORY.md was guarded), wiping the user's agent personality
- re-forced agents.defaults.heartbeat.every to 24h every update
- replaced skills.load.extraDirs wholesale, dropping user-added skill dirs

Now all four workspace files are seeded only when missing; the bundled
/opt/skills dir is unioned into extraDirs without dropping user entries;
heartbeat default is seeded on first install only. Required gateway/proxy
settings are still enforced every init (deep-merge keeps the password).

Updates README.md and instructions.md to match.
@helix-nine

Copy link
Copy Markdown
Contributor Author

Closing — the reported bug is the wiped API key, fixed in #12. The workspace-file overwrite this PR changed is intentional (SOUL/IDENTITY/HEARTBEAT are kept in sync with package defaults per instructions.md; only MEMORY is user data), and the heartbeat/skills merge tweak isn't needed. #12 alone is the fix.

@helix-nine helix-nine closed this Jun 12, 2026
@helix-nine helix-nine deleted the fix/preserve-workspace-files-on-upgrade branch June 12, 2026 12:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant