Managing the Gateway Lifecycle on macOS

I hate it when background services silently fail. You open an app, expect everything to work, but find out a dependency didn’t start or crashed an hour ago. Managing these lifecycles manually is a waste of time, and it is frustrating to keep checking if a process is actually running while you are trying to get work done.

I want to explain how the macOS app handles the Gateway so you don’t have to guess what is happening in the background.

What You’ll Need

• The macOS app
• The openclaw CLI

Quick Start

By default, the macOS app manages the Gateway via launchd. It does not run the Gateway as a child process. When you enable Local mode, the app first tries to find an already-running Gateway on the configured port. If it can’t find one, it uses the openclaw CLI to enable the launchd service.

This setup ensures the Gateway starts at login and restarts automatically if it crashes. You can find the logs at the path shown in your Debug Settings.

If you need to restart or stop the service manually, use these commands:

# Restart the Gateway
launchctl kickstart -k gui/$UID/bot.molt.gateway

# Stop the Gateway
launchctl bootout gui/$UID/bot.molt.gateway

If you are using a specific profile with --profile or OPENCLAW_PROFILE, replace bot.molt.gateway with bot.molt.<profile>.

Troubleshooting

Unsigned Dev Builds

If you use scripts/restart-mac.sh --no-sign for local builds, the script writes a file to ~/.openclaw/disable-launchagent. This prevents launchd from pointing at an unsigned relay binary. If you want to reset this manually and allow launchd to work again, run:

rm ~/.openclaw/disable-launchagent

Attach-only Mode

If you want the app to never manage launchd, you can start it with the --attach-only or --no-launchd flags. This creates the ~/.openclaw/disable-launchagent marker so the app only attaches to a Gateway you have started manually in a terminal. You can also toggle this in the Debug Settings.

Remote Mode

If you are using Remote mode, the app will never start a local Gateway. Instead, it uses an SSH tunnel to connect to your remote host.

Ending

If you run into issues with your specific setup, ask the AI Setup Assistant.

What’s Next

• Gateway logs in Debug Settings
• Using named profiles with OPENCLAW_PROFILE