v0.12.181: OKX-first wallet onboarding via guided setup#3
Merged
Conversation
Fresh installs no longer silently generate a local BIP-39 wallet. When no OKX onchainos session and no saved wallet are present, resolveOrGenerateWalletKey throws OnchainOsRequiredError instead of falling back to local-key generation. The new flow: - `npx @blockrun/xclawrouter` on a fresh interactive terminal auto-runs the guided setup (install onchainos binary if missing → email → OTP via `wallet login` + `wallet verify` two-step). - Non-interactive callers (CI, Docker, gateway daemon) keep the fail-fast error + exit 2 contract so automation isn't left hanging on a stdin prompt. - `xclawrouter setup` exposes the same flow as an explicit subcommand. - `XCLAWROUTER_USE_LOCAL_WALLET=1` opts back into the legacy local BIP-39 path; saved wallets keep working unchanged so existing users upgrade with zero disruption. - scripts/reinstall.sh bootstraps the onchainos binary via OKX's official install.sh and stages the okx-agentic-wallet SKILL.md into the OpenClaw workspace. - CLI bin renamed to `xclawrouter`; help text + updater point at the new package name. - README documents the three OpenClaw install paths (curl one-liner, `openclaw plugins install`, global `npm install -g`).
- src/cli.ts (cmdSetup): redesigned interactive flow with ANSI-styled header, two-line summary box, suppressed onchainos JSON output, and cyan/green/yellow status indicators. Falls back to plain text when stdout isn't a TTY or NO_COLOR is set. - scripts/reinstall.sh: removed the `okx-agentic-wallet` SKILL.md bootstrap and the "ask your agent" hand-off message. The skill is OKX's parallel onboarding path; running both confused users about which route to follow. Email login now flows exclusively through `xclawrouter setup`. - scripts/reinstall.sh: added a prominent "Next step — log in to your OKX Agentic Wallet" block at the end of installs that aren't already logged in, pointing users at `xclawrouter setup`. Skipped when an OKX session, a legacy wallet.key, or XCLAWROUTER_USE_LOCAL_WALLET=1 is already in place.
Resolves CI "Check formatting" failure on BlockRunAI#3.
Addresses the review on PR BlockRunAI#3 (blocking + should-fix items, plus two small DRY nits): - Restore `clawrouter` bin name as a deprecation alias (blocking). v0.12.180 renamed the bin to `xclawrouter` with no transitional alias, breaking pm2 processes, shell aliases, and onboarding docs that referenced the old name. package.json now ships both bins pointing at the same dist/cli.js. Invocations under the old name print a one-line deprecation notice to stderr (suppressible via XCLAW_SUPPRESS_RENAME_NOTICE=1) and continue normally. Alias removed in v0.13 — one release of runway. - Guard the post-setup wallet re-resolve. main() auto-launches cmdSetup on fresh interactive installs then re-calls resolveOrGenerateWalletKey. If a transient TEE issue leaves the wallet still undetected after setup claims success, the second call was throwing OnchainOsRequiredError straight through to main().catch as a generic "Fatal error". Now caught with a targeted "Setup completed but the wallet still isn't detected — diagnose with onchainos wallet status" hint before exit 1. - humanizeDetectionKind() for cmdSetup post-verify failure. The recovery error message used to surface the raw enum (`no-evm-address`, `addresses-error`) to end users. Mapped to one-line plain-English descriptions ("no EVM address found — is this a Solana-only OKX account?"). Only used in the cmdSetup recovery path — formatAgenticWalletStatus already humanizes its lines. - ONCHAINOS_INSTALLER_URL exported from src/auth.ts. The curl-able installer URL was hardcoded in both src/cli.ts (cmdSetup auto-install) and scripts/reinstall.sh. Promoted to one TS-side constant; reinstall.sh keeps its bash variable with a comment to stay in sync (POSIX shell can't import TS). - logOnchainOsRequiredError(logger, err) helper in src/index.ts. The line-by-line warn loop for surfacing the multi-line OnchainOsRequiredError guide was duplicated at the two wallet-resolution sites (gateway-mode startProxyInBackground and the non-gateway-mode register() callback). One helper, same behaviour. Test plan - npm run typecheck — clean - npm run lint — clean - npm run format:check — clean - npx vitest run src/ — 460 pass, 0 fail (same as PR baseline) - npm run build — dist regenerated; new symbols verified embedded in dist/cli.js and dist/index.js - node dist/cli.js --version → 0.12.182
2 tasks
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.
Summary
Fresh installs no longer silently generate a local BIP-39 wallet. The plugin now defaults to the OKX Agentic Wallet (onchainos), guiding users through installation + email/OTP login via a new
xclawrouter setupcommand.What changed
src/auth.ts—resolveOrGenerateWalletKey()throwsOnchainOsRequiredErroron a fresh install when no OKX session + no saved wallet exist, instead of falling back to local-key generation.XCLAWROUTER_USE_LOCAL_WALLET=1opts back into the legacy local BIP-39 path; saved wallets continue to work unchanged (zero-disruption upgrade for existing users).src/cli.ts— addedxclawrouter setupsubcommand. On an interactive TTY,npx @blockrun/xclawrouterauto-triggers setup when no wallet is present. Non-interactive callers (CI, Docker, gateway daemon) still get the fail-fastexit 2contract so automation isn't left hanging on stdin. Polished ANSI-styled UI for email + OTP prompts with a summary box on success.src/index.ts— handlesOnchainOsRequiredErrorfrom both the plugin register hook and the gateway-mode wallet resolution path; prints the multi-line guidance viaapi.logger.warninstead of crashing.scripts/reinstall.sh— bootstraps the onchainos binary via OKX's officialinstall.sh, then surfaces a prominent "Next step — log in to your OKX Agentic Wallet" block at the end of installs that aren't already logged in.clawrouter→xclawrouter(matches package name).openclaw plugins install, globalnpm install -g).XCLAWROUTER_USE_LOCAL_WALLET=1so they don't need a real OKX session.Commits
af3556ev0.12.180: OKX-first wallet onboarding via guided setup09e1eacv0.12.181: polish setup UX, drop skill-install duplicationTest plan
npm run typecheckcleannpm run lintcleannpx vitest run src/— 460 unit tests passnpm pack+ global install of the tgz —xclawrouter --versionreturns0.12.181,xclawrouter --helpshows new command namexclawrouter setup, exit 2wallet.keysaved → still loaded as before (Using saved wallet: 0x...)XCLAWROUTER_USE_LOCAL_WALLET=1→ legacy local generation still worksandy@blockrun.aiaccount — email + OTP completes, proxy on port 8402 uses OKX wallet, nowallet.keywritten to disknpm publish --dry-runclean