OpenClaw — The Self-Hosted AI Assistant That Lives in Your Chat Apps
What is OpenClaw?
OpenClaw is an open-source personal AI assistant you self-host. Think of it as your own Claude/ChatGPT, but instead of going to a website, it meets you where you already are — WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Teams, and more.
Originally called Clawdbot, then Moltbot, now OpenClaw — created by Peter Steinberger (@steipete). The project has grown to 39k+ stars across its ecosystem.
Mascot: Space Lobster
Because every good open-source project needs a crustacean in space.
How It Works — Architecture
At the core of OpenClaw is a single Gateway process (Node.js) that acts as the control plane for everything. It handles all channel connections, routes messages to agents, and manages the tool runtime.
👆 Tap any component to explore its details
ws://127.0.0.1:18789 — WebSocket + HTTP multiplexed
🎬 Message Flow — Watch a request travel through the system
Key Concepts
Why It Matters
The key insight behind OpenClaw is simple: your AI assistant should come to you, not the other way around.
Instead of opening yet another tab (ChatGPT, Claude, etc.), OpenClaw plugs into the messaging apps you're already using all day. Same AI capabilities, zero context switching.
And because it's self-hosted, your conversations, files, and data stay on your machine. It even supports subscription auth (Anthropic Pro/Max, OpenAI) so you don't need API keys — just your existing subscription.
Deep Dive: Tasks, Agents & Always-On
Running Example: The Meal Planner
To make these concepts concrete, we'll follow a single scenario throughout: you've set up OpenClaw to plan weekly meals for your family. It checks grocery deals, builds meal plans, reminds you to shop, and answers cooking questions — all through Telegram. Watch how each system plays its part.
⚡The Always-On Gateway
OpenClaw runs as a daemon process — a long-lived Node.js server managed by systemd (Linux) or launchd (macOS). It starts on boot and stays running 24/7. This is fundamentally different from ChatGPT or Claude web, which only exist when you have a tab open.
The Gateway maintains persistent connections to every configured messaging platform simultaneously. When a message arrives on Telegram at 3 AM, the Gateway is already listening. It receives the message, routes it to the correct agent, runs the AI model, executes any tools needed, and sends the reply — all without you lifting a finger.
🍝 Meal Planner Example
It's Sunday morning and the Safeway weekly ad just went live. You're still asleep, but the Gateway is already running — it's been running since you set it up. A cron job fires at 7 AM, the agent scrapes the weekly deals, builds a meal plan around what's on sale, and sends it to your Telegram. By the time you wake up, this week's dinners are planned.
🔄 Lifecycle
systemd (or launchd) auto-restarts the Gateway if it crashes. The process recovers channel connections, reloads cron jobs from disk, and resumes where it left off — typically within seconds. Your meal plan cron job doesn't miss a week even if the server reboots.
🧠Sessions & Memory
Every conversation is a session. Your main DM is one session. Each group chat gets its own. Cron jobs get isolated sessions. Sub-agent tasks get their own too.
Sessions are stored as JSONL transcripts on disk — every message, tool call, and result is persisted. This means full history survives restarts. The agent picks up exactly where it left off.
🍝 Meal Planner Example
Last week you told the agent "We don't like shellfish" and "Keep it to 1-2 meatless dinners per week." Those preferences live in the main session and in workspace files. When the Sunday cron job builds this week's plan, it reads those files — even though it runs in an isolated session. The agent wrote your preferences to USER.mdand its own memory/ files so they survive session resets and compactions.
📝 Session Reset
By default, sessions reset daily at 4 AM local time. Send /new to force a fresh start. Idle timeouts and per-channel policies are configurable.
📦 Compaction
When context gets large, OpenClaw compacts — summarizing older messages to free up the context window while preserving key information. The agent flushes important notes to files before compacting.
💓Heartbeats — Periodic Awareness
Heartbeats are the agent's internal alarm clock. Every 30 minutes (configurable), the Gateway wakes the agent in the main session and says: "Anything need attention?"
The agent reads HEARTBEAT.md — a checklist you control — and decides what to do. Check email? Scan the calendar? Review a project? If nothing needs attention, it replies HEARTBEAT_OK and goes back to sleep (no message sent to you).
🍝 Meal Planner Example
Your HEARTBEAT.md includes: "If it's Saturday and I haven't confirmed this week's meal plan, remind me." On Saturday afternoon, the heartbeat fires. The agent checks — you haven't responded to Sunday's plan yet. It sends a gentle nudge: "Hey, the meal plan is ready for this week. Want to swap anything before I finalize the grocery list?"On Monday's heartbeat, everything is confirmed, so it stays silent — HEARTBEAT_OK.
# HEARTBEAT.md
- Check email for urgent messages
- Review calendar for events in next 2 hours
- If Saturday + meal plan unconfirmed, nudge about it
- If a background task finished, summarize results
💡 The beauty: one heartbeat turn batches multiple checks. Instead of 5 separate scheduled tasks (email, calendar, weather, notifications, project status), a single heartbeat handles them all in one model call — saving tokens and reducing noise.
⏰Cron Jobs — Precise Scheduling
For tasks that need exact timing, OpenClaw has a built-in cron scheduler. Jobs persist to disk and survive Gateway restarts. Two execution styles:
Main Session
Injects a system event into the main session. The agent handles it on the next heartbeat (or immediately with wake: now). Has full conversation context.
Best for: reminders, nudges, context-aware tasks
Isolated Session
Runs a dedicated agent turn in cron:<jobId> — fresh session, no prior context. Can use a different model or thinking level. Delivers output to any channel.
Best for: reports, analysis, delivery to channels
🍝 Meal Planner Example — Three Cron Jobs
Sunday 7 AM — 0 7 * * 0 — Scrape Safeway deals, build the weekly meal plan, deploy to the meal planner app, send summary to Telegram. Uses Opus for quality.
Wed 4 PM — 0 16 * * 3 — "Reminder: check if you need to pick up any mid-week groceries." This runs in the main session so the agent knows what you've already bought.
Daily 5 PM — 0 17 * * * — "Tonight's dinner is [meal]. Start prepping around 5:30." Quick reminder with tonight's recipe.
📋 Schedule Types
• at — one-shot: "remind me in 20 minutes" or exact ISO timestamp
• every — fixed interval: "every 4 hours"
• cron — 5-field cron expression with timezone: 0 7 * * * (7 AM daily)
📬Message Queue — Handling Concurrency
What happens when 3 messages arrive while the agent is already thinking? The command queue handles this. Each session gets its own lane, and a global concurrency cap prevents overload.
🍝 Meal Planner Example
You see the weekly plan and rapid-fire three messages: "Swap Monday to tacos","Actually make it fish tacos", "And add a side salad." The agent is already working on the first swap. In collect mode (default), all three messages are coalesced into one followup turn — the agent sees them together and makes the final change in one shot, instead of flip-flopping through three separate plans.
collectCoalesce all queued messages into a single followup turn (default). Prevents "continue, continue" spam.
e.g. 3 rapid meal swap requests → agent gets all 3 at once, makes one clean update
steerInject new message into the active run — the agent sees it at the next tool boundary and adjusts course.
e.g. Agent is researching recipes, you say "skip seafood" → it pivots mid-search
followupQueue for the next turn after the current run finishes.
e.g. Agent finishes tonight's recipe, then handles your question about tomorrow's prep
🔱Sub-Agents — Parallel Work
The main agent can spawn sub-agents — isolated sessions that run tasks in parallel without blocking the main conversation. When they finish, they report back.
This is how OpenClaw handles complex multi-step work. Need to research something, build a file, and check an API? Spawn sub-agents for each task. They run concurrently (up to 8 by default), each in their own session with their own context window.
🍝 Meal Planner Example
You say: "I want to host a dinner party Saturday. Plan a 3-course Italian meal for 6, check what's on sale at Safeway, and find wine pairings." The main agent breaks this into three parallel tasks:
All three run simultaneously. While they work, you can keep chatting with the main agent about other things. When they finish, the agent combines results into a cohesive plan: menu, shopping list with sale prices, and wine recommendations.
🔧 How it works
sessions_spawn creates an isolated session, runs the task, and announces the result back to the parent session. The parent can also use sessions_send to message any session, and sessions_history to check on progress.
🔀Multi-Agent Routing
One Gateway can host multiple fully isolated agents — each with their own workspace, personality files, auth credentials, session store, and even different AI models.
Bindings route inbound messages to the right agent using deterministic rules: match by channel, account, peer ID, guild, or team. Most-specific match wins.
🍝 Meal Planner Example — Family Setup
Imagine extending the meal planner to the whole family. One Gateway, three agents:
🏠 "Alfred" — Personal agent (Telegram)
Full access: meal planning, calendar, email, dev tools. Opus model. Your main brain.
👨👩👧 "Family Chef" — Family group chat agent (WhatsApp)
Limited tools. Only sees the recipe book and this week's meal plan. Sonnet model (cheaper). Anyone in the family group can ask "What's for dinner?" or "How do I make the pasta sauce?"
👩🍳 "Callie's Agent" — Partner's personal agent (WhatsApp DM)
Own workspace, own preferences, own session history. Can modify the meal plan independently. Isolated from your personal data.
Same server, same Gateway process. Each agent has its own personality, tools, and data isolation. Messages route automatically based on channel + sender bindings.
Two WhatsApp numbers → two agents
Each phone number routes to a different agent with its own personality and data.
WhatsApp for quick chat, Telegram for deep work
Route WhatsApp to a fast Sonnet agent, Telegram to a powerful Opus agent.
Family group → restricted agent
Bind a group chat to an agent with limited tools and a family-friendly personality.
One number, multiple people
Route different DMs to different agents by sender phone number. True isolation per person.
🎯Putting It All Together
Here's what a typical day looks like with OpenClaw running. Tap any event to see the exact flow of messages through the system — which components fire, what sessions are created, and how the response reaches you.
🎬 A Day in the Life
Tap any event to see exactly how messages flow through the system
3
Cron Triggers
2
Heartbeats
3
User Messages
7
Notifications to You
The Gateway is always running. Heartbeats keep the agent aware. Cron handles precise schedules. Sub-agents handle parallel work. The queue prevents message collisions. And it all routes through whatever messaging apps you already use — no new app required.
Quick Comparison
vs ChatGPT / Claude web
Meets you WHERE YOU ARE (WhatsApp, Telegram, etc.) — no new tab needed
Requires you to go to a specific website or app
vs Custom bots (Telegram bots, Discord bots)
Full agent runtime with tools — browser, exec, files, cron, canvas
Typically just chat + simple commands, limited tool access
vs LangChain / CrewAI
A complete PRODUCT — install, configure, use. Not building blocks.
Frameworks for building — you still need to build the product yourself
vs Self-hosted LLMs (Ollama, etc.)
Uses frontier models (Claude, GPT-4) via subscription. Best quality.
Runs local models — more private but lower quality for complex tasks
Get Started
Install OpenClaw globally via npm
npm install -g openclaw@latestRun the onboarding wizard — sets up Gateway as a daemon
openclaw onboard --install-daemon