OpenClaw — Boole Learn Propositional Map¶

A propositional analysis of OpenClaw's architecture using the Boole Learn framework. OpenClaw reduces to three ontological layers and seven foundational propositions.

The Three-Layer Architecture¶

Routing Layer (P1, P7) — messages → deterministic session keys; channels are interchangeable plugins
State & Authority Layer (P2, P3) — Gateway owns all mutable state; transcripts are append-only trees
Execution & Extension Layer (P4, P5, P6) — agents are stateless RPC clients; plugins hook lifecycle boundaries; compaction is automatic

Unifying principle: Centralized authority (Gateway) + append-only persistence (transcripts) + interruptible execution (agents as RPC clients). This enables stateless channels, auditable plugins, and safe concurrency without distributed consensus.

Foundational Propositions¶

P1: Message-Session Binding is Deterministic — Rock Solid¶

Every inbound message maps to exactly one session key through deterministic routing rules based on channel identity, sender, and group context. Once assigned, this binding is the source of truth for conversation continuity.

Without deterministic routing, the identity model collapses — responses become non-deterministic, sessions fork unpredictably, and security isolation between users fails.

P2: Gateway is the Single Source of Truth for Session State — Contested¶

All session state is owned and persisted by the Gateway process. Clients are read/query only; the Gateway makes all mutations.

Without centralized state, concurrent clients would race and corrupt data. But the implementation has a concurrent-write vulnerability — plugins can mutate sessions.json directly on disk, and in-memory cache invalidation is a known gap.

P3: Transcripts are Append-Only Trees — Rock Solid¶

Conversation transcripts are persisted as append-only JSONL files with tree structure (entries have parentId). Transcripts are never mutated in place.

Append-only prevents corruption from concurrent writes. Tree structure enables threads, sub-sessions, compaction summaries as new entries, and safe navigation of branching conversations. Breaks under concurrent-agent writes to the same transcript (rare by design).

P4: Agents are RPC Clients to a Managed Runtime — Rock Solid¶

Agents invoke tools via RPC; the runtime owns the execution loop, enforces permissions/sandboxing, controls loop termination, compaction, sub-agent spawning, and retries. Agents propose work; the runtime decides what happens.

Without this separation, tool execution would be a free-for-all. The runtime mediates everything: exec approvals, permissions, recursion limits, timeout policies. This enables the hook system, sandboxing, and policy enforcement.

P5: Plugins are Hook-Based Interceptors at Lifecycle Boundaries — Provisional¶

Plugins inject behavior by registering handlers for named lifecycle hooks. Each hook receives event data, can mutate or veto it, and passes control to the next handler.

Sound conceptually but error handling is inconsistent across hooks — some fail-open, some fail-closed. Hook dispatch is linear (first-plugin-to-veto wins), which creates ordering dependencies.

P6: Compaction is Driven by Context Window Pressure — Rock Solid¶

Conversation context is automatically compacted when token count approaches the model's context window minus a reserve. Compaction is reactive, not periodic.

Emergency compaction as fallback (triggered on request_too_large error) makes this reliable even when token counting is inaccurate. Boundary: if a single message + system prompt exceeds the context window, there's no fallback.

P7: Channels are Plugin Interfaces — Rock Solid¶

Messaging channels are plugin packages with a standard interface. The Gateway doesn't hardcode channel logic; it loads and orchestrates plugin instances.

One channel crashing doesn't block others. Plugins can't directly mutate sessions. 20+ channels exist without special-casing in the Gateway. Boundary: not designed for multiple instances of the same channel (e.g., two Telegram bots need two OpenClaw instances).

Logical Structure¶

[P1] Message-Session Binding (deterministic routing)
 ├─→ [P2] Gateway as Source of Truth
 │    ├─→ [P4] Agents as RPC Clients
 │    │    ├─→ [P6] Compaction by Context Pressure
 │    │    └─↔ [P5] Plugins as Hooks (mutual)
 │    └─→ [P5] Plugins as Hooks
 ├─→ [P3] Transcripts as Trees
 │    ├─→ [P6] Compaction by Context Pressure
 │    └─↔ [P5] Plugins as Hooks (mutual)
 └─→ [P7] Channels as Plugins

Upstream: P1 (routing) → P2 (authority) → P4 (execution) Downstream: P5 (extension), P6 (memory management) Lateral: P3 ↔ P5 (hooks mutate transcripts; transcripts persist hook state)

Key Tensions¶

Consistency vs Availability — P2 (Gateway authority) requires serializing writes, reducing availability if Gateway is slow. Should there be local-first mode with sync?
Plugin Ordering — P5 (linear hook dispatch) means first-to-veto wins. What if Plugin A wants to veto unless Plugin B approves? Should hooks support conditional chaining?
Token Counting Accuracy — P6 (compaction by pressure) assumes accurate counts. Provider token counts diverge. Unified counter or accept variance?
Session Pruning vs Compaction — P3 (append-only) and P6 preserve history, but pruning removes entries. How to safely prune without losing compaction summaries?
Plugin Trust Model — P5 and P7 assume plugins don't corrupt state. Should plugins run in a sandbox?

Falsification Summary¶

Proposition	Rating	Strongest Challenge
P1: Deterministic routing	Rock solid	Username changes create session forks (by design)
P2: Gateway authority	Contested	Direct filesystem mutations bypass Gateway
P3: Append-only trees	Rock solid	Concurrent writers can interleave (rare by design)
P4: Agents as RPC	Rock solid	Well-enforced at runtime boundary
P5: Plugins as hooks	Provisional	Inconsistent error handling across hook types
P6: Compaction by pressure	Rock solid	Emergency compaction as reliable fallback
P7: Channels as plugins	Rock solid	Clean isolation; boundaries understood

Where the Framework Breaks Down¶

Distributed deployment — no HA support; single Gateway per host assumption
Concurrent plugin execution — if hooks ever parallelize, ordering guarantees vanish
Tool schema mismatch — plugin registers tool but doesn't update agent's schema → silent failure
Transcript concurrent writes — not prevented by data model, just rare by convention
User-defined session keys — if routing becomes user-configurable, determinism requires validation

What to Study Next¶

Hook dispatch and error handling — how errors propagate across hooks
Token counter implementations — per-provider divergence
Subagent lifecycle — spawnDepth limits, permission escalation
Channel binding model — unified identity across Telegram/Discord/etc
Compaction chunk boundaries — where transcripts split during summarization
Memory flush mechanism — how NO_REPLY turns inject pre-compaction

Provenance¶

Framework: Boole Learn (Boole's epistemology + Popper's falsification + Ausubel's advance organizers) Codebase: ~/dev/openclaw (checked out at v2026.4.11) Generated: 2026-04-13 by CC Sam