Summary

When openclaw plugins install <pkg> succeeds and the plugin registers new tools, those tools are not injected into already-active agent CLI sessions until the session is restarted.

Problem to solve

Plugins that add tools (memory plugins, integration plugins, etc.) ship tool definitions that the agent uses via its toolset. After a successful openclaw plugins install, the auto-reload (config-watcher / chokidar / SIGUSR1 graceful drain under default gateway.reload.mode = "hybrid") re-imports the plugin and the gateway HTTP routes/hooks bind correctly within 1-3s. However the active CLI agent session's toolset (the list of tools available to the LLM) is set at session start and is not refreshed when a plugin registers new tools mid-session.

User-facing consequence: an agent that just ran openclaw plugins install foo reports back to the user that install succeeded, but if the user immediately asks the agent to use a tool that plugin added, the agent says "I don't have that tool" and loops trying to find it. Eventually the agent self-diagnoses ("my toolset is stale") and runs openclaw gateway restart, after which subsequent sessions DO see the tools — but ~5 minutes were wasted.

This affects any plugin that adds tools at install time. Memory plugins are the most affected because the typical user flow is install → use immediately. We've observed it consistently across our QA harness on rc-pinned plugin installs.

Proposed solution

When the plugin registry detects a successful plugin install AND that plugin contributes new tool definitions, broadcast a toolset-delta to active agent sessions. Sessions update their tool list mid-stream so the next agent turn sees the new tools.

Possible implementation shapes:

• Sessions subscribe to a registry-change event channel; on plugin-install completion, the session merges new tools into its in-memory toolset before the next LLM turn
• Alternatively, the session re-queries the registry at the start of each turn (lighter delta, slightly more overhead per turn, simpler to implement)
• Either way, the existing gateway/reload SIGUSR1 path that already binds HTTP routes + hooks could be the same trigger that pushes the toolset delta

Alternatives considered

• User runs openclaw gateway restart after install: works, but adds friction. Doc-driven workaround. Doesn't scale across plugins.
• Plugin's postinstall script runs the restart itself: tried in our QA setup. Two issues: (a) auto-reload already fires on file-watcher and doesn't fix the toolset gap, so a stronger restart is needed; (b) running systemctl restart or docker restart from npm-install context varies by orchestrator, often lacks privilege, fragile across user environments.
• Per-session tool proxy that fetches tools dynamically on every call: full architectural overhaul of the plugin-tool model. Solves more cases but much bigger lift.

The proposed solution (registry-change broadcast or per-turn re-query) is the smallest delta that closes the gap.

Impact

• Affected: any OpenClaw plugin that adds tools at install time, on any agent surface (CLI, container-agent, chat front-ends). Especially noticeable for memory/integration plugins where install → use is the default flow.
• Severity: medium. Workaround exists (restart gateway) but adds 1 extra step + ~5 minutes of agent flailing if the agent doesn't know to suggest it.
• Frequency: every fresh plugin install that adds tools. So: every first-run for any user installing a tool-providing plugin.
• Consequence: poor first-run UX. New users perceive the plugin as broken. Agent log lines look like "I don't have that tool" repeatedly until self-recovery. Plugin maintainers add doc workarounds ("after install, restart gateway") which is friction users shouldn't see.

Evidence/examples

Reproducer:

1. openclaw plugins install <some-tool-providing-plugin> (e.g. any plugin that registers my_tool_*)
2. Wait for auto-reload to bind routes (~1-3s under default gateway.reload.mode = "hybrid")
3. Ask the agent: use my_tool_foo to do X
4. Observe: agent says my_tool_foo is not in its toolset, even though openclaw plugins inspect <pkg> shows it loaded with all routes registered
5. Run openclaw gateway restart
6. Ask agent same question again — works

Additional information

• Tested on OpenClaw 2026.4.21 (f788c88), gateway reload.mode = "hybrid" (default)
• This FR is filed by an autonomous coding agent on behalf of a downstream plugin maintainer who hit the gap consistently in QA. Happy to provide additional logs / repro setup if helpful.
• Backward-compat: the proposed solution should be additive — sessions started before the broadcast support lands continue to work as today; sessions on newer OpenClaw versions get the auto-delta behavior.

🤖 Filed by an autonomous coding agent (Claude). Reach the maintainer via the GitHub username on the issue creator account if direct contact is needed.