docs: add 'openclaw plugins enable' step to Options 2 & 3#7
Merged
Conversation
`openclaw plugins install` writes the install record (plugins.entries) but does NOT add the plugin to plugins.allow — the whitelist the gateway checks at startup to decide which plugins to actually load. Without an explicit enable, users following Options 2 or 3 saw: $ openclaw plugins install @blockrun/xclawrouter $ openclaw gateway restart # plugin loaded? no. # register() called? no. # BlockRun provider injected into openclaw.json? no. # models in OpenClaw TUI picker? no — "no models available". Reproduced live this afternoon. The fix is a single command: openclaw plugins enable xclawrouter which appends "xclawrouter" to plugins.allow in openclaw.json and tells the user to restart the gateway. With that line in place, the next restart actually loads the plugin, register() runs, the provider gets injected, and TUI sees blockrun models. Option 1 doesn't need this addition because scripts/reinstall.sh and scripts/update.sh both handle plugins.allow themselves.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
`openclaw plugins install` writes the install record (`plugins.entries`) but does NOT add the plugin to `plugins.allow` — the whitelist the gateway checks at startup. Without the explicit `enable` step, the gateway never loads the plugin, `register()` never runs, and the BlockRun provider is never injected into `openclaw.json`. Net result: TUI model picker shows "no models available".
Reproduced live just now:
```
$ openclaw plugins install @blockrun/xclawrouter # installs files
$ openclaw gateway restart # gateway up, but plugin NOT loaded
$ openclaw # TUI: "no models available"
$ grep 'BlockRun provider' /tmp/openclaw/openclaw-2026-05-13.log
(empty — register never fired)
```
Fix is a single command:
```
openclaw plugins enable xclawrouter
```
which appends `xclawrouter` to `plugins.allow`. Next restart actually loads the plugin.
Why Option 1 doesn't need this
`scripts/reinstall.sh` and `scripts/update.sh` both edit `plugins.allow` themselves as part of their post-install cleanup. The curl one-liner has always worked end-to-end; only Options 2 and 3 — which bypass those scripts — were broken.
Why `@blockrun/clawrouter` users never hit this
The OpenClaw plugin install command has never auto-enabled plugins, but clawrouter's user docs only ever recommended the curl path, so the bug stayed invisible. XClawRouter exposing Options 2/3 in the README brought it to the surface.
Long-term fix (out of scope for this PR)
This is fundamentally an OpenClaw UX issue: `install` should imply `enable`. Worth filing upstream so every plugin doesn't have to document this trap.
Changes
Two lines, one in Option 2's code block, one in Option 3's.
Test plan