OpenClaw AI Agent Framework: Complete Guide (2026)

What is the OpenClaw Framework?

OpenClaw is a configuration-first AI agent runtime. Where other frameworks ask you to write Python or JavaScript to define agents, OpenClaw asks you to write a markdown file. That file, called SOUL.md, contains everything the framework needs to run a production-ready autonomous agent: its identity, behavior rules, available tools, memory settings, and channel connections.

The framework consists of four main layers working together. The SOUL.md file defines what the agent is. The gateway daemon runs the agent and keeps it alive. The skills system gives the agent tools to take action. And the channels layer connects the agent to messaging platforms like Telegram, Slack, and Discord.

OpenClaw is fully self-hosted. Your agents run on your own machine or server. Data stays local, and you are not dependent on any OpenClaw cloud service. The only external dependency is the language model API you choose, and even that can be replaced with a local model via Ollama.

Core Framework Concepts

Before diving into configuration, it helps to understand the four key files the OpenClaw framework uses. Most OpenClaw workflows involve only SOUL.md. The others become relevant as your setup grows.

SOUL.md — Agent Identity and Behavior

The SOUL.md file is the central configuration document for any OpenClaw agent. It is a structured markdown file with named sections. The gateway parses these sections to build the agent's system prompt, configure its tools, and set its communication behavior. Every agent needs exactly one SOUL.md file.

# Content Writer

## Identity
- Name: Echo
- Role: Content Writer and SEO Specialist
- Model: claude-sonnet-4-5

## Personality
- Clear, concise, and well-structured
- Matches the tone of the target audience
- Always explains the "why" behind recommendations

## Rules
- ALWAYS respond in English only
- Write in active voice, avoid passive constructions
- Include a call-to-action in every piece of content
- Flag requests outside the content scope to @Orion

## Skills
- browser: Research topics and analyze competitor content
- file-manager: Read briefs and save finished drafts

## Memory
- Remember content calendar and brand voice guidelines

## Channels
- telegram: true
- slack: true

HEARTBEAT.md — Scheduled Tasks

HEARTBEAT.md defines scheduled actions your agent runs automatically. You list tasks with cron-style timing and a plain English instruction. The gateway's scheduler reads this file and triggers tasks at the specified intervals without any external cron configuration.

# Heartbeat Schedule

## Daily Tasks
- 09:00 AM: Check analytics dashboard and post daily metrics to Slack
- 06:00 PM: Review today's completed tasks and prepare end-of-day summary

## Weekly Tasks
- Monday 08:00 AM: Generate content calendar for the week
- Friday 04:00 PM: Compile weekly performance report

## Hourly Tasks
- Every 2 hours: Check support queue and flag urgent tickets

MEMORY.md — Persistent Knowledge

MEMORY.md is the agent's long-term memory store. The agent can read from and write to this file across sessions, allowing it to remember facts, preferences, past decisions, and context that would otherwise be lost when a session ends. Unlike the context window of an LLM, memory persists indefinitely and is human-readable.

# Agent Memory

## Brand Guidelines
- Primary color: Orange (#F97316)
- Tone: Direct and technical, avoid corporate jargon
- Target audience: Solo developers and small startup teams
- Content goal: Drive signups, focus on practical examples

## Past Decisions
- Decided to use Next.js App Router over Pages Router (Jan 2026)
- Switched from weekly to daily reporting after user feedback (Feb 2026)

## Key Contacts
- Design lead: Responds fastest on Slack, not email
- Legal review: Required for any pricing-related content changes

AGENTS.md — Multi-Agent Team Definition

AGENTS.md defines the team structure when you run multiple agents together. It lists each agent, its SOUL.md path, and the model it uses. The gateway reads this file to know which agents to load, and agents use the names defined here to hand off tasks via @mentions.

# Team Configuration

## Agents

### @Orion
- SOUL: ./agents/orion/SOUL.md
- Model: claude-sonnet-4-5
- Role: Project manager and task coordinator

### @Echo
- SOUL: ./agents/echo/SOUL.md
- Model: claude-sonnet-4-5
- Role: Content writer and SEO specialist

### @Radar
- SOUL: ./agents/radar/SOUL.md
- Model: gpt-4o
- Role: SEO analyst and keyword researcher

## Workflow
1. @Orion receives requests and assigns tasks
2. @Radar researches keywords and passes brief to @Echo
3. @Echo writes content and flags for @Orion review

Installation and Prerequisites

OpenClaw requires Node.js 22 or later. That is the only system dependency. No Python environment, no Docker, no database setup. The framework installs via npm and runs as a local process.

# Install nvm if you don't have it
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node.js 22
nvm install 22 && nvm use 22

# Verify version
node --version   # Should print v22.x.x

npx openclaw onboard

# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-api03-...

# OpenAI (GPT-4)
export OPENAI_API_KEY=sk-proj-...

# Google (Gemini)
export GOOGLE_API_KEY=AIza...

# Install Ollama from ollama.ai, then pull a model
ollama pull llama3          # General purpose
ollama pull mistral         # Fast and capable
ollama pull phi4            # Lightweight, good for RPi

# Register the agent workspace
openclaw agents add my-agent --workspace ./agents/my-agent

# Start the gateway
openclaw gateway start

# Or run in background (daemon mode)
openclaw gateway start --daemon

# Check running agents
openclaw agents list

# View live logs
openclaw gateway logs --follow

Configuration System: config.yaml and SOUL.md

OpenClaw uses two configuration layers. The SOUL.md file defines the agent's behavior at the application level. The config.yaml file handles infrastructure settings: which model provider to use, API keys, port settings, and logging. Understanding how these two layers interact helps you manage more complex setups.

The config.yaml file sits in your project root or the agent workspace directory. Settings in config.yaml apply to all agents unless overridden by individual SOUL.md configurations. This makes it easy to set a default model for the whole team while letting specific agents use a different provider.

# OpenClaw Project Configuration

gateway:
  port: 18789
  daemon: false
  log_level: info
  auto_restart: true

model:
  provider: anthropic
  model: claude-sonnet-4-5
  max_tokens: 4096
  temperature: 0.7

agents:
  workspace: ./agents
  manifest: ./AGENTS.md

memory:
  enabled: true
  max_size: 50000   # characters

channels:
  telegram:
    enabled: true
    bot_token: {process.env.TELEGRAM_BOT_TOKEN{"}"}
  slack:
    enabled: false

Individual agents can override any config.yaml setting in their SOUL.md. For example, an agent that needs GPT-4o instead of the default Claude simply adds a Model line to its Identity section. The gateway resolves configuration by merging the project config with any agent-level overrides, with the agent-level settings taking precedence.

Skills System: How Agent Tools Work

Skills are the tools that give OpenClaw agents the ability to take action beyond generating text. Each skill is a modular plugin that the framework loads when the agent starts. You enable skills by listing them in your SOUL.md. The gateway injects the available tools into the agent's context, and the language model decides when to use them.

You enable a skill with a single line in the Skills section of SOUL.md. You can optionally add a description that tells the agent when to use it, which improves accuracy for agents with multiple tools.

## Skills
- browser: Use to research topics and analyze competitor pages
- file-manager: Use to read briefs and save completed drafts
- shell: Use to run reporting scripts and data exports
- memory: Use to recall brand guidelines and past decisions

Custom skills can be added by implementing the OpenClaw skill interface and registering the plugin in config.yaml. This allows teams with specific requirements to extend the framework without modifying core code.

Channel Integrations

Channels are built-in integrations that connect your agent to the outside world. OpenClaw handles the connection, message routing, and delivery automatically once you provide the required token. You do not need to write bot code or manage webhooks.

Enabling a channel is a one-line change in SOUL.md. The gateway reads the channel configuration and establishes the connection when it starts. Agents can be active on multiple channels simultaneously and will respond in the same channel the message was received on.

## Channels
- telegram: true   # Reads TELEGRAM_BOT_TOKEN from env
- slack: true      # Reads SLACK_BOT_TOKEN and SLACK_APP_TOKEN from env
- discord: false
- email: false

export TELEGRAM_BOT_TOKEN=7123456789:AAF...
export SLACK_BOT_TOKEN=xoxb-...
export SLACK_APP_TOKEN=xapp-1-...

Model Support: Cloud and Local

OpenClaw is model-agnostic. You select the language model that powers each agent, and you can assign different models to different agents based on their role, cost sensitivity, and privacy requirements. The framework abstracts the provider differences so your SOUL.md stays the same regardless of which model you use.

A practical pattern for multi-agent teams is to use Claude or GPT-4 for agents that handle complex reasoning and writing, and route simpler classification or summarization tasks to a local Ollama model to reduce API costs. You switch models per agent with one line in SOUL.md.

## Identity
- Name: Radar
- Role: SEO Analyst
- Model: gpt-4o          # Override project default

## Identity
- Name: Classifier
- Role: Support Ticket Triage
- Model: ollama/mistral   # Free local model for simple tasks

For a full walkthrough of running agents entirely on local models, see our guide to OpenClaw with Ollama.

Gateway and Daemon: How Agents Stay Running

The OpenClaw gateway is the process that brings all your agents to life. It is a Node.js server that loads your agent configurations, connects to language model providers, manages conversation sessions, and routes messages between channels and agents. The gateway listens on port 18789 by default.

In development, you run the gateway in the foreground and see logs in real time. In production, you run it in daemon mode so it continues running after your terminal session closes and restarts automatically if the process crashes.

# Start gateway (foreground, shows live logs)
openclaw gateway start

# Start gateway as background daemon
openclaw gateway start --daemon

# Restart the gateway (picks up config changes)
openclaw gateway restart

# Stop the gateway
openclaw gateway stop

# View live logs from daemon
openclaw gateway logs --follow

# Check gateway status
openclaw gateway status

For production deployments on a VPS or Mac Mini, you can wrap the gateway in a system service (systemd on Linux, launchd on macOS) to ensure it starts on boot and restarts after server reboots. The gateway also supports auto_restart: true in config.yaml to recover from crashes without manual intervention.

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/my-agents
ExecStart=/usr/local/bin/openclaw gateway start
Restart=always
RestartSec=10
Environment=ANTHROPIC_API_KEY=sk-ant-...
Environment=TELEGRAM_BOT_TOKEN=7123...

[Install]
WantedBy=multi-user.target

Multi-Agent Orchestration

OpenClaw supports multi-agent teams through the AGENTS.md file and an @mention routing system. Each agent in the team has its own SOUL.md and runs as a separate process under the same gateway. When an agent needs to hand off work, it uses an @mention in its response and the gateway routes the message to the correct agent automatically.

The handoff instructions live in each agent's SOUL.md Rules section. For example, you might tell the content writer to @mention the editor when a draft is complete, and tell the editor to @mention the project manager when final copy is approved. The entire workflow runs without human intervention.

## Rules
- Complete content research before drafting anything
- After finishing a draft, always hand off to @editor with the message:
  "@editor — Draft ready for review: [title]. File saved to ./drafts/[filename].md"
- If the brief is unclear or missing a target keyword, escalate to @orion
- NEVER publish directly; all content must go through @editor first

Agent-to-agent messages stay entirely within your local gateway. They never leave your machine, which means your internal workflows are private and latency is negligible. This is a significant advantage over multi-agent systems that route messages through external APIs or cloud orchestration services.

Who Should Use OpenClaw?

OpenClaw fits a specific type of user well. Understanding who it is designed for helps you decide whether it is the right tool for your situation.

Limitations and When to Consider Alternatives

OpenClaw is a strong choice for the use cases above, but it is not the right tool for every situation. Here is where it falls short and when you should consider a different framework.

Related Guides

Frequently Asked Questions