Fix macOS Gateway LaunchAgent Issues

Two Issues on This Page

launchctl kickstart failed — Gateway service not registered after upgrade
CLT does not support macOS 26 — Skill installs fail due to node-gyp version check

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

Need proactive alerts? Join Monitor early access.

Jump to Section

Fix: launchctl kickstart failed Why the Plist Goes Missing Fix: CLT Does Not Support macOS 26 Verify Gateway is Running Still Not Working

Issue 1: launchctl kickstart failed

What the Error Looks Like

launchctl kickstart failed: Could not find service "ai.openclaw.gateway"

% openclaw doctor --fix

kickstart: Could not find service "ai.openclaw.gateway"

This error means the LaunchAgent plist (ai.openclaw.gateway.plist) is either missing from ~/Library/LaunchAgents/ or wasn't properly loaded by launchd.

Fix: Re-register the LaunchAgent

4-Step Fix

# Step 1: Unload any stale registration

launchctl bootout gui/$UID/ai.openclaw.gateway

# Step 2: Remove old plist (may already be gone)

rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# Step 3: Reinstall the gateway service

openclaw gateway install

# Step 4: Start

openclaw gateway start

The bootout command in Step 1 may return an error if the service was never registered — that's expected. Continue with Steps 2-4.

Step 1 — Unload stale service

launchctl bootout gui/$UID/ai.openclaw.gateway

Step 2 — Remove old plist

rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Step 3 — Reinstall service

openclaw gateway install

Step 4 — Start

openclaw gateway start

Why the Plist Goes Missing

Version upgrade removes and re-creates the plist

During some upgrades, the old plist is removed but the new one is not registered due to a stale launchd cache or permission issue.

Manual bootout without reinstall

If you previously ran "launchctl bootout" to troubleshoot but never ran "openclaw gateway install" afterwards, the service stays unregistered.

Port 18789 occupied at install time

If another process was on port 18789 when "openclaw gateway install" ran, launchd may have silently failed to complete registration.

If you suspect port conflict, check first:

Check Port 18789

lsof -i :18789
# If occupied, kill the process
kill -9 <PID>
# Then reinstall
openclaw gateway install && openclaw gateway start

Issue 2: CLT Does Not Support macOS 26

Error: Your Command Line Tools (CLT) does not support macOS 26

Install failed (exit 1)

This error appears when installing skills that have native (compiled) addons. The node-gyp build tool reads your macOS version via sw_vers and fails because version 26 is higher than its supported range. Your Xcode / Command Line Tools are fine — the issue is an outdated node-gyp.

Fix: Update node-gyp

Update node-gyp

npm install -g node-gyp@latest

Set Updated node-gyp as Default

npm config set --global node_gyp $(npm prefix -g)/lib/node_modules/node-gyp/bin/node-gyp.js

Update OpenClaw (includes updated deps)

npm install -g openclaw@latest

Then retry the skill installation that failed.

Verify Gateway is Running

Check Status

openclaw status --all
# Expected: gateway: running, port: 18789

Check LaunchAgent is loaded

launchctl list | grep openclaw

If launchctl list | grep openclaw shows a PID (first column), the service is running correctly.

Still Not Working?

Run the Doctor

npx clawkit-doctor@latest

Checks LaunchAgent registration, port availability, and gateway health automatically.

Related Issues

macOS-specific and gateway issues:

Fix It Faster With Our Tools

Config Wizard

Generate a production-ready clawhub.json in 30 seconds.

Local Doctor

Diagnose Node.js, permissions, and config issues instantly.

Cost Simulator

Calculate your agent burn rate before you get surprised.

Did this guide solve your problem?