From 65eefd65e145be39eba557b76cd272d87884903e Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 14 Feb 2026 20:14:34 +0100
Subject: [PATCH] docs: clarify node host PATH override behavior

---
 docs/cli/nodes.md   | 2 +-
 docs/nodes/index.md | 2 +-
 docs/tools/exec.md  | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/cli/nodes.md b/docs/cli/nodes.md
index 60e6fb9888..547b40e4f8 100644
--- a/docs/cli/nodes.md
+++ b/docs/cli/nodes.md
@@ -64,7 +64,7 @@ Invoke flags:
 Flags:
 
 - `--cwd <path>`: working directory.
-- `--env <key=val>`: env override (repeatable).
+- `--env <key=val>`: env override (repeatable). Note: node hosts ignore `PATH` overrides.
 - `--command-timeout <ms>`: command timeout.
 - `--invoke-timeout <ms>`: node invoke timeout (default `30000`).
 - `--needs-screen-recording`: require screen recording permission.
diff --git a/docs/nodes/index.md b/docs/nodes/index.md
index c8a787158f..9a6f3f1f72 100644
--- a/docs/nodes/index.md
+++ b/docs/nodes/index.md
@@ -279,7 +279,7 @@ Notes:
 - `system.notify` respects notification permission state on the macOS app.
 - `system.run` supports `--cwd`, `--env KEY=VAL`, `--command-timeout`, and `--needs-screen-recording`.
 - `system.notify` supports `--priority <passive|active|timeSensitive>` and `--delivery <system|overlay|auto>`.
-- macOS nodes drop `PATH` overrides; headless node hosts only accept `PATH` when it prepends the node host PATH.
+- Node hosts ignore `PATH` overrides. If you need extra PATH entries, configure the node host service environment (or install tools in standard locations) instead of passing `PATH` via `--env`.
 - On macOS node mode, `system.run` is gated by exec approvals in the macOS app (Settings → Exec approvals).
   Ask/allowlist/full behave the same as the headless node host; denied prompts return `SYSTEM_RUN_DENIED`.
 - On headless node host, `system.run` is gated by exec approvals (`~/.openclaw/exec-approvals.json`).
diff --git a/docs/tools/exec.md b/docs/tools/exec.md
index 31d2f8d286..3bf06687e4 100644
--- a/docs/tools/exec.md
+++ b/docs/tools/exec.md
@@ -75,8 +75,8 @@ Example:
   OpenClaw prepends `env.PATH` after profile sourcing via an internal env var (no shell interpolation);
   `tools.exec.pathPrepend` applies here too.
 - `host=node`: only non-blocked env overrides you pass are sent to the node. `env.PATH` overrides are
-  rejected for host execution. Headless node hosts accept `PATH` only when it prepends the node host
-  PATH (no replacement). macOS nodes drop `PATH` overrides entirely.
+  rejected for host execution and ignored by node hosts. If you need additional PATH entries on a node,
+  configure the node host service environment (systemd/launchd) or install tools in standard locations.
 
 Per-agent node binding (use the agent list index in config):