openclaw-mini: a TypeScript teaching implementation of the OpenClaw agent core

What openclaw-mini is for, and what it refuses to be

Most agent tutorials stop at a while loop that calls a model, executes tools and appends results. The README describes that pattern and then says plainly: "这不是真正的 Agent 架构." The project's stated goal is to explain the design points of the OpenClaw kernel in a small, complete TypeScript codebase, so a reader can follow four threads at once: CLI, Agent Loop, Session, Context and Gateway. The README also says the code keeps comments about why a design was chosen, not just code that runs.

The non-goals matter more than the goals. The README states the project does not aim for 1:1 API compatibility with the main OpenClaw repository, does not cover every channel, provider, plugin or operational capability, and does not carry over all production guards, permissions and compatibility details. Treat it as a reading project with runnable pieces. If you want a drop-in OpenClaw replacement, this is the wrong repository, and the README says so itself.

The four-layer layout: core, extended, production, gateway

The repository is organised into four layers, and the README suggests reading them in the order core, extended, gateway, engineering. The core layer holds the Agent entry point (agent.ts), the agent loop (agent-loop.ts), a typed event stream (agent-events.ts), JSONL session persistence (session.ts), context loading, pruning and compaction (context/), a tool abstraction with ten built-in tools (tools/), and a provider adapter layer built on the pi-ai package.

The extended layer carries features the README calls specific to OpenClaw rather than universal: memory.ts for long-term memory with keyword retrieval and relevance ranking, skills.ts for SKILL.md frontmatter plus trigger-word matching, and heartbeat.ts for a two-layer wake mechanism. The engineering layer is where the production guards live: session-key.ts normalises multi-agent session keys as agent:id:session, tool-policy.ts applies allow/deny/none access levels, command-queue.ts serialises per-session work while allowing global parallelism, and session-tool-result-guard.ts, context-window-guard.ts and sandbox-paths.ts handle missing tool results, context overflow and path checks. The README tells learners they can skip this layer. I would not skip it, because those six files are the difference between a demo loop and something you would let near a real workspace.

How the agent loop actually runs: two nested loops over an event stream

The README frames the problem directly: a simple while loop cannot handle follow-ups, steering injection or context overflow. The answer in agent-loop.ts is an outer loop for follow-up turns and an inner loop for tool execution and steering injection, wrapped in an EventStream that the caller consumes with for-await. The stream is created first, an immediately invoked async function pushes typed events into it, and the function returns the stream before the work finishes. That ordering is what lets a subscriber print streaming text while tools are still running.

The event surface is a discriminated union of twenty MiniAgentEvent types, which the README maps to the AgentEvent type in the main project. Subscription follows the same shape as pi-agent-core: agent.subscribe returns an unsubscribe function, and the callback switches on event.type. The README's example handles message_delta for streamed text, tool_execution_start for tool name and arguments, and agent_error for runtime failures. If you have written a callback-based agent before, the difference here is that every intermediate step is an event you can observe rather than a return value you get at the end.

Sessions, pruning and compaction: where the context budget goes

Session persistence uses JSONL with a dual-write strategy. The README's excerpt of session.ts shows append pushing into an in-memory state first, so reads cost no I/O, and only writing to disk after the first assistant message arrives, to avoid creating files for empty sessions. That first write is a full rewrite containing the header and entries. The README does not document rollback or a recovery path for a partially written session file, so if you plan to build on this, that is a gap to check in the source yourself.

Context handling is split across three files with different jobs. loader.ts loads bootstrap files such as AGENTS.md on demand rather than all at once. pruning.ts applies three progressive cuts: tool results first, then assistant messages, then keeping the most recent turns. compaction.ts does adaptive chunked summarisation when pruning is not enough. The ordering is the interesting part. Tool results are the cheapest thing to drop because they are usually bulky and repeatable, and summarisation is the most expensive because it costs another model call. context-window-guard.ts sits above all of this as the overflow backstop. The README does not give token thresholds or the chunk size used by compaction, so those are numbers you would have to read out of the source.

Installing openclaw-mini and running your first session

The README's quick start assumes pnpm and a git clone over SSH. The npm package name is openclaw-mini, and package.json exposes a bin entry with the same name, so a global install is possible, but the documented path is a local clone with the dependencies installed.

git clone [email protected]:voocel/openclaw-mini.git
cd openclaw-mini
pnpm install
cp .env.example .env

Before anything runs, .env needs at least one working model key. The example file lists the provider switch (anthropic, openai, google, groq, xai, openrouter and others), the model name, an optional base URL for proxies or self-hosted endpoints, and the standard key variables such as ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY and GROQ_API_KEY. The agent id defaults to main. All the lines in .env.example are commented out, so you uncomment the ones you need.

pnpm test
pnpm dev

pnpm test runs the test suite through tsx and node's test runner, which is the smallest check that the toolchain and your environment agree. pnpm dev starts the CLI from source. Once inside, you can subscribe to events the way the README shows: create an Agent with an apiKey and a provider, call agent.subscribe with a callback that switches on event.type, then call agent.run with a session key and a prompt such as listing the files in the current directory. The unsubscribe function returned by subscribe is what you call when you are done.

pnpm example:gateway

That script runs examples/gateway-roundtrip.ts, which exercises the ACK-then-stream path over the WebSocket gateway. The README also documents pnpm build for a TypeScript compile, pnpm pack:check before publishing, and pnpm gateway plus pnpm gateway:connect for the serve and connect CLI modes. A Telegram channel script exists as pnpm channel:telegram, and the package depends on grammy for it, but the README does not document how to configure that channel beyond the script name.

The gateway: ACK-then-stream over WebSocket RPC

The gateway layer turns the CLI agent into a network service, and the README treats it as advanced reading. protocol.ts defines three frame types (req, res, event) plus error codes and constants, mapped to the schema and error-code files in the main project. server.ts handles HTTP and WebSocket, a challenge handshake, method routing, pub/sub broadcast, backpressure control and graceful shutdown. handlers.ts exposes six RPC methods: connect, chat.send, chat.history, sessions.* and health. client.ts keeps a pending map, reconnects with exponential backoff, monitors heartbeats on a tick, and detects sequence gaps.

The design detail worth noticing is the name of the example: gateway-roundtrip is described as an ACK-then-stream chain. The server acknowledges a request before the streamed events arrive, which is what lets a client distinguish an accepted request from a completed one. Sequence-gap detection on the client exists because events can be missed across a reconnect, and the pending map is what pairs a late response with its original request. The README does not state authentication beyond the challenge handshake, so exposing this gateway beyond localhost is something you would need to reason about from the source, not from the documentation.

Memory, skills and heartbeat: the OpenClaw-specific extras

Three files in the extended layer are what separate this from a generic agent skeleton. memory.ts implements long-term memory as keyword retrieval with relevance ranking, which the README maps to memory/manager.ts in the main project. It is retrieval, not embeddings, so recall depends on the words in the query matching the words in the stored entry. skills.ts reads SKILL.md frontmatter and matches trigger words to decide when a skill applies, mirroring agents/skills. heartbeat.ts is a two-layer design: one part merges wake requests, the other schedules a runner. The README's framing is that an agent with memory plus proactive wake-up behaves differently from a stateless function mapping.

Each of these is a minimal version of a larger subsystem, and the gaps are visible. Keyword retrieval will miss paraphrases that a vector index would catch. Trigger-word matching will fire on incidental mentions. The README does not describe how heartbeat intervals are configured or persisted. If your interest is in the mechanisms rather than the results, this is enough to read. If your interest is in retrieval quality, this is a starting point you would replace.

When openclaw-mini is the wrong tool, and what to compare it against

The clearest limitation is stated by the project itself: no 1:1 API compatibility with the main OpenClaw repository. Code written against openclaw-mini will not port unchanged, and the README does not promise a migration path. The provider layer sits on @mariozechner/pi-ai at version 0.50.7, so provider behaviour is that library's behaviour, not something this repository controls. The engineering layer covers session keys, tool policy, command queues, tool-result repair, context-window guarding and sandbox paths, but the README calls these production guards and says the project does not bring over all production protections. There is no documented rollback for session writes and no documented authentication for the gateway beyond the handshake.

As an alternative, consider the main OpenClaw repository itself. The README describes it as a system of over 430,000 lines, and this project exists to distil the core design out of it. The difference is direction: openclaw-mini is optimised for reading time and conceptual coverage, while OpenClaw is optimised for coverage of channels, providers, plugins and operations. If you need a working agent to ship, the larger repository is the one that claims production scope. If you need to understand why an agent loop is shaped the way it is before you touch either, reading a few hundred lines here first is the cheaper route.

Editorial conclusion

Adopt openclaw-mini if you want to read a working TypeScript agent loop with sessions, context pruning, memory and a gateway in one repository, and you are comfortable with pnpm and a model API key. Do not adopt it as a production runtime: the README states it does not cover all channels, providers, plugins or operational concerns, and it is not API-compatible with the main OpenClaw repository. Before committing, verify which provider and model your key matches in .env.example, run pnpm test to confirm the toolchain, and read the engineering layer files (session-key.ts, tool-policy.ts, command-queue.ts) to see which protections you would have to rebuild yourself.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. voocel/openclaw-mini on GitHub