Skip to content

OpenClaw Agent Architecture

Overview

OpenClaw is a personal AI agent framework that connects LLMs to messaging channels (Telegram, Discord, Slack, etc.) with persistent memory, tool use, and multi-agent orchestration.

Core Components

  • Gateway: WebSocket-based daemon that routes messages between channels and agent sessions. LaunchAgent-managed for auto-restart.
  • Agent Sessions: Each conversation gets a session with its own context window, tool access, and memory state.
  • Lossless Context Management (LCM): Compacts conversation history into a DAG of summaries without losing information. Enables long-running sessions without context overflow.
  • Skills: Modular capability definitions (SKILL.md files) that agents load on-demand based on task matching.
  • Heartbeat: Scheduled cron-driven polling that runs system health checks, git autocommits, and playground tasks.

Memory Architecture

Three tiers (see also Karpathy LLM Wiki Pattern):

  1. Daily logs (memory/YYYY-MM-DD.md): Append-only operational events. What happened.
  2. Curated memory (MEMORY.md): Long-term operational facts. Infrastructure state, account details, decisions.
  3. LLM Wiki (projects/llm-wiki/wiki/): Synthesized domain knowledge. What we know.

Plus LCM's compressed conversation DAG for within-session recall.

Multi-Agent Setup

  • Alpha (OpenClaw): Primary agent. Claude Opus / Codex models. Full tool access.
  • Alpha Hermes: Secondary agent via Hermes framework. Codex primary. Shares the LLM Wiki.
  • Sub-agents: Spawned for specific tasks (blog writing, code review, research). Can use different models.
  • ACP (Agent Communication Protocol): For delegating to coding agents (Claude Code, Codex CLI) in persistent sessions.

Workspace Structure

~/.openclaw/workspace/
├── SOUL.md          # Identity and personality
├── USER.md          # Human context
├── MEMORY.md        # Curated long-term memory
├── AGENTS.md        # Operating manual
├── HEARTBEAT.md     # Scheduled task config
├── TOOLS.md         # Environment-specific notes
├── memory/          # Daily operational logs
├── projects/        # Project directories (each its own git repo)
├── tasks/           # Task tracking markdown
├── scripts/         # Automation scripts
├── instructions/    # Detailed policy modules (loaded on-demand)
└── docs/            # Documentation, playbooks, articles

Key Design Principles

  • Pointer-first navigation: Load the smallest specific file needed, not broad bundles.
  • Deterministic startup: Same files read in same order every session.
  • Low-trust execution: Least privilege by default, propose/review for high-risk actions.
  • Skills as workflows: Skills define how to accomplish tasks; TOOLS.md stores environment specifics.