fix: make plugin loadable on OpenClaw 2026.5.7 + wallet funding hint#8
Merged
Conversation
Three latent bugs that block xclawrouter from loading under OpenClaw
2026.5.7's stricter plugin loader, plus eden's wallet-ready funding
hint requested earlier.
## Bug A — plugin id mismatch (fatal)
src/index.ts declared `id: "clawrouter"` while openclaw.plugin.json
manifested `"id": "xclawrouter"`. OpenClaw's loader cross-checks them
and silently refuses to load on mismatch; only `openclaw plugins
doctor` surfaces the error:
xclawrouter [validation]: plugin id mismatch
(config uses "xclawrouter", export uses "clawrouter")
Net effect: gateway boots with "0 plugins" loaded, no provider
registered, no proxy on 8402, TUI shows "no models available". Was
the rename oversight from the @blockrun/clawrouter → xclawrouter
migration.
Fix: src/index.ts plugin id → "xclawrouter".
## Bug B — manifest missing `contracts` declarations (fatal)
OpenClaw 2026.5.7 added capability contracts: plugins must declare
up front every tool/web-search/image/video/music provider they will
register at runtime. Anything undeclared is dropped and the install
itself fails with:
Config validation failed: tools.web.search.provider:
unknown web_search provider: blockrun-exa
plugin must declare contracts.tools before registering agent tools
xclawrouter registers 17 partner tools, blockrun-exa web search,
and three media providers — none were declared. Install hits this
error during the persist phase, OpenClaw rolls the install back,
the user is left with no plugin installed despite the success-looking
log lines.
Fix: openclaw.plugin.json adds a complete `contracts` block with
the 17 tool names, `webSearchProviders: ["blockrun-exa"]`, and the
three media provider ids. Also augments OpenClawPluginDefinition in
src/types.ts with an optional `contracts` field for completeness.
## Bug C — uninstall leaks our own plugin entry (minor)
src/index.ts deactivate path scrubbed legacy `clawrouter` /
`@blockrun/xclawrouter` / `XClawRouter` entries from plugins.entries
but forgot to remove `xclawrouter` itself, so reinstalls accumulated
stale records.
Fix: add `"xclawrouter"` to the cleanup key list.
## Funding-chain hint in wallet-ready summary
The setup command's success box told users the wallet was ready but
didn't say which chain to fund. OKX onchainos only signs x402 on
Base today (Solana support hasn't shipped), and naming the chain
explicitly avoids users bridging to the wrong network. Adds two
lines to the summary box:
Fund send USDC on Base to the address above
(free models work at $0; $5 unlocks paid tier)
Resolves CI 'Check formatting' failure on #8.
2 tasks
KillerQueen-Z
added a commit
that referenced
this pull request
May 14, 2026
After eden's "show what chain to fund + how much" request. The PR #8 wallet-ready box hinted at funding but had no live balance check and no concrete OKX-side steps. Users still asked "do I actually need to fund?" and "where on OKX do I send from?". Changes: - Query Base-chain USDC balance via the existing BalanceMonitor right after OKX login completes (or right after detecting an existing session in the already-signed-in branch). Network/RPC failure is non-fatal — we render "could not query Base RPC" instead of aborting setup. - Add a balance row to the wallet-ready summary box, severity-tagged: empty (< $0.0001) → yellow ⚠ "fund to unlock paid models" low ($0.0001..$1) → yellow ⚠ "recommend $5+" ok (≥ $1) → green ✓ "ready for paid models" - Only render the funding walkthrough when balance is missing/empty/low. Already-funded users see a tight 6-line box; users that need money see the OKX-specific 3-step guide: Fund via OKX (Base network, USDC): 1. Open the OKX app → Wallet 2. Send USDC on Base to the address above 3. ~$5 covers thousands of paid requests Naming OKX explicitly + naming Base explicitly avoids users bridging to a wrong network (the recurring support footgun). - Lazy-import BalanceMonitor so the CLI doesn't pull viem until setup actually needs to query a balance.
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
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.
Three latent bugs that block xclawrouter from loading under OpenClaw 2026.5.7's stricter plugin loader, plus eden's requested wallet-ready funding hint.
Bug A — plugin id mismatch (fatal)
`src/index.ts` declared `id: "clawrouter"` while `openclaw.plugin.json` manifested `"id": "xclawrouter"`. OpenClaw's loader cross-checks them and silently refuses to load on mismatch; only `openclaw plugins doctor` surfaces it:
```
xclawrouter [validation]: plugin id mismatch
(config uses "xclawrouter", export uses "clawrouter")
```
Net effect: gateway boots with "0 plugins" loaded, no provider registered, no proxy on 8402, TUI shows "no models available". Reproduced live this afternoon — was the rename oversight from the `@blockrun/clawrouter` → `xclawrouter` migration.
Bug B — manifest missing `contracts` declarations (fatal)
OpenClaw 2026.5.7 added capability contracts: plugins must declare up front every tool / web-search / image / video / music provider they'll register at runtime. Anything undeclared is dropped and the install itself fails during persist:
```
Config validation failed: tools.web.search.provider:
unknown web_search provider: blockrun-exa
plugin must declare contracts.tools before registering agent tools
```
xclawrouter registers 17 partner tools, blockrun-exa web search, and three media providers — none were declared. OpenClaw rolls the install back, user left with no plugin despite success-looking log lines.
`openclaw.plugin.json` adds a complete `contracts` block listing all 17 tools, `webSearchProviders: ["blockrun-exa"]`, and the three media provider ids. Also augments `OpenClawPluginDefinition` in `src/types.ts` with an optional `contracts` field for completeness.
Bug C — uninstall leaks own plugin entry (minor)
Deactivate path scrubbed legacy `clawrouter` / `@blockrun/xclawrouter` / `XClawRouter` entries from `plugins.entries` but forgot to remove `xclawrouter` itself, so reinstalls accumulated stale records.
Fix: add `"xclawrouter"` to the cleanup key list.
Funding-chain hint (eden's request)
The setup command's success box told users the wallet was ready but didn't say which chain to fund. OKX onchainos only signs x402 on Base today (Solana support hasn't shipped per src/proxy.ts warning), and naming the chain explicitly avoids users bridging to the wrong network. Two lines added to the summary box:
```
│ Fund send USDC on Base to the address above │
│ (free models work at $0; $5 unlocks paid tier) │
```
Why npm 0.12.182 didn't show this
Boss likely tested on an older OpenClaw or via the `curl ... | bash` path with reinstall.sh's `--force` flag. The new validation only fires under OpenClaw 2026.5.7+'s capability-registry path, exercised by `openclaw plugins install` directly (Option 2/3 in README). Once 0.12.182 reaches OpenClaw 2026.5.7 users on those paths, they hit the same bugs we reproduced today.
Test plan