How to Set Up OpenClaw on a Mac Mini (Complete 2026 Guide)

What Is OpenClaw?

OpenClaw is an open-source framework that turns large language models into persistent, always-on AI agents. Unlike ChatGPT or Claude's web apps — where conversations end when you close the tab — OpenClaw runs on your hardware, stays online 24/7, and connects to your real life through channels like Telegram, Discord, and WhatsApp.

Think of it as the operating system for a personal AI. It handles:

• → Multi-channel messaging — talk to your agent from Telegram, Discord, WhatsApp, or all three simultaneously
• → Memory and continuity — your agent remembers context across sessions, days, and weeks
• → Tool use — browse the web, read files, run code, manage calendars, send emails
• → Proactive behavior — heartbeats let your agent check your inbox, calendar, and more without being asked
• → Personality — define who your agent is with a SOUL.md file, not just what it does

It's the difference between a chatbot and an assistant. An assistant that's always there, knows your preferences, and can actually do things.

Hardware Requirements

OpenClaw itself is lightweight — it's a Node.js process that orchestrates API calls, not a local model runner. The hardware requirements are modest:

Installation Step by Step

# Install Homebrew (if you don't have it)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node

# Verify
node --version   # Should be v20+
npm --version

# On macOS: System Settings → Users & Groups → Add User
# Name: openclaw
# Account type: Standard

# On Linux:
sudo adduser openclaw
sudo usermod -aG sudo openclaw

npm install -g openclaw

openclaw --version

openclaw init

Initial Configuration

OpenClaw's brain lives in ~/.openclaw/openclaw.yaml (or .json — YAML is more readable). This is where you wire up your AI provider, channels, and behavior.

The Essentials

# ~/.openclaw/openclaw.yaml

# Your AI provider — OpenClaw works with any OpenAI-compatible API
ai:
  provider: anthropic          # or openai, openrouter, etc.
  model: claude-sonnet-4-20250514     # default model for conversations
  apiKey: sk-ant-xxxxx         # or use ANTHROPIC_API_KEY env var

# Gateway — the service that manages connections
gateway:
  bind: 127.0.0.1:3000         # local only by default
  # remote:
  #   url: https://your-domain.com  # for remote access

# Agent identity
agent:
  name: "MyAgent"
  workspace: ~/.openclaw/workspace

Environment Variables

Create ~/.openclaw/.env for your secrets:

# ~/.openclaw/.env
ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENAI_API_KEY=sk-your-key-here        # optional, for tool use
TELEGRAM_BOT_TOKEN=123456:ABC-xyz      # we'll set this up next

Setting Up Channels

Channels are how you talk to your agent. You can set up one or all of these — they work independently.

# In openclaw.yaml under channels:
channels:
  telegram:
    botToken: ${TELEGRAM_BOT_TOKEN}
    allowedUsers:
      - 123456789    # Your Telegram user ID
    # Get your ID: message @userinfobot on Telegram

channels:
  discord:
    botToken: ${DISCORD_BOT_TOKEN}
    allowedGuilds:
      - "YOUR_SERVER_ID"

Writing Your SOUL.md

This is what makes OpenClaw different from a generic chatbot. SOUL.md defines your agent's personality, values, and behavior. It's loaded at the start of every session and shapes every response.

Your SOUL.md lives at ~/.openclaw/workspace/SOUL.md. Here's what a good one covers:

# SOUL.md — Who You Are

## Personality
- Direct and concise. No filler words.
- Has opinions. Disagrees when warranted.
- Dry humor. Never forces jokes.

## Principles
- Be resourceful before asking questions.
- Actions over words — do the thing, don't talk about doing the thing.
- Private things stay private. Always.

## Communication Style
- Match the user's energy. Short question → short answer.
- Use code blocks for anything technical.
- In group chats: contribute, don't dominate.

## Boundaries
- Never send emails or public posts without explicit confirmation.
- Ask before any destructive operation.
- When uncertain, say so.

You'll also want to fill in USER.md (info about yourself — name, timezone, preferences) and IDENTITY.md (your agent's name, emoji, and vibe). These give the agent context about who it's helping.

Configuring Heartbeats and Cron Jobs

Heartbeats are what make your agent proactive instead of purely reactive. At a configurable interval, OpenClaw pings your agent and says "anything to do?" The agent can then check email, scan calendars, follow up on tasks, or just go back to sleep.

Heartbeat Configuration

# In openclaw.yaml
heartbeat:
  enabled: true
  interval: 30m              # How often to ping
  prompt: |
    Read HEARTBEAT.md if it exists. Follow it strictly.
    If nothing needs attention, reply HEARTBEAT_OK.
  channels:
    - telegram:direct:YOUR_USER_ID   # Where proactive messages go

Create a HEARTBEAT.md in your workspace to tell the agent what to check:

# HEARTBEAT.md
- Check email for anything urgent
- Check calendar for events in the next 2 hours
- If it's morning (8-9 AM), give a brief day overview

Cron Jobs

For tasks that need exact timing — "every Monday at 9 AM, send me a weekly summary" — use cron jobs instead of heartbeats:

# In openclaw.yaml
cron:
  weekly-summary:
    schedule: "0 9 * * 1"     # Every Monday at 9 AM
    prompt: "Write a brief summary of last week's activity and upcoming events."
    channel: telegram:direct:YOUR_USER_ID
    model: claude-sonnet-4-20250514        # Can use a different model per job

Setting Up Memory and Persistence

Every time your agent starts a new session, it wakes up fresh — no memory of previous conversations. That's where the memory system comes in. OpenClaw uses plain Markdown files for memory, which means it's transparent, versionable, and you can read it yourself.

How Memory Works

• → Daily notes (memory/YYYY-MM-DD.md) — raw logs of what happened each day. Created automatically by the agent.
• → Long-term memory (MEMORY.md) — curated insights, preferences, and important context. The agent distills daily notes into this periodically.
• → Session startup — each session, the agent reads SOUL.md, USER.md, today's and yesterday's daily notes, and MEMORY.md. This is how it "remembers."

Directory Structure

~/.openclaw/workspace/
├── SOUL.md           # Agent personality
├── USER.md           # About you
├── IDENTITY.md       # Agent's name/avatar
├── MEMORY.md         # Long-term memory (curated)
├── AGENTS.md         # Workspace rules and conventions
├── HEARTBEAT.md      # What to check on heartbeats
├── TOOLS.md          # Local tool configuration notes
└── memory/
    ├── 2026-03-19.md # Daily notes
    ├── 2026-03-20.md
    └── 2026-03-21.md

The beauty of file-based memory: you can git init the workspace and track changes over time. You can read exactly what your agent remembers. No opaque vector databases — just Markdown.

Remote Access (Tailscale + DeskPad + Screen Sharing)

If your Mac Mini is running headless in a closet (as it should be), you'll want remote access for maintenance. Here's the battle-tested stack:

Tailscale — Secure Networking

Tailscale creates a private network between your devices. No port forwarding, no dynamic DNS, no firewall holes.

# Install Tailscale
brew install --cask tailscale

# Or download from https://tailscale.com/download/mac
# Sign in and connect — that's it.

Once connected, your Mac Mini gets a stable IP on your Tailscale network (like 100.x.x.x). You can SSH into it from anywhere:

ssh openclaw@100.x.x.x

DeskPad — Virtual Display

A headless Mac has no display, which means screen sharing shows nothing useful. DeskPad creates a virtual display:

brew install --cask deskpad

Launch DeskPad, and it creates a virtual screen you can connect to via Screen Sharing or VNC.

Screen Sharing

Enable in System Settings → General → Sharing → Screen Sharing. Then from any other Mac:

# In Finder: Go → Connect to Server
vnc://100.x.x.x    # Your Tailscale IP

Now you can manage your Mac Mini's GUI from your laptop, phone, or anywhere with Tailscale access.

Preventing Sleep for Always-On Operation

An agent that sleeps isn't much of an agent. Here's how to keep your Mac Mini awake and OpenClaw running:

Disable Sleep

# Prevent sleep entirely
sudo pmset -a sleep 0
sudo pmset -a disablesleep 1
sudo pmset -a displaysleep 0

# Verify settings
pmset -g

Also go to System Settings → Energy and uncheck "Put hard disks to sleep when possible" and enable "Start up automatically after a power failure."

Auto-Start OpenClaw

Use a Launch Agent to start OpenClaw on boot:

# Create the plist
cat > ~/Library/LaunchAgents/com.openclaw.gateway.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.openclaw.gateway</string>
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/openclaw</string>
    <string>gateway</string>
    <string>start</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/openclaw.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/openclaw-error.log</string>
</dict>
</plist>
EOF

# Load it
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist

With KeepAlive set to true, macOS will restart the OpenClaw gateway if it crashes. Combined with "Start up after power failure," your agent will survive reboots and power outages.

Start the Gateway

If you want to start manually first (recommended for initial testing):

# Start the gateway
openclaw gateway start

# Check status
openclaw gateway status

# View logs
tail -f /tmp/openclaw.log

Common Issues and Troubleshooting

Next Steps

If you've followed this guide, you should have a fully running OpenClaw agent. It responds to messages, has a personality, checks in proactively, remembers things, and survives reboots. That's a real agent.

From here, you can explore:

• → Skills — install community skills from ClawHub for GitHub, email, weather, Obsidian, and more
• → Multiple channels — add Discord for group chats, WhatsApp for mobile
• → Sub-agents — spawn background agents for coding tasks, research, or long-running jobs
• → Voice — add TTS for spoken responses (great for stories and summaries)
• → Home automation — connect to HomeKit, cameras, smart devices

The workspace files are yours to evolve. The more you use your agent, the more it learns about you, and the more useful it becomes. That's the whole point.