From 4919edcec1a1f8c40306a971dbfbc88372644449 Mon Sep 17 00:00:00 2001 From: Stefano Fiorini Date: Mon, 30 Mar 2026 08:05:53 -0500 Subject: [PATCH] Fix ACP startup guidance for managed acpx path --- docs/openclaw-acp-orchestration.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/openclaw-acp-orchestration.md b/docs/openclaw-acp-orchestration.md index 6974ff8..d06b87b 100644 --- a/docs/openclaw-acp-orchestration.md +++ b/docs/openclaw-acp-orchestration.md @@ -61,7 +61,6 @@ The current host-local OpenClaw config keeps the native `main` orchestrator and - `acp.maxConcurrentSessions = 2` - `plugins.allow += acpx` - `plugins.entries.acpx.enabled = true` -- `plugins.entries.acpx.config.command = /opt/homebrew/lib/node_modules/openclaw/dist/extensions/acpx/node_modules/acpx/dist/cli.js` - ACP-specific `cwd` values are absolute paths, not `~`-prefixed shortcuts The `main` entry is intentional. Once `agents.list` is populated, OpenClaw treats that list as the agent inventory. If `main` is omitted, ACP targets can displace the native orchestrator and break the intended architecture. @@ -89,17 +88,19 @@ Important health nuance: - `openclaw plugins inspect acpx --json` only tells you the plugin is loaded, not that the ACP backend is healthy enough for `sessions_spawn runtime:"acp"` - the actual readiness signal is the gateway log line `acpx runtime backend ready` -- during rollout, the backend stayed unavailable until ACP-specific `cwd` values were changed from `~/.openclaw/workspace` to absolute paths and the plugin command was pinned to the direct `acpx/dist/cli.js` entrypoint +- during rollout, the backend stayed unavailable until ACP-specific `cwd` values were changed from `~/.openclaw/workspace` to absolute paths +- a later startup bug showed that pinning a custom `command` path disables the plugin-local managed install path and can leave ACP unavailable after a restart if the local `acpx` artifact is absent at boot +- the current host fix is to leave `plugins.entries.acpx.config.command` unset so the bundled plugin can manage its own plugin-local `acpx` binary Maintenance note: -- the pinned command path and `expectedVersion = "0.3.1"` are intentionally explicit because they were needed to get this host healthy +- the current host intentionally uses the managed plugin-local default command path rather than a custom override - after any OpenClaw upgrade, re-run: - `openclaw config validate` - `openclaw plugins inspect acpx --json` - `openclaw logs --limit 80 --plain --timeout 10000 | rg 'acpx runtime backend (registered|ready|probe failed)'` - - `node /opt/homebrew/lib/node_modules/openclaw/dist/extensions/acpx/node_modules/acpx/dist/cli.js --version` -- if the pinned path or version no longer matches the bundled layout, update the config deliberately instead of assuming the old override remains valid + - `ls -l /opt/homebrew/lib/node_modules/openclaw/dist/extensions/acpx/node_modules/.bin/acpx` +- if ACP comes up unavailable at startup, check whether a custom `plugins.entries.acpx.config.command` override was reintroduced before debugging deeper ## Security Review