# COMPATIBILITY-STRATEGY.md — OpenClaw Compatibility & Upgrade Strategy > Generated: 2026-06-06 05:20 GMT+8 > Scope: AGENTS.md · GOVERNANCE.md · PORTFOLIO.md · Audit Scripts · Templates · OpenClaw Core Integration --- ## A. Compatibility Surface Map ### A1. Classification ``` Layer │ Path │ Type │ OpenClaw Dep ════════════════════════╪═══════════════════════════════════╪══════════════╪══════════════ │ │ │ Protocol Layer │ AGENTS.md │ Config │ TOOL NAME │ GOVERNANCE.md │ Config │ NONE │ PORTFOLIO.md │ Config │ NONE │ │ │ Configuration Layer │ MEMORY.md │ Config │ NONE │ HEARTBEAT.md │ Config │ NONE │ SOUL.md / IDENTITY.md / USER.md │ Config │ NONE │ │ │ Template Layer │ scripts/templates/* │ Config │ NONE │ │ │ Audit Engine │ scripts/audit-agents.mjs │ Script │ NONE │ scripts/audit-governance.mjs │ Script │ NONE │ scripts/audit-portfolio.mjs │ Script │ NONE │ scripts/audit-all.mjs │ Script │ NONE │ │ │ Runtime │ scripts/runtime.mjs │ Script │ src/agent-runtime/* │ scripts/guard-*.mjs │ Script │ NONE (tool name check only) │ │ │ Orchestration │ .openclaw/cron/jobs.json │ OpenClaw │ HIGH (cron format) │ scripts/dream-cycle.sh │ Script │ OpenClaw cron trigger │ │ │ Memory Integration │ memory_search / memory_get │ OpenClaw API │ HIGH (LLM tool) │ ctx_search / ctx_index │ OpenClaw API │ HIGH (LLM tool) ``` ### A2. Integration Points Detail | # | Integration | File | OpenClaw Dependency | Risk | |---|------------|------|---------------------|------| | IP1 | `ctx_search` tool reference | AGENTS.md §3b (Learning Context) | Tool name in protocol doc | LOW | | IP2 | `memory_search` tool reference | AGENTS.md §3b (Learning Context) | Tool name in protocol doc | LOW | | IP3 | `ctx_index` tool reference | AGENTS.md §Over-budget | Tool name in protocol doc | LOW | | IP4 | `cron` scheduling | .openclaw/cron/ (Dream Cycle) | OpenClaw cron format | MEDIUM | | IP5 | `memory_search` tool name check | scripts/guard-memory-backend.mjs | String in code | LOW | | IP6 | `memory_get` tool name check | scripts/guard-memory-backend.mjs | String in code | LOW | | IP7 | Runtime pipeline imports | scripts/runtime.mjs | src/agent-runtime/* | MEDIUM | | IP8 | Session context injection | (injected by OpenClaw at runtime) | Implicit | MEDIUM | | IP9 | `fs.readFileSync` (stdin) | scripts/runtime.mjs | Node.js built-in | NONE | | IP10 | Task execution cwd | audit-all.mjs runs in workspace | Agent workspace context | LOW | ### A3. Surface Map Summary ``` OpenClaw Core Custom Workspace ───────────── ─────────────── Tool Runtime ───── tool name ref ──────────► AGENTS.md (§3b, §budget) Cron Engine ───── cron config ─────────────► .openclaw/cron/jobs.json ───── cron trigger ─────────► scripts/dream-cycle.sh Memory API ───── memory_search ──────────► AGENTS.md (§3b) ───── memory_get ───────────► (used at runtime by agent) ───── ctx_search ───────────► AGENTS.md (§3b) ───── ctx_index ────────────► AGENTS.md (budget resolution) Session API ───── context injection ──────► (runtime prompt context) ───── tool listing ─────────► guard-*.mjs (string checks) Node.js fs ◄──── fs.readFileSync ────────► audit-*.mjs (pure Node.js) Node.js path◄──── path.resolve ───────────► audit-*.mjs (pure Node.js) BEST PRACTICE: audit scripts have ZERO OpenClaw dependency. Protocol files have MINIMAL (5 tool name refs total). ``` --- ## B. Upgrade Risk Matrix ### B1. Risk Classification | Risk Level | Criteria | Examples | |------------|----------|----------| | **LOW** | Only depends on public/stable interfaces | Tool names (`ctx_search`, `memory_search`), markdown config formats | | **MEDIUM** | Depends on configuration format or structural assumptions | Cron job format, session context structure, pipeline import paths | | **HIGH** | Modifies core runtime or depends on internal APIs | None found in current workspace | ### B2. Risk Matrix ``` ┌──────────────────────────────────────────────────────────────────┐ │ INTEGRATION │ RISK │ MIGRATION EFFORT │ BREAKAGE │ ├──────────────────────────────────────────────────────────────────┤ │ AGENTS.md tool refs │ LOW │ None (name stable)│ UNLIKELY │ │ GOVERNANCE.md │ NONE │ N/A │ NONE │ │ PORTFOLIO.md │ NONE │ N/A │ NONE │ │ audit-*.mjs │ NONE │ N/A │ NONE │ │ Templates (7 files) │ NONE │ N/A │ NONE │ │ │ │ │ │ │ cron/jobs.json │ MEDIUM│ Re-export + │ POSSIBLE │ │ │ │ re-register │ (format │ │ │ │ │ change) │ │ dream-cycle.sh │ MEDIUM│ Update cron │ POSSIBLE │ │ │ │ registration │ │ │ │ │ │ │ │ runtime.mjs (src/*) │ MEDIUM│ Port to new │ POSSIBLE │ │ │ │ runtime API │ │ │ │ │ │ │ │ guard-memory-backend.mjs │ LOW │ Update string │ UNLIKELY │ │ │ │ comparison │ │ │ │ │ │ │ │ TASK EXECUTION │ LOW │ Standard exec │ UNLIKELY │ │ (fs/path/child_process) │ │ │ │ └──────────────────────────────────────────────────────────────────┘ ``` ### B3. Upgrade Scenario Impact | Upgrade Type | Impact | Auto-Migration | User Action | |-------------|--------|---------------|-------------| | OpenClaw patch (x.y.Z) | MINIMAL | ✓ | Run upgrade-test, expect 0 FAIL | | OpenClaw minor (x.Y.0) | LOW | Partial | Re-register cron jobs, verify tool names | | OpenClaw major (X.0.0) | MEDIUM | Guided | Run upgrade-playbook, possibly update compatibility layer | | OpenClaw deprecation | HIGH | None | Self-hosting mode (see §G) | --- ## C. Compatibility Architecture ### C1. Layer Structure ``` ┌─────────────────────────────────────────────────────────────┐ │ CUSTOM PROTOCOL LAYER │ │ AGENTS.md · GOVERNANCE.md · PORTFOLIO.md │ │ (Protocol definitions — no OpenClaw direct refs) │ └───────────────────────────┬─────────────────────────────────┘ │ references abstract interfaces ▼ ┌─────────────────────────────────────────────────────────────┐ │ COMPATIBILITY LAYER (abstract) │ │ │ │ Interface │ OpenClaw Binding │ │ ─────────────────────────┼────────────────────────────────── │ │ knowledge_base_search() │ ctx_search() │ │ memory_query() │ memory_search() / memory_get() │ │ knowledge_index() │ ctx_index() │ │ schedule_job() │ cron() │ │ agent_plan() │ sessions_spawn() │ │ tool_exec() │ exec() │ │ file_read() │ read() │ │ web_fetch_raw() │ web_fetch() │ │ │ │ ALL abstract → concrete mapping in ONE place. │ └───────────────────────────┬─────────────────────────────────┘ │ calls through ▼ ┌─────────────────────────────────────────────────────────────┐ │ OPENCLAW CORE │ │ Tool Runtime · Cron Engine · Memory API · Session API │ └─────────────────────────────────────────────────────────────┘ ``` ### C2. Key Design Decision **DO NOT create a physical compatibility layer file.** Why: - Current integration surface is MINIMAL (5 tool name refs in one file) - Adding a physical layer adds ~2KB of code and maintenance - The tool names (`ctx_search`, `memory_search`) are STABLE — OpenClaw has not renamed them - A 5-entry mapping is trivially updateable inline **IF a rename happens, the change is:** ``` AGENTS.md: s/ctx_search/knowledge_search/g (2 occurrences) AGENTS.md: s/memory_search/memory_query/g (2 occurrences) AGENTS.md: s/ctx_index/knowledge_index/g (1 occurrence) guard-memory-backend.mjs: update string comparison (1 occurrence) ``` That's 5 lines changed across 2 files. **A physical compatibility layer would be over-engineering at this scale.** ### C3. Watch Points Monitor these OpenClaw interfaces for breaking changes: | Interface | Stability | Check Frequency | |-----------|-----------|-----------------| | Tool names (ctx_search, memory_search, etc.) | Stable | Per major upgrade | | Cron job format | Stable | Per major upgrade | | Session context structure | Internal | Not relied upon | | `src/agent-runtime/` (custom) | Custom code | Per local change | --- ## D. Version Contract See `version-contract.md` for the full contract. ### D1. Summary | Field | Value | |-------|-------| | Supported OpenClaw | v0.9.x, v0.10.x | | Required Interfaces | Tool names, cron format, exec, file I/O | | Forbidden Interfaces | None currently used | --- ## E. Upgrade Test Suite See `scripts/upgrade-test.mjs`. ### E1. Test Coverage | Test | What It Checks | |------|----------------| | AGENTS compatibility | All sections present, no syntax errors | | GOVERNANCE compatibility | All sections present, state machine valid | | PORTFOLIO compatibility | All sections present, project states valid | | Audit compatibility | All 4 audit scripts run without crash | | Template compatibility | All 7 templates are valid markdown | | Cross-ref integrity | No broken references between docs | --- ## F. Migration Strategy See `upgrade-playbook.md` for the full playbook. ### F1. Strategy Summary | Upgrade | Pre-check | Migration | Verification | Rollback | |---------|-----------|-----------|-------------|----------| | Minor | Run upgrade-test | Update cron, verify tools | Re-run audit-all | Revert cron config | | Major | Read changelog | Update compatibility mappings | Full audit + manual review | git revert | | Patch | Run upgrade-test | No action | Re-run audit-all | N/A | --- ## G. Self-Hosting Readiness ### G1. Assessment Scored across 5 dimensions, 0–20 points each. | Dimension | Score | Rationale | |-----------|-------|-----------| | **Protocol Files** | 20/20 | Pure markdown. Zero runtime dependency. | | **Audit Scripts** | 20/20 | Pure Node.js fs/path. Zero OpenClaw dependency. | | **Templates** | 20/20 | Pure markdown templates. | | **Runtime** | 10/20 | `runtime.mjs` depends on `src/agent-runtime/*` (custom code, but needs an engine) | | **Orchestration** | 10/20 | Dream Cycle depends on OpenClaw cron. Can be replaced with system cron. | | **Total** | **80/100** | | ### G2. Self-Hosting Mode Architecture ``` Without OpenClaw Core: Protocol Files ──► Manual reading (no automation loss) Audit Scripts ──► node scripts/audit-all.mjs (STILL WORKS) Templates ──► Manual filling (no automation loss) Runtime ──► Would need: express or CLI wrapper for src/agent-runtime/* Orchestration ──► systemd/crontab instead of OpenClaw cron Memory ──► JSON files + grep instead of memory_search (reduced capability) ``` ### G3. Critical Path The ONLY non-replaceable dependency is: 1. **LLM model access** — without an LLM, the protocol is a static document 2. **Tool execution** — without OpenClaw tools, the agent can't execute tool calls Everything else can be replaced with standard POSIX tools + Node.js. ### G4. Self-Hosting Readiness Score: **80/100** Top 20% gap is LLM-dependent features (memory_search, ctx_search at runtime). Protocol layer (documents + scripts) is fully portable. --- ## H. Final Recommendation ### H1. Current Status ``` Compatibility: ✅ PASS — 0 conflicts, 0 internal API deps Self-Hosting: ✅ 80/100 — All documents + scripts portable Upgrade Risk: ✅ LOW — 5 tool name refs in 2 files Audit Safety: ✅ PASS — 0 OpenClaw deps in audit scripts Maintenance: ✅ LOW — Patch upgrades require 0 changes ``` ### H2. Do NOT - ❌ Do NOT create a physical compatibility layer (over-engineering for 5 refs) - ❌ Do NOT abstract tool names in protocol files (increases complexity, reduces clarity) - ❌ Do NOT modify protocol files to "future-proof" — the current codebase is already future-proof ### H3. Do - ✅ Run `scripts/upgrade-test.mjs` after each OpenClaw upgrade - ✅ Monitor the 5 tool name refs during major upgrades - ✅ Keep `version-contract.md` up to date with tested OpenClaw versions - ✅ Follow `upgrade-playbook.md` for major upgrades ### H4. OpenClaw Upgrade Cost Estimate ``` Patch upgrade (v0.9.1 → v0.9.2): 0 min, no changes needed Minor upgrade (v0.9 → v0.10): 5 min, re-register cron, verify tool names Major upgrade (v1.0): 15 min, run upgrade-test, update 5 refs if renamed OpenClaw deprecation: 2h, configure alternate LLM + crontab ``` ### H5. Summary The three-layer protocol architecture (AGENTS + GOVERNANCE + PORTFOLIO) is **designed for portability** — it's pure markdown with zero framework lock-in. The audit scripts are **pure Node.js** with zero OpenClaw dependency. The only integration points are **5 tool name references** in AGENTS.md, which are trivially updateable. **No action required for current version.** **Upgrade cost: near-zero.** **Self-hosting readiness: excellent.**