feat: add local backup CLI by shichangs · Pull Request #40163 · openclaw/openclaw

shichangs · 2026-03-08T18:40:32Z

Summary

Problem: OpenClaw had only ad-hoc documentation for backups, but no first-class CLI backup workflow.
Why it matters: reset and uninstall can remove local state, credentials, sessions, and workspaces, so recoverability depended on manual operator steps.
What changed: added openclaw backup create, openclaw backup verify, optional openclaw backup create --verify, docs, archive manifest validation, atomic archive writes, and backup guidance in destructive flows.
What did NOT change (scope boundary): this PR does not add backup restore yet.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #
Related #

User-visible / Behavior Changes

New openclaw backup create command to archive local state/config/credentials/workspace into a timestamped .tar.gz.
New openclaw backup verify <archive> command to validate backup structure and embedded manifest.json.
New openclaw backup create --verify option to self-check an archive immediately after writing it.
Backup archives are now written atomically through a temp file + rename, so failed runs do not strand partial final archives.
reset and uninstall now recommend running openclaw backup create before state-destructive flows.
Default backup output now falls back out of the source tree when the current working directory is inside backed-up state.

Security Impact (required)

New permissions/capabilities? (Yes/No) Yes
Secrets/tokens handling changed? (Yes/No) No
New/changed network calls? (Yes/No) No
Command/tool execution surface changed? (Yes/No) Yes
Data access scope changed? (Yes/No) Yes
If any Yes, explain risk + mitigation:

This adds a local CLI capability that reads user state/config/workspace paths and writes a backup tarball. Mitigations:

output paths inside backed-up source trees are rejected
symlink/canonical-path containment is checked before writing
final archive writes are atomic via temp file + rename
existing archive files are never overwritten
archive contents are rooted under a generated backup root and described by a manifest
backup verify validates manifest/payload consistency

Repro + Verification

Environment

OS: macOS
Runtime/container: local Node 22
Model/provider: N/A
Integration/channel (if any): N/A
Relevant config (redacted): temp home/state dirs in tests; custom config path for external-workspace coverage

Steps

Run openclaw backup create --output <dir>.
Inspect the generated .tar.gz and embedded manifest.json.
Run openclaw backup verify <archive>.
Run openclaw reset --dry-run or openclaw uninstall --dry-run and confirm backup guidance is shown for state-destructive scopes.

Expected

Backup archive is created with canonicalized payload paths and manifest metadata.
Verification succeeds for valid archives and fails for malformed archives.
Failed writes do not leave a final partial archive behind.
Destructive flows point users at the backup command first.

Actual

Matches expected in targeted test coverage.

Evidence

Failing test/log before + passing after
Trace/log snippets
Screenshot/recording
Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

Verified scenarios:
- backup archive creation for default state layout
- backup archive creation when workspace is outside state
- backup archive verification for valid and malformed archives
- backup guidance emitted by reset and uninstall for state-destructive flows
- create-time verification via --verify
- failed archive creation does not leave a final partial archive behind
Edge cases checked:
- cwd inside backed-up source tree
- dry-run with an already-existing target path
- manifest references missing payload
- archive missing manifest
- symlink/canonical-path containment on macOS temp paths
- temp archive cleanup on failure
What you did not verify:
- restore flow, because it is intentionally out of scope
- full repo tsc, due to unrelated existing failures outside this PR

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

Backward compatible? (Yes/No) Yes
Config/env changes? (Yes/No) No
Migration needed? (Yes/No) No
If yes, exact upgrade steps:

Failure Recovery (if this breaks)

How to disable/revert this change quickly:
- do not use the new backup commands
- revert this PR to restore previous behavior
Files/config to restore:
- none required; this feature is additive
Known bad symptoms reviewers should watch for:
- backup output path accidentally resolving inside state/workspace trees
- verify passing malformed archives
- destructive-flow guidance showing for non-destructive scopes
- partial final archives left behind after failed writes

Risks and Mitigations

Risk: archive verification only validates manifest/payload structure, not file-level checksums.
- Mitigation: keep restore out of scope for now; follow up with stronger integrity metadata if maintainers want it.
Risk: backup now surfaces a larger local-data packaging capability.
- Mitigation: keep it explicit CLI-only, local-only, non-overwriting, atomically written, and guarded against self-inclusion.

Testing

AI-assisted
pnpm exec vitest run src/commands/backup.atomic.test.ts src/commands/backup.test.ts src/commands/backup-verify.test.ts src/commands/reset.test.ts src/commands/uninstall.test.ts src/cli/program/register.backup.test.ts src/cli/program/command-registry.test.ts src/cli/program/preaction.test.ts src/cli/program/register.maintenance.test.ts
pnpm exec tsc -p tsconfig.json --noEmit was attempted earlier, but the repo currently fails on unrelated pre-existing errors in extensions/tlon and existing agent/provider tests

greptile-apps · 2026-03-08T18:45:40Z

Greptile Summary

This PR adds a first-class openclaw backup create CLI command that archives local state, config, credentials, and workspace directories into a timestamped .tar.gz with an embedded manifest.json. The implementation integrates cleanly with the existing command registry and preaction hooks (config-guard bypass, lazy module loading), and the path de-duplication / coverage-detection logic works correctly.

Key concern: The tar.c archive creation writes directly to the final outputPath. If it fails mid-stream (disk full, I/O error, etc.), a corrupt/partial archive is left at outputPath. On the next run assertOutputPathReady refuses to overwrite it, leaving users stuck until they manually remove the file. Writing to a temp path and atomically renaming on success would fix this.

The self-inclusion guard, overwrite prevention, dry-run mode, and JSON output suppression in the banner are all implemented correctly.

Confidence Score: 3/5

Safe to merge after addressing the partial-archive-on-failure scenario to avoid leaving users in an unrecoverable retry loop.
The overall design and test coverage are solid, but the direct write to outputPath in the tar.c call means any mid-archive failure leaves a corrupt file that blocks future retries. This is a meaningful recoverability issue for a feature that is itself about recoverability and should be fixed with atomic write-then-rename semantics.
src/commands/backup.ts — the tar.c archive creation block (lines 240–258) needs atomic write-then-rename to handle mid-archive failures safely.

_{Last reviewed commit: 20c606d}

src/commands/backup.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 92f02cb482

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/commands/backup.ts

shichangs · 2026-03-08T18:49:10Z

@joshavant @gumadeiras this touches core CLI command wiring, local state/storage handling, and DX/docs around destructive flows.

Could one of you take a review when you have a slot?

What is in scope now:

openclaw backup create
openclaw backup verify
openclaw backup create --verify
backup guidance surfaced in reset / uninstall

What is intentionally out of scope:

restore flow

Targeted coverage is in the PR body. If the shape looks right, this should be ready to merge after review.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8e661396e9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/commands/backup-verify.ts

src/commands/backup.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0f32d5a73d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/commands/backup.ts

src/commands/backup-shared.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 71955ffe5b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/commands/backup.ts

src/commands/backup-verify.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a4be741e5f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/commands/backup.ts

gumadeiras · 2026-03-08T20:21:24Z

Merged via squash.

Prepared head SHA: ed46625ae20c71e5f46d51aa801cefe4ef1c92e3
Merge commit: 0ecfd37b44656f3b1ef08268e3b5c6d975107a26

Thanks @shichangs!

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ed46625ae2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/commands/backup-verify.ts

@gumadeiras

Merged via squash. Prepared head SHA: ed46625 Co-authored-by: shichangs <46870204+shichangs@users.noreply.github.com> Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com> Reviewed-by: @gumadeiras

@gumadeiras

Merged via squash. Prepared head SHA: ed46625 Co-authored-by: shichangs <46870204+shichangs@users.noreply.github.com> Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com> Reviewed-by: @gumadeiras

openclaw-barnacle bot added docs Improvements or additions to documentation cli CLI command changes commands Command implementations size: L labels Mar 8, 2026

greptile-apps bot reviewed Mar 8, 2026

View reviewed changes

src/commands/backup.ts Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Mar 8, 2026

View reviewed changes

src/commands/backup.ts Show resolved Hide resolved

openclaw-barnacle bot added size: XL and removed size: L labels Mar 8, 2026

gumadeiras self-assigned this Mar 8, 2026

chatgpt-codex-connector bot reviewed Mar 8, 2026

View reviewed changes

src/commands/backup-verify.ts Outdated Show resolved Hide resolved

src/commands/backup.ts Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Mar 8, 2026

View reviewed changes

src/commands/backup.ts Outdated Show resolved Hide resolved

src/commands/backup-shared.ts Outdated Show resolved Hide resolved

openclaw-barnacle bot added the agents Agent runtime and tooling label Mar 8, 2026

chatgpt-codex-connector bot reviewed Mar 8, 2026

View reviewed changes

src/commands/backup.ts Show resolved Hide resolved

src/commands/backup-verify.ts Outdated Show resolved Hide resolved

gumadeiras force-pushed the codex/backup-cli branch from 71955ff to c301597 Compare March 8, 2026 19:43

openclaw-barnacle bot removed the agents Agent runtime and tooling label Mar 8, 2026

chatgpt-codex-connector bot reviewed Mar 8, 2026

View reviewed changes

src/commands/backup.ts Outdated Show resolved Hide resolved

SC-Claw and others added 12 commits March 8, 2026 16:18

feat: add local backup CLI

e69be43

fix: harden backup path handling

dca7085

feat: surface backup guidance for destructive flows

941ed14

feat: add backup archive verification

bef8409

fix: write backup archives atomically

88e52ff

fix: harden backup validation and planning

254f724

fix: align backup verify extraction

81c22d3

test: isolate gateway secret env fallback

22d78d0

fix: merge backup hardening updates

581ab65

fix: finalize backup hardening

4f98de2

fix: harden backup manifest counting

0b0fb1b

docs: clarify backup scope and limits

9170591

gumadeiras added 4 commits March 8, 2026 16:19

fix: sort backup archives by timestamp

f15712e

feat: add config-only backups

cc2ce77

fix: canonicalize backup cwd fallback

4c8c6fb

docs: update backup changelog details

ed46625

gumadeiras force-pushed the codex/backup-cli branch from 93ff652 to ed46625 Compare March 8, 2026 20:20

gumadeiras merged commit 0ecfd37 into openclaw:main Mar 8, 2026
23 of 26 checks passed

chatgpt-codex-connector bot reviewed Mar 8, 2026

View reviewed changes

src/commands/backup-verify.ts Show resolved Hide resolved

src/commands/backup-verify.ts Show resolved Hide resolved

github-actions bot mentioned this pull request Mar 8, 2026

📡 Upstream Digest — 2026-03-08 22:15 UTC curtismercier/openclaw-mods#216

Open

github-actions bot mentioned this pull request Mar 9, 2026

上游更新: v2026.3.8 — 4 P0 + 48 P1 待合并 jiulingyun/openclaw-cn#488

Open

shichangs mentioned this pull request Mar 9, 2026

CLI: add validated backup restore workflow #41274

Open

20 tasks

simonsbot mentioned this pull request Mar 10, 2026

openclaw backup create fails on Android/Termux — EACCES: permission denied, link (hardlinks blocked by Android) AidanPark/openclaw-android#37

Open

Uh oh!

Conversation

shichangs commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Testing

Uh oh!

greptile-apps bot commented Mar 8, 2026

Greptile Summary

Confidence Score: 3/5

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

shichangs commented Mar 8, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

gumadeiras commented Mar 8, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

shichangs commented Mar 8, 2026 •

edited

Loading