OpenClaw

OpenClaw (also known as Clawdbot) is an open-source AI agent framework that runs locally on your machine, providing a personal AI assistant with full access to your tools, files, and services. Unlike cloud-only AI assistants, OpenClaw operates from your own computer—reading files, executing commands, browsing the web, and connecting to your services.

The framework gained attention through viral posts demonstrating its architecture: a system of configuration files that give agents persistent identity, memory, and self-management capabilities. The key insight: AI agents need infrastructure, not just prompts.

Core philosophy:

• Local-first: Your data stays on your machine
• File-based memory: Text files beat neural memory
• Workspace conventions: Standard files create standard behaviors
• Self-managing agents: Hooks, heartbeats, and automation

OpenClaw uses a workspace directory with standard files that define agent behavior:

~/clawd/                    # Agent workspace
├── SOUL.md                # Agent identity and personality
├── USER.md                # Information about the user
├── MEMORY.md              # Long-term curated knowledge
├── AGENTS.md              # Workspace conventions and rules
├── HEARTBEAT.md           # Periodic check instructions
├── TOOLS.md               # Tool-specific notes
├── BOOTSTRAP.md           # Initial setup (deleted after first run)
├── memory/                # Daily logs and working notes
│   ├── 2024-01-15.md
│   ├── 2024-01-16.md
│   └── heartbeat-state.json
├── skills/                # Modular capabilities
│   ├── camera/
│   ├── calendar/
│   └── email/
└── projects/              # Project-specific context

Each file serves a specific purpose in the agent's operation.

SOUL.md - Agent identity

Defines who the agent is:

# SOUL.md

You are Atlas, a research and productivity assistant.

• Thorough but concise
• Proactive without being pushy
• Direct communication style
• Curious about context

• Accuracy over speed
• Privacy by default
• Respect user's time
• Admit uncertainty

• Never send external communications without confirmation
• Don't access sensitive files unless asked
• Use trash instead of delete

**USER.md - User context**

Information about the person the agent serves:

```markdown
# USER.md

• Software developer, works on AI projects
• Prefers bullet points over paragraphs
• Morning person, most productive before noon

• Communication: Direct, no fluff
• Format: Markdown with headers
• Tone: Professional but casual

• Building AI agent infrastructure
• Writing about agent architecture

**MEMORY.md - Long-term memory**

Curated knowledge that persists:

```markdown
# MEMORY.md

• Project Phoenix deadline: March 15
• Sarah's birthday: March 15
• Preferred meeting times: 10 AM, 2 PM

• Likes detailed code comments
• Prefers TypeScript over JavaScript
• Uses Vim keybindings

• Chose PostgreSQL for the main database
• Selected Tailwind for CSS framework

**AGENTS.md - Workspace rules**

Conventions and behaviors for the workspace:

```markdown
# AGENTS.md

1. Read SOUL.md (identity)
2. Read USER.md (user context)
3. Read recent memory files

• Daily notes: memory/YYYY-MM-DD.md
• Long-term: MEMORY.md
• Write it down—mental notes don't survive restarts

• Don't exfiltrate private data
• trash > rm
• When in doubt, ask

**HEARTBEAT.md - Periodic checks**

Instructions for heartbeat polling:

```markdown
# HEARTBEAT.md

On each heartbeat, check:
- [ ] Urgent emails (from VIP senders)
- [ ] Calendar events in next 2 hours
- [ ] Pending tasks

If nothing needs attention: HEARTBEAT_OK
Track check times in memory/heartbeat-state.json
Quiet hours: 23:00-08:00 unless urgent

BOOTSTRAP.md - Initial setup

First-run instructions (deleted after use):

# BOOTSTRAP.md

This is your first run. Welcome.

1. Read this file to understand your setup
2. Review SOUL.md for your identity
3. Check USER.md to learn about your human
4. Once oriented, delete this file

Session lifecycle

1. Start: Agent wakes, reads workspace files
2. Context loading: SOUL.md → USER.md → MEMORY.md → recent logs
3. Interaction: User messages, agent responds and acts
4. Memory updates: Write significant events to daily log
5. End: Session closes, state persists in files

Tool integration

OpenClaw provides access to:

• File system: Read, write, edit files
• Terminal: Execute shell commands
• Browser: Control web browsers
• APIs: Call external services
• Custom skills: Modular capability packages

Heartbeat system

Periodic polling for proactive behavior:

Every 30 minutes:
  → Agent wakes
  → Reads HEARTBEAT.md
  → Checks configured items
  → Acts if needed, or returns HEARTBEAT_OK

Multi-agent support

Spawn sub-agents for specialized tasks:

Main agent → Sub-agent (research)
          → Sub-agent (analysis)
          → Combines results

Persistence without databases

Files are:

• Human-readable and editable
• Version-controllable
• Debuggable
• Portable across systems

Transparency

Anyone can read the configuration files to understand:

• What the agent knows
• How it's configured
• What it's allowed to do

Simplicity

No complex setup:

• Create directory
• Add markdown files
• Agent works

Evolvability

Modify agent behavior by editing text files:

• No code changes
• No redeployment
• Immediate effect

OpenClaw runs through a gateway service:

User Interface (Terminal/Discord/WhatsApp)
           ↓
      Gateway Service
           ↓
    ┌──────┴──────┐
    ↓             ↓
Main Agent    Sub-agents
    ↓             ↓
  Tools        Tools

The gateway:

• Manages agent sessions
• Routes messages
• Executes tools
• Handles scheduling (cron, heartbeats)
• Coordinates multi-agent work

Installation

npm install -g clawdbot

Initialize workspace

clawdbot init ~/my-agent

This creates the standard file structure with templates.

Customize your agent

Edit the generated files:

• SOUL.md: Define personality and capabilities
• USER.md: Add your information
• AGENTS.md: Customize workspace rules

Start the gateway

clawdbot gateway start

Interact

clawdbot chat

Or connect via Discord, WhatsApp, or other channels.

vs LangChain/LlamaIndex

These are libraries for building agent applications. OpenClaw is a complete agent runtime with workspace conventions.

vs AutoGPT

AutoGPT runs autonomous loops. OpenClaw balances autonomy with human touchpoints and persistent workspace.

vs Custom implementations

OpenClaw provides the infrastructure so you don't build from scratch—file conventions, gateway, channels, tools.

vs Cloud AI assistants

Cloud assistants are stateless and remote. OpenClaw runs locally with persistent memory and tool access.

OpenClaw gained attention for demonstrating production agent patterns:

• Heartbeats: How agents stay "alive" without constant human input
• Soul files: How agents maintain consistent identity
• File-based memory: Why text files beat neural memory
• Self-management: How agents handle their own lifecycle

These patterns solve real problems that anyone building serious AI agents encounters.

OpenClaw is open-source. Contributions welcome:

• Core framework improvements
• New skill packages
• Channel integrations
• Documentation
• Bug fixes

The goal: make AI agents accessible to anyone willing to learn.

Want the benefits of agent architecture without building from scratch? Chipp provides managed AI agents with custom knowledge, actions, and integrations—the patterns without the infrastructure work.