# How to Install and Run OpenClaw (Previously Clawdbot/Moltbot) on Mac

Source: https://zilliz.com/blog/how-to-install-and-run-openclaw-on-mac
Author: Fendy Feng
Published: 2026-02-12T20:00:00.000Z

[OpenClaw](https://openclaw.ai/) is an open-source, self-hosted gateway that bridges your everyday messaging apps to AI coding agents. Instead of switching between tabs, apps, and interfaces, you send a message from WhatsApp or Telegram and get an AI-powered response right in your pocket. It's MIT licensed, runs on your hardware, and keeps you in full control of your data.

In this tutorial, we'll walk through everything you need to install and run OpenClaw on macOS — from prerequisites to your first working chat.



## What You'll Need

Before you begin, make sure you have the following:

- **macOS** (any recent version)
- **Node.js 22 or newer** — the installer script will handle this for you if it's not already installed, but it's good to check
- **An API key** — Anthropic is recommended by the OpenClaw team
- **About 5 minutes** of your time

To check your current Node version, open Terminal and run:

```bash
node --version
```

If you see `v22.x.x` or higher, you're good to go. If not, don't worry — the installer will take care of it.


## Step 1: Install OpenClaw via the Installer Script (Recommended)

The fastest way to install OpenClaw on macOS is the one-line installer script. It handles Node detection, CLI installation, and launches the onboarding wizard — all in one step.

Open Terminal and run:

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

That's it. The script will download the CLI, install it globally via npm, and kick off the onboarding wizard automatically.

### Alternative: Install via npm Directly

If you already have Node 22+ and prefer manual control, you can install OpenClaw with npm:

```bash
npm install -g openclaw@latest
openclaw onboard --install-daemon
```

### Alternative: Install via pnpm

If pnpm is your package manager of choice:

```bash
pnpm add -g openclaw@latest
pnpm approve-builds -g   # approve openclaw, node-llama-cpp, sharp, etc.
openclaw onboard --install-daemon
```

**Note:** pnpm requires explicit approval for packages with build scripts. After the first install shows the "Ignored build scripts" warning, run `pnpm approve-builds -g` and select the listed packages.

### Troubleshooting: `sharp` Build Errors

If you have `libvips` installed globally (common on macOS via Homebrew) and `sharp` fails during installation, force prebuilt binaries:

```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
```

If you see the error `sharp: Please add node-gyp to your dependencies`, either install build tooling (Xcode Command Line Tools + `npm install -g node-gyp`) or use the environment variable above.


## Step 2: Run the Onboarding Wizard

If the installer script didn't automatically launch it, start the onboarding wizard manually:

```bash
openclaw onboard --install-daemon
```

The wizard walks you through configuring auth, gateway settings, and optional channel connections. It also installs OpenClaw as a background service (daemon), so the Gateway stays running even after you close Terminal.

### What the Wizard Configures

- **Authentication** — generates a token for the Gateway so local and remote clients must authenticate
- **Gateway settings** — port, bind address, and service installation
- **Channel connections** — optional setup for WhatsApp, Telegram, Discord, and more


## Step 3: Verify the Gateway Is Running

Once onboarding completes, check that the Gateway is up:

```bash
openclaw gateway status
```

You should see confirmation that the Gateway is running. If you want to run it in the foreground for debugging or quick testing, use:

```bash
openclaw gateway --port 18789
```

For a full health check:

```bash
openclaw health
```



## Step 4: Open the Control UI (Dashboard)

The fastest way to start chatting with OpenClaw is through the browser-based Control UI — no channel setup required.

Run:

```bash
openclaw dashboard
```

This copies the dashboard URL, opens your browser if possible, and displays the link. By default, the Control UI is served at:

```
http://127.0.0.1:18789/
```

If the dashboard prompts for authentication, paste the token from your Gateway config. You can retrieve it with:

```bash
openclaw config get gateway.auth.token
```

 **Security note:** The Control UI is an admin surface — it provides access to chat, configuration, and execution approvals. Do not expose it publicly. Stick to localhost, Tailscale Serve, or an SSH tunnel.



## Step 5: Connect a Chat Channel (Optional)

While the Control UI gives you instant access to chat, the real power of OpenClaw is messaging your AI agent from the apps you already use. Here's a quick overview of supported channels:

| Channel | Setup Complexity | Notes |
|---------|-----------------|-------|
| **Telegram** | Easiest | Simple bot token |
| **WhatsApp** | Easy | QR pairing required; stores more state on disk |
| **Discord** | Moderate | Bot API + Gateway |
| **iMessage** | Moderate | Recommended via BlueBubbles macOS server |
| **IRC** | Low | Classic IRC; channels + DMs |
| **Slack** | Moderate | Bolt SDK; workspace apps |
| **Signal** | Moderate | Privacy-focused; uses signal-cli |

Multiple channels can run simultaneously — configure as many as you want and OpenClaw routes messages per chat.

Check out this post for: [OpenClaw Tutorial: Connect to Slack for Local AI Assistant - Milvus Blog](https://milvus.io/blog/stepbystep-guide-to-setting-up-openclaw-previously-clawdbotmoltbot-with-slack.md)

### Quick Example: Pair WhatsApp

To connect WhatsApp, run:

```bash
openclaw channels login
```

Follow the QR pairing flow, and you'll be able to message your AI agent directly from WhatsApp.



## Step 6: Send a Test Message

With a channel configured, send a test message from the CLI:

```bash
openclaw message send --target +15555550123 --message "Hello from OpenClaw"
```

Replace the phone number with your own. If everything is wired correctly, you'll see the message arrive in your messaging app — and OpenClaw's AI agent will respond.



## Optional: Build from Source

For contributors or anyone who wants to run from a local checkout:

```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
```

Link the CLI globally:

```bash
pnpm link --global
```

Then run onboarding:

```bash
openclaw onboard --install-daemon
```

For hot-reload during development, use `pnpm gateway:watch` instead of the standard gateway command.



## Optional: macOS App Onboarding

OpenClaw also offers a native macOS app (menu bar) with its own onboarding flow. If you're using the app:

1. **Approve the macOS security warning** when first launching
2. **Allow "Find Local Networks"** permission
3. **Choose Local vs. Remote** — select "This Mac" for a local-only Gateway
4. **Grant permissions** — the app may request Automation, Notifications, Accessibility, and other TCC permissions depending on your use case
5. **Install the CLI** (optional) — the app can install the global `openclaw` CLI via npm so terminal workflows work alongside the app
6. **Chat in the onboarding session** — the app opens a dedicated chat so the agent can introduce itself

The stable workflow recommended by the OpenClaw docs: install and launch `OpenClaw.app`, complete the onboarding checklist, then link your channels with `openclaw channels login`.



## Configuration Basics

OpenClaw stores its configuration at `~/.openclaw/openclaw.json`. Out of the box, it uses the bundled Pi binary in RPC mode with per-sender sessions — no configuration needed.

If you want to restrict who can message your agent, add an `allowFrom` rule:

```json
{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  }
}
```

### Key File Locations on macOS

| Path | Purpose |
|------|---------|
| `~/.openclaw/openclaw.json` | Main configuration file |
| `~/.openclaw/workspace/` | Skills, prompts, memories |
| `~/.openclaw/credentials/` | Channel credentials |
| `~/.openclaw/agents/<agentId>/sessions/` | Agent session data |
| `/tmp/openclaw/` | Logs |

### Useful Environment Variables

| Variable | Purpose |
|----------|---------|
| `OPENCLAW_HOME` | Override home directory for internal path resolution |
| `OPENCLAW_STATE_DIR` | Override the state directory |
| `OPENCLAW_CONFIG_PATH` | Override the config file path |



## Troubleshooting: `openclaw` Not Found

If your shell can't find the `openclaw` command after installation, the issue is almost always a missing PATH entry.

Quick diagnosis:

```bash
node -v
npm -v
npm prefix -g
echo "$PATH"
```

If the output of `npm prefix -g` plus `/bin` isn't in your `$PATH`, add it to your shell startup file (`~/.zshrc` for modern macOS):

```bash
export PATH="$(npm prefix -g)/bin:$PATH"
```

Then open a new Terminal window or run `source ~/.zshrc`.



## Troubleshooting: "Unauthorized" / 1008 Error in Dashboard

If the Control UI shows an unauthorized error:

1. Make sure the Gateway is reachable: `openclaw status`
2. Retrieve the token: `openclaw config get gateway.auth.token`
3. In the dashboard settings, paste the token into the auth field and reconnect

If you need to generate a fresh token:

```bash
openclaw doctor --generate-gateway-token
```


## What You Now Have

After completing this tutorial, you have:

- A **running Gateway** on your Mac
- **Authentication configured** for secure access
- **Control UI access** for browser-based chat
- Optionally, one or more **connected messaging channels** (WhatsApp, Telegram, Discord, etc.)

From here, you can explore multi-agent routing, workspace isolation, media support, and the full range of OpenClaw's capabilities.


## Resources

-   [We Extracted OpenClaw’s Memory System and Open-Sourced It (memsearch)](https://milvus.io/blog/we-extracted-openclaws-memory-system-and-opensourced-it-memsearch.md) 
    
-   [What Is OpenClaw? Complete Guide to the Open-Source AI Agent](https://milvus.io/blog/openclaw-formerly-clawdbot-moltbot-explained-a-complete-guide-to-the-autonomous-ai-agent.md) 
    
-   [Build Clawdbot-Style AI Agents with LangGraph & Milvus](https://milvus.io/blog/clawdbot-long-running-ai-agents-langgraph-milvus.md) 
    
-   [How Claude Code Manages Local Storage for AI Agents](https://milvus.io/blog/why-claude-code-feels-so-stable-a-developers-deep-dive-into-its-local-storage-design.md)