# Gateway on macOS

## Overview

The OpenClaw macOS application has evolved to work with an external `openclaw` CLI installation rather than bundling its own runtime. The app manages Gateway operations through launchd services.

## Key Requirements

To use local mode, you must have Node 22+ on the Mac, then install `openclaw` globally via npm. The application provides an **Install CLI** button that automates this setup.

## LaunchAgent Configuration

The system uses launchd to maintain Gateway persistence:

- **Service Label**: `bot.molt.gateway` (or `bot.molt.<profile>` for custom profiles)
- **Configuration Path**: `~/Library/LaunchAgents/bot.molt.gateway.plist`
- **Manager**: The macOS app handles installation and updates in Local mode; the CLI also supports installation via `openclaw gateway install`

## Operational Behavior

App quit does **not** stop the gateway (launchd keeps it alive). If a Gateway instance already runs on your configured port, the application attaches to it instead of launching a new process. The "OpenClaw Active" toggle controls LaunchAgent activation.

## Logging and Diagnostics

Gateway output appears at `/tmp/openclaw/openclaw-gateway.log`. Version compatibility between the app and gateway CLI is verified automatically—mismatches require updating the global CLI installation.

## Verification Commands

Test your setup using provided smoke-check commands to validate Gateway functionality on port 18999.
