Sync Upstream

Upstream Sync

Sync openclaw-orbstack with the latest stable release from openclaw/openclaw.

The goal is to keep our OrbStack installer, config templates, docs, and CLAUDE.md aligned with upstream changes — without blindly copying. Each upstream change needs to be evaluated for whether and how it affects our wrapper project.

Upstream repo: https://github.com/openclaw/openclaw

Step 1 — Version check

Run these two checks in parallel to save time:

• Upstream latest stable tag:

  git ls-remote --tags https://github.com/openclaw/openclaw.git 'v*' \
    | awk '{print $2}' | sed 's|refs/tags/||' \
    | grep -v -e '-beta' -e '-rc' -e '-alpha' \
    | sort -V | tail -1
  

  (The beta/rc/alpha filter here is only to pick the sync target — the newest stable. Step 2 still reads the beta/rc notes in between; do not let this filter leak into Step 2.)
• Our version: read the VERSION file in the repo root.

Compare them. If already in sync, tell the user and stop — there's nothing to do.

If git ls-remote fails (network issue, repo moved), fall back to:

gh release list -R openclaw/openclaw --limit 5

Step 2 — Read upstream release notes

We sync to the latest stable (Step 1's target), but stable release notes are cumulative summaries — they roll up several beta/rc cycles and omit per-PR detail that only appears in the beta/rc release notes. (Example: v2026.5.26 folded in the skipped 5.23–5.25 betas as one rolled-up section.) So read the full range, betas included — not just the stable tags.

First enumerate every release between our version and the target stable, keeping beta/rc tags (do NOT reuse Step 1's grep -v filter here):

git ls-remote --tags https://github.com/openclaw/openclaw.git 'v*' \
  | awk '{print $2}' | sed 's|refs/tags/||' | grep -v '\^{}' \
  | sort -V

If git ls-remote fails here, fall back to gh and keep the beta/rc rows (do NOT filter them out):

gh release list -R openclaw/openclaw --limit 30

Take every tag greater than our VERSION up to and including the target stable — keep the beta/rc entries. Then read each one's notes, oldest to newest:

gh release view <tag> -R openclaw/openclaw

Read ALL intermediate releases (stable and beta/rc) from oldest to newest. Order matters: later releases may revert or supersede earlier changes, and a change first shipped in a beta is often documented only in that beta's notes even when the stable rollup glosses over it.

Classify each change into one of these categories. This classification drives Step 3 — it tells you which of our files to inspect:

Docs Snapshot location: The Docs Snapshot lives in auto-memory (memory/MEMORY.md), not in CLAUDE.md. Update it when providers, channels, or major features change.

Doctor / non-interactive flow scan (mandatory)

scripts/commands/update.sh runs openclaw doctor --fix twice (sudo for plugin deps, then non-sudo for config migration) with stdin redirected to a log file. Any upstream change that introduces new interactive prompts can silently break the entire post-install flow — @clack/prompts treats redirected-stdin EOF as Setup cancelled and skips all subsequent doctor steps (state migration, systemd service repair, security audit).

While reading release notes, flag any line matching these patterns (case-insensitive):

• doctor + (interactive | confirm | prompt | Yes/No | require ... confirmation)
• @clack/prompts | clack (the prompt library)
• Setup cancelled | Setup canceled
• --non-interactive | --yes | --assume-yes (if upstream adds these as opt-out flags, we can drop our yes n workaround)
• doctor --fix behavior changes
• archive / migrate / repair paired with "ask" / "prompt"

For each flagged change, perform an explicit verification step in Step 3:

1. Read scripts/commands/update.sh around the two doctor --fix invocations (grep for doctor --fix — their line numbers move as the file grows). The wrapper has a two-layer non-interactive defense: (a) primary — orphan transcripts are pre-archived just above the doctor calls so doctor sees zero orphans and never raises the v2026.4.29 confirm; (b) defense-in-depth — both calls pipe yes n | in case a new or shifted prompt slips through.
2. Classify the new prompt type:
   • Yes/No confirm — yes n answers "No". Verify "No" is the safe / non-destructive default (e.g., "Archive orphan transcripts? No" → preserves files, ✅ safe). If "No" is destructive ("Delete corrupted lock?" → Yes is required), the wrapper needs to answer differently or fall back.
   • Select / multi-choice — yes n does NOT match a list option. Plan a wrapper fix: expect script, a printf "1\n"-style answer, or wait for an upstream --non-interactive flag.
   • Free-text input — yes n will inject "n" as the answer. Almost always wrong. Plan a wrapper fix.
3. Add the doctor change to the impact table with explicit "verify both doctor --fix invocations in scripts/commands/update.sh still complete" in the action column, even if no other file needs touching. Treat it as a blocker until verified.
4. If a wrapper fix is needed, list it as a separate impact-table row so the user can approve the script change alongside the version bump.

Reference incident: v2026.4.29 #73106 added the Archive N orphan transcript files? confirm. Our update.sh hit Setup cancelled right after plugin registry refresh, leaving systemd service repair on the floor. First fixed in commit 33434d7 by piping yes n to both doctor invocations; later hardened by pre-archiving orphan transcripts before the doctor calls (so the prompt never fires), with yes n kept as the fallback. Whenever release notes mention doctor + interactivity, assume the same regression class until proven otherwise.

Step 3 — Impact analysis

This is the most important step. For each upstream change, verify whether our project actually needs updating by reading the relevant files (don't guess from memory — the codebase may have changed since last time).

Use Grep and Read to find the specific locations. For example:

• A new config option → grep templates/openclaw.json.example for the parent key to see if the section exists and where to insert it.
• A new CLI command or flag → check docs/commands.md for existing documentation and scripts/commands/ to see if a wrapper already exists.
• A new chat command → check docs/commands.md for where to add it.
• A new built-in tool → check sandbox allow list in the config template and any model config sections (e.g., videoGenerationModel, musicGenerationModel).
• A removed feature → grep across docs and templates to find stale references.
• A version bump → read VERSION and grep CLAUDE.md for the version string.
• A doctor / interactive-prompt change → read scripts/commands/update.sh around the two doctor --fix invocations (grep for doctor --fix) and verify the pre-archive + yes n | defense still answers safely (see the "Doctor / non-interactive flow scan" section above). If a new prompt type (select, free-text) would break the pipe, propose a wrapper fix as a separate impact-table row.

Present a numbered table so the user can cherry-pick:

Always include version bumps as separate line items:

• VERSION file
• CLAUDE.md header (**Version:** vX.Y.Z)

Do not edit any files yet. The user needs to review first because some changes (especially breaking config changes) may not apply to our use case, or the user may want to handle them differently.

Step 4 — Wait for approval

Ask the user which items to apply. Accept "all", specific numbers, or exclusions like "all except #3".

Step 5 — Execute

Apply the approved changes. When changes are to independent files, edit them in parallel for speed. When changes depend on each other (e.g., a new config option that also needs a doc update referencing it), apply them sequentially to ensure consistency.

For config template edits (templates/openclaw.json.example):

• Preserve JSON5 formatting (comments, trailing commas).
• Add new options near related existing options, not at the end of the file.
• Include a brief comment explaining what the option does.

For command docs edits (docs/commands.md):

• New CLI commands/flags → add to the appropriate section with version annotation.
• New chat commands (e.g., /dreaming) → add explanation near the related CLI section.
• New built-in tools with config → include a config snippet reference.
• Removed commands → remove from docs or mark as removed with version.
• New advanced/system commands → add to the "高级命令" list at the bottom.

Step 6 — Validate

Run in parallel:

bash -n openclaw-orbstack-setup.sh

shellcheck openclaw-orbstack-setup.sh

Also validate any other shell scripts that were modified (e.g., files in scripts/).

If validation fails, fix the issue before proceeding. Don't ask the user to fix lint errors introduced by this sync.

If this sync touched doctor / non-interactive flow, also remind the user that post-upgrade verification means checking ~/.openclaw/.update-doctor.log for Setup cancelled lines. A clean log = doctor finished all passes. Any Setup cancelled = a new interactive prompt slipped past our checks.

Step 7 — Commit

Create a single commit:

chore: sync with upstream vX.Y.Z

If syncing across multiple versions, use the final target version in the message and mention the range in the body:

chore: sync with upstream vX.Y.Z

Covers changes from vA.B.C through vX.Y.Z.

Step 8 — Stop

Changes are committed locally. Do not push, tag, create a release, or upgrade the VM on your own. The remaining steps — push, tag, GitHub release, and VM upgrade — have no fixed order; the user decides the sequence each time (sometimes VM-first to validate, sometimes wrapper-release-first with the VM upgrade waiting on community feedback). Report the committed state and wait for explicit direction:

Changes committed locally. Push / release / VM upgrade are up to you — tell me what to do and in what order.

Source: aaajiao/openclaw-orbstack — distributed by TomeVault.