Configure OpenClaw Gateway on macOS via launchd

Ever had that annoying moment where you close a desktop app and your background processes suddenly die? Or maybe you’ve struggled to keep a local service running without manually opening a terminal every time you reboot. Managing background tasks on macOS can be tricky when you want a tool to stay active regardless of whether the UI is open.

OpenClaw.app handles this by moving away from bundled runtimes. Instead of managing Node or Bun internally, it expects you to have a global CLI installed. The app uses macOS launchd to manage the Gateway as a service, ensuring it stays alive in the background or connects to a process you’ve already started.

Install the CLI (required for local mode)

You should use Node 24 as your runtime on Mac, as it is the current default. If you need to stay on Node 22 LTS (specifically 22.14+), that works too. To get started, you need to install the openclaw package globally:

npm install -g openclaw@<version>

If you prefer using the UI, the Install CLI button in the macOS app triggers this same process using npm or pnpm. We don’t recommend using bun for the Gateway runtime right now.

Launchd (Gateway as LaunchAgent)

The system uses a specific label and file path to manage the service.

Label:

• ai.openclaw.gateway (or ai.openclaw.<profile>; you might still see legacy com.openclaw.* names)
• This identifier helps macOS track the background process.

Plist location (per‑user):

• ~/Library/LaunchAgents/ai.openclaw.gateway.plist
• ~/Library/LaunchAgents/ai.openclaw.<profile>.plist

Manager:

• When you are in Local mode, the macOS app handles the installation and updates of the LaunchAgent.
• You can also handle this manually via the CLI using openclaw gateway install.

Behavior:

• Toggling “OpenClaw Active” is what actually enables or disables the LaunchAgent.
• Quitting the app does not stop the gateway; launchd is responsible for keeping it alive.
• If a Gateway is already running on your configured port, the app will attach to that one instead of trying to start a second instance.
• This setup ensures your background tasks remain uninterrupted during app restarts.

Logging:

• You can find the launchd stdout and error logs at /tmp/openclaw/openclaw-gateway.log.

Version compatibility

The macOS app is picky about versions. It checks the gateway version against its own internal version string. If they don’t match up, you might run into issues. When the app tells you they are incompatible, just update your global CLI to match the version of the app you are running.

Smoke check

If you want to make sure everything is running correctly, you can run a quick manual check. First, verify the version and try starting the gateway with these flags:

openclaw --version

OPENCLAW_SKIP_CHANNELS=1 \
OPENCLAW_SKIP_CANVAS_HOST=1 \
openclaw gateway --port 18999 --bind loopback

Once that is running, open a new terminal window and test the health of the connection:

openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000

Next steps

• CLI Command Reference
• Troubleshooting Gateway Connections

AI Setup Assistant