Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(cli): make wrap openclaw npm-first and idempotent

JerrettDavis3a25ed4571e9
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index f02c5df59..769ac7e9a 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -412,11 +412,6 @@ def _run_checked(
raise click.ClickException(f"{action} failed: {details}") from e
-def _default_openclaw_plugin_dir() -> Path:
- """Return repo-relative plugins/openclaw path for editable/dev installs."""
- return Path(__file__).resolve().parents[2] / "plugins" / "openclaw"
-
-
def _resolve_openclaw_extensions_dir(openclaw_bin: str) -> Path:
"""Resolve OpenClaw extension root from active config file path."""
result = _run_checked([openclaw_bin, "config", "file"], action="openclaw config file")
@@ -828,12 +823,18 @@ def cursor(port: int, no_rtk: bool, no_proxy: bool, learn: bool, verbose: bool)
"--plugin-path",
type=click.Path(path_type=Path, file_okay=False, dir_okay=True),
default=None,
- help="Path to the OpenClaw plugin source directory (default: repo plugins/openclaw)",
+ help="Path to local OpenClaw plugin source directory (advanced/dev override)",
+)
+ "--plugin-spec",
+ default="headroom-openclaw",
+ show_default=True,
+ help="NPM plugin spec for OpenClaw install (used when --plugin-path is omitted)",
)
@click.option(
"--skip-build",
is_flag=True,
- help="Skip npm install/build before plugin install",
+ help="Skip npm install/build in local source mode (--plugin-path)",
)
@click.option(
"--copy",
@@ -860,6 +861,7 @@ def cursor(port: int, no_rtk: bool, no_proxy: bool, learn: bool, verbose: bool)
@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
def openclaw(
plugin_path: Path | None,
+ plugin_spec: str,
skip_build: bool,
copy: bool,
proxy_port: int,
@@ -873,8 +875,8 @@ def openclaw(
\b
What this command does:
- 1. Builds plugin source (npm install + npm run build)
- 2. Installs plugin with unsafe-install flag required by OpenClaw
+ 1. Installs OpenClaw plugin from npm (or local --plugin-path)
+ 2. Builds plugin source if --plugin-path is used
3. Writes minimal plugin config and sets contextEngine slot
4. Validates config
5. Restarts OpenClaw gateway (unless --no-restart)
@@ -890,17 +892,17 @@ def openclaw(
"'openclaw' not found in PATH. Install OpenClaw CLI first."
)
- plugin_dir = (plugin_path or _default_openclaw_plugin_dir()).resolve()
- if not plugin_dir.exists():
- raise click.ClickException(
- f"Plugin path not found: {plugin_dir}. Pass --plugin-path explicitly."
- )
- if not (plugin_dir / "package.json").exists():
- raise click.ClickException(f"Invalid plugin path (missing package.json): {plugin_dir}")
- if not (plugin_dir / "openclaw.plugin.json").exists():
- raise click.ClickException(
- f"Invalid plugin path (missing openclaw.plugin.json): {plugin_dir}"
- )
+ plugin_dir = plugin_path.resolve() if plugin_path else None
+ local_source_mode = plugin_dir is not None
+ if plugin_dir:
+ if not plugin_dir.exists():
+ raise click.ClickException(f"Plugin path not found: {plugin_dir}.")
+ if not (plugin_dir / "package.json").exists():
+ raise click.ClickException(f"Invalid plugin path (missing package.json): {plugin_dir}")
+ if not (plugin_dir / "openclaw.plugin.json").exists():
+ raise click.ClickException(
+ f"Invalid plugin path (missing openclaw.plugin.json): {plugin_dir}"
+ )
npm_bin = shutil.which("npm")
if not skip_build and not npm_bin:
@@ -913,12 +915,17 @@ def openclaw(
click.echo(" ║ HEADROOM WRAP: OPENCLAW ║")
click.echo(" ╚═══════════════════════════════════════════════╝")
click.echo()
- click.echo(f" Plugin source: {plugin_dir}")
+ if local_source_mode:
+ click.echo(f" Plugin source: local ({plugin_dir})")
+ else:
+ click.echo(f" Plugin source: npm ({plugin_spec})")
- if not skip_build:
+ if local_source_mode and not skip_build:
click.echo(" Building OpenClaw plugin (npm install + npm run build)...")
_run_checked([npm_bin or "npm", "install"], cwd=plugin_dir, action="npm install")
_run_checked([npm_bin or "npm", "run", "build"], cwd=plugin_dir, action="npm run build")
+ elif not local_source_mode and skip_build:
+ click.echo(" Skipping build: npm install mode does not build local source.")
install_cmd = [
openclaw_bin,
@@ -926,12 +933,16 @@ def openclaw(
"install",
"--dangerously-force-unsafe-install",
]
- if copy:
- install_cmd.append(str(plugin_dir))
- install_cwd = None
+ if local_source_mode:
+ if copy:
+ install_cmd.append(str(plugin_dir))
+ install_cwd = None
+ else:
+ install_cmd.extend(["--link", "."])
+ install_cwd = plugin_dir
else:
- install_cmd.extend(["--link", "."])
- install_cwd = plugin_dir
+ install_cmd.append(plugin_spec)
+ install_cwd = None
click.echo(" Installing OpenClaw plugin with required unsafe-install flag...")
install_result = subprocess.run(
@@ -946,11 +957,14 @@ def openclaw(
combined_error = "\n".join(
x for x in [install_result.stderr.strip(), install_result.stdout.strip()] if x
)
+ plugin_already_exists = "plugin already exists" in combined_error.lower()
linked_install_bug = (
"also not a valid hook pack" in combined_error.lower()
and "--dangerously-force-unsafe-install" in " ".join(install_cmd)
)
- if linked_install_bug:
+ if plugin_already_exists:
+ click.echo(" Plugin already installed; continuing with configuration/update steps.")
+ elif linked_install_bug and local_source_mode and plugin_dir is not None:
click.echo(
" OpenClaw linked-path install bug detected; applying extension-path fallback..."
)
diff --git a/tests/test_cli/test_wrap_openclaw.py b/tests/test_cli/test_wrap_openclaw.py
index c5a2f8b52..6cba09dfd 100644
--- a/tests/test_cli/test_wrap_openclaw.py
+++ b/tests/test_cli/test_wrap_openclaw.py
@@ -35,9 +35,7 @@ def _make_successful_run(calls: list[dict]) -> object:
return run
-def test_wrap_openclaw_happy_path_installs_builds_configures_and_restarts(
- runner: CliRunner, plugin_dir: Path
-) -> None:
+def test_wrap_openclaw_default_installs_from_npm_and_restarts(runner: CliRunner) -> None:
calls: list[dict] = []
def which(name: str) -> str | None:
@@ -48,35 +46,35 @@ def test_wrap_openclaw_happy_path_installs_builds_configures_and_restarts(
return mapping.get(name)
with patch("headroom.cli.wrap.shutil.which", side_effect=which):
- with patch("headroom.cli.wrap._default_openclaw_plugin_dir", return_value=plugin_dir):
- with patch("headroom.cli.wrap.subprocess.run", side_effect=_make_successful_run(calls)):
- result = runner.invoke(main, ["wrap", "openclaw"])
+ with patch("headroom.cli.wrap.subprocess.run", side_effect=_make_successful_run(calls)):
+ result = runner.invoke(main, ["wrap", "openclaw"])
assert result.exit_code == 0, result.output
cmds = [c["cmd"] for c in calls]
- assert ["npm", "install"] in cmds
- assert ["npm", "run", "build"] in cmds
assert [
"openclaw",
"plugins",
"install",
"--dangerously-force-unsafe-install",
- "--link",
- ".",
+ "headroom-openclaw",
] in cmds
assert ["openclaw", "config", "validate"] in cmds
assert ["openclaw", "gateway", "restart"] in cmds
assert ["openclaw", "plugins", "inspect", "headroom"] in cmds
- # Verify plugin install uses plugin cwd when linking
+ # Verify plugin install in npm mode does not set cwd
install_call = next(
c
for c in calls
if c["cmd"][:4]
== ["openclaw", "plugins", "install", "--dangerously-force-unsafe-install"]
)
- assert install_call["cwd"] == str(plugin_dir)
+ assert install_call["cwd"] is None
+
+ # No local build in npm mode
+ assert ["npm", "install"] not in cmds
+ assert ["npm", "run", "build"] not in cmds
# Verify config payload includes enabled + expected defaults
set_entry = next(c for c in calls if c["cmd"][:4] == ["openclaw", "config", "set", "plugins.entries.headroom"])
@@ -118,6 +116,37 @@ def test_wrap_openclaw_skip_build_and_no_restart(runner: CliRunner, plugin_dir:
assert ["openclaw", "gateway", "restart"] not in cmds
+def test_wrap_openclaw_local_source_mode_builds_and_links(runner: CliRunner, plugin_dir: Path) -> None:
+ calls: list[dict] = []
+
+ def which(name: str) -> str | None:
+ mapping = {
+ "openclaw": "openclaw",
+ "npm": "npm",
+ }
+ return mapping.get(name)
+
+ with patch("headroom.cli.wrap.shutil.which", side_effect=which):
+ with patch("headroom.cli.wrap.subprocess.run", side_effect=_make_successful_run(calls)):
+ result = runner.invoke(
+ main,
+ ["wrap", "openclaw", "--plugin-path", str(plugin_dir)],
+ )
+
+ assert result.exit_code == 0, result.output
+ cmds = [c["cmd"] for c in calls]
+ assert ["npm", "install"] in cmds
+ assert ["npm", "run", "build"] in cmds
+ assert [
+ "openclaw",
+ "plugins",
+ "install",
+ "--dangerously-force-unsafe-install",
+ "--link",
+ ".",
+ ] in cmds
+
+
def test_wrap_openclaw_fails_when_openclaw_missing(runner: CliRunner, plugin_dir: Path) -> None:
def which(name: str) -> str | None:
return None if name == "openclaw" else "npm"
@@ -171,3 +200,35 @@ def test_wrap_openclaw_uses_extension_fallback_on_linked_install_bug(
assert result.exit_code == 0, result.output
copy_fallback.assert_called_once()
+
+
+def test_wrap_openclaw_continues_when_plugin_already_exists(
+ runner: CliRunner,
+) -> None:
+ calls: list[dict] = []
+
+ def which(name: str) -> str | None:
+ mapping = {
+ "openclaw": "openclaw",
+ "npm": "npm",
+ }
+ return mapping.get(name)
+
+ def run(cmd, **kwargs): # noqa: ANN001
+ calls.append({"cmd": list(cmd), **kwargs})
+ if cmd[:3] == ["openclaw", "plugins", "install"]:
+ return MagicMock(
+ returncode=1,
+ stdout="plugin already exists: C:\\Users\\test\\.openclaw\\extensions\\headroom",
+ stderr="",
+ )
+ return MagicMock(returncode=0, stdout="", stderr="")
+
+ with patch("headroom.cli.wrap.shutil.which", side_effect=which):
+ with patch("headroom.cli.wrap.subprocess.run", side_effect=run):
+ result = runner.invoke(main, ["wrap", "openclaw", "--no-restart"])
+
+ assert result.exit_code == 0, result.output
+ cmds = [c["cmd"] for c in calls]
+ assert ["openclaw", "config", "validate"] in cmds
+ assert ["openclaw", "plugins", "inspect", "headroom"] in cmds