feat: refresh ClawRouter models through shared Model Core

[KillerQueen-Z]

ClawRouter currently requires a catalog release to expose each upstream chat model. This change bundles the shared @blockrun/model-catalog runtime and refreshes metadata from the active gateway at startup and every five minutes. New chat models appear in /v1/models, the OpenClaw provider/allowlist, and per-agent model caches; updated prices feed routing estimates and spend-cap checks.

The runtime is pinned to immutable commit 465c45941fb8ea9d6858fe8402abc8ba8934be90 (BlockRunAI/model-catalog#2). That Core fix is now merged, so this dependency is satisfied. The package version remains unchanged; this PR does not publish a release.

Behavior and boundaries

• Each proxy has its own catalog cache. API credentials go only to the configured gateway catalog request; public policy reads receive no credentials, and catalog redirects are rejected.
• Invalid data or network failure retains the last complete view. Offline startup uses the existing ClawRouter catalog; malformed remote policy does not prevent valid gateway rows from refreshing.
• Preserve existing aliases, curated legacy entries, free fallback order, capability overrides, and Auto routing candidates. Newly discovered chat models become explicit choices; a coding category does not grant tool support. Pinned free choices cannot silently become paid.
• Refresh price/limit-only changes in the provider and agent caches. Use per-request catalog snapshots for estimates, capabilities, reasoning timeouts and thinking normalization.
• Payment signing stays on the existing Base/Solana/API-key paths. New models still require upstream protocol compatibility. Catalog prices are estimates; gateway payment quotes and account settlement remain authoritative.
• Restart an existing proxy after installation. OpenClaw may need to reload provider configuration to display the changed picker. An already-running external proxy cannot acquire this behavior through handle reuse.
• Regenerated the tracked distribution bundles. Isolated API-key test spending ledgers from local user settings and taught the cost-cap fixture to distinguish free catalog GETs from model POSTs.

Validation

• Full unit suite: 1,139 passed, 1 existing skipped (104 passing files) after syncing main on 2026-10-03.
• GitHub checks on 0c1d1ba027fe9fd85ae10fe7ca525c3422012e70: Build & Test, Lint & Typecheck, Desktop, and scanner all passed. The initial run exposed a random-port collision in the existing proxy-reuse fixture; it now reserves its listener through the OS and avoids public gateway requests, and the rerun passed.
• Proxy lifecycle integration: 5 passed.
• Typecheck, ESLint, full Prettier check, brand-number check, build and distribution smoke test passed.
• Added coverage for discovery/repricing/removal, account/network isolation, malformed-policy and malformed-gateway fallback, free-model protection, agent-cache metadata refresh, and a real local HTTP proxy forwarding a new model with account auth while enforcing its advertised-price budget cap before dispatch.
• Real paid end-to-end validation completed on 2026-10-02 at commit 0c1d1ba027fe9fd85ae10fe7ca525c3422012e70: 6/6 paid requests passed. On both Base and Solana, a live-discovered model absent from the static registry (poolside/laguna-s-2.1) returned the exact test marker; GPT-6 Luna completed a two-request streaming tool-call/result round trip. Every request returned a successful payment receipt and had a successful transaction independently checked via chain RPC. Wallet deltas matched signed quotes exactly: Base $0.006, Solana $0.003; total $0.009. Per-payment cap $0.05; total test cap $0.50. No credentials, wallets, signatures or transaction identifiers are published.
• Initial Solana attempts were blocked locally by the test harness using a full genesis hash instead of the canonical shortened CAIP-2 network ID; zero signed requests were transmitted and zero balance change was observed. Correcting the harness to use the SDK constant made all Solana cases pass without changing application code. API-key paid billing remains untested because no local credential was available.

Review status and known limits

Independent preliminary source review covered the initial source diff and supporting credential/payment boundaries; its cache-sync and reasoning-metadata observations were fixed and retested. The managed security scan could not generate its inventory (could not read committed diff blob ...:package.json, despite the blob resolving locally). It remains incomplete: this PR does not claim a completed security scan or zero vulnerabilities.

The 2026-10-02 npm audit snapshot reported 26 affected-package entries (4 high, 5 moderate, 17 low, 0 critical). Every advisory-affected lockfile entry is identical to the base revision. The only new package is the shared catalog, which has no runtime dependencies. Existing dependency remediation remains separate from this catalog integration.

Summary by CodeRabbit

• New Features
  • Model listings refresh at startup and every five minutes, adding eligible chat models and updating prices across the proxy and OpenClaw.
  • Refreshed models are reflected in provider configuration and per-agent model caches. OpenClaw may need to reload provider configuration to display updates.
  • Existing product policies and model capabilities remain unchanged; gateway quotes and settlement remain authoritative.
• Documentation
  • Added guidance on catalog refresh behavior, configuration, and handling network or policy errors.

2026-10-03 main sync

Merged current main 14d20ac into this branch as 3944cfa2f58326103c99506359d317580df1acfc, resolving the new proxy/bundle conflicts while preserving upstream outcome-memory behavior and the catalog-based free-model fallback check. Full local regression (1,139 tests plus 5 lifecycle tests), typecheck, lint, formatting, build and distribution smoke checks passed. GitHub now reports the PR mergeable; CI is rerunning on this commit. The real paid evidence above remains explicitly tied to the previously tested 0c1d1ba revision.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: BlockRunAI/ClawRouter/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: bea9a1f5-d1fc-42e4-aa1f-201ccad24eaf

📥 Commits

Reviewing files that changed from the base of the PR and between 0c1d1ba and 3944cfa.

⛔ Files ignored due to path filters (6)

• dist/cli.js is excluded by !**/dist/**
• dist/cli.js.map is excluded by !**/dist/**, !**/*.map
• dist/index.d.ts is excluded by !**/dist/**
• dist/index.js is excluded by !**/dist/**
• dist/index.js.map is excluded by !**/dist/**, !**/*.map
• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (1)

• src/proxy.ts

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

ClawRouter now refreshes a shared model catalog from the active gateway and projects eligible model metadata into proxy listings, routing and cost calculations, and OpenClaw model configuration and caches.

Changes

Shared model catalog

Layer / File(s)	Summary
Catalog projection and refresh package.json, src/models.ts, src/model-catalog.ts, src/model-catalog.test.ts, README.md, vitest.config.ts	Adds a pinned catalog dependency and a client that filters and projects eligible gateway models. Refresh behavior retains the current view on errors or non-live results. Tests cover catalog projection, refresh, policy handling, and model constraints.
Proxy catalog lifecycle src/proxy.ts, src/provider.ts, src/model-catalog.test.ts, src/proxy.api-key-*.test.ts, src/proxy.max-tokens-cap.test.ts	The proxy refreshes catalog data at startup and every five minutes, updates pricing and capability snapshots, serves the current model list, and exposes catalog updates. The provider uses catalog models when the proxy is active. Proxy tests include catalog integration and test setup updates.
Catalog-backed routing and estimates src/proxy.ts	Request handling uses the active catalog for estimates, free-model checks, capability and context filtering, timeouts, retries, and usage logging.
OpenClaw configuration and cache updates src/index.ts, src/index.agent-cache.test.ts	Provider models, allowlists, and agent caches use the supplied visible catalog. Catalog updates refresh configuration and caches, and freshness checks compare serialized model contents.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Suggested reviewers: vickyxai

Sequence Diagram(s)

sequenceDiagram
  participant startProxy
  participant createClawCatalog
  participant Gateway
  participant PolicyURL
  participant ProxyRouter
  participant OpenClawConfig
  startProxy->>createClawCatalog: Configure for active gateway and network
  startProxy->>createClawCatalog: Refresh catalog
  createClawCatalog->>Gateway: Fetch gateway model data
  createClawCatalog->>PolicyURL: Fetch policy data
  createClawCatalog-->>startProxy: Return projected model view
  startProxy->>ProxyRouter: Update pricing and capabilities
  startProxy->>OpenClawConfig: Send visible models through callback

Loading

Merge Risk: ⚪ Minimal · up to 3944c

The reported request-time catalog mismatch does not occur; no actionable merge-blocking issue remains after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 3944c

Remote metadata now influences available choices and cost estimates. Credentials remain restricted to the configured destination, and existing payment checks remain in place. Partial updates can leave different views out of sync; their downstream effects are not fully verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — A compromised or incorrect gateway catalog can influence the owning proxy's model definitions and local estimates, then propagate visible metadata into the user's provider configuration and existing agent caches. Catalog cache ownership is per proxy, but downstream persistence spans multiple agents in the user's OpenClaw directory.

Security Findings and Attack Paths

• observed — Catalog prices and free-model classification feed API-key spend admission. The existing wrapper checks and reserves estimated cost before dispatch, releases reservations on fetch failure, and records a reported charge when available. Wallet policy enforcement instead checks selected payment requirements before signing. Catalog-to-billing discrepancies remain relevant, but these paths do not establish an introduced spending-control bypass.

Trust Boundaries and Controls

• observed — The credential-bearing fetcher is selected only for the exact configured gateway catalog URL; policy reads use the unkeyed fetcher. Both reject redirects. The API-key fetcher additionally enforces the configured origin, rejects embedded URL credentials, and removes payment headers. Model dispatch retains the configured gateway destination.
• observed — The installed shared runtime validates nonempty rows, unique model identifiers, finite nonnegative paid and flat prices, zero free prices, and positive integer limits. It validates policy snapshots and projects the complete candidate before committing cache fields. These controls reject malformed data; they do not prove that schema-valid prices match actual billing.

Resilience and Maintainability Implications

• observed — Concurrent catalog refreshes share one in-flight promise, and failed local projection preserves the previous view. Downstream update failures do not stop serving. Agent-cache repair changes only an existing provider's model list, preserving other providers and connection or authentication fields.

Hardening Proposals

• proposed — Track the applied catalog generation for runtime configuration and persistent caches, and expose synchronization failures. This would make partial updates and stale pricing views easier to detect and recover without treating model discovery as a transaction.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.22% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 12 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: refreshing ClawRouter models through the shared Model Core catalog.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}