Greptile Summary

This PR adds optional documentation for an operator-managed macOS launchd watchdog that monitors Gateway health and attempts recovery when the process is alive but unhealthy. The scope is correctly limited to docs, clearly framed as optional, and the recovery order (doctor → doctor --fix → gateway restart) is conservative and sensible.

Key findings:

• The example watchdog script invokes openclaw as a bare command. launchd runs jobs with a very restricted default PATH (/usr/bin:/bin:/usr/sbin:/sbin), so npm global binaries (installed to /usr/local/bin, nvm shims, etc.) will not be found. Every openclaw call will silently exit with "command not found" (exit code 127), and because each remediation line uses || true, the failures are swallowed. Operators will believe the watchdog is active and protecting them when it is doing nothing. The example should use a full absolute path or inject the correct PATH via EnvironmentVariables in the plist.
• The cross-reference added in updating.md is clean and the anchor slug correctly matches the new section heading.
• The launchctl bootstrap/bootout commands, the plist structure, and the StartInterval: 60 interval are all correct.

Confidence Score: 3/5

• Docs-only PR; safe to merge after addressing the PATH issue in the watchdog script example, otherwise operators will set up a watchdog that silently never fires.
• The change is entirely documentation, so there is no risk to runtime behavior. However, the watchdog script example has a real usability defect (bare openclaw command will not be found by launchd) that would cause the feature to silently not work for most users without warning. This needs to be fixed before the docs are published to avoid giving operators a false sense of security.
• docs/platforms/mac/bundled-gateway.md — the watchdog script's PATH handling needs to be addressed.

This is a comment left during a code review.
Path: docs/platforms/mac/bundled-gateway.md
Line: 93-102

Comment:
**`openclaw` may not be on launchd's PATH**

When launchd executes this script, its default `PATH` is very restricted (typically `/usr/bin:/bin:/usr/sbin:/sbin`). npm global binaries are usually installed in locations like `/usr/local/bin`, `~/.npm-global/bin`, or inside an nvm/nodenv shim directory — none of which are in launchd's default PATH.

As written, every `openclaw` call will produce a "command not found" error (exit code 127). Because the remediation lines all end in `|| true`, those failures are silently swallowed. The watchdog will appear to run successfully (launchd shows it as active) but will do absolutely nothing, leaving operators with a false sense of security.

The fix is to either resolve the binary path explicitly in the script, or inject it via the plist's `EnvironmentVariables`:

**Option A – resolve path at the top of the script:**
```suggestion
#!/bin/zsh
set -euo pipefail

# Resolve openclaw binary — adjust if you installed via nvm, nodenv, pnpm, etc.
OPENCLAW_BIN="${OPENCLAW_BIN:-/usr/local/bin/openclaw}"

if "$OPENCLAW_BIN" health --json >/dev/null 2>&1; then
  exit 0
fi

"$OPENCLAW_BIN" doctor >/dev/null 2>&1 || true
"$OPENCLAW_BIN" doctor --fix >/dev/null 2>&1 || true
"$OPENCLAW_BIN" gateway restart >/dev/null 2>&1 || true
```

**Option B – extend PATH inside the plist** (add before `StartInterval`):
```xml
<key>EnvironmentVariables</key>
<dict>
  <key>PATH</key>
  <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>
```

At minimum the docs should warn readers to verify (e.g. `which openclaw`) and substitute the correct absolute path for their install.

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: fe7ef93}

Follow-up after local validation:

• I tightened the wording so this is explicitly scoped to local macOS LaunchAgent setups.
• I verified that Docker/container deployments already have a documented HEALTHCHECK + restart-policy path in docs/install/docker.md and docker-compose.yml.
• I verified that Linux/systemd deployments already document Restart=-based recovery.

So this PR is intentionally not presenting the watchdog as a cross-platform default; it documents an optional operator-managed runbook for a narrower macOS local-service case.

Good catch — launchd's default PATH was the real footgun here, and the original example could indeed fail quietly while still looking "installed".

I updated the docs to make that failure mode much less likely:

• the script now uses OPENCLAW_BIN with an absolute default path instead of a bare openclaw command
• the docs explicitly tell the operator to verify the path first with which openclaw
• the LaunchAgent example now also sets EnvironmentVariables.PATH as a second layer of protection

So the example no longer depends on launchd inheriting a friendly shell PATH, which was the weak spot in the first draft.

Thanks — this was a real issue, not just wording.

Quick follow-up after the latest push:

• rebased onto current main
• resolved the docs/install/updating.md conflict against the newer update docs layout
• kept the launchd PATH hardening from the previous fix (OPENCLAW_BIN + explicit EnvironmentVariables.PATH)
• current docs checks are passing on fc7424cccb

So at this point the PR should be back to a clean docs-only state and ready for re-review. If there's still anything unclear or too operator-footgun-y in the runbook, I can tighten it further.

@codex review

Docs checks are green and the PR is now cleanly rebased on current main.

If a maintainer has a minute for a quick docs review, this should be ready to merge.

Codex review: found issues before merge.

Summary
This PR adds an optional macOS LaunchAgent watchdog recovery runbook and links it from the update rollback docs.

Reproducibility: Do we have a high-confidence way to reproduce the issue? Yes, by static inspection of the PR diff against current main: healthCommand keeps exit success after Gateway RPC reachability, and managed Gateway services preserve profile/config/state variables that the sample LaunchAgent omits.

Next step before merge
The remaining blockers are concrete, but choosing whether to narrow this docs runbook or wait for the broader rescue-watchdog work needs maintainer/product judgment.

Security
Cleared: The PR is documentation-only and does not modify repository code execution, CI, dependencies, lockfiles, workflows, package metadata, or committed executable scripts.

Review findings

• [P2] Align the watchdog gate with the promised failure mode — docs/platforms/mac/bundled-gateway.md:107-109
• [P2] Carry the managed service environment into the watchdog — docs/platforms/mac/bundled-gateway.md:133-137