fix: hot reload plugin management changes (#75976)

Summary:
- The PR changes Gateway reload planning, CLI plugin install-index writes, plugin runtime/cache cleanup, docs, changelog, and tests so plugin enable/disable hot reloads while install/update/uninstall stay restart-backed.
- Reproducibility: yes. The earlier blocker has a source-level reproduction: run an external plugin install/up ...  watches config and only the managed plugin index changes; the PR now tests that path and queues a restart.

ClawSweeper fixups:
- Included follow-up commit: fix: hot reload plugin management changes
- Included follow-up commit: fix(clawsweeper): address review for automerge-openclaw-openclaw-7597…
- Ran the ClawSweeper repair loop before final review.

Validation:
- ClawSweeper review passed for head 860594f722.
- Required merge gates passed before the squash merge.

Prepared head SHA: 860594f722
Review: https://github.com/openclaw/openclaw/pull/75976#issuecomment-4363168379

Co-authored-by: Peter Steinberger <steipete@gmail.com>
Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com>

docs/tools/plugin.md

@@ -55,6 +55,16 @@ temporary set of OpenClaw-owned plugin packages while that migration finishes.
 
   </Step>
 
+  <Step title="Chat-native management">
+    In a running Gateway, owner-only `/plugins enable` and `/plugins disable`
+    trigger the Gateway config reloader. The Gateway reloads plugin runtime
+    surfaces in process, and new agent turns rebuild their tool list from the
+    refreshed registry. `/plugins install` changes plugin source code, so the
+    Gateway requests a restart instead of pretending the current process can
+    safely reload already-imported modules.
+
+  </Step>
+
   <Step title="Verify the plugin">
     ```bash
     openclaw plugins inspect <plugin-id> --runtime --json
@@ -251,20 +261,19 @@ tool name. If a tool allowlist references plugin tools, add the owning plugin id
 to `plugins.allow` or remove `plugins.allow`; `openclaw doctor` warns about this
 shape.
 
-Config changes **require a gateway restart**. If the Gateway is running with config
-watch + in-process restart enabled (the default `openclaw gateway` path), that
-restart is usually performed automatically a moment after the config write lands.
-There is no supported hot-reload path for native plugin runtime code or lifecycle
-hooks; restart the Gateway process that is serving the live channel before
-expecting updated `register(api)` code, `api.on(...)` hooks, tools, services, or
-provider/runtime hooks to run.
+Config changes made through `/plugins enable` or `/plugins disable` trigger an
+in-process Gateway plugin reload. New agent turns rebuild their tool list from
+the refreshed plugin registry. Source-changing operations such as install,
+update, and uninstall still restart the Gateway process because already-imported
+plugin modules cannot be safely replaced in place.
 
 `openclaw plugins list` is a local plugin registry/config snapshot. An
 `enabled` plugin there means the persisted registry and current config allow the
 plugin to participate. It does not prove that an already-running remote Gateway
-child has restarted into the same plugin code. On VPS/container setups with
-wrapper processes, send restarts to the actual `openclaw gateway run` process,
-or use `openclaw gateway restart` against the running Gateway.
+has reloaded or restarted into the same plugin code. On VPS/container setups
+with wrapper processes, send restarts or reload-triggering writes to the actual
+`openclaw gateway run` process, or use `openclaw gateway restart` against the
+running Gateway when the reload reports a failure.
 
 <Accordion title="Plugin states: disabled vs missing vs invalid">
   - **Disabled**: plugin exists but enablement rules turned it off. Config is preserved.

docs/tools/slash-commands.md

@@ -250,8 +250,8 @@ User-invocable skills are also exposed as slash commands:
     - In multi-account channels, config-targeted `/allowlist --account <id>` and `/config set channels.<provider>.accounts.<id>...` also honor the target account's `configWrites`.
     - `/usage` controls the per-response usage footer; `/usage cost` prints a local cost summary from OpenClaw session logs.
     - `/restart` is enabled by default; set `commands.restart: false` to disable it.
-    - `/plugins install <spec>` accepts the same plugin specs as `openclaw plugins install`: local path/archive, npm package, `git:<repo>`, or `clawhub:<pkg>`.
-    - `/plugins enable|disable` updates plugin config and may prompt for a restart.
+    - `/plugins install <spec>` accepts the same plugin specs as `openclaw plugins install`: local path/archive, npm package, `git:<repo>`, or `clawhub:<pkg>`, then requests a Gateway restart because plugin source modules changed.
+    - `/plugins enable|disable` updates plugin config and triggers Gateway plugin reload for new agent turns.
 
   </Accordion>
   <Accordion title="Channel-specific behavior">
@@ -429,8 +429,9 @@ Examples:
 
 <Note>
 - `/plugins list` and `/plugins show` use real plugin discovery against the current workspace plus on-disk config.
+- `/plugins install` installs from ClawHub, npm, git, local directories, and archives.
 - `/plugins enable|disable` updates plugin config only; it does not install or uninstall plugins.
-- After enable/disable changes, restart the gateway to apply them.
+- Enable and disable changes hot-reload Gateway plugin runtime surfaces for new agent turns; install requests a Gateway restart because plugin source modules changed.
 
 </Note>