openclaw - 💡(How to fix) Fix gateway.cmd does not inherit system PATH when run under macOS LaunchAgent [1 participants]

Summary

When OpenClaw is launched via macOS LaunchAgent (e.g., for headless cron scheduling on a Mac), gateway.cmd runs with a minimal PATH that doesn't include user-installed binaries. Tool invocations that depend on node, python3, git, etc. either fail silently or pick up wrong versions (often falling back to system-bundled tools at /usr/bin/...).

Observed in

• Production deployment on a headless Mac Mini, running OpenClaw under a ~/Library/LaunchAgents/<name>.plist
• Originally observed against OpenClaw v2026.2.26; persists in our deployment on later versions because we've worked around it (see below) and never re-tested without the workaround.

Reproduction

1. Install OpenClaw on macOS.
2. Configure a LaunchAgent plist for the gateway with no explicit EnvironmentVariables.PATH key.
3. Boot the agent under the LaunchAgent (not from an interactive shell).
4. From an agent prompt, invoke a tool that shells out to node, python3, or git and depends on a homebrew/pyenv-managed version.
5. Tool either fails silently or runs against /usr/bin/python3 (system) instead of the user-managed binary.

The root cause is that LaunchAgent inherits a minimal PATH (typically /usr/bin:/bin:/usr/sbin:/sbin) and gateway.cmd doesn't source the user's shell profile or accept a config-level PATH.

Workaround

Explicit PATH in the LaunchAgent plist:

<key>EnvironmentVariables</key>
<dict>
  <key>PATH</key>
  <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>

Works, but every macOS user setting up headless OpenClaw has to discover this independently. The failure mode is silent — tools just behave wrong.

Suggested fix

One of (in increasing intrusiveness):

1. Document the LaunchAgent setup pattern explicitly in the macOS install docs so users don't hit this silently.
2. Accept a PATH config key in OpenClaw config that gets prepended to the inherited environment when the gateway boots.
3. Source the user's shell profile (~/.zshrc / ~/.bash_profile) before tool invocations on macOS LaunchAgent runs.

(1) alone would already prevent most of the pain.

Severity

High for macOS LaunchAgent users, zero impact for everyone else.