89088414/16gagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
16gagent/COMPATIBILITY-STRATEGY.md
T
大海 a188ee1426 🎉 init: 小龙的工作空间
2026-06-06 10:40:48 +08:00

17 KiB
Raw Permalink Blame History

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.

Reference in New Issue View Git Blame Copy Permalink