openclaw - 💡(How to fix) Fix plugins install fails to commit install records when plugins config is loaded via $include [1 comments, 2 participants]

Summary

openclaw plugins install fails to persist install records when the plugins config section is loaded via $include. The plugin files install correctly to disk, but the commit step is rejected by the $include-ownership protection added in cd0092c654 (fix for #70087). This leaves the plugin physically present but unloadable at runtime.

Steps to Reproduce

1. Use $include for the plugins section in openclaw.json:

   { "plugins": { "$include": "./plugins.json5" } }

   where plugins.json5 contains allow, slots, entries (no installs).

2. Run:

   openclaw plugins install @openclaw/brave-plugin --force

3. Files install correctly to ~/.openclaw/npm/node_modules/@openclaw/brave-plugin/ (including dist/index.js).

4. The persist step fails with:

   [openclaw] Failed to start CLI: Error: Config write would flatten $include-owned config at plugins; edit that include file directly or remove the $include first.
       at preserveUntouchedIncludes (.../io-D-sSCO_A.js:1324:58)
       at resolvePersistCandidateForWrite (.../io-D-sSCO_A.js:1333:20)
       at writeConfigFile (.../io-D-sSCO_A.js:19239:23)
       ... commitPluginInstallRecordsWithWriter ... persistPluginInstall ... tryInstallPluginOrHookPackFromNpmSpec

5. plugins.installs.<id> is never written. On gateway restart:

   [plugins] installed plugin package requires compiled runtime output for TypeScript entry index.ts: expected ./dist/index.js, ./dist/index.mjs, ./dist/index.cjs, index.js, index.mjs, index.cjs (plugin=brave, source=/home/.../@openclaw/brave-plugin)

   even though dist/index.js exists and loads fine via node -e "import(...)".

6. Plugin is silently skipped at runtime. For Brave, web_search falls back to Gemini despite tools.web.search.provider: "brave" and a valid BRAVE_API_KEY.

Expected Behavior

openclaw plugins install should write the install record into the include target file when the section is $include-owned (the same way the existing protection assumes for read), or persist install records to a separate index file outside the user-edited config.

Workarounds Tried (None Work)

• Adding installs: {} to plugins.json5 then re-running install: Still errors with the same $include flatten message.
• Inlining plugins back into openclaw.json: Install proceeds further but then errors with Config validation failed: agents: Unrecognized key: "$include" because the writer revalidates the full file and other sections are still $include'd.
• openclaw config patch for plugins.installs.brave: Rejected with plugins.installs is managed by the plugin index and cannot be edited with config set.

Users with any $include layout for plugins are effectively unable to install new external plugins.

Environment

• OpenClaw v2026.5.4 (commit 325df3e), pnpm install
• Linux 6.17.0-23-generic x64, Node 22.22.2
• Gateway running as systemd user service

Impact

• Web search silently degrades to fallback provider with no warning to the agent (just provider: "gemini" in the response). Users may not notice.
• Affects any externally-installed plugin (brave, discord, etc.) on configs that use $include for plugins — which is the recommended layout for survive-updates user config.

Suggested Fix Area

commitPluginInstallRecordsWithWriter → replaceConfigFile path. Either:

1. Detect $include ownership for the plugins path and append the install record to the included file directly, or
2. Move install records out of plugins.installs into a dedicated state file (e.g. ~/.openclaw/plugins-installs.json) that doesn't participate in config write protection.

Related

• #70087 — the original $include flatten bug whose fix introduced the protection that now blocks this path