大海
6.2 KiB
6.2 KiB
Upgrade Playbook
Migration strategy for upgrading OpenClaw core while maintaining protocol compatibility. Part of COMPATIBILITY-STRATEGY.md §F.
§1 Pre-Upgrade Checklist
Before any upgrade:
- [ ] Run `node scripts/upgrade-test.mjs` — record baseline PASS count
- [ ] Run `node scripts/audit-all.mjs` — record baseline WARN/FAIL counts
- [ ] Commit all outstanding changes (`git status` should be clean)
- [ ] Read OpenClaw changelog for the target version
- [ ] Check version-contract.md §3 Required Interfaces for changes
§2 Patch Upgrade (v0.9.1 → v0.9.2)
Definition: Bugfix release. No breaking changes.
Procedure
1. Upgrade OpenClaw ← per OpenClaw install instructions
2. Run upgrade-test ← node scripts/upgrade-test.mjs
3. Run full audit ← node scripts/audit-all.mjs
4. Verify ← all PASS, no regressions
Expected changes: 0 files modified.
Rollback: openclaw restart with previous version.
§3 Minor Upgrade (v0.9.x → v0.10.x)
Definition: Feature release. Possible tool name additions, config format changes.
Procedure
PRE-CHECK
├─ Read OpenClaw changelog for:
│ ├─ Tool name changes
│ ├─ Cron format changes
│ └─ Config format changes
├─ Run baseline tests (upgrade-test + audit-all)
└─ git stash or commit
MIGRATION
├─ [IF tool names changed] Update AGENTS.md §3b, §6, §CPB
│ ├─ s/old_name/new_name/ in ctx_search references
│ └─ s/old_name/new_name/ in memory_search references
├─ [IF cron format changed] Re-register Dream Cycle job:
│ cron(action="remove", ...) → cron(action="add", ...)
├─ [IF config format changed] Update `.openclaw/` config files
└─ git commit -m "chore: adapt to OpenClaw v0.10.x"
VERIFICATION
├─ node scripts/upgrade-test.mjs ← all PASS
├─ node scripts/audit-all.mjs ← baseline match
└─ Manual: verify Dream Cycle runs at next scheduled time
ROLLBACK
├─ git revert the migration commit
├─ Re-register old cron job format
└─ openclaw restart
Common Minor Upgrade Actions
| Change | Affects | Action |
|---|---|---|
| Tool API signature change | AGENTS.md §3b | Update search parameter format |
| New tool addition | — | Optional: add to protocol if relevant |
| Cron syntax change | .openclaw/cron/ | Re-register all jobs |
| Memory format change | None (protocol uses abstract) | No action |
§4 Major Upgrade (v0.x → v1.0)
Definition: Breaking change release. Requires full compatibility review.
Procedure
PRE-CHECK
├─ Same as minor upgrade, PLUS:
├─ Read full migration guide from OpenClaw
├─ Review COMPATIBILITY-STRATEGY.md §A (Surface Map)
├─ Review version-contract.md §3 (Required Interfaces)
├─ Review version-contract.md §4 (Forbidden Interfaces)
└─ Create recovery branch: git checkout -b upgrade/v1.0-prep
MIGRATION
├─ Phase 1: Update tool references
│ ├─ Update all tool name references in AGENTS.md
│ ├─ Update guard-memory-backend.mjs string comparisons
│ └─ Run: node scripts/upgrade-test.mjs
│
├─ Phase 2: Update cron integration
│ ├─ List current cron jobs: cron(action="list")
│ ├─ Remove all: cron(action="remove", ...)
│ ├─ Re-register with new format
│ └─ Verify: cron(action="list")
│
├─ Phase 3: Update runtime if needed
│ ├─ Check if runtime.mjs still compiles
│ ├─ Check src/agent-runtime/* imports
│ └─ Update import paths if needed
│
├─ Phase 4: Run full verification
│ ├─ node scripts/upgrade-test.mjs ← must PASS all
│ ├─ node scripts/audit-all.mjs ← 0 FAIL, baseline WARN
│ └─ Manual walkthrough of one complex task
│
└─ git commit -m "chore: migrate to OpenClaw v1.0"
VERIFICATION
├─ Same as minor, PLUS:
├─ Verify all 3 protocol layers are self-consistent
├─ Verify audit-report.md generates correctly
└─ Mark tested version in version-contract.md §1
ROLLBACK
├─ git checkout main (pre-upgrade branch)
├─ Restore .openclaw/cron/ from git backup
├─ openclaw restart
└─ Note: Any data created during v1.0 may be incompatible
Major Upgrade Risk Areas
| Area | Breakage Likelihood | Recovery Difficulty |
|---|---|---|
| Tool names | MEDIUM (known to be stable) | LOW (5 refs to update) |
| Cron format | LOW | LOW (re-register) |
| Session context | LOW (not relied upon) | NONE |
| runtime.mjs imports | MEDIUM | MEDIUM (port to new API) |
| LLM behavior changes | MEDIUM (prompt sensitivity) | LOW (adjust prompts) |
§5 OpenClaw Deprecation / Self-Host Mode
Definition: OpenClaw core is no longer available or maintained.
Procedure
PRE-CHECK
├─ Read SELF-HOSTING READINESS in COMPATIBILITY-STRATEGY.md §G
├─ Score is 80/100 — protocol layer is portable
└─ Identify which features to maintain vs drop
MIGRATION OPTIONS
├─ Option A: Replace with basic CLI
│ ├─ Audit scripts run via: node scripts/audit-all.mjs (STILL WORKS)
│ ├─ Protocol docs are static markdown (readable anywhere)
│ └─ Lost: memory_search, ctx_search, cron-Triggered Dream Cycle
│
├─ Option B: Replace with custom agent runtime
│ ├─ Build minimal tool executor (5-10 tools)
│ ├─ Use system cron or launchd for Dream Cycle
│ ├─ Use grep/ripgrep + sqlite for memory search (reduced capability)
│ └─ Keep: all protocol docs, audit scripts, templates
│
└─ Option C: Hybrid
├─ Keep protocol docs and audit scripts
├─ Replace only cron + memory with POSIX equivalents
└─ Import protocol docs into new toolchain
SELF-HOSTED VERIFICATION
├─ node scripts/upgrade-test.mjs ← all PASS (no OpenClaw dep!)
├─ node scripts/audit-all.mjs ← all PASS
└─ Manual: verify cron/launchd triggers Dream Cycle
§6 Upgrade History Log
| Date | From | To | Type | Changed Files | Duration | Issues |
|---|---|---|---|---|---|---|
| — | — | — | — | — | — | — |
(Populate on each upgrade)