Run a sandbox upgrade rehearsal

Verifiedon 2026-08-022026.7.1

Make the rehearsal boring on purpose

A rehearsal is not a smaller production upgrade. It is an experiment designed to expose the assumptions that production cannot afford to discover late. The target should represent the boundaries that matter—version, configuration shape, state store, service supervisor, plugin set, and at least one synthetic integration—while remaining isolated enough that a failed migration cannot reach real users or credentials.

This lesson uses OpenClaw stable 2026.7.1 and upstream revision 2d2ddc43d0dcf71f31283d780f9fe9ff4cc04fe4 as the verified course scope. The current Update reference and Updating guide are the source of truth for install-method-specific commands. The live pages were checked 2026-08-01 UTC. Resolve any difference between those pages and the installed CLI before executing an update; never turn a course example into a blind production command.

The committed game-day receipt shows the required shape of a bounded rehearsal: fake token auth, loopback-only gateway, verified archive, an invalid mutation rejected by validation, a valid bad-state mutation, and a post-restore health check. It is evidence for the represented synthetic boundaries only; the receipt’s missing backup restore command is an explicit stop condition.

A good rehearsal has an entry gate, a single attributable change, a set of acceptance checks, a stop condition, a recovery path, and a decision record. If the sandbox cannot represent a critical boundary—say, a proprietary channel or a stateful plugin—write that limitation down. “Sandbox passed” then means “the represented boundaries passed,” not “production is safe.”

1. Entry gate proves the sandbox is isolated and restorable.
2. Capture records version, baseline, and backup before mutation.
3. The change is one attributable target, not several repairs bundled together.
4. Acceptance compares expected and actual results before promotion is considered.

Build an entry gate

Before touching the target, prove the following:

• Isolation: the gateway cannot deliver to real recipients, invoke production tools, or write to a shared state path. Use synthetic accounts and a separate state directory or container volume.
• Identity: record the exact installed version, install method, package/source identity, and service owner. A shell executable and the managed service may point to different roots.
• Baseline: run the known-good workflow and record expected output, duration, version, configuration shape, queue state, and state-store health. Keep payloads synthetic.
• Recovery: verify the backup or snapshot and know the fresh restore target. A plan to “copy it back later” is not a tested recovery path.
• Scope: write the one change under test, affected boundaries, target release, owner, reviewer, and maintenance clock.
• Stop conditions: decide what will halt the run: failed backup verification, missing state owner, schema incompatibility, critical workflow regression, unbounded restart loop, or unexpected secret/payload exposure.

The Backup reference documents openclaw backup create --verify, archive manifests, SQLite snapshots, and fresh-target restore behavior. The Restart recovery reference explains what normally survives a restart, including sessions, background tasks, queued deliveries, and restart sentinels. That does not make a restart risk-free: the rehearsal must still observe drain time, recovery markers, and any channel or plugin behavior that is relevant to the proposed change.

Worked example: one controlled upgrade

Imagine the sandbox is on 2026.7.1, with a synthetic WebChat workflow and one test channel account. The run sheet begins:

Entry: isolated state=/srv/openclaw-sandbox/state; no production credentials; owner A
Baseline: version=2026.7.1; health=pass; synthetic workflow=pass; restore proof=verified
Target: exact release approved by review record; install method=package
Preflight: openclaw update status --json; openclaw update --dry-run --json
Change: run the approved update path once; do not bundle config edits or plugin changes
Acceptance: version, doctor lint, gateway health, config load, synthetic channel, state check
Stop: any schema error, unexpected write, critical acceptance failure, or crash loop
Decision: promote to next review, repeat narrower, rollback, or defer

The two preflight commands are read-only in the documented current flow. Record their JSON output and the planned restart behavior. A dry run does not prove the package can start, does not validate your restore, and does not authorize a production mutation. After the approved change, use the release-specific post-upgrade steps. The current Doctor reference documents openclaw doctor --post-upgrade and --lint; use --lint for structured read-only findings and --post-upgrade for compatibility probes where supported.

openclaw --version && openclaw doctor --lint --json && openclaw doctor --post-upgrade --json

If the installed 2026.7.1 binary does not expose one of these flags, stop and record the mismatch. Do not “adapt” by running a similarly named repair. The expected output is a shape to compare; the real evidence must include the exact command, exit status, UTC timestamp, and redaction review.

Choose acceptance checks that can fail meaningfully

Avoid “process is running” as the only acceptance test. Use a layered set:

1. Process and readiness: the managed service is running and the documented readiness surface responds.
2. Configuration: the current build loads the intended config shape without silently dropping keys.
3. State: global and agent stores open, verify, and contain the expected synthetic state.
4. Critical path: the same bounded workflow used for the baseline completes with the same required fields and safety boundary.
5. Integration: the representative channel or plugin probe succeeds without sending to a real recipient.
6. Observability: logs, doctor output, and the run sheet show the result and no unexpected repair loop.

For each check, write expected, actual, evidence location, assessor, and whether the check is blocking. “Looks fine” is not an acceptance result. A check can be non-blocking only when the review owner has decided that in advance.

Lab: the controlled failure

Use a disposable sandbox. First complete the entry gate and baseline. Then introduce one agreed failure signal at a planned point—such as making a synthetic acceptance check fail or withholding a test-only dependency. Do not corrupt a real database or revoke a real credential. Pause the run, capture evidence, and decide whether this is a rollback rehearsal or a defect investigation.

Steps:

1. Freeze the run clock and announce the decision point.
2. Capture version, service state, command output, logs, and the failure signal without copying payloads.
3. Compare the result with the pre-written stop condition.
4. If rollback is the approved action, follow the rollback lesson’s recorded procedure. If not, leave the target unchanged and open an evidence gap.
5. Re-run the acceptance suite and record expected versus actual.
6. Close with promote, repeat narrower, rollback, or defer—and give the next owner a timestamped handoff.

Expected output is a completed run sheet, evidence index, acceptance table, and decision record. Failure cases include changing two variables at once, using a shared state path, skipping the restore proof, declaring success after only a process restart, or hiding a failed check. Roll back the exercise by destroying only the sandbox and synthetic credentials after evidence is preserved. Never “clean up” the evidence by deleting the failure.

Checkpoint: “the sandbox passed”

Ask: which boundary did it represent, and which did it not? If the answer is not explicit, the result is not portable. A sandbox that excludes the state migration or channel plugin under review cannot validate those risks. Narrow the claim, add a representative fixture, or defer the maintenance window.

Learner artifact and source receipt

Submit a run sheet with entry gates, action/evidence columns, acceptance table, failure case, rollback trigger, and final decision. Include a text alternative for the diagram and a short paragraph listing unrepresented production boundaries. Primary receipts: Update, Updating, Doctor, Backup, Restart recovery, and v2026.7.1 release notes.