PR #75246: Fix macOS LaunchAgent PATH canonicalization

• Repository: openclaw/openclaw
• Author: NianJiuZst
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/75246

Description (problem / solution / changelog)

Summary

• Problem: macOS gateway LaunchAgent installs could persist an interactive-shell PATH containing Volta, asdf, fnm, pnpm, and other user toolchain directories.
• Why it matters: the supervised gateway and its children could resolve different Node binaries across install, doctor, and update flows.
• What changed: macOS service PATH generation now defaults to /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin, and macOS installs no longer merge old plist PATH entries back into the generated environment.
• What did NOT change (scope boundary): Linux service PATH keeps its existing user-bin/version-manager compatibility behavior, and runtime Node selection/warnings are unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #75233
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the shared minimal service PATH helper treated macOS version-manager and package-manager directories as expected service PATH entries, and the gateway install plan merged preserved existing PATH values back into rewritten service environments.
• Missing detection / guardrail: tests asserted the old macOS version-manager PATH policy rather than locking in a canonical launchd PATH.
• Contributing context (if known): Linux and macOS service PATH policy shared the same user-bin-first behavior even though launchd does not load the user's shell init.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/daemon/service-env.test.ts, src/commands/daemon-install-helpers.test.ts
• Scenario the test should lock in: macOS service env ignores HOME/env version-manager roots by default and macOS install plans do not preserve existing plist PATH entries.
• Why this is the smallest reliable guardrail: the bug is in the service environment builder and install-plan merge seam, before launchd writes the plist.
• Existing test that already covers this (if any): service audit coverage still flags non-minimal version-manager PATH entries.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

macOS openclaw gateway install, onboarding service install, and doctor service repair now write a canonical LaunchAgent PATH instead of preserving shell/version-manager PATH entries. Users who intentionally need custom tools from the gateway service should configure explicit absolute paths or service-managed environment instead of relying on the interactive shell PATH.

Diagram (if applicable)

N/A

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS dev host
• Runtime/container: Node/pnpm repo test wrapper
• Model/provider: N/A
• Integration/channel (if any): macOS launchd Gateway service
• Relevant config (redacted): N/A

Steps

1. Build a macOS gateway service environment with HOME plus FNM_DIR, PNPM_HOME, VOLTA_HOME, and ASDF_DATA_DIR.
2. Build a macOS gateway install plan with an existing PATH containing Volta, asdf, fnm, pnpm, a custom bin, and /usr/bin.
3. Audit the changed lanes and run the focused service env/install/service audit tests.

Expected

• The macOS generated service PATH is /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin.
• Existing macOS plist PATH entries are not preserved into the rewritten install environment.
• Linux user-bin PATH compatibility tests continue to pass.

Actual

• Matches expected after this patch.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Added regression assertions for the reported macOS PATH behavior and verified them with the focused test command below.

Human Verification (required)

• Verified scenarios:
  • pnpm docs:list
  • pnpm test src/daemon/service-env.test.ts src/daemon/service-audit.test.ts src/commands/daemon-install-helpers.test.ts src/commands/doctor-gateway-services.test.ts
  • pnpm exec oxfmt --check --threads=1 src/daemon/service-env.ts src/daemon/service-env.test.ts src/commands/daemon-install-helpers.ts src/commands/daemon-install-helpers.test.ts docs/gateway/doctor.md CHANGELOG.md
  • git diff --check HEAD~1..HEAD
  • pnpm changed:lanes --base upstream/main --json
  • pnpm check:changed --base upstream/main --dry-run
• Edge cases checked: macOS ignores env-configured version-manager roots by default; explicit opt-in helper behavior remains covered; Linux user-bin/version-manager PATH behavior remains covered; macOS old plist PATH preservation is skipped.
• What you did not verify: no live launchd install/restart was performed. Blacksmith Testbox pnpm check:changed was attempted with tbx_01kqfzcnffe6x8py5awx71t1tw, but the box remained queued without a run URL and was stopped to avoid leaving resources active.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) Yes, macOS generated LaunchAgent PATH is intentionally more restrictive
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: a macOS gateway service that relied on shell PATH user directories for child tools may no longer find those tools by bare name.
  • Mitigation: this matches launchd's deterministic service model; use absolute tool paths or explicit service-managed environment for required custom tools. Linux PATH behavior is unchanged.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/gateway/doctor.md (modified, +1/-1)
• src/commands/daemon-install-helpers.test.ts (modified, +34/-0)
• src/commands/daemon-install-helpers.ts (modified, +7/-1)
• src/daemon/service-env.test.ts (modified, +43/-46)
• src/daemon/service-env.ts (modified, +7/-6)