OpenClaw Stops Scratch Starts and Duplicate launchd Managers from Retargeting the Managed Gateway

OpenClaw has merged two main-branch fixes for a dangerous class of Gateway failure: the process an operator intends to start and the service a supervisor actually owns can diverge.

The first prevents openclaw gateway start from rewriting an existing managed service merely because the invoking shell exports scratch OPENCLAW_STATE_DIR or OPENCLAW_CONFIG values. The upstream record says this was reproduced on a live production Gateway. The second makes macOS refuse a competing system LaunchDaemon and user LaunchAgent for the same Gateway label and port instead of allowing two KeepAlive loops to fight.

These are not routine daemon polish. One bug could silently retarget durable service configuration; the other could create repeated kill-and-respawn cycles. Operators running managed Gateways should audit service ownership before the next upgrade or repair action.

The operator decision

If the Gateway is stable and neither condition applies, do not jump to an unversioned source build. Add the checks to the next controlled upgrade.

Why shell intent was not enough

A managed Gateway has durable configuration outside the current terminal: its supervisor definition determines the executable, arguments, environment and restart policy. An operator may export scratch paths intending to start a throwaway instance, but a start-time “repair” path must not reinterpret those temporary values as instructions to rewrite the installed production service.

PR #115935 changes that boundary. The supplied upstream record says a service user invoked openclaw gateway start with OPENCLAW_STATE_DIR and OPENCLAW_CONFIG pointing at scratch state, and the command rewrote the managed product service. The fix stops start-time repair from retargeting that service.

Interpretation: starting a process and changing the supervisor’s durable declaration are separate privileges and should require separate intent. Environment variables are useful process inputs; they are a poor implicit migration plan for a service definition.

Why two launchd owners are worse than one failed start

On macOS, a system-domain LaunchDaemon and a per-user LaunchAgent can each supervise a process independently. If both target the same Gateway label and port, one process can occupy the listener while the other fails, exits and is relaunched. Independent KeepAlive policies can turn a configuration mistake into persistent churn and client disconnects.

PR #97285 adds refusal logic for duplicate launchd Gateway managers. Refusal is the safer outcome: it leaves an observable ownership conflict for the operator rather than trying to win a supervisor race.

This check is macOS-specific, but the operating principle applies everywhere: one production Gateway should have one declared supervisor owner. A shell, systemd unit, container restart policy and process manager should not all compete for the same state and listener.

Safe audit and acceptance test

Before changing anything, record the current service definition, running process identity, bound port and configured state path without copying secrets into tickets or logs.

Then, in a maintenance window:

1. Confirm which supervisor owns the production Gateway.
2. Check for a second service definition targeting the same label, executable, state directory or port.
3. Start a disposable Gateway only with harmless fixture state and a distinct port.
4. Export alternate state/config paths in that disposable shell and run the candidate start workflow.
5. Prove the production service definition remains byte-for-byte unchanged.
6. On macOS staging, create a controlled duplicate-manager condition and confirm the candidate build refuses it with a useful diagnostic rather than entering a restart loop.
7. Remove the fixture, restart the intended owner once and verify channels, scheduled work and clients reconnect to the expected state boundary.

Do not manufacture a competing production LaunchDaemon or edit a live service definition merely to test this. Use a disposable host or isolated fixture.

Incident response

If a managed Gateway suddenly points at the wrong state or repeatedly respawns:

• stop issuing blind start, repair or update commands;
• preserve the supervisor definitions and Gateway logs;
• identify the authoritative state/config paths before restoring service;
• check for competing listeners and supervisor domains;
• remove or disable only the confirmed duplicate owner; and
• verify the recovered process opens the intended state before allowing inbound automation.

Do not delete the apparent scratch state until you know whether the misdirected service wrote new sessions, schedules or approvals there.

Evidence and limits

OpenClaw Academy reviewed the official merged pull-request, commit and documentation-change records supplied by the repository collector. Upstream labels both changes P1 and reports proof for the fixes; the live PR pages could not be independently retrieved during this run because the configured web backends were unavailable. We did not reproduce the production retargeting incident or create competing launchd managers.

No supplied release record establishes a packaged version containing both commits. The audit and acceptance procedure above is our operator guidance, not an upstream claim.

Bottom line

A production Gateway should not be redefined by a scratch shell and should never have two supervisors fighting over it. Audit the durable service owner now, keep disposable instances genuinely separate, and adopt these fixes through a confirmed containing release or pinned source revision—not by guessing that “latest” includes them.