How to Set Up OpenClaw on Mac and Linux: Complete 2026 Guide

You’ve seen the OpenClaw screenshots. You’ve read the setup guides for Windows. Now you’re sitting at your MacBook or Ubuntu terminal wondering: is this thing going to be a headache to install, or does it actually work?

Short answer: it works. Better on Mac and Linux than most people expect. We’ve run OpenClaw on a Mac mini M2 as a home server, an Ubuntu 22.04 VPS on DigitalOcean, and a Raspberry Pi 5. Here’s the honest breakdown of each – what goes smoothly, what trips you up, and the exact commands we use.

Before You Install: What OpenClaw Actually Needs

OpenClaw is a Node.js application. That’s the whole dependency story – no Docker required, no Python environment conflicts, no Conda hell. Node 20 or later, npm, and an API key from Anthropic (or OpenAI, or whichever model provider you’re using). That’s it.

Think of it like installing any modern CLI tool – the kind that takes three commands and just works. Homebrew on Mac, apt on Ubuntu. The friction is in configuration, not installation.

• Node.js 20+ – required
• npm 9+ – included with Node
• At least one AI API key – Anthropic Claude recommended
• ~200MB disk space – for the package and workspace
• Internet connection – for API calls (obviously)

One thing worth knowing upfront: OpenClaw’s cron system, Telegram integration, and skill ecosystem all work identically on Mac and Linux. There’s no Windows-only or Mac-only feature wall. The only real platform differences are in how you keep it running – launchd on Mac, systemd on Linux. We’ll cover both.

Installing OpenClaw on macOS

Step 1: Install Node.js via Homebrew

If you’re on a Mac and don’t have Homebrew, get it first. It’s the package manager that should have shipped with macOS but didn’t:

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

Then install Node:

brew install node

Verify it worked:

node --version
npm --version

You want v20.x.x or higher. If you’re on an older Mac running Monterey or Ventura, this still works fine – the M-series chips and Intel both handle it without issues.

Step 2: Install OpenClaw

npm install -g openclaw

That’s the whole install. No sudo needed on a fresh Homebrew Node setup because Homebrew installs to user-writable paths. If you get a permissions error (usually means you’re on system Node, not Homebrew Node), prefix with sudo – but switch to Homebrew Node when you get a chance.

Confirm the install:

openclaw --version

Step 3: Initialize Your Workspace

Pick a permanent home for your OpenClaw workspace. We use ~/openclaw but anywhere works:

mkdir ~/openclaw
cd ~/openclaw
openclaw init

The init command walks you through the basics – API key setup, default model, workspace path. Takes about 2 minutes. Answer the prompts, and you’ll end up with a config/ directory and your first AGENTS.md file.

Step 4: Set Your API Key

OpenClaw uses environment variables for API keys. Add them to your shell profile so they persist across sessions:

# For zsh (default on macOS Catalina+)
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc

# For bash (older setups)
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.bash_profile
source ~/.bash_profile

Then test it:

openclaw status

If you see your model and session info, you’re connected. If you get an auth error, double-check the key format – Anthropic keys start with sk-ant-.

Step 5: Connect Telegram (Recommended)

This is optional but genuinely changes how useful OpenClaw is. Once it’s on Telegram, you can send commands from your phone while you’re away from your desk. We have a full guide on connecting OpenClaw to Telegram – the short version is:

1. Message @BotFather on Telegram, create a bot, copy the token
2. Add to your OpenClaw config: openclaw config set telegram.botToken "your-token"
3. Message your bot on Telegram and run openclaw gateway start

Step 6: Run OpenClaw as a Background Service (launchd)

This is where Mac setup diverges from Linux. macOS uses launchd (not systemd) for services. Here’s how to make OpenClaw start automatically and stay running:

Create a launchd plist file:

nano ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Paste this – update the paths to match your actual install:

<?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>ai.openclaw.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/openclaw</string>
        <string>gateway</string>
        <string>start</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
        <key>ANTHROPIC_API_KEY</key>
        <string>your-key-here</string>
    </dict>
    <key>WorkingDirectory</key>
    <string>/Users/yourusername/openclaw</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/yourusername/openclaw/logs/gateway.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/yourusername/openclaw/logs/gateway-error.log</string>
</dict>
</plist>

Load and start it:

mkdir -p ~/openclaw/logs
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl start ai.openclaw.gateway

Verify it’s running:

launchctl list | grep openclaw

You’ll see a process ID in the output. Message your Telegram bot – if it responds, you’re live. From this point on, OpenClaw starts automatically every time your Mac boots, even without you logging in first (as long as you load it into the user session, which the above does).

To stop or restart:

launchctl stop ai.openclaw.gateway
launchctl start ai.openclaw.gateway

One honest note: if your Mac goes to sleep (lid close, energy saver), the gateway pauses. For a home server setup that needs to stay awake 24/7, go to System Settings ? Battery ? Prevent automatic sleeping when the display is off. Or better yet, use a Mac mini with the lid always open – that’s our actual setup.

Installing OpenClaw on Linux (Ubuntu/Debian)

Linux setup is actually cleaner than Mac in most ways. No Homebrew dependency, systemd is more powerful than launchd, and VPS deployments are rock solid. We’ve been running OpenClaw on DigitalOcean Ubuntu 22.04 droplets for months without any issues.

Step 1: Install Node.js via NodeSource

Don’t use the default apt Node package – it’s usually ancient (v12 or older on some systems). Use NodeSource for a current version:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify:

node --version   # Should be 20.x or higher
npm --version

On Ubuntu 24.04, you can also use the snap package, but we’ve had better luck with NodeSource for server deployments.

Step 2: Install OpenClaw

sudo npm install -g openclaw

On Linux server setups (root or non-root with sudo), the sudo is usually needed for global installs. If you prefer to avoid sudo, use nvm (Node Version Manager) which installs Node in your user directory:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
npm install -g openclaw

Either path works. nvm is nicer for development machines where you might juggle multiple Node versions. sudo global install is fine for dedicated servers.

Step 3: Initialize and Configure

mkdir ~/openclaw && cd ~/openclaw
openclaw init

For Linux, store your API keys in ~/.bashrc or ~/.profile:

echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

Or better yet, create a dedicated env file and source it – keeps secrets out of shell history:

cat > ~/openclaw/.env << 'EOF'
ANTHROPIC_API_KEY=your-key-here
TELEGRAM_BOT_TOKEN=your-token-here
EOF
chmod 600 ~/openclaw/.env

Step 4: Run as a systemd Service

This is the clean way to do it on Linux. systemd handles automatic restarts, logging, and boot startup without any manual intervention. Create the service file:

sudo nano /etc/systemd/system/openclaw.service

Paste this (update yourusername and paths):

[Unit]
Description=OpenClaw AI Gateway
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=yourusername
WorkingDirectory=/home/yourusername/openclaw
EnvironmentFile=/home/yourusername/openclaw/.env
ExecStart=/usr/bin/openclaw gateway start
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

Check status:

sudo systemctl status openclaw

View live logs:

journalctl -u openclaw -f

The Restart=always line means if OpenClaw crashes for any reason – network blip, API timeout, whatever – systemd brings it back up automatically within 10 seconds. We’ve had zero manual intervention incidents on our VPS in months of running. That’s the kind of reliability you get with a properly configured systemd service.

Step 5: Firewall Considerations

OpenClaw’s gateway doesn’t open any inbound ports by default – it connects outbound to Telegram/Discord APIs and Anthropic. So standard UFW setups on Linux don’t need changes for basic operation:

sudo ufw status

If you’re using OpenClaw’s optional web interface or exposing any local ports for integrations, you’d add rules then. For most people running it as a Telegram bot + cron automation setup, the default firewall config is fine as-is.

Installing OpenClaw on Raspberry Pi

This deserves its own section because the Pi is genuinely a great OpenClaw host – it runs 24/7, draws about 5W of power, and costs nothing after the initial hardware. We’ve had an OpenClaw instance running on a Pi 5 for two months. Here’s the honest experience.

What Works Well

• Node.js 20 runs fine on Pi OS (Bookworm, 64-bit)
• Telegram integration is rock solid
• Cron jobs execute reliably
• systemd service management is identical to Ubuntu
• The Pi never crashes or overheats (with a basic case fan)

What to Watch Out For

• RAM: The Pi 4 with 2GB is workable. The Pi 4 with 4GB or Pi 5 is comfortable. If you’re running other services on the same Pi (Home Assistant, Nginx, etc.), 2GB can get tight during heavy API sessions.
• SD card wear: Logs are written constantly. Point your OpenClaw logs to a USB SSD instead of the SD card, or use tmpfs for ephemeral logs. SD cards that run 24/7 fail within 1-2 years from write wear.
• API latency: The Pi’s internet connection (usually through home router) adds a bit of latency vs a VPS. For cron jobs this doesn’t matter. For interactive conversations it’s barely noticeable.

The install process is identical to Ubuntu/Debian – NodeSource, npm install, systemd service. No special Pi steps needed.

Configuring Your First Skills on Mac/Linux

Once OpenClaw is running, skills are what make it actually useful. Skills are specialized instruction sets that give OpenClaw new capabilities – things like searching the web, posting to WordPress, querying Google Search Console, and hundreds more from the ClawdHub marketplace.

Installing a skill on Mac or Linux is the same command regardless of platform:

clawdhub install obsidian-daily
clawdhub install brave-search
clawdhub install gsc

Skills install into your workspace’s skills/ directory. OpenClaw automatically picks them up – no restart required. After installing, just describe what you want and OpenClaw selects the right skill.

For a solid starting setup, we recommend installing these first:

• brave-search – web search without burning tokens on browser automation
• obsidian-daily – daily note management if you use Obsidian
• gsc – Google Search Console queries for SEO tracking
• github – GitHub CLI integration for code management

You can see how we use these together in our full guide on building an AI content pipeline with OpenClaw.

Setting Up Cron Jobs on Mac/Linux

Cron automation is where OpenClaw goes from “neat tool” to “AI employee.” The system uses OpenClaw’s built-in cron scheduler, not the OS-level cron – so it’s identical across Mac, Linux, and Windows. But there’s one Mac/Linux-specific consideration: the gateway needs to be running for crons to fire.

This is why the launchd/systemd setup from earlier matters. If OpenClaw isn’t running when a cron fires, the job is skipped. Get the service configured correctly first, then set up your crons.

To add a cron job via CLI:

openclaw cron add "0 9 * * *" "Check BTC price and send summary to Telegram"

Or configure them in your workspace’s cron config file. Full documentation is in the official OpenClaw docs under the Automation section.

We have a detailed breakdown of cron job patterns in our OpenClaw cron jobs guide – that’s where to go for the actual use cases and examples.

Troubleshooting Common Mac/Linux Issues

“openclaw: command not found” after npm install

This usually means the global npm bin directory isn’t in your shell path. Find where npm puts global binaries:

npm config get prefix

That returns something like /usr/local or /home/yourusername/.nvm/versions/node/v20.x.x. Append /bin to that value and add it to your shell profile. On zsh:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Permission denied on global install (Linux)

Two clean solutions: use sudo npm install -g openclaw, or switch to nvm (which installs in user space). Don’t chmod 777 your npm directory – that’s a security hole and it’ll come back to bite you.

Gateway crashes silently on Mac

Check the log files you configured in the launchd plist:

tail -n 100 ~/openclaw/logs/gateway-error.log

Common causes: API key expired, Node version too old (update to 20+), or a Telegram bot token change. The error log almost always tells you exactly what happened.

Cron jobs not firing

First, verify the gateway is actually running:

# Mac
launchctl list | grep openclaw

# Linux
systemctl status openclaw

If the service shows as stopped, start it. If it starts and immediately stops, check the error log – it’s almost always a config issue or a missing environment variable.

High CPU usage on Pi or low-spec VPS

OpenClaw itself is lightweight. If CPU spikes during API calls, that’s normal – it’s brief and drops back to near-zero when idle. If you’re seeing sustained high CPU, check for runaway cron loops: a cron that spawns a sub-agent that triggers another cron can create a feedback loop. Review your cron config and add appropriate spacing between jobs.

Telegram messages delayed or missing

Check if the gateway is running and connected. On Linux:

journalctl -u openclaw -n 50

Look for connection errors. Often it’s a network blip on a VPS – systemd’s Restart=always handles these automatically. If delays are consistent, the issue might be Telegram’s polling interval. Check your OpenClaw config for the telegram.pollingInterval setting.

Mac vs Linux vs Windows: Which Should You Use?

Here’s the honest comparison based on running OpenClaw across all three:

Factor	macOS	Linux (VPS)	Windows
Install friction	Low (Homebrew)	Low (NodeSource)	Medium (path config)
Service management	Good (launchd)	Best (systemd)	Workable (Task Scheduler)
24/7 reliability	Good (if no sleep)	Best	Good
Cost	Hardware you own	$4-12/month VPS	Hardware you own
SSH scripting	Native	Native	Needs paramiko/WSL
Developer ergonomics	Excellent	Excellent	Improving

Our honest take: if you want OpenClaw running 24/7 as a persistent AI employee, a $6/month DigitalOcean Ubuntu VPS is the right call. It’s always on, the systemd service just works, and you’re not burning home electricity or relying on your laptop staying awake.

If you already have a Mac that’s always on (Mac mini, MacBook permanently plugged in), that works great too. We wouldn’t set up Windows specifically for OpenClaw, but if Windows is your primary machine and you don’t want to pay for a VPS, it runs fine – just read our Windows setup guide for the extra steps needed.

What to Do After Setup

Once you’re up and running, there are a few directions to go depending on what you want OpenClaw to do:

• Automate content workflows – See our content pipeline guide
• Monitor your website – See our website monitoring guide
• Set up Discord/Slack notifications – See our Discord and Slack integration guide
• Automate affiliate operations – See our affiliate marketing automation guide
• Compare AI agent platforms – See how OpenClaw stacks up against Auto-GPT and AgentGPT before committing
• Explore complementary tools – See our Best AI Chatbots 2026 roundup for tools that work well alongside OpenClaw

The OpenClaw GitHub repository is also worth bookmarking – the README is genuinely useful and the issues section is where most community knowledge lives.

Frequently Asked Questions

Does OpenClaw work on macOS Sonoma and Sequoia?

Yes. We’ve tested on Sonoma (macOS 14) and Sequoia (macOS 15) on both M-series and Intel chips. The install process is identical across all recent macOS versions. No compatibility issues as of March 2026.

Can I run OpenClaw on a Raspberry Pi 3?

Technically yes, but we don’t recommend it for anything beyond basic testing. The Pi 3 has 1GB RAM which gets tight under load. The Pi 4 with 2GB is the minimum we’d actually use in production; Pi 4 with 4GB or Pi 5 is comfortable for full-time operation.

Do I need root access to install OpenClaw on Linux?

No – if you use nvm (Node Version Manager), you can install Node.js and OpenClaw entirely in your user directory without any sudo. This is the cleaner approach on shared servers or environments where you don’t have root.

How much does it cost to run OpenClaw on a VPS?

The VPS itself runs $4-12/month depending on provider and specs. DigitalOcean’s $6/month Basic droplet (1GB RAM, 1 vCPU) handles OpenClaw comfortably for moderate workloads. The bigger ongoing cost is API usage – Anthropic charges per token, so heavy cron automation can add up. Budget $10-30/month for API costs on an active setup.

What’s the difference between openclaw gateway start and running it as a service?

Running openclaw gateway start manually starts it in your current terminal session – it stops when you close the terminal or log out. Running it as a launchd (Mac) or systemd (Linux) service means it starts automatically on boot and restarts on crashes. For any real use case beyond quick testing, you want the service approach.

Can I use OpenClaw without a Telegram or Discord bot?

Yes. OpenClaw works fine with just the CLI. You send commands from your terminal, crons fire on schedule, and you read output in the logs. The messaging integrations just add convenience – especially useful if you want to query your AI assistant from your phone while away from your computer.

How do I update OpenClaw to the latest version?

Same command as the install: sudo npm install -g openclaw@latest on Linux, or without sudo if using nvm or Homebrew. After updating, restart the gateway service: systemctl restart openclaw on Linux or launchctl stop/start ai.openclaw.gateway on Mac. Check the GitHub changelog for what changed before upgrading.