openclaw

OpenClaw — self-hosted personal AI assistant by peter-steinberger (github.com/openclaw/openclaw). Persistent daemon on the user’s own machine; provider-agnostic LLM (Claude / GPT / Kimi / local via Ollama); connects to 23+ messaging platforms (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, etc.). tw93 uses it as the case-study implementation in 2026-04-27-agent-principles-architecture-engineering — not his own project.

🦞 mascot. Naming history: Clawdbot (2025) → Moltbot (after trademark dispute with anthropic) → OpenClaw (Jan 2026).

Sources in this wiki

• 2026-04-27-agent-principles-architecture-engineering § Implementing Agents: A Look at OpenClaw — full architecture walkthrough used as the running example for the prior chapters’ design principles.

Five-layer architecture (per the source)

This is parallel to but not the same as Tw93’s Claude Code six-layer frame. The Claude Code frame is about a code-collaborator harness; OpenClaw’s frame is about a personal-assistant daemon — same engineering principles applied to a different product shape.

Workspace conventions

• Workspace root: ~/.openclaw/workspace.
• Layered system prompt files (resident, loaded bottom-up): SOUL.md (identity, hard constraints, “done” definition) → AGENTS.md → TOOLS.md → USER.md → MEMORY.md → Skills index.
• Sub-Agents get a stripped prompt — only Tooling, Workspace, Runtime — no Skills or Memory (multi-agent-orchestration).
• HEARTBEAT.md loaded on the heartbeat cadence (every 5 min) — used so the Agent can pick up cron-scheduled or background work without waiting for a user message.

Engineering decisions worth citing

• MessageBus between channels and Agent loop. Channels write inbound messages and read outbound; AgentLoop only consumes from the bus. dispatch is not awaited, so different sessionKeys process concurrently — but the same session must be serialized (queue or mutex) to avoid races on history writes and compaction.
• Memory hybrid retrieval. memory/YYYY-MM-DD.md for raw append-only logs, MEMORY.md for the Agent-curated fact set, memory_search over a 70/30 vector/keyword blend. Markdown-first means the human can read and edit it (agent-memory).
• Persistent task state. Long tasks write .openclaw/tasks/<taskId>.json after every step so a crash mid-task can resume without restarting from scratch (long-running-agents).
• Three-layer security. Allowlist (only authorized userIds can speak to the Agent at all) → workspace path check (path.relative rejects anything escaping the workspace; execFile not exec to block shell-injection) → audit log (.openclaw/audit.jsonl, append-only, every command captured before execution).
• Provider fallback. Iterate over [Anthropic, OpenAI, Anthropic Sonnet] — first that doesn’t throw wins. Saves manual switching when one vendor 503s.
• Implementation order asserted by the source: single channel first → security boundary before features → memory consolidation early → Skills before new tools → first failure becomes a test case.

Why it earns a page

OpenClaw is currently the wiki’s only fully-walked-through Agent implementation outside the claude-code / kaku axis. Several concept pages cite it as the worked example: see multi-agent-orchestration, long-running-agents, agent-memory, prompt-injection. If a second comparable case study lands, the implementation-detail bullets above can split into their own page.

Open questions

• The 70/30 vector/keyword blend is presented without ablation — is the ratio doing the work, or is “have keyword fallback at all” the load-bearing decision? See agent-memory.
• The “5 MCP servers ≈ 55K tokens of definitions” figure differs from the prior source’s 25K (model-context-protocol) — different counting, or just different MCP servers? Worth a real /mcp reading on a connected install.