大海
17 KiB
17 KiB
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:
- LLM model access — without an LLM, the protocol is a static document
- 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.mjsafter each OpenClaw upgrade - ✅ Monitor the 5 tool name refs during major upgrades
- ✅ Keep
version-contract.mdup to date with tested OpenClaw versions - ✅ Follow
upgrade-playbook.mdfor 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.