Skip to main content
This lesson opens the engine compartment of OpenClaw and explains how it composes four foundational packages (originally developed by Mario Zechner). Each package owns a distinct layer of the stack and together they implement the agent runtime: from raw LLM calls up to channel delivery, tools, and policies. Overview of the four-layer stack:
  • PyLLM (pi-ai) — raw LLM calls and token streaming (foundation).
  • PyAgent (pi-agent-core) — shared types and runtime events.
  • PyAgentCoding (pi-coding-agent) — agent session engine, tool loop, and history.
  • OpenClaw — channels, tools, memory, security, and delivery (edges and orchestration).
Each package has a single responsibility; OpenClaw composes and extends them rather than duplicating functionality.
A stylized diagram titled "THE ENGINE" showing four stacked software layers—OpenClaw, pi-coding-agent, pi-agent-core, and pi-ai—each with short role descriptions (channels/tools, agent session engine, shared types, raw LLM calls). A footer notes "Each has a job · OpenClaw extends them."
Summary table — quick reference for each package and its role:

​
PyLLM (pi-ai) — LLM transport and streaming

PyLLM is the low-level provider integration layer. It performs the HTTP requests to model providers and returns tokens as they stream. OpenClaw uses PyLLM in three main scenarios:
  1. Agent loop — streamSimple is the streaming call used to send the conversation to the model and receive token deltas. OpenClaw wraps this call to inject temperature, caching, routing headers, and other runtime tuning.
  2. Voice synthesis — when converting a long assistant response to speech, OpenClaw summarizes the response using a non-streaming completion (e.g., completeSimple) before passing it to a TTS provider.
  3. Image analysis — when an agent needs to analyze images, OpenClaw calls PyLLM for non-streaming completions for image captioning or related tasks.
These integration points keep provider-specific concerns confined to PyLLM while allowing OpenClaw to control behavior through small wrappers.

​
PyAgent (pi-agent-core) — shared types and runtime events

PyAgent defines the common interfaces and events used across OpenClaw and the other packages. Two core concepts are:
  • AgentTool: the interface implemented by every tool exposed to the agent (SlackTool, WebSearchTool, BashTool, MemoryTool, etc.). Implementing AgentTool allows tools to be invoked uniformly by the agent loop.
  • AgentEvent: runtime events emitted during session execution, such as MessageStartEvent, MessageDeltaEvent, ToolExecutionStartEvent, and ToolExecutionEndEvent. OpenClaw subscribes to these events to stream partial responses and tool outputs back to channels and UIs in real time.
A stylized slide titled "pi-agent-core" showing two panels: "AgentTool" (every tool implements this interface) listing example tools like SlackTool, Web SearchTool, BashTool and MemoryTool. The right panel, "AgentEvent," lists runtime events such as message_start, message_update, tool_execution_start, and tool_execution_end.

​
PyAgentCoding (pi-coding-agent) — the agent session engine

PyAgentCoding is the heart of the runtime that OpenClaw relies on heavily. It provides a session object responsible for:
  • Holding conversation state and the message history.
  • Running the tool call loop (detecting and invoking tools).
  • Persisting history to disk.
  • Emitting the AgentEvents that other layers subscribe to.
The primary entry point is createAgentSession. OpenClaw constructs a session with a session file, a model specification, and the set of tools available to the agent. Calling session.prompt(text) runs the agent loop: it sends messages to the model, detects tool calls, executes tools, loops until the agent reaches a completion, and writes history. Example usage (JavaScript):
Callout: system prompt behavior
PyAgentCoding ships with a default system prompt, but OpenClaw completely replaces it. OpenClaw builds a dynamic system prompt from 19 sections that are assembled at runtime depending on the agent, the originating channel, and enabled skills. This allows fine-grained control over agent behavior per-channel and per-skill.
File tools and sandboxing OpenClaw uses PyAgentCoding’s file tools (read/edit/write) but wraps them with sandboxed path enforcement so the agent cannot access files outside its workspace.
File tool operations are sandboxed by OpenClaw. Do not disable path enforcement in production or you risk exposing host files to agent access.

​
PyUI — terminal UI primitives used by OpenClaw

PyUI provides the TUI primitives that OpenClaw’s tui command uses. PyUI supplies a basic chat UI (header, scrollable chat log, status area, and a custom editor). OpenClaw subclasses the editor to add key bindings and a combined autocomplete (slash commands + filesystem paths). Message rendering behavior:
  • Assistant messages: rendered with a Markdown component and updated live as tokens stream in.
  • Tool calls: rendered inside a bordered box showing structured tool output.
  • User messages: rendered as plain Markdown.
A neon, retro-styled mockup of a terminal TUI titled "pi-tui" showing a left-side layout (header, chat log, status area, custom editor) and right-side message-rendering panels labeled ASSISTANT, TOOL CALLS, and USER.

​
The complete request/response flow in OpenClaw

All messages funnel through the same end-to-end path. Below is the canonical flow OpenClaw implements when processing a user message:
  1. A user sends a message through a channel (Slack, Terminal, Web UI, etc.).
  2. The channel calls runEmbeddedPyAgent or the appropriate OpenClaw entrypoint.
  3. OpenClaw assembles the toolset: file tools (sandboxed), channel tools, and any custom tools — each implements AgentTool.
  4. SessionManager loads history from disk and calls createAgentSession.
  5. OpenClaw overrides the default system prompt with its dynamic, multi-section prompt.
  6. PyLLM’s streamSimple is wired in and wrapped with OpenClaw-specific headers, routing, and tuning.
  7. Event handlers subscribe to AgentEvent objects so UIs and channels receive streaming updates and partial outputs.
  8. The session runs: PyAgentCoding executes the tool loop, emits events, persists history, and streams the agent response.
  9. The response streams back through OpenClaw to the originating channel.
  10. The channel/UI renders the response appropriately (live Markdown updates, tool output formatting, attachments, etc.).
A dark-themed graphic titled "THE COMPLETE FLOW" showing a two-column, ten-step, color-coded flowchart of an agent processing pipeline. Each step lists actions like "User sends message", "createAgentSession()", and "Override system prompt", with component labels (OpenClaw, pi-coding-agent, pi-ai, pi-agent-core) and a legend at the bottom.
In short: OpenClaw owns the edges (channels, tools, delivery, policies), and composes the middle layers (LLM calls, the agent loop, and history) provided by the pi-* packages. This separation keeps provider integrations, runtime semantics, and edge behavior modular and extensible.

Watch Video

Practice Lab