大海
336 lines
17 KiB
Markdown
336 lines
17 KiB
Markdown
# 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.**
|