Skip to main content
What this unit solvesOpenClaw assembles an agent’s persona, memory, heartbeat, and tool conventions from a set of Markdown files stored in the workspace, so the agent “reads its own soul” before starting work each session. This unit starts from the actual files in the repository and dissects OpenClaw’s origins and positioning, its Gateway execution loop, heartbeat scheduling, memory system, and the exact responsibilities of each custom md file. Details that cannot be confirmed directly from the repository defer to official documentation. By the end of this unit you can summarize OpenClaw’s architecture and judge whether its design philosophy suits your own harness work.

​
Learning objectives

  • Explain OpenClaw’s lineage (Warelay, Clawdbot, Moltbot, OpenClaw) and the problem it solves: letting an agent take real action inside the communication channels the user already uses
  • Describe the role of the Gateway control plane and how the heartbeat schedule triggers periodic agent turns
  • State the responsibility and load timing of each standard workspace md file (AGENTS.md, BOOTSTRAP.md, HEARTBEAT.md, IDENTITY.md, MEMORY.md, SOUL.md, TOOLS.md, USER.md)
  • Summarize the system in one everyday analogy
  • Evaluate whether OpenClaw’s “harness-as-visible-files” design could apply to your own agent configuration

​
1. Origins and positioning

OpenClaw did not appear out of nowhere. It has a traceable evolution, and the name itself tells the story: This naming axis records a rapid rebranding rather than a long evolution: author Peter Steinberger first published under the name Warelay (2025-11), became widely known as Clawdbot, renamed to Moltbot on 2026-01-27 after an Anthropic trademark complaint, and three days later (2026-01-30) settled on OpenClaw and open-sourced it on GitHub (VISION.md as of 2026-05). The problem it solves is straightforward: most AI assistants require the user to “switch to a new interface,” whereas OpenClaw inverts that, executing real tasks directly inside the communication channels the user already uses (WhatsApp, Telegram, Slack, Discord, and 20+ others). It is not another chat UI; it is a personal assistant daemon woven into the user’s existing conversation flow. Its positioning is “local-first personal agent harness”: written in TypeScript because “widely known, fast to iterate, easy to read and modify” — a consensus across engineering communities (VISION.md). In the taxonomy of agent shells it belongs to the “single-machine self-hosted, multi-channel routing, plugin-extensible” type: the core stays lean while optional capabilities are delivered as plugins, avoiding core bloat.
The engineering implication of “local-first”Runs on your machine by default, accesses your local resources by default, uses the tools you already have by default. The cost: no enterprise SLA, no shared team infrastructure, no unified audit trail. If you need those, see 05-3 NemoClaw for the hardened shell pattern; OpenClaw itself does not address that problem.

​
2. Core technology: Gateway control plane and execution loop

The heart of the OpenClaw system is a Gateway control plane running persistently on the local machine. It is not the agent itself — it is “the bus that manages all agents, sessions, channels, tools, and events.” Abstracting this layer away from agent logic is the most consequential design decision in OpenClaw: the integration layer can change without forcing rewrites of the agent logic. The Gateway’s core responsibilities divide into four areas:
  1. Multi-channel routing: messages arriving from any inbound channel are routed to isolated agent instances, each with its own workspace and session, with no context bleed between them
  2. Multi-agent isolation: each agent is an independent “person” with its own workspace, session, and memory; contexts are never shared
  3. Tool and permission management: which agent can call which tool, who authorized it, and whether it runs in a sandbox are all decided at this layer
  4. Event bus: all events (user messages, heartbeat ticks, cron triggers, tool returns) enter the same bus, and agents use it to know “what to do right now”
On top of this, OpenClaw provides a heartbeat mechanism that lets an agent be woken periodically even when there are no user messages. The default interval is 30 minutes; when using Anthropic OAuth/token authentication the default is 1 hour (heartbeat docs as of 2026-05). The default prompt for a heartbeat turn is:
This prompt is itself a design statement: the heartbeat is not “let the agent invent tasks on its own” — it is “read the explicit task list in HEARTBEAT.md and reply HEARTBEAT_OK if there is nothing to do.” When HEARTBEAT.md is empty, OpenClaw skips the model call entirely, without issuing a single LLM inference (heartbeat docs).
Heartbeat vs cron: how they divide responsibilitiesThe heartbeat is a periodic turn within the main session and does not create background task records. Cron is the mechanism for creating independent background task records (ACP runs, subagents). Confusing the two leads to disappointment when you expect the heartbeat to run long tasks: the heartbeat’s nature is a periodic wake within a session, and long tasks belong to independent subagents dispatched by cron.

​
3. System structure: how the components fit together

OpenClaw places the agent’s “living space” by default at ~/.openclaw/workspace, which is the relative root for the file tool. This can be overridden in openclaw.json.
~/.openclaw/
openclaw.json · workspace settings (paths, model, sandbox options)
workspace/ · agent working directory
AGENTS.md · operational instructions and memory usage rules
SOUL.md · persona, tone, boundaries
IDENTITY.md · name, creature type, vibe, emoji, avatar
USER.md · data about the user
TOOLS.md · local tool convention notes
HEARTBEAT.md · heartbeat task list
MEMORY.md · long-term memory distillation layer
BOOTSTRAP.md · one-time first-run ritual (deleted when complete)
logs/ · Gateway and per-agent logs
A few key design points to clarify upfront:
  • The workspace is not a sandbox. The workspace is only the agent’s working directory. Without agents.defaults.sandbox enabled, the agent can still reach the host filesystem via absolute paths. Think of it as the agent’s “home,” not the agent’s “cage.”
  • Bootstrap is a ritual. A fresh workspace is seeded by the Gateway with standard md files and a BOOTSTRAP.md; on first start the agent uses a question-and-answer exchange with the user to collaboratively fill in IDENTITY.md and SOUL.md, then deletes BOOTSTRAP.md (bootstrapping docs). This “decide together who you are” ritual is not decoration; it is core to OpenClaw’s design philosophy: agent identity is negotiated jointly by the user and the agent, not hard-coded.
  • Plugins load from the skills/ directory. Skills are stored as ~/.openclaw/workspace/skills/<skill>/SKILL.md; the central marketplace is ClawHub (clawhub.ai — as of 2026-05 per the README; check the official page for current marketplace status and availability).
  • The security model is permissive by default. The main session represents you personally and has full host access by default. Non-main sessions (groups, incoming channels) can be set to Docker / SSH / OpenShell sandboxes in openclaw.json to restrict the tool set.
Full host access in the main session is a design choice, not a bugOpenClaw trusts “instructions you give in person through the main session” by default. That assumption holds in your own workflow; it does not hold when “someone else in a shared group calls your agent through a channel.” In that scenario, set the corresponding session to sandbox mode in openclaw.json, otherwise a successful prompt injection gives the agent full host permissions to execute arbitrary commands.

​
4. Custom md files, one by one

None of the workspace md files are decorative. Each has a defined responsibility and load timing. The responsibilities below come from the repository’s docs/concepts/agent-workspace.md and docs/reference/templates/ (as of 2026-05): Common points of confusion:
  • SOUL.md vs USER.md: the former is “who I am and how I speak”; the latter is “who you are and what you like.” The former belongs to the agent; the latter belongs to you.
  • AGENTS.md vs SOUL.md: AGENTS.md is operational policy (“do A before B; call tool Y when you encounter X”), while SOUL.md is the persona layer (“direct tone, conclusion first, no emoji”). One governs “what to do”; the other governs “what kind of person to be.”
  • MEMORY.md vs memory/YYYY-MM-DD.md: MEMORY.md holds distilled long-term facts (“the user lives in Taichung, researches precision livestock AI”). The daily logs hold that day’s detailed records. MEMORY.md is automatically truncated when it exceeds the bootstrap budget; the log files are preserved in full.
  • TOOLS.md vs skills/: TOOLS.md holds environment-specific notes (“my camera is named front_door, SSH alias is lab”). skills/ holds shareable, reusable procedures. Keeping these two layers separate means upgrading a skill or switching machines does not leak your personal infrastructure.
Walking through a workspace bootstrapOn a fresh install, first Gateway startup:
1

Seed templates

Automatically plants AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md, HEARTBEAT.md, MEMORY.md templates, and BOOTSTRAP.md
2

Q&A identity setup

The agent reads BOOTSTRAP.md and asks in sequence: “What would you like me to call you?” (written to USER.md); “What should I call myself, what creature, what emoji?” (written to IDENTITY.md); “What tone and limits should I use?” (written to SOUL.md)
3

Ritual complete

After confirmation, BOOTSTRAP.md is deleted and the session begins normally
Why this matters: from this point on, every session start reassembles the agent’s persona and understanding of you from these files. If the files are empty, contradictory, or stale, behavior drifts from the very first line of each session.

​
5. What to take away: the harness concepts OpenClaw makes visible

OpenClaw’s biggest design contribution is not its model support or tool set; it is that it makes harness concepts that are usually buried in system prompts or source code fully visible as readable, diff-able md files. The engineering significance of that equals its product design significance: turning implicit configuration into explicit assets. Mapped against 01-6 Harness Engineering: Design lessons worth internalizing:
  • Lean core + plugin: OpenClaw’s core retains only what is essential; skills, channels, and policies are all extended through plugins and md files. Core bloat is where software decay starts, and the same applies to harnesses.
  • Separate environment-specific from shareable behavior: TOOLS.md (what your camera is called) and SOUL.md (this agent’s persona) are managed separately, so sharing SOUL.md and skills/ does not leak your infrastructure.
  • Ritual is not decoration: BOOTSTRAP.md forces the agent and user to sit down and agree on “who we are and how we will work together.” This produces more real behavioral constraint than a “default persona” written in documentation.
  • “Nothing to do, reply OK” is a cost-saving design: leaving HEARTBEAT.md empty skips even the model call — a zero-cost on/off switch for “installed but not yet in use” scenarios.

​
6. One everyday analogy

OpenClaw is like a flatmate with their own “life manual”: a note on the fridge that says “who I am and how I speak” (SOUL.md), leftover labels in the fridge from yesterday (MEMORY.md), a kitchen timer that rings every half hour asking “have I checked on the stove?” (HEARTBEAT.md), a notebook at the door for “what is this camera called, how do I SSH to that machine” (TOOLS.md), and each evening before sleep they review the day’s notes to decide what gets written into long-term memory (daily memory/YYYY-MM-DD.md distilled into MEMORY.md). The person is not the agent; the agent is the joint assembly of person and environment, and that life manual is the environment.

​
Hands-on exercises

1

Install locally and observe the bootstrap

Clone OpenClaw locally and run openclaw onboard --install-daemon. Watch which md files are seeded into the workspace and how the bootstrap ritual builds IDENTITY.md and SOUL.md through a question-and-answer exchange. Verify that BOOTSTRAP.md is actually deleted when complete.
2

Edit HEARTBEAT.md and observe a heartbeat turn

Add a task to ~/.openclaw/workspace/HEARTBEAT.md such as “every half hour, check whether my GitHub has any new issues assigned to me.” After 30 minutes, observe whether the heartbeat turn executes correctly and replies HEARTBEAT_OK or takes real action.
3

Read the repository template directory

Read the SOUL.md, AGENTS.md, and MEMORY.md templates under docs/reference/templates/ directly. Compare them against the versions generated by your local bootstrap. That diff is the “defaults vs your customization” boundary.

​
Common pitfalls

  • Writing SOUL.md like a corporate manual: a wall of rules raises token cost while reducing compliance (an overly long high-priority layer gets ignored or diluted by the model). Short, behaviorally effective instructions work; keep it under one A4 page.
  • Packing detailed logs into MEMORY.md: MEMORY.md is a distillation layer, not a log. Detailed records belong in memory/YYYY-MM-DD.md. Filling MEMORY.md with logs triggers bootstrap truncation and causes important information to be lost.
  • Forgetting to delete BOOTSTRAP.md: if the ritual is completed but the file is not deleted, every startup re-runs the first-time setup (the agent treats the presence of BOOTSTRAP.md as “first run”).
  • Main session default full-host permissions: see the Warning in Section 3. Confusing “group / stranger channels” with “main session” is the most common exposure point in OpenClaw; a successful prompt injection gives the agent full host permissions to execute arbitrary commands.
  • Treating plugins as “more is better”: each additional OpenClaw skill injects more context into every session, increasing token cost. Install only what you will actually use and audit regularly.

​
Self-check

The bar for passing this unit
  1. Without looking at the documentation, can you state the difference between SOUL.md, IDENTITY.md, and MEMORY.md, and when each one is loaded?
  2. Can you explain the division of responsibilities between heartbeat and cron jobs, and why a heartbeat turn does not create background task records?
  3. Can you explain to a colleague in one sentence “what OpenClaw hides in the workspace md files”?
  4. In your current agent configuration — whether Claude Code, Codex, Cursor, or anything else — is there any operational procedure that lives “scattered in a system prompt string, not version-controllable”? Could that piece also be made visible as a md file?

​
Sources and further reading

Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.