NativeAIHub
🦞

How OpenClaw Works

A self-hosted gateway that connects AI models to your chat apps, gives them persistent memory, browser control, scheduled tasks, and runs 24/7 on your machine or VPS.

10 sections·1 min read

01Architecture

In Plain English

Think of the Gateway like a receptionist at a hotel. Guests (your messages) arrive from different entrances (WhatsApp, Telegram, Discord, iMessage). The receptionist takes each message, walks it over to the right expert (the AI model), gets the answer, and brings it back to whichever entrance the guest came from.

The Gateway is that receptionist. It is a single program running on your computer (or a server) that connects your chat apps on one side to an AI brain on the other side. It also handles scheduling, memory, and tools, so the AI can actually do useful things beyond just chatting.

OpenClaw is a single process (the Gateway) that bridges your chat channels to an AI model. Messages come in via WebSocket, the agent thinks and acts, replies stream back out.

Chat ChannelsGatewayAI Models
Layer 1💬 WhatsApp (via Baileys)🦞 OpenClaw Gateway🧠 Claude (Anthropic)
Layer 2✈️ Telegram (via grammY)Port 18789🤖 GPT / o-series (OpenAI)
Layer 3🎮 Discord (via discord.js)Session manager, Tool executor💎 Gemini (Google)
Layer 4🍎 iMessage (macOS CLI)Cron scheduler, Memory indexer🔀 OpenRouter (any model)

Why does this matter?

Without the Gateway, your chat apps and AI models have no way to talk to each other. It is like having a brilliant consultant locked in a room with no phone. The Gateway gives them a phone line to the outside world, plus a notebook (memory), a web browser, and an alarm clock (scheduled tasks).
The Gateway also has a Control UI (web dashboard), a macOS menu bar app, and iOS/Android nodes that can pair with the Gateway for mobile Canvas surfaces and chat.

What this means for you

You pick which AI model you want to power your assistant (Claude, GPT, Gemini, or others), and you pick which chat apps you want to talk to it through. The Gateway connects them all together. You can even switch AI models later without changing anything about how you chat.

02Message Flow

In Plain English

When you send a message to your AI assistant, a lot happens behind the scenes in about one to three seconds. Think of it like ordering food at a restaurant. Your message is the order. The waiter (Gateway) takes it to the kitchen, reminds the chef (AI model) about your dietary preferences and past orders (memory files), hands over the recipe book (instructions), and then the chef cooks up a response. If the chef needs to look something up (browse the web, check your calendar), they do that too. Then the waiter brings the finished plate back to your table.

The seven steps below describe this process in detail. You do not need to understand every step to use OpenClaw; just know that all of this happens automatically every time you send a message.

Step 1: Message arrives

You send "Check my calendar for today" via WhatsApp. The channel adapter receives it and enqueues it in the session lane.

Step 2: Bootstrap files injected

On the first turn, OpenClaw reads your workspace files and injects them into context: SOUL.md (persona/tone) + AGENTS.md (instructions/memory) + USER.md (who you are) + TOOLS.md (tool guidance) + IDENTITY.md (agent name/vibe).

Step 3: Memory loaded

Today's daily log (memory/YYYY-MM-DD.md) and yesterday's are read. If the session is private, MEMORY.md (long-term memory) is also loaded.

Step 4: System prompt assembled

OpenClaw builds the full system prompt from: base prompt + skills prompt + bootstrap context + per-run overrides. Compaction reserve tokens are enforced to prevent overflow.

Step 5: Model inference + tool calls

The AI model (e.g. Claude) receives the prompt and starts streaming. If it needs a tool (browser, web search, cron, exec), the Gateway executes it and feeds the result back. This loops until the model is done.

Step 6: Reply streams back

Assistant text streams as deltas. Block streaming can chunk long replies into digestible pieces. The final payload is sent back through the channel (WhatsApp, Telegram, etc.).

Step 7: Session persisted

The full transcript is stored as JSONL at ~/.openclaw/agents/<id>/sessions/. If the context nears compaction, a memory flush is triggered first to preserve durable notes.

Key takeaway

The important thing to understand is that the AI does not just "wing it" every time you send a message. It first reads its personality file, your preferences, and recent notes. Then it thinks and responds. If it needs to look something up or take an action, it can pause, do that, and then continue. Finally, the entire conversation is saved so nothing is lost. This is what makes OpenClaw feel like a real assistant rather than a forgetful chatbot.

03Workspace

In Plain English

Every person has a desk with their important documents, sticky notes, and personal items. The workspace is your AI assistant's desk. It is a folder on your computer that contains simple text files describing who the AI is, how it should behave, what it knows about you, and what it remembers from past conversations.

You can open and edit these files with any text editor. Want your assistant to be more formal? Edit the personality file. Want it to know your timezone or your name? Update the user file. It is all just plain text, nothing complicated.
🟣
SOUL.md

Persona, tone, boundaries. "You are a concise, proactive assistant." Loaded every session.

🔵
AGENTS.md

Operating instructions. Rules, priorities, memory guidelines, how to behave. Loaded every session.

🔷
USER.md

Who you are. Name, timezone, preferences, how to address you. Loaded every session.

🩵
IDENTITY.md

Agent's name, emoji, vibe. Created during bootstrap ritual. "I'm Claw 🦞"

🟠
TOOLS.md

Notes about local tools and conventions. Does not control availability; just guidance.

🟢
MEMORY.md

Curated long-term memory. Durable facts, preferences, decisions. Only loaded in private sessions.

📅
memory/YYYY-MM-DD.md

Daily log (append-only). One file per day. Today + yesterday read at session start.

💓
HEARTBEAT.md

Optional tiny checklist for autonomous heartbeat runs. Keep short to save tokens.

Think of it like a character sheet in a role playing game

SOUL.md defines the character's personality. AGENTS.md is the rulebook that tells them how to play. USER.md is information about you, the player. IDENTITY.md is the character's name and style. MEMORY.md is their journal of important facts. And the daily logs are like a diary that gets a fresh page every day.

What this means for you

You are in full control of your AI's behavior. Unlike cloud chatbots where the company decides how the AI behaves, here you write the rules yourself in plain text. If something feels off, you just open the file and tweak it. No coding required.

04Memory System

In Plain English

Most chatbots forget everything once you close the window. OpenClaw is different. It writes important things down in plain text files on your computer, just like you might jot notes in a notebook.

There are two types of memory. Daily logs are like diary entries; a new page every day where the AI jots down what happened. Long term memory is for the big stuff: your preferences, important decisions, people you mention often. The AI reads these notes at the start of every conversation, so it always knows what is going on.

There is also a search feature that lets the AI find old notes even when the exact words are different. If you mentioned "my dog Max" three months ago, the AI can still find that note when you talk about "my pet."
📝
Daily Logs

memory/YYYY-MM-DD.md. Append-only daily notes. Today + yesterday loaded automatically. Running context, events, conversations.

🧠
Long-term Memory

MEMORY.md. Curated durable facts. Preferences, decisions, people. Only loaded in private/main sessions.

🔍
Vector Search

Semantic recall via embeddings (OpenAI, Gemini, Voyage, or local GGUF). Hybrid BM25 + vector search for best precision.

Persistent memory requires an API key for embeddings

Without it, the agent can still read/write Markdown files, but memory_search (semantic recall) won't work. You need an OpenAI, Gemini, or Voyage API key, or a local GGUF model via node-llama-cpp.
1

Markdown files

~400 token chunks

2

Embeddings

OpenAI / Gemini / Local

3

SQLite Index

sqlite-vec

4

Hybrid Search

BM25 + Vector merge

5

MMR + Decay

Diversity + Recency

What this diagram means

When the AI needs to remember something, it does not just search for matching words (like Ctrl+F). Instead, it understands the meaning behind your question and finds notes that are related conceptually. It also prefers recent notes over very old ones, and makes sure to give you a diverse set of results rather than five copies of the same thing. Think of it like a very smart librarian who understands what you actually need, not just what you literally asked for.

05Browser Control

In Plain English

Your AI assistant gets its own web browser, completely separate from the one you use every day. It can open websites, click buttons, fill out forms, take screenshots, and read what is on the page. This is what allows it to do things like "go check this website and tell me what it says" or "log into my dashboard and grab the latest numbers."

The important part: this browser is totally isolated. It does not touch your bookmarks, saved passwords, or browsing history. It is like giving your assistant their own separate computer to browse on.
1

🦞 Gateway

Control server, Loopback HTTP API

2

🎭 Playwright

CDP connection, Actions + Snapshots

3

🌐 Managed Browser

Isolated profile, Dedicated data dir

🌐Open & Navigate
🖱️Click & Type
📸Screenshots & PDFs
👁️AI Snapshots
🍪Cookies & Storage
📊Console & Network
👥Multi-profile
🔗Remote CDP

Imagine a robot arm that can use a mouse and keyboard

That is essentially what the browser control gives your AI. It can navigate the web just like a human would, clicking links, scrolling pages, and reading content. But it does all of this on its own separate screen, so it never interferes with what you are doing on your computer.

What this means for you

You can ask your assistant to do web based tasks for you. "Check if that product is still in stock." "Take a screenshot of my website's homepage." "Read the latest blog post from this URL and summarize it." The assistant can see and interact with websites just like you can.

06Automation

In Plain English

This is one of the most powerful features. Your AI assistant can set its own alarms and do things on a schedule without you having to ask. Two concepts to understand:

Cron jobs are like recurring calendar events for your AI. "Every morning at 7am, check my email and send me a summary on WhatsApp." "Every Friday, review my project board and write a weekly report." You set it up once, and it runs automatically from then on.

Heartbeat is simpler: the AI just "wakes up" every so often (say, every 30 minutes) to check if there is anything it should do. Think of it like a watchful security guard who does rounds periodically.
1

⏰ Schedule

at / every / cron expr

2

🦞 Gateway Scheduler

Persisted jobs.json

3

🧠 Agent Turn

Main or isolated

4

📤 Delivery

Announce / Webhook

Cron Jobs

Purpose

Scheduled tasks that persist across restarts

Schedule types

at (one-shot), every (interval), cron (expression with timezone)

Execution

Main session or isolated sessions with dedicated context

Storage

~/.openclaw/cron/jobs.json

Best for

"Run this specific prompt at 7am every day and send to WhatsApp"

Heartbeat

Purpose

Periodic autonomous check-in

Schedule types

Fixed interval (e.g. every 30 minutes)

Execution

Reads HEARTBEAT.md and processes queued system events

Storage

Cron wakes heartbeat

Best for

"Check in every 30 minutes to see if anything needs doing"

# Example: recurring morning brief delivered to WhatsApp
openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "Europe/Ljubljana" \
  --session isolated \
  --message "Summarize inbox + calendar for today." \
  --announce \
  --channel whatsapp \
  --to "+38640123456"

What the code above does

That block of text is a command you would type into your terminal (the text based interface on your computer). It tells OpenClaw: "Create a task called Morning brief. Run it every day at 7am Ljubljana time. When it runs, ask the AI to summarize my inbox and calendar. Then send the result as a WhatsApp message to my phone number." You set this up once and your assistant will text you a personalized morning briefing every single day.

07Built-in Tools

In Plain English

Tools are the skills your AI assistant has access to. Without tools, an AI can only chat. With tools, it can actually do things: browse the web, read and write files, run programs, send messages, set reminders, create visual dashboards, and more.

Think of each tool as a different gadget in a toolbox. The "browser" tool lets the AI surf the web. The "exec" tool lets it run commands on your computer. The "cron" tool lets it schedule future tasks. You can control which tools are available, so the AI only has access to what you are comfortable with.
🌐
browser

Navigate, click, type, screenshot, snapshot, manage tabs and profiles. Full browser automation.

🔎
web_search

Search the web via configured search providers. Returns results the agent can process.

📡
web_fetch

Fetch and read any URL. Converts HTML to readable content for the model.

⚡
exec

Execute shell commands. Run scripts, install packages, check system status. Sandboxable.

📂
read / write / edit

Full filesystem access. Read, create, and edit files in the workspace and beyond.

⏰
cron

Add, update, remove, and run scheduled jobs. The agent can self-schedule tasks.

💬
message

Send messages to any connected channel (WhatsApp, Telegram, Discord, etc.).

🧠
memory_search

Semantic search over memory files. Hybrid BM25 + vector for precise recall.

🖼️
canvas

Render HTML/SVG surfaces on connected nodes. Visual dashboards, charts, UIs.

📋
sessions

Manage agent sessions. List, read transcripts, switch contexts.

📱
nodes

Manage connected node hosts (iOS, Android, remote machines).

🎨
image

Generate and process images. Supports image input/output across channels.

🎛️Tool profiles: minimal, coding, messaging, full
📦Tool groups: group:runtime, group:fs, group:sessions, group:memory, group:web, group:ui, group:automation

What are profiles and groups?

Profiles are like permission levels. "Minimal" gives the AI only basic abilities. "Full" unlocks everything. Groups let you fine tune which categories of tools are available. For example, you might want your AI to browse the web and send messages, but not run programs on your computer. You pick the combination that feels right for your needs.

08MCP Integrations

In Plain English

MCP stands for Model Context Protocol. Think of MCPs as plug-in adapters that let your AI assistant connect to other apps and services. OpenClaw already comes with a solid set of built-in tools, but MCPs let you expand its abilities even further.

For example, want your assistant to manage your Notion workspace? Plug in the Notion MCP. Want it to check stock prices? Plug in the Yahoo Finance MCP. Each MCP is like adding a new specialty to your assistant's resume. Below are some popular combinations that work especially well with OpenClaw.
🎭
Puppeteer MCP

Alternative browser control via Puppeteer. Useful for specific scraping tasks or when you need Puppeteer-specific features alongside OpenClaw's built-in browser.

🔥
Firecrawl MCP

Advanced web scraping with JS rendering, structured extraction, site crawling, and search. Cleaner output than raw fetching.

📋
Notion MCP

Read and write Notion pages/databases. Let the agent manage your knowledge base, project boards, or content calendar.

📧
Gmail / Google Workspace MCP

Email access for automated briefings, inbox summaries, and calendar management via cron jobs.

🐙
GitHub MCP

Manage repos, issues, PRs. Let the agent monitor commits, review code, and create issues from chat.

✅
Todoist / Linear MCP

Task management integration. Create, update, and complete tasks via natural language from any chat channel.

💹
Yahoo Finance MCP

Stock prices, financials, news. Combine with cron for daily market briefings delivered to WhatsApp.

🔎
Perplexity / Brave Search MCP

AI-powered search with citations. Deep research capabilities for complex questions requiring sourced answers.

Think of MCPs like apps on your phone

Your phone can make calls and send texts out of the box, but installing apps gives it new powers: banking, navigation, food delivery. MCPs work the same way for your AI assistant. The base system is useful on its own, and each MCP you add teaches it how to work with one more service.

09Deployment

In Plain English

You need a computer to run OpenClaw, and you have two choices. Option A: run it on your own Mac (or PC). This is free and easy, but your assistant goes to sleep whenever your computer does. Option B: rent a small server in the cloud (called a VPS) for about $5 to $20 per month. This keeps your assistant running around the clock, even when your laptop is closed.

A VPS is essentially a computer in a data center that never sleeps. If you want your morning briefing to arrive at 7am every day regardless of whether your laptop is open, a VPS is the way to go. The best approach? Use both. Run the brain on the VPS, and connect your Mac as a helper for things only your Mac can do (like iMessage or your local files).

Local Mac

Cost

Zero server cost, use existing hardware

Uptime

Must keep machine running 24/7; sleep/restart kills the Gateway

Network

Dynamic IP complicates remote access; needs Tailscale/tunnel

iMessage

yes

Browser

Direct browser access on your screen

Cron reliability

Misses jobs during sleep

Resources

Uses your machine's RAM and CPU

VPS (Recommended)

Cost

Monthly cost ($5-20/mo for a small VPS)

Uptime

True 24/7 uptime, no sleep interruptions; systemd auto-restart

Network

Static IP, easy firewall + DNS

iMessage

no

Browser

Headless browser only (no visual debugging)

Cron reliability

Cron jobs fire reliably at exact times; heartbeat never misses

Resources

Dedicated resources on the VPS

Best of both worlds

Run the Gateway on a VPS for 24/7 reliability, then pair a node host on your Mac. The node bridges your local browser, iMessage, and filesystem to the VPS-hosted Gateway. The agent thinks on the VPS, but acts on your Mac when needed.
1

📱 Your Phone

WhatsApp / Telegram

2

🖥️ VPS Gateway

24/7 uptime, Cron + Memory + AI

3

💻 Mac Node Host

Browser + iMessage, Local files

What this diagram shows

In the hybrid setup, your phone sends a message to the VPS (the always on server). The VPS does the AI thinking and decision making. If the AI needs to use your local browser or send an iMessage (which only works on a Mac), it reaches out to your Mac through a secure connection, does what it needs to do there, and then sends the result back through the VPS to your phone. You get the best of both worlds: 24/7 availability plus access to your local Mac features.

10Reference

In Plain English

This section is a cheat sheet for anyone who wants to find specific files on their computer. OpenClaw stores everything inside a folder called ~/.openclaw (the ~ symbol means "your home folder"). Inside that folder, you will find the main settings file, the workspace where your AI's personality lives, conversation histories, scheduled tasks, and more. You do not need to memorize these paths; just bookmark this page for when you need to find something.
PathDescription
Config~/.openclaw/openclaw.jsonMain config file (Gateway, models, channels, tools, memory, cron)
Workspace~/.openclaw/workspace/Agent workspace (SOUL.md, AGENTS.md, memory/, skills/)
Sessions~/.openclaw/agents/&lt;id&gt;/sessions/Session transcripts (JSONL, per-agent)
Cron jobs~/.openclaw/cron/jobs.jsonPersisted cron job definitions
Cron runs~/.openclaw/cron/runs/Cron run history (JSONL per job)
Credentials~/.openclaw/credentials/OAuth tokens, API keys (never commit)
Memory index~/.openclaw/memory/&lt;id&gt;.sqlitePer-agent memory vector index
Skills~/.openclaw/skills/Managed/local skills (outside workspace)
# Minimal openclaw.json
{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  },
  "channels": {
    "whatsapp": {
      "allowFrom": ["+38640123456"]
    }
  }
}

What this config file does

This is the smallest possible settings file to get OpenClaw running. It tells the system two things: where the workspace folder is (the AI's personality and memory files) and which AI model to use (in this case, Claude). It also sets up WhatsApp and specifies which phone number is allowed to talk to the assistant. You edit this file once during setup; after that, OpenClaw handles the rest.