v0.12.181: OKX-first wallet onboarding via guided setup

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to XClawRouter.
 
 ---
 
+## v0.12.182 — May 12, 2026
+
+- **Restore the `clawrouter` CLI bin name as a deprecation alias.** v0.12.180 renamed the bin from `clawrouter` to `xclawrouter` (matching the new package name) but didn't keep a transitional alias, so anyone running `pm2 start clawrouter`, shell aliases, or following older onboarding docs broke on upgrade. `package.json` now ships both `xclawrouter` and `clawrouter` bin entries pointing at the same `./dist/cli.js`; invocations under the old name print `clawrouter is deprecated — use xclawrouter (alias removed in v0.13)` to stderr and then continue normally. Suppress the notice with `XCLAW_SUPPRESS_RENAME_NOTICE=1`. The alias will be removed in v0.13 — one release of deprecation runway, called out in the warning text.
+- **`xclawrouter setup`: don't show users the internal enum on failure.** After `wallet verify` we re-detect; if the re-detection still isn't `kind: "ok"`, the failure message used to print the literal discriminant (e.g. `Login completed but status check failed: no-evm-address`). Added a `humanizeDetectionKind()` mapping so users see "no EVM address found — is this a Solana-only OKX account?" instead. Only used in the cmdSetup recovery path — `formatAgenticWalletStatus` already humanizes its lines.
+- **Guard the post-setup wallet re-resolve.** `src/cli.ts:main()` auto-launches `cmdSetup` on a fresh interactive install, then re-calls `resolveOrGenerateWalletKey()`. If a transient TEE issue or stale onchainos session leaves the wallet still undetected after setup claims success, the re-resolve was throwing `OnchainOsRequiredError` straight through to `main().catch` where it surfaced as a generic `[XClawRouter] Fatal error: …` log. Now we catch the second throw specifically and print a targeted "Setup completed but the wallet still isn't detected — diagnose with `onchainos wallet status`" hint before exiting non-zero.
+- **`ONCHAINOS_INSTALLER_URL` constant in `src/auth.ts`** — the curl-able OKX installer URL was duplicated between `src/cli.ts` (cmdSetup auto-install) and `scripts/reinstall.sh` (curl-one-liner path). Promoted to a shared export so the TS side has one source of truth; `reinstall.sh` keeps its bash variable (POSIX shell can't import TS), with a comment noting the two must stay in sync.
+- **`logOnchainOsRequiredError(logger, err)` helper in `src/index.ts`** — the line-by-line `for (const line of err.message.split("\n")) api.logger.warn(line)` loop was duplicated at the two wallet-resolution sites (gateway-mode `startProxyInBackground` and the non-gateway-mode `register()` callback). One helper, same behaviour.
+
+---
+
 ## v0.12.179 — May 12, 2026
 
 - **The real reason v0.12.175-178 never reached users: install scripts pulled the wrong npm package.** This XClawRouter repo bundles `scripts/reinstall.sh`, `scripts/update.sh`, `scripts/update.ps1`, and `scripts/uninstall.sh` for OpenClaw plugin installation — and all four still pointed at `@blockrun/clawrouter` (a separate, unrelated project also published on npm) instead of `@blockrun/xclawrouter` (this project). Net effect: anyone running `bash reinstall.sh` got OpenClaw to fetch a totally different codebase from npm, so none of the previous releases' silent-fallback fixes actually shipped to users on the OpenClaw path. The user-visible symptom was the original bug — silent fallback to a local key with no Agentic Wallet messaging — even though `cli.ts` / `index.ts` had been fixed two days earlier.
@@ -27,15 +37,15 @@ All notable changes to XClawRouter.
 
 - **Fix: the Agentic Wallet status block we added in v0.12.177 only fired on the standalone CLI path (`src/cli.ts`).** Users running XClawRouter as an OpenClaw plugin — which is the install path the documentation recommends — went straight through `src/index.ts`, whose two wallet-logging sites (gateway-mode `startProxyInBackground` and the non-gateway-mode `register` callback) destructured `{ address, source, email }` from the resolution and never read `onchainosDetection`. Net effect: every silent-fallback path you listed last week (onchainos installed but not logged in, binary missing, `wallet status` crashed, no EVM address available) was still silent on the OpenClaw path, just hidden one entry point further from view than the standalone CLI. Plugin users saw `Using saved wallet: 0x…` and nothing else, exactly the original bug.
 - **`formatAgenticWalletStatus(detection): AgenticWalletStatusLine[]`** — refactored from `string[]` to `{ level: "info" | "warn"; text }[]` so callers using a structured logger (OpenClaw's `api.logger.info` / `.warn`) can route failure markers (⚠ not installed, ✗ not logged in) and neutral confirmations (✓ installed, → Run …) to the right severity, while stdout callers (the standalone CLI) just print every line. The lines themselves no longer carry the `[XClawRouter]` prefix — `src/cli.ts` prepends it when emitting through `console.log`, and `src/index.ts` lets OpenClaw's logger add its own plugin-name prefix. This means the block looks identical to users on both paths (same `✓`/`⚠`/`✗`/`→` markers, same copy, same severity routing) without one site or the other carrying double prefixes.
-- **`emitAgenticWalletStatusViaLogger(logger, wallet)`** — small helper added to `src/index.ts` that calls `formatAgenticWalletStatus` and routes each line by `level` through `api.logger.info` / `.warn`. Honors `XCLAW_QUIET=1`. Invoked at both `index.ts` wallet-log sites (the gateway-mode path and the non-gateway-mode register block) immediately before the existing `Using ... wallet:` log, so the user reads "OKX Agentic Wallet not installed / not logged in / status check failed" *before* learning which local fallback we picked.
+- **`emitAgenticWalletStatusViaLogger(logger, wallet)`** — small helper added to `src/index.ts` that calls `formatAgenticWalletStatus` and routes each line by `level` through `api.logger.info` / `.warn`. Honors `XCLAW_QUIET=1`. Invoked at both `index.ts` wallet-log sites (the gateway-mode path and the non-gateway-mode register block) immediately before the existing `Using ... wallet:` log, so the user reads "OKX Agentic Wallet not installed / not logged in / status check failed" _before_ learning which local fallback we picked.
 - **Cleanup in the `generated` warning box.** The "Or install OKX onchainos to use your OKX wallet: <url>" lines inside the new-wallet-generated banner (in both `index.ts` sites) were redundant with the now-always-emitted status block above the banner, so they're removed. The banner's primary job — telling the user to back up their private key for the wallet that was just created — stays intact and unchanged.
-- **Tests (`src/auth.okx.test.ts`)**. The 7 status-block tests updated to assert on the new `{ level, text }` shape: confirms install markers go to `info`, failure markers (⚠/✗) go to `warn`, advisory next-steps (→) go to `info`, embedded newlines are still forbidden, and the `[XClawRouter]` prefix is *no longer* baked into the formatter's output (callers prefix). Full suite: 494 passing, 3 pre-existing skips.
+- **Tests (`src/auth.okx.test.ts`)**. The 7 status-block tests updated to assert on the new `{ level, text }` shape: confirms install markers go to `info`, failure markers (⚠/✗) go to `warn`, advisory next-steps (→) go to `info`, embedded newlines are still forbidden, and the `[XClawRouter]` prefix is _no longer_ baked into the formatter's output (callers prefix). Full suite: 494 passing, 3 pre-existing skips.
 
 ---
 
 ## v0.12.177 — May 12, 2026
 
-- **Replace the one-line Warn/Tip pair with a structured "Agentic Wallet status" block.** v0.12.175/.176 made the silent fallback non-silent — the CLI now told you when OKX detection failed and nudged you toward `onchainos login` — but two short, separated lines were still easy to miss in a noisy startup, and they never explicitly told the user "Agentic Wallet IS installed; you just need to log in." Replace both formatters with a single multi-line block emitted *before* the `Using ... wallet:` line, so the install state and login state are unambiguous and act-on-able from a single glance.
+- **Replace the one-line Warn/Tip pair with a structured "Agentic Wallet status" block.** v0.12.175/.176 made the silent fallback non-silent — the CLI now told you when OKX detection failed and nudged you toward `onchainos login` — but two short, separated lines were still easy to miss in a noisy startup, and they never explicitly told the user "Agentic Wallet IS installed; you just need to log in." Replace both formatters with a single multi-line block emitted _before_ the `Using ... wallet:` line, so the install state and login state are unambiguous and act-on-able from a single glance.
 - **`formatAgenticWalletStatus(detection): string[]`** — new exported pure helper in `src/auth.ts`, replaces `formatOnchainosWarning` and `formatOnchainosTip` (both deleted). Returns the literal lines to print for each detection kind:
   - `no-binary` →
     `[XClawRouter] ⚠ OKX Agentic Wallet not installed`
@@ -56,7 +66,7 @@ All notable changes to XClawRouter.
     `[XClawRouter] ✗ Could not read wallet addresses: <reason>`
   - `ok` → empty array (the existing `Using OKX onchainos wallet:` log conveys ready-state; a status banner above it would be noise).
 - **`ONCHAINOS_DOWNLOAD_URL` exported as a single constant** (`https://web3.okx.com/onchainos`) so the download link lives in one place and tests can pin to it rather than asserting a literal URL string.
-- **CLI integration (`src/cli.ts`).** After `resolveOrGenerateWalletKey()`, emit each status line via `console.log` before the `Using ... wallet:` log. The block leads — so the user reads "Agentic Wallet not installed / not logged in" *first*, then sees which local fallback we landed on. `XCLAW_QUIET=1` suppresses the whole block. A trailing `[XClawRouter]   (set XCLAW_QUIET=1 to suppress this block)` line prints only when the block was actually emitted, so OKX users (where the block is empty) don't end up with a dangling suppression hint.
+- **CLI integration (`src/cli.ts`).** After `resolveOrGenerateWalletKey()`, emit each status line via `console.log` before the `Using ... wallet:` log. The block leads — so the user reads "Agentic Wallet not installed / not logged in" _first_, then sees which local fallback we landed on. `XCLAW_QUIET=1` suppresses the whole block. A trailing `[XClawRouter]   (set XCLAW_QUIET=1 to suppress this block)` line prints only when the block was actually emitted, so OKX users (where the block is empty) don't end up with a dangling suppression hint.
 - **Removed**: `formatOnchainosWarning`, `formatOnchainosTip` from `src/auth.ts` and their callers in `src/cli.ts`. The two-formatter design was a stepping stone that got superseded after one release — kept the symbols cleanly out of the public surface rather than leaving them as deprecated shims.
 - **Tests (`src/auth.okx.test.ts`).** The old 14 formatter tests are replaced by 7 status-block tests covering each detection kind: presence of `✓`/`⚠`/`✗` markers, the literal download URL in the no-binary block, the literal `onchainos login` command where applicable, the underlying error `reason` carried through into the `status-error` / `addresses-error` blocks, the Solana-only hint for `no-evm-address`, the `[XClawRouter]` prefix on every line, and the single-line-per-entry invariant. 502 tests passing (was 502; net zero — old formatter tests pruned, new status tests added).
 

README.md

@@ -82,25 +82,41 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r
 
 ### Option A — OpenClaw Agent
 
-[OpenClaw](https://openclaw.ai) is an AI coding agent. If you're using it, ClawRouter installs as a plugin:
+[OpenClaw](https://openclaw.ai) is an AI coding agent. If you're using it, XClawRouter installs as a plugin. Three install paths — pick whichever fits:
+
+**1. One-liner (recommended)** — bundles config injection, cleanup of legacy installs, and onchainos bootstrap:
 
 ```bash
 curl -fsSL https://blockrun.ai/XClawRouter-update | bash
 openclaw gateway restart
 ```
 
-Done. Smart routing (`blockrun/auto`) is now your default model.
+**2. Manual via OpenClaw plugin manager** — if you want to see each step:
+
+```bash
+openclaw plugins install @blockrun/xclawrouter
+openclaw gateway restart
+```
+
+**3. Global npm install** — same effect as #2, useful for CI or pinned deployments:
+
+```bash
+npm install -g @blockrun/xclawrouter
+openclaw gateway restart
+```
+
+Done. Smart routing (`blockrun/auto`) is now your default model. On first run XClawRouter prompts you to log in to your OKX Agentic Wallet via email — no local private key, signing happens in OKX's TEE.
 
 ### Option B — Standalone (continue.dev, Cursor, VS Code, any OpenAI-compatible client)
 
 > **Using Claude Code?** Check out [BRCC](https://blockrun.ai/brcc.md) — it's purpose-built for Claude Code with the same smart routing and x402 payments.
 
-No OpenClaw required. ClawRouter runs as a local proxy on port 8402.
+No OpenClaw required. XClawRouter runs as a local proxy on port 8402.
 
 **1. Start the proxy**
 
 ```bash
-npx @blockrun/clawrouter
+npx @blockrun/xclawrouter
 ```
 
 **2. Fund your wallet** — optional, skip for free tier

VERSION

@@ -1 +1 @@
-0.12.117
+0.12.182