Every major concept explained in plain English. Agents, Skills, MCPs, Memory, Heartbeat, Cron, Sub-agents, and Identity files. This is the full mental model.
An agent is an AI that goes beyond answering questions. It takes actions. When you send a message to your OpenClaw agent, it doesn't just respond with text. It might read a file, search the web, write code, send a message to another service, and then report back what it did.
OpenClaw runs a single embedded agent runtime called Pi. Pi is built on the same foundation as Claude Code but wired to OpenClaw's session management, tool system, and channel connections.
How an agent turn works:
Each conversation is a session. Sessions have their own context window (the "working memory" limit of the AI). Long sessions eventually hit this limit. OpenClaw handles this automatically through a process called compaction, summarizing older parts of the conversation to make room for new content.
Skills are add-on capabilities for your OpenClaw agent. Think of them as apps on a smartphone. The phone works without them, but the right skills make your agent dramatically more useful for your specific needs.
Skills can add:
The official skills marketplace is ClawhHub.com. Browse by category or search for your use case.
Skills install into your workspace's skills/ folder. For managed skills, you can install directly:
# Install a skill by name
openclaw skills install [skill-name]
# List installed skills
openclaw skills listYou can also manually copy a skill folder into ~/.openclaw/skills/ or into your workspace's skills/ folder. OpenClaw loads from all three locations: bundled (shipped with OpenClaw), managed (~/.openclaw/skills/), and workspace (workspace/skills/). Workspace skills take priority if there's a name conflict.
MCP stands for Model Context Protocol, a standardized way for AI models to call external tools and services.
The waiter analogy: Imagine you're at a restaurant. You tell the waiter what you want. The waiter goes to the kitchen and places your order. The kitchen prepares the food. The waiter brings it back to you. You never saw the inside of the kitchen.
MCPs work exactly like that. The AI tells the MCP what it needs (e.g., "search Google for X"). The MCP protocol handles the translation to the actual service. The result comes back to the AI. The AI never needs to know the specifics of how Google's API works, just how to talk to the waiter.
In OpenClaw, MCPs let your agent connect to:
MCPs are configured in your openclaw.json config file under plugins.entries. Each MCP has its own connection URL and authentication details.
AI models have no inherent memory; every session starts blank. OpenClaw's memory system solves this with a practical, human-readable approach: everything is stored as plain Markdown files.
memory/YYYY-MM-DD.mdEvery day, the agent creates (or writes to) a dated file like memory/2026-03-20.md. This is the running log of what happened: decisions made, tasks completed, things worth remembering.
At the start of each session, the agent automatically reads today's and yesterday's daily logs. This is how it picks up where it left off, like a colleague who re-reads their notes before a meeting.
MEMORY.mdThis is the curated, permanent memory file. Think of it as a notebook where the most important, durable facts live: your preferences, your ongoing projects, your business context, things the agent should always know.
Important security note: MEMORY.md is only loaded in your private main session (direct chat with your gateway). It's NOT loaded in group chats or shared sessions where others can read along. This protects private context from leaking.
OpenClaw can build a searchable index of all your memory files, allowing the agent to find relevant past notes even when the exact wording differs. It uses a combination of semantic search (meaning-based) and BM25 keyword search for best results.
When a session is nearing its context window limit and about to be compacted, OpenClaw automatically prompts the agent to write any important notes to memory before the compaction happens. This prevents information loss during long sessions.
The heartbeat is what makes OpenClaw proactive rather than reactive.
Without a heartbeat, your agent only does things when you ask. With the heartbeat, it wakes up periodically, checks what needs attention, and acts without being prompted.
How it works: OpenClaw sends a configurable message to your agent on a schedule (typically every 30 minutes). The agent reads this message plus the current HEARTBEAT.md file and decides what to do.
The HEARTBEAT.md file is your heartbeat task list. Write things like:
# HEARTBEAT.md
- Check email for anything urgent (1x per hour)
- Monitor weather if there are outdoor events today
- Review calendar for any meetings in the next 2 hours
- If it's Monday morning, compile weekly task list from last week's notesThe agent reads this, acts on whatever's relevant, and either takes action or returns HEARTBEAT_OK if nothing needs attention.
When to use heartbeat vs cron:
Cron is a standard Unix way of scheduling tasks. You describe when something should run using a time expression, and it runs automatically at that time.
In OpenClaw, cron jobs spawn a separate agent session at the scheduled time to run a specific task. This is ideal for:
Cron syntax uses 5 fields: minute, hour, day-of-month, month, day-of-week.
# Examples:
# 7:00 AM every day
0 7 * * *
# Every Monday at 9 AM
0 9 * * 1
# Every hour on the hour
0 * * * *
# Every 30 minutes
*/30 * * * *Cron jobs are configured in openclaw.json under agents.cron. Each job has a schedule expression, a prompt to send the agent, and optionally a target channel to send the output to.
Sub-agents are additional AI instances that your main agent can spawn to handle specific tasks in parallel.
The analogy: You're the manager. You have one main assistant (your OpenClaw agent). When a big project comes in, your assistant can hire specialist contractors for specific pieces of work: a researcher, a writer, a data analyst, then coordinate their output. That's sub-agents.
Why this matters:
OpenClaw uses a set of Markdown files in your workspace to give the agent context at the start of every session. These are read automatically and injected into the agent's context, so you never need to re-explain who you are or how you want things done.
| File | What It Contains | When to Edit |
|---|---|---|
SOUL.md |
The agent's personality, tone, and values. How it should behave, what opinions it should have, what it shouldn't do. | Customize when you want a specific personality or communication style. |
USER.md |
Who you are: your name, preferences, work context, how you like things explained, your business background. | Fill this in during initial setup and update as your context changes. |
AGENTS.md |
Operating instructions for the agent's workspace: how it should use memory, what rules to follow, how to manage background tasks. | Modify if you want to change the agent's operating procedures. |
TOOLS.md |
Notes about the specific tools you have available: camera names, SSH details, API conventions, local quirks. | Add notes about your specific setup that the agent should know. |
IDENTITY.md |
The agent's name, emoji avatar, and general vibe. Cosmetic but adds personality. | Personalize if you want to name your agent something specific. |
BOOTSTRAP.md |
One-time first-run ritual. The agent reads this, follows the instructions, then deletes the file. | Pre-filled by openclaw setup; usually don't edit manually. |
HEARTBEAT.md |
Task list for heartbeat check-ins. What the agent should look for during periodic polls. | Update whenever you want to add or remove periodic checks. |
MEMORY.md |
Long-term curated memory. Your preferences, important context, ongoing projects. | The agent writes to this; you can also edit directly. |
These files are plain text. You can edit them in any text editor, Notepad, Obsidian, or VS Code. The agent reads them fresh at the start of each session, so changes take effect immediately on the next session.
openclaw setup to create all these files with sensible defaults if you haven't already. Then open USER.md and fill in your actual name, timezone, and context. That alone will noticeably improve the quality of responses.Was this guide helpful?