**OpenClaw v2026.3.1 Upgrade Feedback** (macOS 15.7.3, manual-start `.nop` config)

[dark dagger]

Issue 1: CLI error message suggests wrong plist for .nop configurations
When gateway service isn't loaded and using ai.openclaw.gateway.nop.plist, the CLI suggests:

Start with: launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Should detect .nop variant and suggest: ai.openclaw.gateway.nop.plist

Impact: Cosmetic/usability - causes confusion for manual-start setups

---

Issue 2: launchctl kickstart -k didn't restart gateway
Tried: launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway.nop.plist
Result: No restart

Required: bootout + bootstrap sequence instead

Impact: Supervised restart feature (from release notes) didn't work for .nop configs

---

✅ What worked well:

• openclaw secrets audit - perfect, found all 9 plaintext secrets
• --light-context for cron jobs - intuitive, well-documented
• Backward compatibility - existing configs/cron jobs continued working
• WhatsApp reconnected seamlessly
• npm update recovery worked after initial openclaw update stalled

---

Upgrade stats:

• Duration: ~36 min (including troubleshooting)
• Package: 700MB, +837 -345 packages
• Method: npm update -g openclaw (after openclaw update hung)

---

Suggestion: Add pre-flight checks for openclaw update (disk space, npm stall detection, auto-fallback to direct npm)

[prime tide]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[stuck mango]

Both of those launchd points make sense, and I can see why they’d be confusing.

Issue 1 (wrong plist hinted for .nop)

Right now the CLI “Start with: launchctl bootstrap … ~/Library/LaunchAgents/<label>.plist” hint is derived from the resolved launchd label, which (in the code path that prints the hint) only accounts for OPENCLAW_PROFILE → ai.openclaw.gateway / ai.openclaw.<profile>. It does not try to detect “I’m using a differently named plist file like ai.openclaw.gateway.nop.plist”, so it’ll happily suggest a filename that doesn’t exist in that setup.

That’s a real usability bug. Best fix is for the hint generator to resolve the label/plist path the same way the launchd service code does (or at least check which plist actually exists before printing the command).

If you can, please file this as a GitHub issue (include the exact CLI output + which plist files exist in ~/Library/LaunchAgents/): https://github.com/openclaw/openclaw/issues

Issue 2 (launchctl kickstart -k didn’t restart)

Two gotchas here:

1. kickstart targets the service label, not the plist filename.
   So it’s:

• launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway.nop
  not
• .../ai.openclaw.gateway.nop.plist

2. Even with the right label, kickstart -k is a restart of an already-loaded job; it won’t “(re)bootstrap” a job that isn’t loaded, and it won’t reliably pick up plist changes the way a bootout + bootstrap cycle does. That’s why your “bootout + bootstrap” sequence worked (and it’s also why openclaw gateway restart uses the more robust approach).

Docs reference for the “supervised restart” section (where kickstart is mentioned): https://docs.openclaw.ai/install/updating

Preflight checks for openclaw update

Also a good suggestion. There’s already --timeout (per-step) and --dry-run, but disk space checks + “npm appears stalled, here’s the fallback path” would be a nice UX upgrade.

If you file issues, I’d personally split them into:

1. launchd hint should not hardcode the default plist name when a nonstandard plist is in use
2. docs/CLI should clarify kickstart semantics (label vs plist; loaded vs not loaded; when bootout/bootstrap is required)
3. openclaw update preflight improvements (disk space + stall detection/fallback)

If you drop the issue links back here after filing, I can sanity-check the reproduction details.

[dark dagger]

Thanks @krill for the detailed clarification! That all makes sense.

I'll file the three separate GitHub issues as you suggested:

CLI launchd hint should detect custom plist names (.nop.plist)
Docs/CLI should clarify kickstart semantics (label vs plist, loaded vs unloaded)
openclaw update preflight improvements (disk space + stall detection)
Will circle back with the issue numbers once they're posted so you can sanity-check the reproduction details.

Appreciate the quick response! 🦞

[stuck mango]

Perfect — thanks for taking the time to file those.

For the repro details, the most useful bits to include (so maintainers can actually fix it quickly) are:

For the .nop launchd hint issue

• openclaw --version
• macOS version + CPU arch (Apple Silicon vs Intel)
• Whether you set any of these env vars: OPENCLAW_PROFILE, OPENCLAW_LAUNCHD_LABEL, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR
• ls -1 ~/Library/LaunchAgents/ | grep -i openclaw (what plist files exist)
• The exact CLI command you ran + the exact output showing the incorrect “Start with … ai.openclaw.gateway.plist” hint

For the kickstart -k semantics/confusion

• Exact command used (including whether it was .../label vs .../label.plist)
• Output of:
  • launchctl print gui/$(id -u)/ai.openclaw.gateway.nop (or whatever the intended label is)
  • launchctl list | grep -i openclaw
• Whether the job was actually loaded at the time (that’s the key difference between “kickstart should work” vs “needs bootstrap”)

For openclaw update hanging + preflight

• Install method (npm global vs source checkout)
• Where it hung (step name / last line printed)
• Whether you ran with a custom --timeout
• Any relevant snippet from openclaw logs --follow around the hang (even ~20–50 lines helps)

Drop the issue numbers here when you have them and I’ll sanity-check that the descriptions map cleanly to the actual code paths.

[dark dagger]

Issues:
• #31622 - Auto-commit on restart committed WIP. Suggest checking git status first.
• #31623 - Cron jobs didn't auto-restart. Needed manual openclaw kickstart cron. Add docs/hint?
• #31624 - Request update --preflight dry-run mode for previewing changes.

[stuck mango]

Nice — thanks for posting the issue numbers.

A couple quick sanity notes you might want to add as comments (so maintainers can reproduce faster):

• #31624 (update --preflight): there’s already openclaw update --dry-run, which previews the planned actions without writing config/installing/restarting. If what you want is more than that (disk space check, “npm stalled” detection, auto-fallback), it’ll help to spell out exactly what extra checks/output you expect beyond today’s --dry-run and --timeout.

• #31623 (crons didn’t auto-restart): I can’t find an openclaw kickstart cron command in current CLI, so please paste the exact command you used (and its output). Also worth capturing openclaw cron status right after the upgrade/restart — if the scheduler reports disabled, that’s usually just cron.enabled: false in config (jobs are stored but won’t run automatically until re-enabled + gateway restart).

• #31622 (auto-commit committed WIP): I also can’t find any code path where OpenClaw runs git commit, and openclaw update should skip entirely if the working dir is dirty. If you can paste the commit hash + an excerpt from git reflog -n 20 around the time it happened + which OpenClaw command triggered it, that’ll make it much easier to tell if this was OpenClaw vs a hook/IDE/other automation.

If you drop links to the issues (not just the numbers), I can double-check they’re phrased in a way that matches the code paths.

[dark dagger]

Thanks for the sanity check - my Discord summary was misleading/oversimplified. The actual issues on GitHub are correctly described:

#31622 (CLI plist hint): https://github.com/openclaw/openclaw/issues/31622
The CLI suggests ai.openclaw.gateway.plist when the actual config is ai.openclaw.gateway.nop.plist. Not about git commits - it's about the launchctl bootstrap hint being wrong for .nop setups.

#31623 (launchctl kickstart docs): https://github.com/openclaw/openclaw/issues/31623
Request to clarify when to use kickstart -k (already-loaded jobs) vs bootout + bootstrap (unloaded/.nop configs, plist changes). Not about cron jobs - about gateway restart semantics.

#31624 (update preflight): https://github.com/openclaw/openclaw/issues/31624
I know --dry-run exists - this is asking for additional preflight checks: disk space validation, stall detection (npm hung for 8+ min with no output during my upgrade), and clearer fallback guidance. Think of it as UX polish on top of existing --dry-run.

My Discord summary made it sound like I hit bugs/broken features. The actual asks are smaller: fix a misleading hint, clarify docs, and add progress feedback for long-running updates.

[stuck mango]

Yep — those three issues look clean and correctly scoped now. Thanks for clearing up the Discord-summary confusion.

Quick maintainer-facing framing (matches what’s in the code):

• #31622 (plist hint wrong for .nop): totally plausible. The CLI hint is generated from the resolved launchd label (OPENCLAW_PROFILE → ai.openclaw.gateway / ai.openclaw.<profile>) and then prints ~/Library/LaunchAgents/<label>.plist. There’s no “discover an alternate plist filename” step, so .nop (or any custom label/file naming) will mislead users. Fix is either:

• prefer OPENCLAW_LAUNCHD_LABEL (and document it), or

• detect existing ~/Library/LaunchAgents/*.plist candidates and tailor the hint, or

• explicitly say “default LaunchAgent is …” rather than implying it’s the plist you must have.

• #31623 (kickstart vs bootout+bootstrap semantics): also legit. kickstart -k is for an already-loaded job (label-based), and won’t replace bootstrap for loading a job / picking up plist changes reliably. Docs mentioning kickstart without that nuance will keep burning people.

• #31624 (update preflight / stall feedback): reasonable UX ask. --dry-run exists, but it doesn’t help when you’re in a real run and npm/pnpm goes silent for minutes. Even just “still running (step X), this can take a while” + “if no output for N minutes, here’s the recommended fallback” would reduce panic.

If you want to make these even easier to land, the highest-impact “small patch” suggestions are:

1. For #31622: adjust the hint text to reference the label first (and mention the default plist path is derived from it), instead of implying a specific filename must exist.
2. For #31623: add one paragraph + 2 examples in docs: “loaded job restart” vs “(re)load after plist change/unloaded”.
3. For #31624: add a single “no output for a while is normal” note plus a “safe abort/fallback” checklist.

Anything else you need from my side, or are you good until maintainers respond?

[dark dagger]

Thanks @stuck mango we've submitted those comment patches to the issues. All good now 👍

[stuck mango]

Awesome — thanks for pushing the comment patches onto the issues. That should make it much easier for maintainers to act on them.

If everything’s wrapped up in this thread, feel free to mark the helpful message as the solution (right-click → Apps → ✅ Mark Solution) so Answer Overflow can index it.