Skip to content

Running OpenClaw as a launchd service on macOS

The deep dive on the OpenClaw launchd plist — LaunchAgent vs LaunchDaemon, RunAtLoad and KeepAlive semantics, EnvironmentVariables, StandardOutPath, plutil-lint, log rotation, and SMAppService for the optional menubar companion.

You have OpenClaw (openclaw.ai) installed on macOS and the gateway works when you run it in a terminal. Now you want it to come back after every reboot, after every sleep-wake cycle, after every macOS point update, without you having to think about it. On macOS that means launchd — Apple’s native init system — and a property list (plist) describing the job. This article is the deep dive on the plist itself: the right scope (LaunchAgent, not LaunchDaemon), the directives that matter, the gotchas with KeepAlive semantics, and the verification commands.

Scenario

A Mac running macOS 13 Ventura or newer, with OpenClaw installed globally via Homebrew Node or nvm. You log in graphically, the agent runs as you (not root), and you want:

  • The gateway started at login.
  • The gateway restarted automatically if it crashes, not restarted when you intentionally stop it for maintenance.
  • Logs in stable, named files under ~/.openclaw/logs/ rather than scattered in the system journal.
  • Environment variables (PATH, HOME, NODE_COMPILE_CACHE) explicitly declared, because launchd inherits almost nothing from your interactive shell.

Outcome and prereqs

When this is done you’ll have:

  • A LaunchAgent plist at ~/Library/LaunchAgents/ai.openclaw.gateway.plist.
  • launchctl print gui/$(id -u)/ai.openclaw.gateway showing the job loaded, the process running, the last exit status zero.
  • Logs rotating in ~/.openclaw/logs/.
  • plutil -lint returning OK on the plist.

Prereqs:

  • macOS 13 Ventura or newer (15 Sequoia for the menubar companion app).
  • OpenClaw installed and openclaw onboard has been run at least once.
  • which openclaw returns the executable path you will hard-code into the plist.

Time and resource footprint

10-15 minutes attended. The plist itself is a one-time write; launchd handles the rest.

Step 1 — LaunchAgent vs LaunchDaemon

This is the decision that decides everything else.

LaunchAgentLaunchDaemon
Runs asThe logged-in userroot (or a specified user, but typically root)
Loaded whenThe user logs in graphicallyAt boot, before any user logs in
Location~/Library/LaunchAgents/ or /Library/LaunchAgents//Library/LaunchDaemons/
Right for OpenClaw on a personal MacYesNo

OpenClaw is a personal agent. It needs your user’s file ACLs (~/Documents, ~/Downloads, ~/Mail, Keychain access, Automation prompts for Safari/Calendar/Messages). A LaunchDaemon running as root has none of those by default and would fight every macOS privacy prompt. Even worse, granting node blanket Automation access at the root level is a security footgun.

Use a LaunchAgent in ~/Library/LaunchAgents/. The OpenClaw --install-daemon flag does exactly this; this article walks you through writing it by hand so you understand every line.

Step 2 — Write the plist

Save the following at ~/Library/LaunchAgents/ai.openclaw.gateway.plist. Replace /Users/your-username and the openclaw binary path with what whoami and which openclaw return.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.openclaw.gateway</string>

    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/openclaw</string>
        <string>gateway</string>
        <string>--port</string>
        <string>18789</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <dict>
        <key>SuccessfulExit</key>
        <false/>
        <key>Crashed</key>
        <true/>
    </dict>

    <key>ThrottleInterval</key>
    <integer>10</integer>

    <key>EnvironmentVariables</key>
    <dict>
        <key>HOME</key>
        <string>/Users/your-username</string>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
        <key>NODE_COMPILE_CACHE</key>
        <string>/Users/your-username/.cache/openclaw-compile-cache</string>
    </dict>

    <key>WorkingDirectory</key>
    <string>/Users/your-username</string>

    <key>StandardOutPath</key>
    <string>/Users/your-username/.openclaw/logs/gateway.out.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/your-username/.openclaw/logs/gateway.err.log</string>

    <key>ProcessType</key>
    <string>Interactive</string>

    <key>Nice</key>
    <integer>0</integer>

    <key>SoftResourceLimits</key>
    <dict>
        <key>NumberOfFiles</key>
        <integer>65536</integer>
    </dict>
</dict>
</plist>

Validate the syntax before loading anything:

plutil -lint ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# /Users/.../ai.openclaw.gateway.plist: OK

plutil is bundled with macOS and is the canonical way to syntax-check a plist. The man page is plutil(1).

Step 3 — The KeepAlive semantics that bite

KeepAlive is the part of launchd that people get wrong on first read. The two safe patterns:

  • <key>KeepAlive</key><true/> — restart unconditionally. Even if you launchctl unload to do maintenance, launchd will try to bring the job back at next load. This is rarely what you want for a service you sometimes need to stop on purpose.
  • <key>KeepAlive</key><dict>...</dict> — restart conditionally. The dict above says: restart on Crashed=true, do not restart on SuccessfulExit=false (which actually means “do not insist on restarting if the process exited cleanly”). Translated: if the gateway crashes, bring it back. If you launchctl unload to do work, stay down until you load again.

ThrottleInterval sets the minimum seconds between launches. The default is 10 seconds, which is the same number the plist above declares explicitly for clarity. Without it, a tight crash loop would hammer the model provider — five back-to-back failures equals five model handshakes equals real money in some cases.

The full KeepAlive matrix is documented in the launchd.plist(5) man page.

Step 4 — Load the agent

mkdir -p ~/.openclaw/logs ~/.cache/openclaw-compile-cache

# Modern launchctl uses the bootstrap/bootout verbs
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl enable    gui/$(id -u)/ai.openclaw.gateway
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

bootstrap registers the job in the user’s GUI domain, enable ensures it is not disabled, kickstart -k starts it immediately (or restarts if already running). The older launchctl load is still supported and shorter:

launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Either works on Ventura and newer. Apple’s documentation prefers bootstrap/bootout going forward.

Check the job:

launchctl print gui/$(id -u)/ai.openclaw.gateway | head -40

You want to see state = running, pid = <some-pid>, and a last exit code = 0 (if it has restarted at all). The program line should match the absolute path in ProgramArguments.

Also confirm the listener:

lsof -nP -iTCP:18789 -sTCP:LISTEN
# COMMAND  PID USER  ... NAME
# node     ###  you  ... TCP 127.0.0.1:18789 (LISTEN)

Step 5 — Log rotation

StandardOutPath and StandardErrorPath route stdout and stderr to named files. launchd does not rotate them — that is your job. The cleanest path is newsyslog, which macOS ships with:

Create /etc/newsyslog.d/ai.openclaw.gateway.conf (run as your user; sudo to write to /etc):

# logfilename                                                  [owner:group]    mode count size when  flags [/pid_file] [sig_num]
/Users/your-username/.openclaw/logs/gateway.out.log            your-username:staff  644  7     5120  *     J
/Users/your-username/.openclaw/logs/gateway.err.log            your-username:staff  644  7     5120  *     J

That tells newsyslog to rotate each log when it crosses 5 MB, keep 7 archives, and bz2-compress (J). The man page is newsyslog.conf(5). You can also use logrotate if you have it from Homebrew, but newsyslog is built in.

If you would rather have the process itself rotate, configure OpenClaw’s log target in openclaw.json to a directory with rotation handled by an external tool you already trust.

Verification

openclaw doctor
launchctl print gui/$(id -u)/ai.openclaw.gateway | grep -E "state|pid|last exit"

A healthy openclaw doctor plus state = running from launchctl print is the canonical “this Mac is actually serving the agent” check.

Smoke-test:

openclaw agent --message "Open a Finder window at my Downloads folder and count the items"

Watch the logs:

tail -f ~/.openclaw/logs/gateway.out.log

Kill the gateway by PID. Within ThrottleInterval seconds, launchd should restart it. launchctl print ... | grep last_exit_code should show the non-zero exit and the new PID.

Reloading after a plist edit

You edited the plist, you need launchd to pick it up. The clean dance:

launchctl bootout gui/$(id -u)/ai.openclaw.gateway
plutil -lint ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

Or with the older verbs:

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl load   ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Either way, never edit the plist while the job is loaded and expect launchd to notice. It will not.

Rollback

launchctl bootout gui/$(id -u)/ai.openclaw.gateway
rm ~/Library/LaunchAgents/ai.openclaw.gateway.plist
rm /etc/newsyslog.d/ai.openclaw.gateway.conf  # if you wrote one

This stops the supervisor and removes the file. The OpenClaw install itself stays put; npm uninstall -g openclaw removes that separately. The ~/.openclaw/ directory holds your stateful surface — leave it or archive it.

Troubleshooting

Plist fails to load with Bootstrap failed: 5: Input/output error. Permissions on the file. The plist must be chmod 600 or 644 and owned by you. chmod 644 ~/Library/LaunchAgents/ai.openclaw.gateway.plist.

Job loads but immediately exits with status 1 every 10 seconds. Read ~/.openclaw/logs/gateway.err.log first. Most common: command not found because the openclaw path in ProgramArguments is wrong (you moved from Homebrew Node to nvm and forgot to update the plist), or EnvironmentVariables does not include HOME and openclaw cannot find ~/.openclaw/.

Gateway works from Terminal, dies under launchd. launchd inherits almost no environment from your shell. The EnvironmentVariables dictionary in the plist is the only env the job sees. The launchd.plist(5) man page is explicit: do not rely on ~/.zshrc running.

launchctl list | grep openclaw shows the job, but lsof -iTCP:18789 shows no listener. The process is starting and dying inside the bind step. Almost always another OpenClaw process holding the port — pgrep -af 'openclaw gateway' shows them all.

Plist edits are not taking effect. You forgot bootout before bootstrap. launchd caches the loaded version; until the job is booted out, edits to the file are inert.

Gatekeeper prompts when the agent opens Safari, Calendar, or Mail. Expected — System Settings → Privacy & Security → Automation lists node (or the wrapper) as requesting control. Approve only the apps you want the agent to touch. Do not blanket-allow.

plutil -lint reports an error at offset N. Open the plist in an editor, find character offset N, look for an unclosed <dict> or <string>. Usually a stray > in a StandardOutPath that contains an odd character.

Production-readiness

For a Mac you treat as production:

  • The plist is in version control (a personal dotfiles repo). The actual file in ~/Library/LaunchAgents/ is a symlink.
  • ~/.openclaw/ in your Time Machine or restic backup target. Skip logs/.
  • A daily cron (run via a separate launchd timer) that runs openclaw doctor and emails you on red.
  • API keys in ~/.openclaw/.env rotated quarterly.
  • Auto-update of macOS verified — after every point release, which openclaw to confirm the path is still valid (Homebrew’s prefix has not moved on Apple Silicon for a while, but check anyway).

For organizations that want this hardened across a Mac fleet with monitoring and on-call, talk to a senior operator at Stack Harbor about your self-hosted OpenClaw setup.

Sources

  • OpenClaw home page — https://openclaw.ai.
  • OpenClaw README and daemon flags — https://github.com/openclaw/openclaw.
  • launchd.plist(5) man page — Apple developer documentation: KeepAlive, RunAtLoad, EnvironmentVariables, ThrottleInterval, ProcessType.
  • launchctl(1) man page — bootstrap, bootout, enable, kickstart, print.
  • plutil(1) man page — plist linting.
  • newsyslog.conf(5) man page — log rotation.

Last verified on OpenClaw current (May 2026).