From 15b0d43412e8f2a76ec2ea12e9693ecc14a395a3 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 16 May 2026 17:11:44 +0100 Subject: [PATCH] docs: clarify plugin gateway auto-restart --- docs/plugins/manage-plugins.md | 11 +++++++---- docs/tools/plugin.md | 24 +++++++++++++++--------- docs/tools/slash-commands.md | 4 ++-- 3 files changed, 24 insertions(+), 15 deletions(-) diff --git a/docs/plugins/manage-plugins.md b/docs/plugins/manage-plugins.md index 1e277308d66..454886b263b 100644 --- a/docs/plugins/manage-plugins.md +++ b/docs/plugins/manage-plugins.md @@ -17,7 +17,7 @@ Most install workflows are: 1. find a package 2. install it from ClawHub, npm, git, or a local path -3. restart the Gateway that serves your channels +3. let the managed Gateway auto-restart, or restart it manually when unmanaged 4. verify the plugin's runtime registrations ## List and search plugins @@ -82,7 +82,10 @@ target. For routine upgrades of tracked npm, ClawHub, or hook-pack installs, use ## Restart and inspect -After installing plugin code, restart the Gateway that serves your channels: +After installing, updating, or uninstalling plugin code, a running managed +Gateway with config reload enabled restarts automatically. If the Gateway is not +managed or reload is disabled, restart it yourself before checking live runtime +surfaces: ```bash openclaw gateway restart @@ -128,12 +131,12 @@ matching `@beta` releases. For the exact fallback and pinning rules, see openclaw plugins uninstall --dry-run openclaw plugins uninstall openclaw plugins uninstall --keep-files -openclaw gateway restart ``` Uninstall removes the plugin's config entry, persisted plugin index record, allow/deny list entries, and linked load paths when applicable. Managed install -directories are removed unless you pass `--keep-files`. +directories are removed unless you pass `--keep-files`. A running managed +Gateway restarts automatically when the uninstall changes plugin source. In Nix mode (`OPENCLAW_NIX_MODE=1`), plugin install, update, uninstall, enable, and disable commands are disabled. Manage those choices in the Nix source for diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 9bbc6c54de7..2318c6ad30c 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -27,7 +27,7 @@ Before installing a plugin, make sure you have: - network access to the selected source, such as ClawHub, npm, or a git host - any plugin-specific credentials, config keys, or operating-system tools named by that plugin's setup docs -- permission to restart the Gateway that serves your channels +- permission for the Gateway that serves your channels to reload or restart ## Quick start @@ -82,15 +82,20 @@ Before installing a plugin, make sure you have: - + + Installing, updating, or uninstalling plugin code requires a Gateway + restart. When a managed Gateway is already running with config reload + enabled, OpenClaw detects the changed plugin install record and restarts the + Gateway automatically. If the Gateway is not managed or reload is disabled, + restart it yourself: + ```bash openclaw gateway restart ``` - Installing, updating, or uninstalling plugin code requires a Gateway - restart. Enable and disable operations update config and refresh the cold - registry, but a restart is still the clearest verification path for live - runtime surfaces. + Enable and disable operations update config and refresh the cold registry. + A runtime inspect is still the clearest verification path for live runtime + surfaces. @@ -204,9 +209,10 @@ openclaw plugins inspect --runtime --json openclaw gateway restart ``` -On VPS or container installs, make sure the process you restart is the actual -`openclaw gateway run` child that serves your channels, not only a wrapper or -supervisor. +Managed Gateways restart automatically after plugin install, update, and +uninstall changes that alter plugin source. On VPS or container installs, make +sure any manual restart targets the actual `openclaw gateway run` child that +serves your channels, not only a wrapper or supervisor. ## Troubleshooting diff --git a/docs/tools/slash-commands.md b/docs/tools/slash-commands.md index cd4e4956795..4404c284031 100644 --- a/docs/tools/slash-commands.md +++ b/docs/tools/slash-commands.md @@ -251,7 +251,7 @@ User-invocable skills are also exposed as slash commands: - In multi-account channels, config-targeted `/allowlist --account ` and `/config set channels..accounts....` 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 ` accepts the same plugin specs as `openclaw plugins install`: local path/archive, npm package, `git:`, or `clawhub:`, then requests a Gateway restart because plugin source modules changed. + - `/plugins install ` accepts the same plugin specs as `openclaw plugins install`: local path/archive, npm package, `git:`, or `clawhub:`. Managed Gateways restart automatically because plugin source modules changed. - `/plugins enable|disable` updates plugin config and triggers Gateway plugin reload for new agent turns. @@ -432,7 +432,7 @@ Examples: - `/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. -- Enable and disable changes hot-reload Gateway plugin runtime surfaces for new agent turns; install requests a Gateway restart because plugin source modules changed. +- Enable and disable changes hot-reload Gateway plugin runtime surfaces for new agent turns; install restarts managed Gateways automatically because plugin source modules changed.