openclaw - ✅(Solved) Fix LaunchAgent plist not updated on npm update — requires manual `openclaw doctor` after every upgrade [1 pull requests, 2 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#51564Fetched 2026-04-08 01:09:34
View on GitHub
Comments
2
Participants
3
Timeline
5
Reactions
0
Author
Timeline (top)
cross-referenced ×3commented ×2

Fix Action

Fix / Workaround

The npm update lifecycle (or the gateway startup itself) should detect a stale plist and either:

  • Automatically regenerate/patch the plist during postinstall, or
  • Detect the mismatch at gateway startup and self-heal, or
  • At minimum, log a clear warning like "LaunchAgent plist is outdated — run openclaw doctor --fix"

PR fix notes

PR #51811: fix(daemon): repair stale LaunchAgent plist after global updates

Description (problem / solution / changelog)

Summary

  • repair stale macOS ~/Library/LaunchAgents/ai.openclaw.gateway.plist entries during global npm postinstall updates
  • reuse the existing daemon repair logic from a narrow, non-interactive postinstall path instead of making users rerun openclaw doctor --fix
  • keep installs non-blocking and cover the global-install, opt-out, and missing-LaunchAgents-directory paths with focused tests

Testing

  • pnpm test -- src/postinstall-gateway-service.test.ts src/commands/node-daemon-install-helpers.test.ts src/cli/daemon-cli/install.integration.test.ts src/cli/daemon-cli/install.test.ts

Fixes #51564

Changed files

  • Dockerfile (modified, +2/-1)
  • docs/install/docker-vm-runtime.md (modified, +1/-1)
  • docs/install/docker.md (modified, +1/-1)
  • package.json (modified, +2/-0)
  • postinstall.mjs (added, +12/-0)
  • scripts/docker/cleanup-smoke/Dockerfile (modified, +1/-1)
  • scripts/e2e/Dockerfile (modified, +1/-1)
  • scripts/e2e/Dockerfile.qr-import (modified, +1/-1)
  • src/daemon/program-args.test.ts (modified, +22/-0)
  • src/daemon/program-args.ts (modified, +8/-2)
  • src/postinstall-gateway-service.test.ts (added, +326/-0)
  • src/postinstall-gateway-service.ts (added, +203/-0)
  • tsdown.config.ts (modified, +1/-0)
RAW_BUFFERClick to expand / collapse

Bug Description

After updating OpenClaw via npm update -g openclaw, the LaunchAgent plist file (~/Library/LaunchAgents/ai.openclaw.gateway.plist) is not automatically updated to reflect the new entry point or version metadata. This causes the gateway service to fail on next restart/reboot.

Steps to Reproduce

  1. Install OpenClaw and run openclaw doctor --fix to set up the LaunchAgent (works fine)
  2. Update OpenClaw: npm update -g openclaw
  3. Gateway service crashes or WhatsApp listener becomes unavailable
  4. Running openclaw doctor --fix regenerates the plist and fixes the issue

Expected Behavior

The npm update lifecycle (or the gateway startup itself) should detect a stale plist and either:

  • Automatically regenerate/patch the plist during postinstall, or
  • Detect the mismatch at gateway startup and self-heal, or
  • At minimum, log a clear warning like "LaunchAgent plist is outdated — run openclaw doctor --fix"

Actual Behavior

The gateway silently fails. WhatsApp (and other channel listeners) become unavailable. The user has to manually discover the issue and run openclaw doctor + reinstall the service after every update.

Environment

  • OS: macOS (arm64, Darwin 25.3.0)
  • Node: v22.22.0
  • OpenClaw version: 2026.3.13 (at time of report)
  • Install method: npm global (/opt/homebrew/lib/node_modules/openclaw)

Additional Context

The plist Comment field shows the version at install time (e.g. v2026.3.13). After an npm update, the binary changes but the plist still references the old paths/config. The KeepAlive directive causes rapid restart loops until ThrottleInterval kicks in, burning CPU.

This is a recurring issue — happens on every update cycle.

extent analysis

Fix Plan

To address the issue of the LaunchAgent plist file not being updated after an OpenClaw update, we will implement an automatic plist regeneration mechanism during the postinstall lifecycle of the npm update process.

Step-by-Step Solution

  1. Modify the postinstall script in the OpenClaw package to regenerate the plist file:
    • In the package.json file of OpenClaw, add or modify the scripts section to include a postinstall script that runs a command to regenerate the plist file.
    • Example:
      "scripts": {
        "postinstall": "node ./regeneratePlist.js"
      }
  2. Create a regeneratePlist.js script:
    • This script will check if the plist file exists and if its version matches the current OpenClaw version.
    • If the versions do not match, it will regenerate the plist file with the updated version information.
    • Example script:
      const fs = require('fs');
      const path = require('path');
      const plist = require('plist');
      
      const plistPath = path.join(process.env.HOME, 'Library/LaunchAgents/ai.openclaw.gateway.plist');
      const packageJson = require('./package.json');
      const version = packageJson.version;
      
      fs.readFile(plistPath, 'utf8', (err, data) => {
        if (err) {
          // Handle error or generate a new plist if it doesn't exist
          generateNewPlist();
        } else {
          const plistData = plist.parse(data);
          if (plistData.Label === 'ai.openclaw.gateway' && plistData.Comment !== `v${version}`) {
            // Regenerate the plist with the updated version
            generateNewPlist();
          }
        }
      });
      
      function generateNewPlist() {
        const newPlist = {
          Label: 'ai.openclaw.gateway',
          ProgramArguments: [
            process.execPath,
            './index.js',
            '--gateway'
          ],
          Comment: `v${version}`,
          KeepAlive: true,
          ThrottleInterval: 60
        };
      
        const plistString = plist.build(newPlist);
        fs.writeFile(plistPath, plistString, (err) => {
          if (err) {
            console.error('Error writing plist file:', err);
          } else {
            console.log('Plist file regenerated successfully.');
          }
        });
      }
  3. Implement a self-healing mechanism at gateway startup to detect and update the plist if it's outdated:
    • Modify the gateway startup script to check the plist version against the current OpenClaw version.
    • If the versions do not match, regenerate the plist file before starting the gateway service.

Verification

  • After implementing these changes, update OpenClaw using

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix LaunchAgent plist not updated on npm update — requires manual `openclaw doctor` after every upgrade [1 pull requests, 2 comments, 3 participants]