Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

openclaw gateway install generates ~/.openclaw/service-env/<label>.env with a hardcoded PATH that does not include the directory containing the openclaw binary, so child processes spawned by the gateway (e.g. agent shells) cannot find openclaw on PATH. Reproduced on 2026.5.18 with an npm-global install at ~/.npm-global/bin/openclaw.

Steps to reproduce

1. Install OpenClaw to a non-homebrew prefix: npm config set prefix ~/.npm-global && npm install -g openclaw so the binary lives at ~/.npm-global/bin/openclaw.
2. Run openclaw gateway install --force (or let an openclaw update regenerate the service env, as 2026.5.12 → 2026.5.18 did on this machine).
3. Inspect the generated env file: grep '^export PATH=' ~/.openclaw/service-env/ai.openclaw.gateway.env.
4. From an agent session (or any gateway-spawned shell), run which openclaw.

Expected behavior

The generated PATH in the service env file should include the directory of the openclaw binary that performed the install — i.e. path.dirname(process.execPath) or equivalent. Child processes of the gateway should be able to invoke openclaw from the shell.

Actual behavior

The generated PATH is hardcoded to homebrew + system paths only:

export PATH='/opt/homebrew/opt/node/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin'

/Users/<user>/.npm-global/bin (where the active openclaw binary lives) is not in the list. Agent child processes report openclaw: command not found. The LaunchAgent's inherited environment does include ~/.npm-global/bin — but the wrapper script (ai.openclaw.gateway-env-wrapper.sh) sources the generated env file, whose export PATH=... overrides the inherited value before execing node.

OpenClaw version

2026.5.18 (50a2481)

Operating system

macOS 26.2 (arm64)

Install method

npm global (npm install -g openclaw with prefix ~/.npm-global)

Model

openai/gpt-5.5 (not relevant to this bug — issue is in installer/service-env generation, not the agent runtime)

Provider / routing chain

openclaw -> openai (not relevant to this bug)

Logs, screenshots, and evidence

which openclaw from the user shell:

$ which openclaw
/Users/magpie/.npm-global/bin/openclaw
$ ls -l /Users/magpie/.npm-global/bin/openclaw
lrwxr-xr-x  1 magpie  staff  41 May 18 19:03 /Users/magpie/.npm-global/bin/openclaw -> ../lib/node_modules/openclaw/openclaw.mjs

launchctl print gui/502/ai.openclaw.gateway shows the LaunchAgent inherited PATH contains the right directory:

inherited environment = {
    PATH => /Users/magpie/.npm-global/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
}

But the generated service env file overrides it:

$ grep '^export PATH=' ~/.openclaw/service-env/ai.openclaw.gateway.env
export PATH='/opt/homebrew/opt/node/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin'

The wrapper script sources that file and then execs the gateway:

#!/bin/sh
set -eu
env_file="$1"
shift
if [ -f "$env_file" ]; then
  . "$env_file"
fi
exec "$@"

So node (and every child it spawns) inherits the narrower PATH, missing ~/.npm-global/bin.

Impact and severity

• Affected: any user whose openclaw binary lives outside the installer's hardcoded path list — npm-global installs to a user prefix, pnpm-global, volta, asdf, fnm, and other non-homebrew layouts.
• Severity: Medium. Agents cannot invoke openclaw as a shell tool from within their own sessions, which silently disables any agent workflow that calls back into the CLI (skills, hooks, recovery flows). The gateway itself stays healthy because it was launched with an absolute path.
• Frequency: Deterministic — every regeneration of the service env file reproduces it.
• Consequence: Agent reports openclaw: command not found and any CLI-dependent capability degrades silently.

Additional information

Workaround: edit the generated env file to prepend the openclaw binary's directory to PATH:

export PATH='/Users/<user>/.npm-global/bin:/opt/homebrew/opt/node/bin:...'

Then openclaw gateway restart. This holds until the next openclaw gateway install --force (which the 5.7 update suggested as a recovery step), at which point the file is regenerated and the override returns.

Suggested fix: in the service-env generator, derive the openclaw binary's directory from path.dirname(process.execPath) (or from which('openclaw') if process.execPath points to node rather than the wrapper) and prepend it to the default PATH list. Optionally also merge in the installer's own process.env.PATH so that whatever the user's shell saw is preserved.

This is the same shape of bug as #77416 / PR #77421 (channel contract API resolver assumed a layout that held for some installs but not others). The installer is making layout assumptions that hold for homebrew-installed openclaw but not for npm-global or other prefix-based installs.

AI-assisted: this report was drafted by Claude (Anthropic) based on direct investigation of the user's local install. All evidence (file paths, launchctl print output, env file contents, wrapper script contents) was read from the user's machine and verified before filing. Reporter (mogglemoss) reviewed and approved before submission.