Mac Mini + OpenClaw + Claude Code: Complete Setup Guide

A step-by-step guide to setting up a headless AI agent on a Mac Mini, based on a production setup that's been running since January 2026. Your agent will be reachable via Slack, Telegram, WhatsApp, and more, with scheduled automations, browser control, and MCP integrations.

Last updated: March 17, 2026 — OpenClaw 2026.3.13. New sections: Model Management, Memory Search, Dashboard v2, Agent Control Protocol, Sandbox Containers, Backup & Recovery, Work Pulse pattern. See also: team-agents for multi-agent team coordination.

+---------------------------------------------------------------+
|                         Mac Mini                              |
|                                                               |
|   +--------------+   +--------------+   +--------------+     |
|   |   OpenClaw   |   |  Claude Code |   |   Browser    |     |
|   |   Gateway    |<->|   (Agent)    |<->|  (Headless)  |     |
|   |   :18789     |   |              |   |              |     |
|   +------+-------+   +------+-------+   +--------------+     |
|          |                  |                                 |
|     +----+----+        +----+----+                            |
|     |Channels |        |   MCP   |                            |
|     +---------+        | Servers |                            |
|     | Slack   |        +---------+                            |
|     |Telegram |        | Gmail   |                            |
|     |WhatsApp |        |Calendar |                            |
|     | Discord |        | Slack   |                            |
|     | Signal  |        +---------+                            |
|     |   ...   |                                               |
|     +---------+   +--------------+                            |
|                   |  Cron Jobs   |                            |
|                   |  Watchdogs   |                            |
|                   +--------------+                            |
+---------------------------------------------------------------+

---

Table of Contents

1. Prerequisites
2. Install OpenClaw
3. Install Claude Code
4. Workspace Setup
5. Channels Overview — how to talk to your agent
6. Create Your Slack App — start here if short on time
7. Telegram Bot Setup
8. WhatsApp Setup
9. MCP Servers
10. Gateway Configuration
11. Cron Jobs & Automation
12. Skills Installation
13. Notification Hooks
14. Browser Automation
15. Model Management & Fast Mode ✨ new
16. Memory Search ✨ new
17. Dashboard & Control UI
18. Agent Control Protocol ✨ new
19. Sandbox Containers ✨ new
20. Backup & Recovery ✨ new
21. Work Pulse — Autonomous Work Cycles ✨ new
22. Security Checklist
23. Known Issues & Workarounds
24. Quick Reference

---

1. Prerequisites

Hardware

• Mac Mini with Apple Silicon (M1/M2/M3/M4)
• macOS 15 Sequoia or later
• Stable internet connection (the agent runs 24/7)

Software

Install Homebrew first, then everything else:

# Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Node.js (required by OpenClaw)
brew install node

# GitHub CLI
brew install gh
gh auth login

# Python 3 (ships with macOS, but verify)
python3 --version

Accounts & Keys You'll Need

• Anthropic account — Claude Pro/Max subscription or Console API key
• GitHub account — for workspace repo and gh CLI
• Slack workspace — admin access to create a Slack app
• (Optional) Telegram account — to create a bot via @BotFather
• (Optional) WhatsApp — personal number for self-chat mode

---

2. Install OpenClaw

# Install globally
npm install -g openclaw

# Verify
openclaw --version

# Initial setup — creates ~/.openclaw/ directory
openclaw setup

# Interactive onboarding — walks you through:
# - Anthropic API key
# - Workspace directory
# - Channel configuration
openclaw onboard

# Fine-tune agent defaults
openclaw configure

After setup, your ~/.openclaw/ directory will look like:

~/.openclaw/
├── openclaw.json          # Main configuration (everything lives here)
├── agents/                # Agent state & sessions
├── browser/               # Headless browser profiles
├── credentials/           # Channel credentials (Telegram, WhatsApp)
├── cron/                  # Scheduled jobs
├── devices/               # Paired devices
├── hooks/                 # Custom hooks
├── hook-packs/            # Hook packages
├── identity/              # Device keypair (Ed25519)
├── logs/                  # Gateway & watchdog logs
├── scripts/               # Custom scripts (watchdogs, etc.)
└── skills/                # Bundled skills

Set Agent Defaults

In openclaw.json, configure:

{
  "agents": {
    "defaults": {
      "workspace": "/Users/YOUR_USERNAME/clawd",
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "1h"
      },
      "compaction": {
        "mode": "safeguard"
      },
      "heartbeat": {
        "every": "10m"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}

---

3. Install Claude Code

# Install Claude Code (native method)
# Follow: https://docs.anthropic.com/en/docs/claude-code/getting-started

# Verify
claude --version

# First run in your workspace — accept trust prompt
cd ~/clawd
claude

Configure Settings

Edit ~/.claude/settings.json:

{
  "effortLevel": "high"
}

See examples/settings.json.example for a full example with notification hooks.

---

4. Workspace Setup

Your workspace is the shared directory between OpenClaw and Claude Code. Think of it as your agent's brain.

# Create and initialize
mkdir -p ~/clawd
cd ~/clawd
git init

# Create the key files
touch AGENTS.md IDENTITY.md TOOLS.md USER.md MEMORY.md

Key Files

File	Purpose
AGENTS.md	Multi-agent coordination rules, Slack behavior, memory management
IDENTITY.md	Agent persona — name, personality, communication style
USER.md	Your context — who you are, timezone, preferences, working style
TOOLS.md	Local tool setup notes — SSH hosts, API quirks, device names
MEMORY.md	Long-term memory — credentials, baselines, recurring context
HEARTBEAT.md	Periodic check instructions (email, calendar, mentions)

Permissions

Create .claude/settings.local.json to allowlist tools and domains your agent can use:

{
  "permissions": {
    "allow": [
      "WebSearch",
      "Bash(openclaw:*)",
      "Bash(git:*)",
      "Bash(gh:*)",
      "Bash(npm:*)",
      "Bash(python3:*)",
      "Bash(curl:*)",
      "Bash(docker:*)",
      "Bash(brew:*)",
      "Bash(claude mcp:*)",
      "WebFetch(domain:docs.openclaw.ai)",
      "WebFetch(domain:github.com)",
      "WebFetch(domain:docs.anthropic.com)"
    ]
  }
}

See examples/settings.local.json.example for a more comprehensive permissions list.

Skills Directory

mkdir -p ~/clawd/skills

Skills are loaded from this directory automatically if you set skills.load.extraDirs in openclaw.json:

{
  "skills": {
    "load": {
      "extraDirs": ["/Users/YOUR_USERNAME/clawd/skills"]
    },
    "install": {
      "nodeManager": "npm"
    }
  }
}

---

5. Channels Overview

OpenClaw supports many ways to talk to your agent. Here's a comparison to help you decide which to set up.

Recommended Channels

Channel	Setup Time	Best For	Pros	Cons	Docs
Slack	20 min	Team collaboration	Socket mode (no public IP), reactions, threads, mention gating, most reliable	Requires Slack admin to create app	docs
Telegram	10 min	Personal/mobile alerts	Fastest to set up, great for cron job delivery, voice notes, inline buttons	Less common in work teams	docs
WhatsApp	30 min	Self-chat, personal use	Familiar, media support (50MB), reply threading	Connection drops, QR pairing required	docs

Other Supported Channels

Channel	Best For	Setup	Key Detail	Docs
Discord	Community, gaming	Medium	Voice channels, threads, slash commands, PluralKit support	docs
Signal	Privacy-first	Medium	End-to-end encrypted, DM + group support, 8MB media cap	docs
iMessage (BlueBubbles)	Apple ecosystem	Hard	macOS-only, requires BlueBubbles server, edit/unsend, tapbacks	docs
Microsoft Teams	Enterprise	Hard	Azure AD setup, RSC permissions, Adaptive Cards	docs
Mattermost	Self-hosted teams	Hard	Requires Mattermost instance, bot token + WebSocket	docs
Matrix	Federated/self-hosted	Medium	Open protocol, decentralized, self-hosted option	docs
Google Chat	Google Workspace	Easy	HTTP webhook, native Google integration	docs
IRC	Legacy systems	Hard	Classic protocol, persistent channels	docs
Nostr	Decentralized	Hard	Censorship-resistant, experimental	docs
WebChat	Quick access	Easy	Built-in gateway UI, no app needed — run openclaw dashboard	—

How to Choose

• Starting out? Set up Slack first — it's the most reliable and your team is already there.
• Want mobile notifications? Add Telegram — 10-minute setup, great for cron job delivery (morning briefings, reminders).
• Privacy-focused? Use Signal — end-to-end encrypted, no data stored externally.
• Apple-only team? iMessage via BlueBubbles keeps everything in the Apple ecosystem but requires a dedicated macOS machine (which you already have).
• Enterprise? Teams or Mattermost for compliance and IT control.

You can run multiple channels simultaneously — messages from any channel reach the same agent.

---

6. Create Your Slack App

This is the most important integration. Once Slack is working, you can message your agent from your phone, laptop, or any device with Slack.

Step 1: Create the App

1. Go to api.slack.com/apps
2. Click Create New App → From scratch
3. Name it (e.g., "Ercole" or "My Agent")
4. Select your workspace

Step 2: Enable Socket Mode

Socket mode is critical — it uses persistent WebSocket connections instead of webhooks, which is more reliable for a Mac Mini that may not have a public IP.

1. Go to Settings → Socket Mode
2. Toggle Enable Socket Mode → ON
3. Create an App-Level Token with connections:write scope
4. Save the token — it starts with xapp-

Step 3: Add Bot Token Scopes

Go to OAuth & Permissions → Scopes → Bot Token Scopes and add:

Scope	Why
chat:write	Send messages
channels:read	List channels
channels:history	Read channel messages
groups:read	List private channels
groups:history	Read private channel messages
im:read	List DMs
im:history	Read DMs
im:write	Open DMs
reactions:write	Add acknowledgment reaction
reactions:read	Read reactions
users:read	Look up user info
app_mentions:read	Detect @mentions

Step 4: Enable Events

Go to Event Subscriptions → Enable Events → Subscribe to bot events:

• message.channels
• message.groups
• message.im
• app_mention

Step 5: Install to Workspace

1. Go to Install App → Install to Workspace
2. Authorize the permissions
3. Copy the Bot User OAuth Token — starts with xoxb-

Step 6: Get Your Slack User ID

In Slack, click your profile → ... → Copy member ID (e.g., U0XXXXXXXXX).

Step 7: Configure OpenClaw

Add to openclaw.json:

{
  "channels": {
    "slack": {
      "mode": "socket",
      "webhookPath": "/slack/events",
      "botToken": "xoxb-YOUR-BOT-TOKEN",
      "appToken": "xapp-YOUR-APP-TOKEN",
      "userTokenReadOnly": true,
      "groupPolicy": "open",
      "actions": {
        "reactions": true
      },
      "dm": {
        "policy": "allowlist",
        "allowFrom": ["YOUR_SLACK_USER_ID"]
      },
      "channels": {
        "#your-agent-channel": {
          "allow": true,
          "requireMention": false
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "slack": {
        "enabled": true
      }
    }
  }
}

Step 8: Set Up Guard Rails

Your agent should be helpful to teammates while keeping you informed. Here's the approach that works well in practice:

In your workspace's AGENTS.md, define these rules:

1. Respond to anyone who tags the agent in Slack — be helpful, answer their question
2. Notify the owner via DM after every interaction with someone else:
   • If tagged in a channel: send the link to the message
   • If tagged in a DM: send the content of their message
3. Never load MEMORY.md in shared contexts — it contains personal data that shouldn't leak to others
4. DM policy stays as allowlist — only you can DM the agent directly

This gives teammates access to the agent's capabilities while keeping the owner in the loop on all interactions. The agent is helpful but doesn't volunteer private information.

Step 9: Test It

# Restart gateway to pick up changes
openclaw gateway restart

# Check status
openclaw status

Then send a message in your configured Slack channel. You should see:

1. 👀 reaction appears (acknowledgment)
2. Agent responds
3. 👀 reaction is removed

What Worked / What Didn't

Worked well:

• Socket mode is rock-solid for persistent connections
• The 👀 ack reaction is great UX — you know the agent saw your message
• requireMention: false in dedicated channels means no need to @mention
• Responding to everyone + DM notification to owner = best balance of helpful and informed

Watch out for:

• If the gateway restarts, socket mode reconnects automatically (usually within seconds)
• Keep groupPolicy: "open" if you want the agent to work in any channel it's invited to, or switch to "allowlist" for tighter control

---

7. Telegram Bot Setup

Good for personal/mobile notifications. The morning briefing and scheduled summaries get delivered here.

Step 1: Create a Bot

1. Message @BotFather on Telegram
2. Send /newbot
3. Follow the prompts — pick a name and username
4. Copy the bot token (looks like 1234567890:AABBccDDeeFFggHHiiJJkkLLmmNNoo)

Step 2: Get Your User ID

Message @userinfobot — it replies with your numeric user ID.

Step 3: Configure OpenClaw

{
  "channels": {
    "telegram": {
      "dmPolicy": "allowlist",
      "botToken": "YOUR_BOT_TOKEN",
      "allowFrom": [
        "your_telegram_username",
        "your_numeric_user_id"
      ],
      "groupPolicy": "allowlist",
      "streamMode": "partial"
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  }
}

Step 4: Test

openclaw gateway restart

Send a message to your bot on Telegram.

For the full setup guide, see: docs.openclaw.ai/channels/telegram

---

8. WhatsApp Setup (Optional)

WhatsApp uses a web-based client session. It works but has known stability issues.

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "selfChatMode": true,
      "allowFrom": ["+1YOUR_PHONE_NUMBER"],
      "groupPolicy": "allowlist",
      "mediaMaxMb": 50,
      "ackReaction": {
        "emoji": "👀",
        "direct": true,
        "group": "always"
      },
      "debounceMs": 0
    }
  },
  "plugins": {
    "entries": {
      "whatsapp": {
        "enabled": true
      }
    }
  }
}

Then pair via QR code:

openclaw channels login --verbose

Known issues: Connection drops (408, 503 errors) are common. The gateway auto-reconnects, but WhatsApp is the least reliable of the three channels. Good for self-chat, not recommended as your primary channel.

For the full setup guide, see: docs.openclaw.ai/channels/whatsapp

---

9. MCP Servers

MCP (Model Context Protocol) servers give Claude Code access to external services as tools.

Built-in Claude.ai Integrations

These are connected through your Claude account (no manual setup):

• Gmail — read/search/draft emails
• Google Calendar — list/create/update events, find free time
• Slack — search/read/send messages (separate from the OpenClaw Slack plugin)

Optional: Add PostHog (Analytics)

claude mcp add -s user --transport http posthog \
  https://mcp.posthog.com/mcp \
  --header "Authorization: Bearer YOUR_POSTHOG_API_KEY"

Get your key from PostHog → Settings → Personal API Keys → select "MCP Server preset".

List Configured MCP Servers

claude mcp list

Verify Connection

Inside Claude Code, run /mcp to check server status.

---

10. Gateway Configuration

The gateway is the core process that connects everything — channels, agent, cron, browser.

openclaw.json Gateway Section

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "GENERATE_A_RANDOM_TOKEN"
    },
    "tailscale": {
      "mode": "off"
    }
  }
}

Generate a token:

openssl rand -hex 24

Start the Gateway

# Foreground (for testing)
openclaw gateway

# Force restart (kills existing process first)
openclaw gateway --force

# Check health
openclaw health

# View logs
openclaw logs

Gateway as a Background Service

For 24/7 operation, set up a launchd plist so the gateway starts on boot. Example plist at ~/Library/LaunchAgents/com.openclaw.gateway.plist.

Remote Access via Tailscale (Optional)

If you want to reach the gateway from outside your network:

{
  "gateway": {
    "tailscale": {
      "mode": "on"
    }
  }
}

Requires Tailscale installed and configured on the Mac Mini.

---

11. Cron Jobs & Automation

OpenClaw has a built-in cron scheduler for recurring tasks.

Example: Morning Briefing

openclaw cron

Or configure directly in ~/.openclaw/cron/jobs.json. Here's what a daily morning briefing looks like:

{
  "id": "morning-briefing",
  "label": "Morning Briefing",
  "schedule": "30 6 * * *",
  "enabled": true,
  "prompt": "Prepare my morning briefing: check calendar, triage email, weather forecast.",
  "deliver": {
    "channel": "telegram",
    "target": "YOUR_TELEGRAM_USER_ID"
  }
}

Real-World Cron Job Examples

Job	Schedule	Description
Morning briefing	30 6 * * *	Calendar check, email triage, daily quote → Telegram
RSS monitors	45 11 * * *	Watch blogs (Paul Graham, Sam Altman, etc.) for new posts
Slack channel sync	0 8-20/2 * * *	Pull latest Slack channel history to a local log file
Database sync	0 23 * * *	Git push personal JSON databases
Mention monitor	*/5 * * * *	Check for unanswered Slack @mentions
Work Pulse kickoff	0 9 * * 1-5	Start autonomous work cycle on weekdays
Work Pulse	5,20,35,50 9-16 * * 1-5	Run work cycle every 15 min during the day
End of Day	0 17 * * 1-5	Summarize the day's work, post to Slack

Cron Commands Reference

openclaw cron list                      # List all jobs with status
openclaw cron runs --limit 20           # Show recent run history
openclaw cron status                    # Scheduler health
openclaw cron run <job-id>              # Trigger a job immediately (debug)
openclaw cron add --name "Daily Check" --schedule "0 9 * * *" --message "Run briefing"
openclaw cron edit <job-id> --enabled true
openclaw cron disable <job-id>
openclaw cron rm <job-id>

Job Types

// Recurring cron job
{
  "id": "morning-briefing",
  "name": "Morning Briefing",
  "enabled": true,
  "schedule": { "kind": "cron", "expr": "30 6 * * *", "tz": "America/Los_Angeles" },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat",
  "payload": {
    "kind": "agentTurn",
    "message": "Run my morning briefing..."
  }
}

sessionTarget: isolated (clean session, no shared context) or main (uses your running session) wakeMode: next-heartbeat (waits for agent heartbeat) or now (fires immediately)

Known Issue: One-Shot Jobs Are Broken

OpenClaw's at-style one-time reminders don't fire reliably (GitHub issue #43471). Workaround: use macOS launchd for one-shot reminders.

launchd workaround:

# Create a reminder script
cat > ~/clawd/reminders/schedule-reminder.sh << 'EOF'
#!/bin/bash
LABEL="com.openclaw.reminder.$(date +%s)"
TIME="$1"  # HH:MM format
MESSAGE="$2"
# Creates a launchd plist that fires once at the specified time
# See the reminders/ directory for full implementation
EOF
chmod +x ~/clawd/reminders/schedule-reminder.sh

Watchdog Scripts

The gateway can become unresponsive or drop Slack events silently. Two watchdog scripts handle this automatically:

Script	What It Monitors	Trigger
health-watchdog.sh	Gateway health endpoint	Restarts if openclaw health times out
gap-watchdog.sh	Slack event gaps in gateway.log	Restarts if "event gap detected" appears

Both have a 5-minute cooldown between restarts to avoid restart loops.

# Copy both watchdog scripts
mkdir -p ~/.openclaw/scripts
cp examples/health-watchdog.sh examples/gap-watchdog.sh ~/.openclaw/scripts/
chmod +x ~/.openclaw/scripts/*.sh

# Add both to crontab (runs every 5 minutes)
crontab -e
# Add these two lines:
# */5 * * * * ~/.openclaw/scripts/health-watchdog.sh
# */5 * * * * ~/.openclaw/scripts/gap-watchdog.sh

Important: Use the full path to the openclaw binary (e.g., /opt/homebrew/bin/openclaw) in watchdog scripts. The cron environment doesn't have the same PATH as your shell — we hit a bug where the health watchdog couldn't find node, causing false-positive restart loops.

---

12. Skills Installation

Skills extend what your agent can do. They live in the skills/ directory with a SKILL.md file that describes capabilities and provides context.

How Skills Work

~/clawd/skills/
└── my-skill/
    ├── SKILL.md          # Required: description, instructions, examples
    ├── scripts/          # Optional: helper scripts
    └── data/             # Optional: state files

The SKILL.md frontmatter:

---
name: my-skill
description: "What this skill does"
version: 0.1.0
---

# My Skill

Instructions for the agent on how to use this skill...

Installing Skills

# From ClawHub (if available)
clawdhub install skill-name

# Or manually — copy to skills directory
cp -r /path/to/skill ~/clawd/skills/

# Enable in openclaw.json (if needed)
openclaw config set skills.entries.my-skill.enabled true

Recommended Skills to Start With

Skill	Purpose
self-improving-agent	Logs errors and learnings automatically
google-calendar	Calendar API access
airtable	Query Airtable bases

Skills with Environment Variables

Some skills need API keys. Configure in openclaw.json:

{
  "skills": {
    "entries": {
      "open-wearables": {
        "enabled": true,
        "env": {
          "OPEN_WEARABLES_API_KEY": "sk-YOUR-KEY",
          "OPEN_WEARABLES_URL": "http://localhost:8000/api/v1"
        }
      }
    }
  }
}

---

13. Notification Hooks (Mac Mini Edition)

Since Mac Mini has no camera (no LED blink trick), we use voice + system notifications.

Quick Setup (Inline in settings.json)

Edit ~/.claude/settings.json:

{
  "effortLevel": "high",
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "say 'Need help'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "say 'Done'"
          }
        ]
      }
    ]
  }
}

Full Setup (With System Sound + Notification Banner)

For a richer experience with sound effects and macOS notification banners:

mkdir -p ~/.claude/hooks
cp examples/alert.sh examples/notify.sh examples/stop.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

Then in settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/alert.sh & ~/.claude/hooks/notify.sh; wait"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/stop.sh"
          }
        ]
      }
    ]
  }
}

What you'll hear:

• "Need help" + Glass chime + notification banner — when the agent needs your input
• "Done" — when the agent finishes

See also: claude-notification-hooks-mac-mini

---

14. Browser Automation

OpenClaw includes a built-in headless browser for tasks the agent can't do with APIs alone — OAuth re-auth, web scraping, screenshots, and interacting with pages that require JavaScript.

How It Works

OpenClaw manages a dedicated Chromium instance with its own profile, cookies, and login sessions. The agent can control it programmatically: open tabs, click elements, fill forms, take screenshots, and extract data.

Browser Profile Types

Type	How It Works	Best For
OpenClaw-managed (default)	Isolated Chromium instance managed by the gateway	Most use cases — OAuth, scraping, screenshots
user profile	Attaches to your signed-in Mac Chrome via DevTools	Pages where you're already logged in (no re-auth)
chrome-relay	Extension relay into live Chrome tabs	Reusing active browser sessions
Remote CDP	Connect to an external browser via WebSocket	Cloud-hosted browsers, CI/CD

Chrome DevTools Attach Mode (New in 2026.3.13)

Connect to your real signed-in Chrome instead of a headless instance. Useful when a site's login is hard to automate or you need your actual session state.

# 1. Launch Chrome with remote debugging enabled
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222

# 2. Open chrome://inspect/#remote-debugging to verify

# 3. Use the 'user' profile in your agent session
# In openclaw.json:
{
  "browser": {
    "defaultProfile": "user"
  }
}

Profile Management

openclaw browser profiles           # List all profiles
openclaw browser create-profile --name work
openclaw browser reset-profile --name openclaw  # Reset to clean state

Key Capabilities

• Deterministic tab control — list, open, focus, close tabs by ID
• AI snapshots — the agent sees a simplified representation of the page with numeric references it can click/type into
• State management — cookies, localStorage, credentials persist across sessions
• Device emulation — set geolocation, timezone, viewport size
• Console & network monitoring — capture errors, trace network requests
• Screenshots — saved to ~/.openclaw/media/browser/

Configuration

In openclaw.json:

{
  "browser": {
    "defaultProfile": "openclaw"
  }
}

Real-World Use Cases

• Google OAuth re-auth: OAuth tokens for unpublished Google apps expire after ~7 days. The agent uses the browser to re-authenticate headlessly instead of requiring manual intervention.
• Web scraping: Pages that require JavaScript rendering or login sessions.
• Taking screenshots: Visual verification of deployments, dashboards, or UI changes.
• Form submission: Filling out web forms that don't have an API.

Docs

Full browser tool documentation: docs.openclaw.ai/tools/browser

---

15. Model Management & Fast Mode

Configure which models your agent uses, set up aliases, and enable fast mode for quicker responses.

Model Aliases

Define short names for models in openclaw.json:

{
  "auth": {
    "models": {
      "aliases": {
        "opus": "anthropic/claude-opus-4-5",
        "opus4.6": "anthropic/claude-opus-4-6",
        "sonnet": "anthropic/claude-sonnet-4-6"
      }
    }
  }
}

Use aliases when sending messages: openclaw agent --model opus4.6 --message "..."

Fast Mode

Fast mode reduces latency at the cost of some throughput — good for quick back-and-forth.

openclaw models list                    # See available models
openclaw models set primary --model opus4.6
openclaw models aliases                 # List configured aliases
openclaw models scan --provider openrouter  # Discover available free models

Setting the Primary Model

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-6"
      }
    }
  }
}

---

16. Memory Search

OpenClaw indexes your workspace memory files for semantic search. Find anything your agent has written down.

openclaw memory status                  # Check indexing status
openclaw memory status --deep           # Probe embedding provider health
openclaw memory search "meeting notes"  # Semantic search
openclaw memory search --query "deployment" --max-results 20
openclaw memory index --force           # Reindex all memory files

Memory files indexed: everything in ~/your-workspace/memory/YYYY-MM-DD.md and MEMORY.md.

---

17. Dashboard & Control UI

The web dashboard gives you a visual interface to monitor and control your agent.

openclaw dashboard                      # Open web UI in browser

What's in the Dashboard (v2, 2026.3.13)

View	Purpose
Overview	Gateway health, active sessions, recent activity
Chat	Send messages to your agent from the browser
Config	View and edit openclaw.json visually
Agent	Per-agent settings, model selection
Session	Active session transcripts

Command palette available via Cmd+K. Mobile-responsive with bottom tab navigation.

Device Pairing

Each device gets its own auth token (new in 2026.3.12: short-lived bootstrap tokens for security):

openclaw pairing                        # Start pairing flow
openclaw pairing approve <channel> <code>

---

18. Agent Control Protocol

ACP lets you send messages directly to agent sessions via the gateway — useful for scripting, automation, and inter-agent communication.

openclaw acp client                     # Interactive CLI
openclaw acp --session main:main --message "Run daily check"
openclaw acp --provenance meta          # Include request metadata

Useful for triggering agent work from scripts or other processes without going through a messaging channel.

---

19. Sandbox Containers

Docker-based per-session isolation. Each agent session can run in its own container with controlled tool access.

openclaw sandbox list                   # List active sandboxes
openclaw sandbox list --browser         # Show browser sandboxes
openclaw sandbox recreate --all         # Recreate all containers
openclaw sandbox recreate --session main
openclaw sandbox explain                # Show effective sandbox policy

Requires Docker to be installed and running.

---

20. Backup & Recovery

Back up your entire OpenClaw setup: config, credentials, sessions, and workspace state.

openclaw backup create --output ~/openclaw-backup-$(date +%Y%m%d).tar.gz
openclaw backup verify ~/openclaw-backup.tar.gz

What's included: ~/.openclaw/openclaw.json, credentials, session history, device identity, cron jobs, hook configurations.

What's NOT included: Your workspace files (those are in git), skills, and browser profile data.

Recommended: schedule a weekly backup cron job.

---

21. Work Pulse — Autonomous Work Cycles

The Work Pulse pattern lets your agent work autonomously in 15-minute cycles throughout the day — checking its own progress, spawning sub-tasks, and reporting results without constant supervision.

How it works:

1. Morning Kickoff (9am) — Sets the day's goals and spawns initial work
2. Work Pulse (every 15 min) — Harvests completed work, assesses progress, spawns next tasks, posts a Slack checkpoint
3. End of Day (5pm) — Summarizes the day, posts report

Key insight: The agent can't track time itself — cron handles timing, the agent handles work. A lock file prevents overlapping pulses.

Setup: See the solo-founders/team-agents repo for the full Work Pulse protocol, state machine definition, and guard scripts. It's documented there as a team pattern rather than here.

# Example cron config for Work Pulse
# Morning kickoff
# 0 9 * * 1-5  → openclaw cron job → "Morning kickoff: read goals, plan the day, spawn work"
# Every 15 min
# 5,20,35,50 9-16 * * 1-5 → "Work pulse: harvest results, spawn next tasks, post checkpoint"
# End of day
# 0 17 * * 1-5 → "End of day: summarize, create daily log, post report"

---

22. Security Checklist

OpenClaw supports multiple paired devices, each with their own auth token.

How It Works

On first setup, OpenClaw generates an Ed25519 keypair stored in ~/.openclaw/identity/. This is your device identity.

Control UI (Web Dashboard)

openclaw dashboard

Opens a web-based control UI where you can:

• View active sessions
• Send messages to the agent
• Monitor health

Pair a New Device

openclaw pairing

---

22. Security Checklist

Setting	Recommended Value	Why
Gateway bind	loopback	Only accessible from localhost
Gateway auth	Token-based	Prevents unauthorized access
Slack DM policy	allowlist	Only you can DM the bot
Telegram DM policy	allowlist	Only your user ID can interact
WhatsApp DM policy	allowlist	Only your phone number
MEMORY.md loading	Main session only	Personal data doesn't leak to group chats
Workspace permissions	Explicit allowlist	Only approved commands run
Credentials	In ~/.openclaw/credentials/	Not in workspace repo

Device Pairing Security (New in 2026.3.12)

Unknown senders now get a short-lived bootstrap token instead of sharing gateway credentials. This means:

• New contacts trying to DM your agent get a one-time pairing code
• The code expires — no persistent credential exposure
• You approve pairing explicitly: openclaw pairing approve <channel> <code>

Token Generation

# For gateway auth token
openssl rand -hex 24

# For any API integration
openssl rand -hex 32

What NOT to Commit

Never commit these to your workspace repo:

• API keys and tokens
• credentials.json files
• ~/.openclaw/openclaw.json (contains all tokens)
• .env files

---

23. Known Issues & Workarounds

Issue	Impact	Workaround	Status
Cron one-shot jobs don't fire	Reminders broken	Use macOS launchd plist	Open (GH #43471)
Google OAuth expires ~7 days	Gmail/Calendar API fails	Browser automation re-auth or publish your Google app	Active workaround
Health watchdog can't find Node	False restart loops	Use full path /opt/homebrew/bin/openclaw in scripts	Easy fix
WhatsApp connection drops	408/503 errors	Gateway auto-reconnects; monitor logs	Intermittent
Slack thread sessions lack context	Agent responds confused in threads	Fetch thread context via API before responding	Open (GH #44638)
Slack message read threadId broken	Can't read thread replies	Use direct Slack API call	Open (GH #44591)

Slack Thread Context Workaround

When someone replies in a Slack thread, OpenClaw creates a new session for that thread. This session starts blank — the agent has no context of the parent message or prior thread replies.

Symptom: Agent responds to thread asking "what are you referring to?" even though the context is in the thread above.

Root cause: Thread sessions don't bootstrap with thread history. Filed as #44638.

Workaround script (~/clawd/scripts/slack-thread-context.sh):

#!/bin/bash
# Fetch Slack thread context using conversations.replies API
# Usage: slack-thread-context.sh <channel_id> <thread_ts> [limit]

CHANNEL="${1:?Usage: $0 <channel_id> <thread_ts> [limit]}"
THREAD_TS="${2:?Usage: $0 <channel_id> <thread_ts> [limit]}"
LIMIT="${3:-20}"
BOT_TOKEN="xoxb-YOUR-BOT-TOKEN"

curl -s "https://slack.com/api/conversations.replies?channel=${CHANNEL}&ts=${THREAD_TS}&limit=${LIMIT}" \
  -H "Authorization: Bearer ${BOT_TOKEN}" | \
  jq -r '.messages[] | "[\(.user)] \(.text[0:500])"'

Agent behavior update (add to AGENTS.md):

### Thread Context (CRITICAL)

**ALWAYS do this when responding in Slack threads:**
1. Check if session name contains `thread:TIMESTAMP`
2. If yes, fetch thread context BEFORE responding:
   ```bash
   ~/clawd/scripts/slack-thread-context.sh <channel_id> <thread_ts>

3. Read the context, then respond appropriately

How to extract channel/thread from session name:

• Session: agent:main:slack:channel:c0al7kz75tp:thread:1773368311.447129
• Channel: C0AL7KZ75TP (uppercase)
• Thread ts: 1773368311.447129

### Slack Channel Message Monitoring

To catch any missed @mentions (safety net):

```bash
#!/bin/bash
# ~/clawd/scripts/slack-check-unanswered.sh
# Check for unanswered @mentions in last 2 hours

BOT_TOKEN="xoxb-YOUR-BOT-TOKEN"
BOT_USER_ID="U0ACMDPT58X"  # Your bot's user ID
CHANNELS=("C0AL7KZ75TP" "C0ACMGAQ9PZ")  # Channels to monitor
OLDEST=$(( $(date +%s) - 7200 ))

for CHANNEL in "${CHANNELS[@]}"; do
  curl -s "https://slack.com/api/conversations.history?channel=${CHANNEL}&oldest=${OLDEST}&limit=50" \
    -H "Authorization: Bearer ${BOT_TOKEN}" | \
    jq -r --arg bot "$BOT_USER_ID" '
      .messages[]? | 
      select(.text | contains("<@" + $bot + ">")) |
      select(.user != $bot) |
      "Channel: '"$CHANNEL"' | ts: \(.ts) | text: \(.text[0:100])"
    '
done

Add to HEARTBEAT.md for periodic monitoring:

### Slack Monitoring (every few hours)
Check for unanswered @mentions:
\`\`\`bash
~/clawd/scripts/slack-check-unanswered.sh
\`\`\`
If any found, respond to them.

Slack Config: No Mention Required

To let your agent see all messages (not just @mentions), set requireMention: false for each channel:

{
  "channels": {
    "slack": {
      "channels": {
        "#your-channel": {
          "allow": true,
          "requireMention": false
        }
      }
    }
  }
}

Important: When requireMention: false, your agent sees EVERY message. Add response rules to AGENTS.md:

### When to Respond in Channels

**Respond when:**
- Directly @mentioned
- Continuing a conversation you're already in
- Your name comes up naturally
- You have genuinely useful info to add

**Stay silent (NO_REPLY) when:**
- General chatter between humans
- Topics you have nothing to add to
- Someone else already answered

---

24. Quick Reference

File Paths

What	Where
OpenClaw config	~/.openclaw/openclaw.json
Cron jobs	~/.openclaw/cron/jobs.json
Gateway logs	~/.openclaw/logs/gateway.log
Error logs	~/.openclaw/logs/gateway.err.log
Watchdog log	~/.openclaw/logs/health-watchdog.log
Device identity	~/.openclaw/identity/device.json
Paired devices	~/.openclaw/devices/paired.json
Credentials	~/.openclaw/credentials/
Browser data	~/.openclaw/browser/openclaw/
Claude Code settings	~/.claude/settings.json
Workspace	~/clawd/
Skills	~/clawd/skills/
Memory	~/clawd/MEMORY.md

Common Commands

# OpenClaw — Gateway
openclaw status                    # Channel health & recent activity
openclaw health                    # Gateway health check
openclaw gateway                   # Start gateway (foreground)
openclaw gateway --force           # Kill & restart gateway
openclaw gateway restart           # Graceful restart
openclaw logs                      # View gateway logs
openclaw doctor                    # Diagnose issues
openclaw doctor --fix              # Auto-fix common configuration issues
openclaw dashboard                 # Open web control UI

# OpenClaw — Cron
openclaw cron list                 # List all jobs
openclaw cron runs --limit 20      # Run history
openclaw cron run <id>             # Trigger job now (debug)
openclaw cron status               # Scheduler health

# OpenClaw — Browser
openclaw browser profiles          # List browser profiles
openclaw browser start             # Start headless browser
openclaw browser screenshot --full-page

# OpenClaw — Models
openclaw models list               # Available models
openclaw models aliases            # Configured aliases
openclaw models set primary --model opus4.6

# OpenClaw — Memory
openclaw memory search "query"     # Semantic search
openclaw memory status --deep      # Indexing health
openclaw memory index --force      # Reindex

# OpenClaw — Sandbox & Backup
openclaw sandbox list              # Active containers
openclaw sandbox explain           # Effective policy
openclaw backup create --output ~/backup.tar.gz

# OpenClaw — ACP
openclaw acp client                # Interactive agent CLI
openclaw acp --session main:main --message "test"

# Misc
openclaw plugins list              # List installed plugins
openclaw skills list               # List available skills
openclaw config get channels       # View channel config
openclaw message send --channel slack --target "#channel" --message "test"

# Claude Code
claude                             # Start interactive session
claude mcp list                    # List MCP servers
claude mcp add ...                 # Add MCP server
/mcp                               # Check MCP status (inside Claude Code)
/hooks                             # Reload hooks (inside Claude Code)

Message Acknowledgment Flow

User sends message in Slack
         |
         v
   Ack reaction added
         |
         v
   Agent processes message
         |
         v
   Agent sends reply
         |
         v
   Ack reaction removed

---

Getting Help

• OpenClaw docs: docs.openclaw.ai
• Claude Code docs: docs.anthropic.com/en/docs/claude-code
• OpenClaw CLI help: openclaw --help or openclaw <command> --help
• Search docs: openclaw docs "your question"