Set up OpenClaw on your Mac

Beginner20 minutes

Target audience: Absolute beginners -- no terminal knowledge required
Duration: 20 minutes (+ optional 30-60 min for Skills)
Difficulty: Beginner
Tested on: macOS 12+, M1/Intel

⚠️ Security note: OpenClaw has access to files and can run commands. This guide works on your Mac/PC — however, we recommend installing it on a VPS or a separate device.

Prerequisite: Check for Node.js

Before we start: Does your Mac have Node.js?

Open Terminal

Press Cmd + Space
Type: terminal
Press Enter

A black-and-white window opens -- that's Terminal.

Node.js Check

In Terminal, type:

node --version

Press Enter.

What do you see?

A number like v22.x.x or v20.x.x?

Great! Jump ahead to Step 1.

"command not found: node"?

No problem! Continue with Step 0.1 below.

Step 0.1: Install Node.js (If needed)

If Node.js is missing:

Install Homebrew

In Terminal:

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

Press Enter. It will ask for your Mac password (it won't be displayed -- that's normal).

Type it in and press Enter. This takes 5-10 minutes.

Install Node.js with Homebrew

In Terminal:

brew install node

Press Enter. This takes 2-3 minutes.

Verify Node.js

node --version

You should see: v22.x.x or similar.

Perfect!

Step 1: Install OpenClaw

In Terminal:

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

Press Enter.

Installation takes 3-5 minutes. At the end you'll see:

Installation complete!

Step 2: Configure

This is the most important step! A configuration wizard with several screens (not "questions").

In Terminal:

openclaw onboard

Press Enter.

Note: openclaw onboard is the full first-time setup assistant. If you only want to change specific settings later (e.g. channels or model), you can use openclaw configure.

SCREEN 1: Gateway Location

Where will the Gateway run?
  Local (this machine)
  Remote (info-only)

Local is already selected.

Press Enter.

SCREEN 2: What would you like to configure?

Select sections to configure

● Workspace
○ Model
○ Web tools
○ Gateway
○ Daemon
○ Channels (Link WhatsApp/Telegram/etc)
○ Skills
○ Health check
○ Continue

The cursor (●) is on Workspace. Use the arrow key (↓) to navigate down to Model and press Enter.

SCREEN 3: Choose an AI provider

You'll see several options:

Model/auth provider

  OpenAI (ChatGPT)
  Anthropic (Claude)
  Google (Gemini)
  vLLM (Local)
... (many more)

Important: Understanding OAuth vs API Key:

OAuth (recommended for beginners) -- FREE with an existing subscription

OpenAI (ChatGPT): You need a ChatGPT Pro subscription (EUR 20/month)

- OpenClaw uses your existing subscription — no extra API key needed

- You do NOT pay extra

API Key -- PAID, pay-as-you-go

Google Gemini: Charged per API call (approx. EUR 0.01-0.10 per request)

- Requires a credit card

- Less reliable than subscription-based

Others: All cost money

Recommendation for beginners:

If you have ChatGPT Pro: Choose OpenAI → OAuth login, no API key needed

If you have neither: Easiest option is Google Gemini (free API key via Google AI Studio)

Select your choice with the arrow keys and press Enter.

SCREEN 4: Login (OAuth)

Your browser opens automatically.

For OpenAI:

Sign in with your ChatGPT account
Grant OpenClaw permission
The browser closes automatically
Terminal shows: "Auth successful"

For Anthropic:

Sign in with your Claude account
Grant OpenClaw permission
Done!

SCREEN 2 (back): More configuration?

You'll see again:

Select sections to configure

● Workspace
○ Model (done)
○ Web tools
○ Gateway
○ Daemon
○ Channels (WhatsApp/Telegram/etc)
○ Skills
○ Health check
○ Continue

Your options:

Option A: Dashboard only (quick)

Select Continue and press Enter
OpenClaw starts right away
You can set up WhatsApp/Telegram later

Option B: Connect WhatsApp now (10 min more)

Select Channels and press Enter
Follow SCREEN 3-5 below

Option C: Install Skills (30-60+ min, optional)

Select Skills and press Enter
Warning: This takes a very long time! (especially on older Macs)
Many skills may fail -- that is NORMAL

(Optional) Connect WhatsApp

If you chose Channels:

SCREEN 3: Channel Status

You'll see:

Channel status

Telegram: needs token
WhatsApp (default): not linked   <-- This is what we want to change
Discord: needs token
...

Select WhatsApp and press Enter.

SCREEN 4: WhatsApp Setup

Channels
  Configure/link (Add/update channels)
  Remove channel config

Configure is already selected. Press Enter.

SCREEN 5: Choose WhatsApp Channel

Select a channel

  Telegram (Bot API)
  WhatsApp (QR link)   <-- This is it!
  Discord (Bot API)
...

WhatsApp is already selected. Press Enter.

SCREEN 6: QR Code

WhatsApp linking

Scan the QR with WhatsApp on your phone.
Credentials are stored under ~/.openclaw/credentials/whatsapp/

Waiting for WhatsApp connection...
Scan this QR in WhatsApp (Linked Devices):

[large QR code]

How it works:

Open WhatsApp on your phone
Go to Settings (bottom right, three dots)
Tap Linked Devices
Tap Link a Device
Open the camera app
Hold your camera over the QR code in Terminal
WhatsApp opens and links
Back in Terminal you'll see: Linked

SCREEN 7: Your Number

WhatsApp phone setup

  This is my personal phone number
  Separate phone just for OpenClaw

Your personal WhatsApp number (the phone you will message from)
+43XXXXXXXXXX

Type your WhatsApp number (with +43 country code).

Press Enter.

SCREEN 2 (back): Continue?

Select sections to configure

● Workspace
○ Model (done)
○ Web tools
○ Gateway
○ Daemon
○ Channels (WhatsApp configured)
○ Skills
○ Health check
○ Continue

Select Continue and press Enter.

SCREEN 8: Done!

Control UI

Web UI: http://127.0.0.1:18789/
Gateway WS: ws://127.0.0.1:18789

Configure complete.

Perfect!

Step 3: Open the Dashboard

In Terminal:

openclaw dashboard

Press Enter.

Your browser opens with:

http://127.0.0.1:18789/

You'll see a chat window -- that's your AI assistant!

Step 4: Test Message

Click into the chat window
Type: "Hello! Who are you?"
Press Enter

You should get a response!

Step 5: Updates

In the Dashboard you'll sometimes see:

Update available: v2026.3.13

Click on it. OpenClaw updates itself (30 seconds).

Step 6: Use WhatsApp

If you connected WhatsApp:

Open WhatsApp on your phone and send a message:

"What can you do?"

OpenClaw replies directly in WhatsApp!

Step 7: Use Telegram (optional)

If you connected Telegram, there is one important extra step: OpenClaw needs to verify that it trusts you.

When you message your Telegram bot for the first time, you'll receive a pairing code in the terminal (or dashboard).

Confirm this code in the terminal:

openclaw pairing approved telegram <CODE>

Replace <CODE> with the code you received.

After that, OpenClaw will reply to your Telegram messages without further confirmation.

Tip: If you don't see a pairing request, check the dashboard under Pairing, or run openclaw pairing to view open requests.

Common Errors and Solutions

Error 1: "command not found: openclaw"

Problem: After installation, openclaw doesn't work

Solution:

Close Terminal completely (Cmd + Q)
Reopen it
Try again

Error 2: "Gateway not running" or "localhost:18789 doesn't work"

Problem: Dashboard won't load

Solution:

openclaw gateway restart

Wait 5 seconds, then try again.

Error 3: "WhatsApp (QR link) not found" or "Unknown channel"

Problem: WhatsApp doesn't work during Channels setup

Solution:

This is normal with older configurations
Type again: openclaw configure
Choose Channels again
WhatsApp should then be visible

Error 4: "No API key found"

Problem: Dashboard shows: "Agent failed before reply: No API key found"

Solution:

This means: OAuth login didn't work
Type: openclaw configure
Choose Model
Try logging in again

Error 5: Skills installation takes forever

Problem: During skills installation: 45+ minutes, your Mac gets hot

This is NORMAL! Especially on older Macs.

Solution:

Wait (it just takes a while)
If you want to cancel: press Ctrl + C
Then run openclaw configure and skip Skills

Error 6: "Skills installation failed"

Problem: Errors like "apple-notes -- requires macOS Sonoma"

This is NORMAL! Especially on older Macs.

OpenClaw still works perfectly fine.

Useful Terminal Commands

Gateway \& Status

openclaw dashboard              # Open the Dashboard in your browser
openclaw gateway status         # Is OpenClaw running?
openclaw gateway restart        # Restart (fixes most issues)
openclaw gateway stop           # Stop
openclaw gateway start          # Start
openclaw gateway run            # Run in foreground (with live logs)
openclaw status                 # Show channel health and recent sessions
openclaw health                 # Fetch Gateway health
openclaw --help                 # Show all available commands

Diagnostics \& Troubleshooting

openclaw doctor                 # Health check — detects and reports issues
openclaw doctor --repair        # Like doctor, but tries to fix issues automatically
openclaw logs --follow          # View live logs (Ctrl+C to stop)
openclaw logs --follow --json   # Logs in JSON format (for developers)
openclaw tui                    # Terminal UI — chat directly in the terminal

Exec Approvals (Tool Permissions)

openclaw approvals get                               # Show current permissions
openclaw approvals allowlist add "/bin/bash"         # Allow bash
openclaw approvals allowlist add "/usr/bin/python3"  # Allow Python

Note: If your assistant cannot run terminal commands, it's usually because Exec Approvals are not configured yet. Start with openclaw approvals get and openclaw doctor.

Channels (WhatsApp, Telegram, Discord)

openclaw channels status        # Connection status of all channels
openclaw channels logs          # View channel logs
openclaw configure              # Set up or reconnect channels

Sessions \& Agents

openclaw sessions list          # Show stored sessions
openclaw agents list            # Show all configured agents

Skills \& Updates

openclaw skills list            # Show installed skills
openclaw skills search <name>   # Search for a new skill
openclaw update                 # Update OpenClaw

Security \& Backup

openclaw security audit         # Run a security audit
openclaw backup create          # Create a backup
openclaw backup verify          # Verify a backup

Advanced

openclaw memory search <query>  # Search memory files
openclaw models list            # Show available AI models
openclaw message send --target +43... --message "Test"  # Send a message
openclaw docs                   # Search documentation

Congratulations!

You now have your own AI assistant on your Mac!

Running locally on your device (your data stays private)
Accessible in your browser: http://127.0.0.1:18789/
Optionally via WhatsApp/Telegram
With regular auto-updates

Too complicated? We do it for you.

Managed Hosting — we set up OpenClaw for you and take care of everything.

View all hosting plans Ask a question