Skip to content

fix: make plugin loadable on OpenClaw 2026.5.7 + wallet funding hint#8

Merged
KillerQueen-Z merged 2 commits into
mainfrom
fix/plugin-id-and-contracts
May 13, 2026
Merged

fix: make plugin loadable on OpenClaw 2026.5.7 + wallet funding hint#8
KillerQueen-Z merged 2 commits into
mainfrom
fix/plugin-id-and-contracts

Conversation

@KillerQueen-Z
Copy link
Copy Markdown
Collaborator

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

  • `openclaw plugins doctor` clean: "No plugin issues detected."
  • `openclaw plugins install --force ` succeeds end to end (no rollback)
  • Gateway restart loads plugin: log shows `BlockRun provider registered`, `x402 proxy listening on port 8402`
  • `curl /v1/models` returns 188 models
  • TUI on main agent shows blockrun/* in picker
  • Real chat completion routes successfully (`free/gpt-oss-120b` chosen with $0 wallet)
  • `npm run typecheck` clean, `npx vitest run src/` passes, prettier clean

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.
@KillerQueen-Z KillerQueen-Z merged commit 5c39d09 into main May 13, 2026
3 checks passed
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant