openclaw - 💡(How to fix) Fix openclaw plugins install <path> rejects valid plugin paths with cryptic error; correct install path nowhere documented [1 comments, 2 participants]

Summary

In plain English: openclaw plugins install <path> rejects valid plugin paths with the error "Invalid path: must stay within extensions directory" — but it never tells you where that directory is. Users hit this trying to install a plugin from a build-output dir; the error gives no actionable guidance and the secondary "hook pack" error muddies the diagnosis further. Workaround: skip the CLI and cp -a the plugin directly into /sandbox/.openclaw-data/extensions/<plugin-id> — auto-discovery picks it up at next gateway start.

Repro

# In a NemoClaw sandbox image build (Dockerfile step):
RUN openclaw plugins install /opt/openclaw-deep-observability

Output:

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

Exit 1.

The plugin tree at /opt/openclaw-deep-observability/ is a perfectly valid OpenClaw plugin (built dist/, package.json with openclaw.plugin block, etc.). The CLI rejects it because the source path isn't already located under the extensions directory.

Root cause

openclaw plugins install <path> requires the source path to already be located under the configured extensions directory (in NemoClaw, that's /sandbox/.openclaw-data/extensions/, symlinked from /sandbox/.openclaw/extensions). The error message names "extensions directory" but doesn't print the path the CLI is checking against, doesn't say the contract is "must already be there before install can run", and doesn't say the install is essentially a registration step rather than a copy step.

The secondary "hook pack" error is a fallback attempt that fires when the plugins install path doesn't recognize the directory shape. It compounds the confusion because users see two errors and don't know which is the actual reason for the failure.

Workaround we use

Skip openclaw plugins install entirely. cp -a the plugin tree into the extensions directory; the gateway auto-discovers it at startup:

cp -a /opt/openclaw-deep-observability /sandbox/.openclaw-data/extensions/openclaw-deep-observability

After the cp, openclaw plugins list shows the plugin discovered with all hooks registered.

Suggested fix (in priority order)

1. Print the expected path in the error message

-Invalid path: must stay within extensions directory
+Invalid path: source must already be located under the extensions directory
+(currently /sandbox/.openclaw-data/extensions/). To install from a source
+outside this directory, copy the plugin into place first:
+    cp -a <source> /sandbox/.openclaw-data/extensions/<plugin-id>

This alone removes 90% of the confusion. Users get an immediately actionable hint.

2. Drop the secondary "hook pack" error when "Invalid path" already fired

The second error is misleading — users assume the plugin IS broken, when actually the plugins-install CLI just rejected the path before it could examine the plugin contents.

3. Make plugins install <path> accept any path and copy/link automatically

The friendlier behavior: detect that <path> is a valid plugin (has package.json + openclaw.plugin.json or openclaw.hooks block), and copy/link it into the extensions directory automatically. This matches what users expect from pip install <path>, npm install <path>, etc.

If a copy is undesirable (read-only build context, etc.), an --in-place=copy|link|register-only flag would let the user pick.

Alternatives considered

• Document the contract loudly in the CLI help: lower bar than fixing the error, but openclaw plugins install --help is short and doesn't include this gotcha. A docs fix alone would be insufficient given how many users hit this.

Test plan

After fix lands:

• openclaw plugins install /tmp/path/outside-extensions should either succeed (option 3) or fail with a clear error pointing at the right copy command (option 1).
• openclaw plugins install /sandbox/.openclaw-data/extensions/<existing-plugin> should still work as today.

Risk / blast radius

• Option 1 (better error message): zero risk.
• Option 2 (drop secondary error): zero risk.
• Option 3 (auto-copy): bigger change. Risk of accidentally writing to a system path. Mitigated by limiting destination to the extensions directory (already enforced).

Open questions for maintainers

1. Is the "must stay within extensions directory" constraint a security one (preventing arbitrary-path symlink attacks), or just an artifact of the registration-vs-copy split? The answer affects which fix path to take.
2. The auto-discovery from extensions/ already works without plugins install. What's the intended use case for plugins install once the plugin's already in extensions? (Worth clarifying in docs regardless of fix path.)

Tested-against

• OpenClaw v2026.4.9
• NemoClaw v0.0.26 (sandbox provider — extensions path is /sandbox/.openclaw-data/extensions/)

Severity

Medium-high. Anyone trying to install an OpenClaw plugin via the CLI for the first time hits this; the error doesn't lead anywhere productive without source-diving into the openclaw npm package.