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 environment variables and the config file

Set two environment variables first:

export XAI_API_KEY="sk-..."
export OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)"

Default path:

~/.openclaw/openclaw.json

This is the currently recommended gpt-5.4 + openai-responses setup:

{
  "models": {
    "mode": "replace",
    "providers": {
      "xairouter": {
        "baseUrl": "https://api.xairouter.com/v1",
        "apiKey": "${XAI_API_KEY}",
        "api": "openai-responses",
        "models": [
          { "id": "gpt-5.4", "name": "GPT-5.4" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "xairouter/gpt-5.4" },
      "models": {
        "xairouter/gpt-5.4": {
          "alias": "Codex",
          "params": { "transport": "sse" }
        }
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    },
    "http": {
      "endpoints": {
        "responses": { "enabled": true }
      }
    }
  }
}

Notes:

• api: "openai-responses" + https://api.xairouter.com/v1 is the OpenClaw-documented custom-provider structure.
• Do not add headers.originator; keeping the provider config minimal is the better default.
• params.transport: "sse" keeps the upstream on HTTP /v1/responses; change it to "auto" if you want WebSocket-first behavior.
• This guide uses models.mode = "replace" to avoid ambiguity from built-in catalogs or agent-local models.json overrides.
• OpenClaw's built-in openai-codex OAuth path goes directly to OpenAI and does not route through XAI Router.
• Prefer injecting both apiKey and gateway.auth.token via environment variables.

3) Start the Gateway (foreground)

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

Run one minimal verification first:

curl -sS http://127.0.0.1:18789/v1/responses \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-openclaw-agent-id: main" \
  -d '{"model":"openclaw","input":"ping"}'

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