A minimal, learning-oriented reimplementation of the OpenClaw core architecture, demonstrating system-level AI Agent design including dual-loop Agent Loop, EventStream, Session persistence, three-tier context management, and WebSocket RPC gateway.
openclaw-mini is a minimal, learning-oriented reimplementation of the OpenClaw core architecture, written in TypeScript (92.2%) and running on Node.js ≥ 20. Rather than serving as a production-grade Agent framework, its goal is to demonstrate the essential design principles of AI Agent systems with minimal code.
The project is organized in four layers: the Core Layer covers a dual-loop Agent Loop (outer follow-up + inner tool execution), 20 typed events via MiniAgentEvent discriminated union, JSONL Session persistence (in-memory cache + disk dual-write), three-tier progressive context management (Pruning → Compaction with adaptive chunked summarization → Bootstrap on-demand config loading), and 10 built-in extensible tools; the Extension Layer implements keyword-based long-term memory, SKILL.md frontmatter skill system, and multi-source triggered proactive heartbeat wake; the Engineering Layer includes Session Key, three-level Tool Policy, Context Window Guard and other production-grade protections; the Gateway Layer provides a full WebSocket RPC service with Challenge-Response handshake, timing-safe authentication, Pub/Sub broadcast with backpressure, ACK-then-stream message pattern, and 150ms Delta throttling.
Multi-model support is built on the @mariozechner/pi-ai adapter, supporting 22+ providers including Anthropic, OpenAI, Google, and Groq, with baseUrl configuration for any OpenAI-compatible API. The project also depends on grammy for Telegram Bot integration (feature completeness unconfirmed). The codebase distills 20 design patterns with "why designed this way" annotations, and the author recommends a reading path of Core → Extension → Gateway → Engineering.
Installation#
git clone git@github.com:voocel/openclaw-mini.git
cd openclaw-mini
pnpm install
cp .env.example .env
# Configure at least one model key, then
pnpm dev
Usage#
- CLI mode:
pnpm dev -- --provider openai --model gpt-4o - Gateway mode:
pnpm gateway -- --port 8080 --token mySecret - Programmatic API:
import { Agent } from "openclaw-mini"then useagent.subscribe()for events andagent.run()for tasks
Unconfirmed Information#
- The OpenClaw main repository URL is not explicitly linked in the README; whether the upstream project is publicly accessible is unconfirmed
- Whether
openclaw-minihas actually been published to the npm registry is unverified (publishConfig set to public in package.json, but no GitHub Releases) - GitHub Topics include
clawdbot, but the README does not explain its relationship with OpenClaw - The project explicitly states it is not intended for production use; the actual completeness of Engineering Layer modules requires further verification