fix(mac): avoid launchd startup crash loops

BunsDev · BunsDev · commit 68bf98c40700 · 2026-05-14T02:29:53.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- macOS/Gateway: make LaunchAgent keepalive relaunch clean exits for intentional update/restart handoffs without respawning non-zero startup failures in a launchd crash loop. Fixes #73673. Thanks @BunsDev.
 - Security/sandbox: include Windows `USERPROFILE` in the sandbox blocked home roots so credential-bearing binds (such as `.codex`, `.openclaw`, or `.ssh` under the Windows user profile) are denied even when `HOME` points at a different shell home. (#63074) Thanks @luoyanglang.
 - Models config/auth: stop inferring provider env-var markers from broad `^[A-Z_][A-Z0-9_]*$` strings, and resolve config-backed provider `apiKey` values only through structured env SecretRefs (`secrets.providers[id]` / `secrets.defaults`), so unrelated env vars cannot accidentally become provider credentials. Thanks @sallyom.
 - Media fetch: skip allocating and buffering the response body for bodyless media responses (HEAD probes and 204-style empty bodies), avoiding wasted heap on streams that carry no payload. Thanks @shakkernerd.
diff --git a/docs/platforms/mac/bundled-gateway.md b/docs/platforms/mac/bundled-gateway.md
@@ -46,6 +46,9 @@ Behavior:
 - App quit does **not** stop the gateway (launchd keeps it alive).
 - If a Gateway is already running on the configured port, the app attaches to
   it instead of starting a new one.
+- Launchd relaunches clean Gateway exits used by update/restart handoffs, but
+  non-zero startup failures remain stopped so logs stay inspectable instead of
+  looping indefinitely.
 
 Logging:
 
diff --git a/src/daemon/launchd-plist.ts b/src/daemon/launchd-plist.ts
@@ -1,9 +1,8 @@
 import fs from "node:fs/promises";
 import type { GatewayServiceEnvironmentValueSource } from "./service-types.js";
 
-// launchd defaults to a 10s spawn throttle. Keep that default explicitly so
-// crash loops back off instead of respawning every second while still allowing
-// explicit kickstart restarts to take effect.
+// launchd defaults to a 10s spawn throttle. Keep that default explicitly for
+// clean-exit relaunch handoffs and operator kickstart restarts.
 export const LAUNCH_AGENT_THROTTLE_INTERVAL_SECONDS = 10;
 export const LAUNCH_AGENT_EXIT_TIMEOUT_SECONDS = 20;
 // launchd stores plist integer values in decimal; 0o077 renders as 63 (owner-only files).
@@ -180,5 +179,5 @@ export function buildLaunchAgentPlist({
     ? `\n    <key>Comment</key>\n    <string>${plistEscape(comment.trim())}</string>`
     : "";
   const envXml = renderEnvDict(environment);
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n  <dict>\n    <key>Label</key>\n    <string>${plistEscape(label)}</string>\n    ${commentXml}\n    <key>RunAtLoad</key>\n    <true/>\n    <key>KeepAlive</key>\n    <true/>\n    <key>ExitTimeOut</key>\n    <integer>${LAUNCH_AGENT_EXIT_TIMEOUT_SECONDS}</integer>\n    <key>ProcessType</key>\n    <string>${LAUNCH_AGENT_PROCESS_TYPE}</string>\n    <key>ThrottleInterval</key>\n    <integer>${LAUNCH_AGENT_THROTTLE_INTERVAL_SECONDS}</integer>\n    <key>Umask</key>\n    <integer>${LAUNCH_AGENT_UMASK_DECIMAL}</integer>\n    <key>ProgramArguments</key>\n    <array>${argsXml}\n    </array>\n    ${workingDirXml}\n    <key>StandardOutPath</key>\n    <string>${plistEscape(stdoutPath)}</string>\n    <key>StandardErrorPath</key>\n    <string>${plistEscape(stderrPath)}</string>${envXml}\n  </dict>\n</plist>\n`;
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n  <dict>\n    <key>Label</key>\n    <string>${plistEscape(label)}</string>\n    ${commentXml}\n    <key>RunAtLoad</key>\n    <true/>\n    <key>KeepAlive</key>\n    <dict>\n      <key>SuccessfulExit</key>\n      <true/>\n    </dict>\n    <key>ExitTimeOut</key>\n    <integer>${LAUNCH_AGENT_EXIT_TIMEOUT_SECONDS}</integer>\n    <key>ProcessType</key>\n    <string>${LAUNCH_AGENT_PROCESS_TYPE}</string>\n    <key>ThrottleInterval</key>\n    <integer>${LAUNCH_AGENT_THROTTLE_INTERVAL_SECONDS}</integer>\n    <key>Umask</key>\n    <integer>${LAUNCH_AGENT_UMASK_DECIMAL}</integer>\n    <key>ProgramArguments</key>\n    <array>${argsXml}\n    </array>\n    ${workingDirXml}\n    <key>StandardOutPath</key>\n    <string>${plistEscape(stdoutPath)}</string>\n    <key>StandardErrorPath</key>\n    <string>${plistEscape(stderrPath)}</string>${envXml}\n  </dict>\n</plist>\n`;
 }
diff --git a/src/daemon/launchd.test.ts b/src/daemon/launchd.test.ts
@@ -559,7 +559,7 @@ describe("launchd install", () => {
     expect(state.dirModes.get(tmpDir)).toBe(0o700);
   });
 
-  it("writes KeepAlive=true policy with shutdown and throttle limits", async () => {
+  it("writes clean-exit KeepAlive policy with shutdown and throttle limits", async () => {
     const env = createDefaultLaunchdEnv();
     await installLaunchAgent({
       env,
@@ -570,8 +570,9 @@ describe("launchd install", () => {
     const plistPath = resolveLaunchAgentPlistPath(env);
     const plist = state.files.get(plistPath) ?? "";
     expect(plist).toContain("<key>KeepAlive</key>");
+    expect(plist).toContain("<dict>");
+    expect(plist).toContain("<key>SuccessfulExit</key>");
     expect(plist).toContain("<true/>");
-    expect(plist).not.toContain("<key>SuccessfulExit</key>");
     expect(plist).toContain("<key>ExitTimeOut</key>");
     expect(plist).toContain(`<integer>${LAUNCH_AGENT_EXIT_TIMEOUT_SECONDS}</integer>`);
     expect(plist).toContain("<key>ProcessType</key>");
diff --git a/src/daemon/service-audit.test.ts b/src/daemon/service-audit.test.ts
@@ -462,6 +462,67 @@ describe("auditGatewayServiceConfig", () => {
   });
 });
 
+describe("auditGatewayServiceConfig launchd policy", () => {
+  async function withLaunchdPlist(
+    contents: string,
+    run: (params: { env: Record<string, string>; plistPath: string }) => Promise<void>,
+  ) {
+    const tmpHome = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-launchd-audit-"));
+    const launchdDir = path.join(tmpHome, "Library", "LaunchAgents");
+    const plistPath = path.join(launchdDir, "ai.openclaw.gateway.plist");
+    try {
+      await fs.mkdir(launchdDir, { recursive: true });
+      await fs.writeFile(plistPath, contents);
+      await run({ env: { HOME: tmpHome }, plistPath });
+    } finally {
+      await fs.rm(tmpHome, { recursive: true, force: true });
+    }
+  }
+
+  it("accepts the canonical clean-exit KeepAlive dictionary", async () => {
+    await withLaunchdPlist(
+      `<?xml version="1.0" encoding="UTF-8"?>
+<plist version="1.0"><dict>
+<key>RunAtLoad</key><true/>
+<key>KeepAlive</key><dict><key>SuccessfulExit</key><true/></dict>
+</dict></plist>`,
+      async ({ env }) => {
+        const audit = await auditGatewayServiceConfig({
+          env,
+          platform: "darwin",
+          command: {
+            programArguments: ["/usr/bin/node", "gateway"],
+            environment: { PATH: "/usr/bin:/bin" },
+          },
+        });
+
+        expect(hasIssue(audit, SERVICE_AUDIT_CODES.launchdKeepAlive)).toBe(false);
+      },
+    );
+  });
+
+  it("flags launchd plists without the canonical KeepAlive policy", async () => {
+    await withLaunchdPlist(
+      `<?xml version="1.0" encoding="UTF-8"?>
+<plist version="1.0"><dict>
+<key>RunAtLoad</key><true/>
+</dict></plist>`,
+      async ({ env }) => {
+        const audit = await auditGatewayServiceConfig({
+          env,
+          platform: "darwin",
+          command: {
+            programArguments: ["/usr/bin/node", "gateway"],
+            environment: { PATH: "/usr/bin:/bin" },
+          },
+        });
+
+        expect(hasIssue(audit, SERVICE_AUDIT_CODES.launchdKeepAlive)).toBe(true);
+      },
+    );
+  });
+});
+
 describe("checkTokenDrift", () => {
   it("returns null when both tokens are undefined", () => {
     const result = checkTokenDrift({ serviceToken: undefined, configToken: undefined });
diff --git a/src/daemon/service-audit.ts b/src/daemon/service-audit.ts
@@ -186,7 +186,11 @@ async function auditLaunchdPlist(
   }
 
   const hasRunAtLoad = /<key>RunAtLoad<\/key>\s*<true\s*\/>/i.test(content);
-  const hasKeepAlive = /<key>KeepAlive<\/key>\s*<true\s*\/>/i.test(content);
+  const hasKeepAlive =
+    /<key>KeepAlive<\/key>\s*<true\s*\/>/i.test(content) ||
+    /<key>KeepAlive<\/key>\s*<dict>[\s\S]*?<key>SuccessfulExit<\/key>\s*<true\s*\/>[\s\S]*?<\/dict>/i.test(
+      content,
+    );
   if (!hasRunAtLoad) {
     issues.push({
       code: SERVICE_AUDIT_CODES.launchdRunAtLoad,
@@ -198,7 +202,7 @@ async function auditLaunchdPlist(
   if (!hasKeepAlive) {
     issues.push({
       code: SERVICE_AUDIT_CODES.launchdKeepAlive,
-      message: "LaunchAgent is missing KeepAlive=true",
+      message: "LaunchAgent is missing the canonical KeepAlive policy",
       detail: plistPath,
       level: "recommended",
     });
