Step by Step: Install and Use OpenClaw on macOS

OpenClaw + macOS

This is a from-scratch guide for running OpenClaw locally on macOS. It covers:

• Install the OpenClaw CLI
• Write the config file
• Start the Gateway (foreground / background)
• Access the Control UI
• Add Telegram (optional)
• Enable macOS system capabilities (optional)

0) Prerequisites

• Node.js 22+ (CLI + Gateway only)
• macOS Terminal
• If you want macOS system actions (system.run / screen / camera / notifications), install OpenClaw.app (menu-bar app)

Node.js official download: https://nodejs.org/ (LTS recommended)

1) Install the OpenClaw CLI

sudo npm install -g openclaw@latest

If your npm global prefix is user-writable, you can drop sudo:

npm install -g openclaw@latest

Verify:

openclaw --version

Tip: Do not use sudo to run OpenClaw. It will write configs under /var/root and break macOS permissions.

2) Prepare the config file

Default path:

~/.openclaw/openclaw.json

Below is an OpenAI Responses compatible example (image input + maxTokens=32000):

{
  "models": {
    "mode": "merge",
    "providers": {
      "xairouter": {
        "baseUrl": "https://api.xairouter.com/v1",
        "apiKey": "${XAI_API_KEY}",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.2",
            "name": "GPT",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 32000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "xairouter/gpt-5.2" },
      "models": { "xairouter/gpt-5.2": { "alias": "GPT" } }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": { "mode": "token", "token": "REPLACE_WITH_TOKEN" }
  }
}

Notes:

• If you don’t need image input, set input to "text".
• Prefer environment variables for API keys.
• Save to ~/.openclaw/openclaw.json or set OPENCLAW_CONFIG_PATH.

3) Start the Gateway (foreground)

openclaw gateway --bind loopback --port 18789 --verbose

Control UI:

http://127.0.0.1:18789/

If gateway.auth.token is set, you’ll be asked for the token.

4) Install as a background service (launchd)

To auto-start at login:

openclaw gateway install

Common maintenance commands:

openclaw gateway status
openclaw gateway restart
openclaw gateway stop

Logs:

~/.openclaw/logs/gateway.log
~/.openclaw/logs/gateway.err.log

If you run OpenClaw.app in Local mode, it manages the Gateway for you—avoid manual install to prevent conflicts.

5) Add Telegram (optional)

Fastest way (CLI writes config):

openclaw channels add --channel telegram --token <BOT_TOKEN>

Or edit config directly:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "BOT_TOKEN",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist"
    }
  }
}

First DM requires pairing approval:

openclaw pairing list telegram
openclaw pairing approve telegram <code>

6) Enable macOS system capabilities (optional)

To use system.run, screen recording, camera, notifications, etc:

1. Install and launch OpenClaw.app (menu bar)
2. Grant permissions (Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Automation/AppleScript)
3. Configure Exec approvals in the app

Exec approvals file:

~/.openclaw/exec-approvals.json

Recommended allowlist example:

{
  "version": 1,
  "defaults": { "security": "allowlist", "ask": "on-miss" },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [
        { "pattern": "/opt/homebrew/bin/rg" },
        { "pattern": "/usr/bin/osascript" }
      ]
    }
  }
}

If you fully understand the risks and want no prompts, set security: "full" and ask: "off".

Fully open example (high risk):

{
  "version": 1,
  "defaults": { "security": "full", "ask": "off" },
  "agents": {
    "main": {
      "security": "full",
      "ask": "off"
    }
  }
}

7) Common checks

openclaw health
openclaw status
openclaw models status
openclaw channels status

Summary

• CLI + Gateway: run OpenClaw locally on macOS
• OpenClaw.app: unlock system permissions and device features
• Gateway install: make it auto-start and run in the background