OpenClaw Complete Setup: Memory, Heartbeats, Skills, and Production Config

You have OpenClaw installed and your agent responds on Telegram. Now what?

The 30-minute quick start guide gets you from zero to a working agent. This guide picks up where that one leaves off. It covers the configuration that turns a basic chatbot into a production-grade autonomous agent: persistent memory, heartbeat scheduling, skill installation, cron jobs, multi-channel messaging, and the settings that make the difference between an agent that works and one that works reliably.

This is the intermediate guide. Some terminal comfort required.

What OpenClaw Actually Is

OpenClaw is a gateway that sits between you and an AI model. Instead of chatting in a browser tab that forgets everything when you close it, OpenClaw creates a persistent agent that:

• Remembers everything across conversations (via Markdown files it reads and writes)
• Runs on a schedule with heartbeats and cron jobs (checking tasks, sending updates)
• Connects to real messaging apps so you talk to it on Telegram, WhatsApp, or Discord, not a web interface
• Accesses your machine to run commands, read files, browse the web, and execute code
• Gets smarter over time as its memory files accumulate knowledge about your preferences, projects, and workflows

Think of it as the difference between hiring someone for a one-hour consultation versus hiring a full-time assistant who learns your business.

What You Need Before Starting

Before installing anything, make sure you have:

• A computer that stays on (Mac, Linux, or Windows with WSL2). A Mac Mini, a VPS, or any always-on machine works. A laptop works too, but your agent sleeps when the lid closes.
• Node.js 22 or newer installed. Check with node --version in your terminal. Install from nodejs.org if needed.
• Access to an AI model via one of the options below (subscription or API key).
• A Telegram account (for this guide). OpenClaw supports 20+ channels including WhatsApp, Discord, Signal, and Slack, but Telegram is the fastest to set up.

Choosing Your Model Access (Subscription vs. API)

This is the most common question beginners have: do you need an API key, or can you use the Claude/ChatGPT subscription you already pay for? The answer is both options work. Here's how they compare:

Option A: Use Your Claude Pro or Max Subscription (Easiest for Beginners)

If you already have a Claude Pro ($20/month) or Claude Max ($100-200/month) subscription, you can use it directly with OpenClaw. No API key needed.

This works through setup-tokens generated by the Claude Code CLI:

1. Install the Claude Code CLI on any machine: follow the Claude Code setup instructions
2. Log in to the CLI with your Claude subscription account
3. Generate a setup-token:

claude setup-token

4. During OpenClaw onboarding, choose "Anthropic token (paste setup-token)" and paste it in

Or if OpenClaw is already installed:

openclaw models auth setup-token --provider anthropic

Option B: Use an API Key (Most Flexible)

Create an API key from your provider's console and pay per token:

• Anthropic (Claude): console.anthropic.com (recommended)
• OpenAI (ChatGPT): platform.openai.com/api-keys
• OpenRouter (many models): openrouter.ai/keys

During onboarding, choose the API key option and paste it in. Or set it in your config:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  }
}

Option C: Use OpenRouter (One Key, Many Models)

OpenRouter provides a single API key that routes to Claude, ChatGPT, Gemini, Llama, Mistral, and dozens of other models. This is great for experimenting or switching models without managing multiple API keys.

openclaw onboard --auth-choice apiKey --token-provider openrouter --token "sk-or-..."

Which Option Should You Choose?

All options work equally well with OpenClaw. The onboarding wizard walks through whichever you choose.

Step 1: Install OpenClaw

Open your terminal and run:

curl -fsSL https://openclaw.ai/install.sh | bash

iwr -useb https://openclaw.ai/install.ps1 | iex

openclaw onboard --install-daemon

openclaw gateway status

openclaw gateway start

At this point, you already have a working agent. Open the built-in dashboard with openclaw dashboard and you can chat with it directly in the browser at http://127.0.0.1:18789/.

But a browser chat tab isn't why you're here. Let's connect it to Telegram.

Step 2: Create a Telegram Bot

Telegram is the fastest channel to set up because it uses a simple bot token (no phone number pairing, no QR codes, no OAuth flows).

openclaw configure --section channels

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN_HERE",
      "dmPolicy": "pairing"
    }
  }
}

openclaw gateway restart

openclaw pairing list telegram
openclaw pairing approve telegram YOUR_CODE

Step 3: Give Your Agent an Identity

Your agent's personality and behavior are defined by Markdown files in the workspace at ~/.openclaw/workspace/. The onboarding wizard creates starter files, but customizing them is where the magic happens.

SOUL.md (Who the Agent Is)

This defines personality, tone, and boundaries:

# SOUL.md

## Who I Am
I'm a productivity-focused AI assistant. I'm direct, proactive,
and I always lead with what I've done rather than what I need.

## Communication Style
- Clear and concise
- Lead with results, not questions
- Honest about limitations
- Friendly but professional

## Boundaries
- I never share personal information about my operator
- I verify before taking destructive actions
- I ask for confirmation before spending money

AGENTS.md (How the Agent Operates)

This is the operating manual, covering rules, workflows, and priorities:

# AGENTS.md

## Operating Rules
- Always check memory before answering questions about prior work
- Write important decisions and facts to memory immediately
- When given a task, start working on it instead of asking clarifying questions
  (unless the task is genuinely ambiguous)
- Provide status updates, not play-by-play narration

## Priorities
1. Respond to direct requests
2. Complete in-progress tasks
3. Proactive improvements and monitoring

USER.md (Who You Are)

Tell the agent about yourself so it can personalize its responses:

# USER.md

## About
- Name: [Your name]
- Timezone: America/New_York
- Location: New York City

## Work
- Role: Software developer at a startup
- Key tools: VS Code, GitHub, Slack

## Preferences
- Prefers concise communication
- Values proactive action over asking for permission
- Morning person, usually available 8 AM to 6 PM

TOOLS.md (Local Environment Notes)

Notes about your specific setup that help the agent use tools effectively:

# TOOLS.md

## GitHub
- Username: your-github-handle
- SSH auth configured

## Project Directories
- Main project: ~/projects/my-app
- Blog: ~/projects/blog

Step 4: Set Up Memory (The Superpower)

Memory is what separates OpenClaw from every other AI chat. Your agent writes notes to Markdown files that persist across sessions, conversations, and restarts. It reads those notes at the start of every session. Knowledge compounds.

How Memory Works

Two layers:

• MEMORY.md in the workspace root: Long-term curated facts (people, projects, preferences, lessons learned)
• memory/YYYY-MM-DD.md files: Daily logs (what happened today, decisions made, tasks completed)

The agent writes to these files during conversations. When a session gets long, OpenClaw automatically prompts the agent to save important information before compacting the context.

Memory Search

OpenClaw builds a vector index over your memory files so the agent can semantically search past knowledge. If you told it about a project three weeks ago, it can find that information even if the exact words are different.

Memory search works out of the box with remote embeddings (OpenAI or Gemini). For fully local embeddings:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "local"
      }
    }
  }
}

Best Practices for Memory

• Tell your agent "remember this" when sharing important information
• Periodically review MEMORY.md and clean up outdated entries
• Use memory/daily files for session-specific context
• Keep MEMORY.md under 20KB for fast loading (move old content to archives)

Step 5: Configure Heartbeats (Always-On Mode)

Heartbeats are periodic check-ins where your agent wakes up, looks at its task list, and takes action if needed. This is what makes it "always-on" rather than "responds when you message."

By default, heartbeats run every 30 minutes. The agent reads HEARTBEAT.md for instructions:

# HEARTBEAT.md

## Check These
- Any pending tasks in the project backlog?
- New messages or notifications to process?
- Scheduled reports due?

The agent evaluates whether anything needs attention. If nothing does, it replies HEARTBEAT_OK and goes quiet (no message is sent to you). If something needs action, it handles it and sends you the results.

Tuning Heartbeats

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m"
      }
    }
  }
}

Set to "0m" to disable heartbeats entirely (recommended when first setting up, enable once comfortable). Set to "15m" for more responsive behavior, but be aware this burns more API tokens. See the heartbeat docs for advanced configuration.

Step 6: Set Up Cron Jobs (Scheduled Automation)

Cron jobs are scheduled tasks that run at specific times. They're more powerful than heartbeats because they can carry specific instructions and run in isolated sessions.

Creating Your First Cron Job

openclaw cron add \
  --name "Morning Brief" \
  --cron "0 9 * * *" \
  --session isolated \
  --message "Generate a morning status report. Check calendar, pending tasks, and any overnight notifications. Send summary to Telegram." \
  --delivery announce

This creates a job that runs every day at 9 AM, generates a status report, and sends it to your Telegram chat.

Useful Cron Job Ideas

Managing Cron Jobs

openclaw cron list              # See all jobs
openclaw cron run <job-id>      # Trigger immediately
openclaw cron runs --id <id>    # View run history
openclaw cron remove <job-id>   # Delete a job

Step 7: Connect Additional Channels

Telegram is just the starting point. OpenClaw supports over 20 messaging channels:

Other supported channels include Slack, Google Chat, iMessage, Mattermost, Matrix, Microsoft Teams, Line, and more.

Each channel is added through the configuration wizard:

openclaw configure --section channels

Or by editing ~/.openclaw/openclaw.json directly. Each channel has its own section with authentication details and behavior settings.

WhatsApp (Requires a Second Number)

WhatsApp connects via QR code pairing. A dedicated phone number is recommended to avoid mixing personal messages with agent messages:

openclaw channels login

Scan the QR code with the WhatsApp app on the second phone. Set channels.whatsapp.allowFrom to restrict who can message the bot.

Discord (Bot Application)

Create a bot in the Discord Developer Portal, add it to your server, and configure the token:

{
  "channels": {
    "discord": {
      "enabled": true,
      "botToken": "YOUR_DISCORD_BOT_TOKEN"
    }
  }
}

Step 8: Add Skills (Expand Capabilities)

Skills are packaged instructions that teach your agent how to handle specific tasks. They live in ~/.openclaw/workspace/skills/ as directories with a SKILL.md file and optional supporting resources.

Finding Skills

Browse community skills at clawhub.com or check what's bundled:

ls ~/.openclaw/workspace/skills/

Installing a Skill

Download or create a skill directory:

skills/
└── weather/
    └── SKILL.md

The agent automatically detects available skills and reads the relevant SKILL.md when a matching task comes in.

Creating Your Own Skills

A skill is just a Markdown file with instructions. Create skills/my-skill/SKILL.md:

---
name: daily-report
description: Generate daily project status reports
---

# Daily Report Skill

When asked to generate a daily report:

1. Check git log for today's commits
2. Review open issues on GitHub
3. Summarize progress in a clean format
4. Send via Telegram

Skills are one of the most powerful features for building a truly specialized agent. Over time, building a library of skills turns a general-purpose assistant into a domain expert.

Step 9: Security and Access Control

Running an AI agent with shell access on your machine requires careful security configuration. OpenClaw includes multiple layers of protection, but you need to configure them correctly. Full security documentation: docs.openclaw.ai/security.

DM Access Control

By default, OpenClaw uses pairing mode for Telegram DMs. Unknown senders must provide a pairing code that expires after 1 hour. This is the safest default. See pairing docs for details.

{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing",
      "allowFrom": ["YOUR_TELEGRAM_USER_ID"]
    }
  }
}

Group Access

For Telegram groups, control which groups the bot responds in and which senders it listens to:

{
  "channels": {
    "telegram": {
      "groups": {
        "-1001234567890": {
          "requireMention": true,
          "groupPolicy": "allowlist"
        }
      },
      "groupAllowFrom": ["YOUR_USER_ID"]
    }
  }
}

Gateway Authentication

The gateway API itself is protected by a token. Never expose port 18789 to the public internet without authentication:

{
  "gateway": {
    "auth": {
      "mode": "token"
    }
  }
}

Step 10: Going Always-On

For a truly autonomous agent, the gateway needs to run 24/7. The onboarding wizard can set this up automatically, but here's what happens under the hood:

macOS (LaunchAgent)

The --install-daemon flag during onboarding creates a LaunchAgent that starts the gateway on login:

# Check status
launchctl list | grep openclaw

# Manually start/stop
openclaw gateway start
openclaw gateway stop

Linux (systemd)

# Enable lingering (keeps service running after logout)
sudo loginctl enable-linger $USER

# Check status
systemctl --user status openclaw-gateway

# Start/stop
openclaw gateway start
openclaw gateway stop

Remote Access with Tailscale

For accessing your agent from anywhere (not just the host machine), Tailscale creates a private network between your devices:

# Install Tailscale on the host machine
# Then access the dashboard from any device on your tailnet
http://your-machine-name:18789/

This is far safer than exposing ports to the public internet.

The Complete Configuration File

Here's a real-world configuration that puts everything together. Two examples: one for API key users, one for subscription users.

If using an API key:

{
  "env": {
    // Keep all tokens/keys in env vars for security
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "TELEGRAM_BOT_TOKEN": "123456789:ABCdef...",
    "BRAVE_API_KEY": "YOUR_BRAVE_SEARCH_KEY"
  },
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-20250514" },
      "heartbeat": { "every": "30m" },
      "timeoutSeconds": 1800
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["YOUR_USER_ID"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "tools": {
    "web": {
      "search": {
        "enabled": true
      }
    }
  }
}

If using a Claude subscription (setup-token):

{
  "env": {
    "TELEGRAM_BOT_TOKEN": "123456789:ABCdef..."
  },
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-20250514" },
      "heartbeat": { "every": "30m" },
      "timeoutSeconds": 1800
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["YOUR_USER_ID"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

With the setup-token approach, no API key is needed in the config. The token handles authentication. Run openclaw models auth setup-token --provider anthropic to set it up.

After saving, protect the config file since it contains tokens:

chmod 600 ~/.openclaw/openclaw.json

Restart the gateway to apply changes: openclaw gateway restart

Common First-Week Tasks

Once your agent is running, try these to build confidence:

Troubleshooting Common Issues

Bot doesn't respond on Telegram

1. Check the gateway is running: openclaw gateway status
2. Verify the bot token: look for errors in openclaw logs --follow
3. Make sure you approved the pairing: openclaw pairing list telegram
4. Check your user ID is in allowFrom

Agent forgets things between conversations

1. Verify MEMORY.md exists in ~/.openclaw/workspace/
2. Tell the agent explicitly: "Write this to memory"
3. Check that memory search is working: the agent should use memory_search before answering questions about past work

High API costs

1. Reduce heartbeat frequency: set heartbeat.every to "60m" or "0m"
2. Use a cheaper model for routine tasks (Claude Sonnet instead of Opus)
3. Keep HEARTBEAT.md short (every word is a token)
4. Use the /compact command to manually compress long conversations

Gateway won't start

1. Check if something is already using port 18789: lsof -i :18789
2. Verify your config is valid JSON: openclaw doctor
3. Check logs for specific errors: openclaw logs --follow

What Comes Next

This guide covers the foundation. Once comfortable with the basics, explore:

• Building an AI Agent Team: Set up a coordinator agent that manages specialists for research, coding, and content
• AI Agents 2026 Guide: Understand the broader landscape of what agents can do
• Build Your First AI Agent: Deeper dive into agent architecture patterns

Official resources:

• OpenClaw Documentation (complete reference)
• OpenClaw GitHub (source code, issues)
• OpenClaw Discord (community support)
• ClaWHub (community skills and plugins)
• Gateway Configuration (all config options)
• Channel Setup Guides (WhatsApp, Discord, Slack, Signal, etc.)

The real power reveals itself over weeks, not minutes. As your agent accumulates memory about your projects, learns your communication preferences, and builds a library of skills, it transforms from a useful tool into something closer to an always-available team member who never forgets, never sleeps, and gets better at the job every day.

Start simple. Let it compound.