openclaw - 💡(How to fix) Fix openclaw plugins install <path> rejects valid plugin paths with cryptic 'must stay within extensions directory' error [1 comments, 1 participants]

In plain English: when you try to install a plugin from a path on disk via openclaw plugins install <path>, the CLI rejects it with a confusing error message that mentions "extensions directory" but doesn't say where that directory is. The actual constraint — that the source path has to already be located under /sandbox/.openclaw-data/extensions/ (NemoClaw) or ~/.openclaw-data/extensions/ (host install) — is documented nowhere. New plugin authors hit this on their first install attempt and have to read source to figure out the right path.

Problem

openclaw plugins install <path> fails with:

Invalid path: must stay within extensions directory
Also not a valid hook pack: Error: package.json missing openclaw.hooks

regardless of where <path> points. The error message names "extensions directory" but doesn't print which directory it expects, and the secondary "hook pack" fallback error muddies the diagnosis.

Reproducer

In a NemoClaw sandbox during build:

COPY openclaw-deep-observability/ /opt/openclaw-deep-observability/
RUN openclaw plugins install /opt/openclaw-deep-observability
# → Invalid path: must stay within extensions directory

Workaround: skip openclaw plugins install entirely and cp -a the plugin into the auto-discovery path:

RUN mkdir -p /sandbox/.openclaw-data/extensions \
    && cp -a /opt/openclaw-deep-observability /sandbox/.openclaw-data/extensions/openclaw-deep-observability

The runtime then auto-discovers the plugin from /sandbox/.openclaw-data/extensions/ without any further help. So the install command is gating something that isn't actually required for plugin loading — the runtime is more permissive than the install command.

Root cause

openclaw plugins install requires the source path to already be inside the extensions directory. The actual auto-load path on NemoClaw is /sandbox/.openclaw-data/extensions/ (symlinked from /sandbox/.openclaw/extensions); on a host install it's ~/.openclaw-data/extensions/. The CLI knows what it expects but doesn't surface this constraint in the error message or in the docs.

Proposed fix

Three improvements (any one helps; all together is the right shape):

1. Print the expected path in the error. Instead of "must stay within extensions directory", say:

   Source path must be under the extensions directory:
     <expected-path-here>
   Provided: <user's path>

2. Document the install contract in the plugin docs: "plugins install <path> requires the source to already be under <extensions-dir>; alternatively, copy the plugin directly into <extensions-dir> for auto-discovery."
3. Make plugins install <path> accept any path and copy/link the plugin into the right location automatically. This is the more user-friendly behavior and matches what most package managers do (npm install, pip install, etc.). Backwards-compatible if the path-validation logic is replaced with a "copy if outside, no-op if inside" pattern.

(3) is the biggest UX win; (1) and (2) cost nothing.

Alternatives considered

• Add a --symlink flag. Workable for hosts that allow symlinks; fails on Landlocked NemoClaw sandboxes that have RO /sandbox/.openclaw.
• Auto-detect "you mean to install from <other-path>?" via heuristics. Brittle; safer to just print the canonical path.

Test plan

• Cold install on NemoClaw: openclaw plugins install /opt/<plugin> should either succeed (after fix 3) or print the expected extensions path (after fix 1).
• Idempotent re-install: running install twice for the same plugin should not error or duplicate.

Risk / blast radius

• Fix 1 (better error) — purely cosmetic, zero risk.
• Fix 2 (docs) — purely cosmetic, zero risk.
• Fix 3 (behavior change) — needs a careful look at concurrent-install semantics and whether the source path should be moved or copied. Recommend copy-by-default with a --in-place flag for symlink behavior.

Open questions

1. Is plugins install intended for end-users or just for internal/build-time use? If the latter, fix 1 + 2 are enough; fix 3 isn't needed.
2. Are there security reasons for restricting source paths to the extensions directory? (The cp -a workaround proves auto-discovery is more permissive, so if it's a security gate, the gate is incomplete.)
3. Preferred error message format? Happy to draft a concrete patch if useful.

Tested-against: OpenClaw v2026.4.9 inside a NemoClaw v0.0.26 sandbox.

This is one of a small batch of plugin-install / gateway-lifecycle UX findings from a recent end-to-end test of the deep-observability plugin under NemoClaw — sibling issues being filed for the gateway crash on os.networkInterfaces(), the silent-truncation of async plugin register(), and the openclaw gateway stop no-op on foreground-launched gateways.