Summary

On macOS, an OpenClaw gateway launched via LaunchAgent can stay in state = running for minutes without listening on its websocket port. During that window, clients hit handshake timeouts / 1006 abnormal closure. The same gateway starts in a few seconds when run in the foreground, and also starts in a few seconds under launchd if the plist includes ProcessType = Interactive.

This looks like a launchd integration bug in the generated plist rather than a user misconfiguration.

Environment

• macOS 26.1 (arm64)
• Node /opt/homebrew/opt/node@24/bin/node
• OpenClaw 2026.3.28
• LaunchAgent label: ai.openclaw.cleancheck
• Gateway port: 19011

Current generated plist

The installed LaunchAgent contains:

• RunAtLoad = true
• KeepAlive = true
• ThrottleInterval = 1
• no ProcessType
• no explicit WorkingDirectory

Reproduction

1. Install/run the gateway as a LaunchAgent.
2. Restart it with launchctl kickstart -k gui/$(id -u)/ai.openclaw.cleancheck.
3. Immediately probe the socket and inspect logs.

Observed timeline before the plist fix:

• 09:39:09 receives SIGTERM
• 09:42:01 auth-store work begins
• 09:42:11 gateway finally starts listening on ws://127.0.0.1:19011

So the process is alive for ~3 minutes before the port is reachable.

Actual behavior

• launchctl print shows the job as state = running
• lsof shows no listener on the configured port for a long time
• clients attempting to connect during that window hit handshake failures / 1006 abnormal closure
• sampled process time is spent in Node/V8 parsing/compiling JS modules rather than doing network work

Expected behavior

A launchd-started gateway should reach listening on ws://127.0.0.1:<port> in a few seconds, similar to foreground startup.

Key evidence

1) Slow startup only under the default plist

Before the fix, restart timing looked like this:

• 09:39:09 SIGTERM
• 09:42:11 listening on ws://127.0.0.1:19011

2) Sample shows the process is stuck in JS parse/compile work

A macOS sample taken during the startup delay shows the main thread deep in Node/V8 parse/compile paths such as:

• node::contextify::CompileFunctionForCJSLoader
• v8::ScriptCompiler::CompileFunction
• v8::internal::Parser::ParseProgram
• v8::internal::Scanner::ScanString

This suggests the process is being heavily slowed during bundle cold-start rather than blocked on I/O or lock contention.

3) A/B validation with launchd

I created a temporary LaunchAgent using the same command/env but added:

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

Result: the gateway started listening in ~4 seconds.

I then applied the same change to the real LaunchAgent and reproduced again:

• 09:58:31 SIGTERM
• 09:58:35 auth-store/canvas/heartbeat complete
• 09:58:35 listening on ws://127.0.0.1:19011

Port probe succeeded at t=4s.

Why this looks like an OpenClaw bug

The user-facing problem is triggered by the LaunchAgent generated/installed by OpenClaw. If the gateway needs better launchd classification to avoid slow cold-start under macOS, that should be encoded in the generated plist or documented as required.

Right now, a default launchd deployment can look "alive" but be unreachable for minutes, which then cascades into websocket handshake errors that are hard to diagnose.

Suggested fix

When generating/installing the macOS LaunchAgent, include at least:

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

ProcessType = Interactive appears to be the important change. WorkingDirectory = / just makes the current runtime behavior explicit.

Related issue

This may be related to the broader launchd classification / throttling behavior discussed in #54861.