Gateway on macOS

OpenClaw.app no longer bundles Node/Bun or the Gateway runtime. The macOS app expects an external

CLI install, does not spawn the Gateway as a child process, and manages a per‑user launchd service to keep the Gateway running (or attaches to an existing local Gateway if one is already running).

Install the CLI (required for local mode)

Node 24 is the default runtime on the Mac. Node 22 LTS, currently

, still works for compatibility. Then install globally:

bash
Copy
npm install -g openclaw@<version>

The macOS app’s Install CLI button runs the same global install flow the app uses internally: it prefers npm first, then pnpm, then bun if that is the only detected package manager. Node remains the recommended Gateway runtime.

Launchd (Gateway as LaunchAgent)

Label:

• text

  Copy

  ai.openclaw.gateway
  (or
  text

  Copy

  ai.openclaw.<profile>
  ; legacy
  text

  Copy

  com.openclaw.*
  may remain)

Plist location (per‑user):

• text

  Copy

  ~/Library/LaunchAgents/ai.openclaw.gateway.plist
  (or
  text

  Copy

  ~/Library/LaunchAgents/ai.openclaw.<profile>.plist
  )

Manager:

• The macOS app owns LaunchAgent install/update in Local mode.
• The CLI can also install it:
  text

  Copy

  openclaw gateway install
  .

Behavior:

• “OpenClaw Active” enables/disables the LaunchAgent.
• App quit does not stop the gateway (launchd keeps it alive).
• If a Gateway is already running on the configured port, the app attaches to it instead of starting a new one.

Logging:

• launchd stdout/err:
  text

  Copy

  /tmp/openclaw/openclaw-gateway.log

Version compatibility

The macOS app checks the gateway version against its own version. If they’re incompatible, update the global CLI to match the app version.

Smoke check

bash
Copy
openclaw --version

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

Then:

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

Related

• macOS app
• Gateway runbook