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.
  • Known model capabilities and free-model protections are preserved. Gateway quotes and settlement remain authoritative.
• Documentation
  • Added guidance on catalog configuration, refresh behavior, 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]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Repository: BlockRunAI/ClawRouter/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 87c0719c-93f1-4d7d-91fe-782ecf0ca995

---

📥 Commits

Reviewing files that changed from the base of the PR and between 3944cfa and 5d89d57.

---

⛔ 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 (5)

• README.md
• src/model-catalog.test.ts
• src/model-catalog.ts
• src/proxy.catalog-free-cap.test.ts
• src/proxy.ts

---

 _________________________________________________________________
< You are pretty high on the list of people I want to help today. >
 -----------------------------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

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

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

📝 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.}

[VickyXAI]

Thanks. Almost all of the diff is dist/ chunk renumbering (the source change is about 670 lines). The design holds up: prices come only from the active gateway's listing, aliases and FREE_MODELS order are untouched, models the gateway adds are never Auto candidates, and the API key is scoped to apiBase with redirect:"error". I checked the projection against live Base and Sol data today. Prices match the gateway exactly, and nothing throws. Two things block the merge.

Blocking

1. A gateway listing can switch off the strict cost cap. model-catalog.ts:82 adds any billing_mode === "free" row to freeIds. Only free → paid is guarded (L47–49); paid → free, and new free rows, are not. Once rebased onto v0.12.283, isFreeModel = catalog.freeIds.has(modelId) sends the request to non-strict SessionSpend.track. The signing hook then returns early (if (!spend?.isStrict) return;), so the 402 quote is never checked against maxCostPerRun. The balance preflight is skipped too. The listing and the 402 quote are produced separately and have disagreed before (blockrun-sol#406). Please keep cap and balance gating on the product-owned free/* ids, or keep the strict quote check active for "free" models. Add a test where a model the catalog lists as free gets a non-zero 402 quote.
2. Rebase onto v0.12.283. src/proxy.ts conflicts at the three success-path sites, which are now sessionSpend.recordSuccess(...). Use catalog.freeIds and the catalog estimate() there. Main's FREE_MODELS / estimateAmount would record no spend for models the catalog added. Then rebuild dist/ and re-run your paid end-to-end test.

Follow-ups

• Please drop the GitHub policy fetch, or pin it to a commit SHA. Right now it fetches raw.githubusercontent.com/.../main every 5 minutes from every install. That is a mutable trust input and it shows GitHub every running proxy, while in ClawRouter it only reorders models that would be visible anyway.
• refresh has an empty catch {}, so a failed refresh (for example the free → paid throw) freezes the catalog with no log. Also, the timer interval equals the TTL and expiry is set after the fetch completes, so every other tick is a cache hit that still rebuilds the view and re-syncs openclaw.json.
• On every gateway start, injectModelsConfig and onCatalogUpdated write two different model lists to openclaw.json, one after the other.

[VickyXAI]

Thanks. A few things need to change before this can merge:

1. The model list is fetched every 5 minutes from a file on the main branch of a public GitHub repo. Anyone with push access there controls what models ClawRouter users see. Please pin to a signed or content-hashed release (or a commit SHA) and fall back to the bundled list if verification fails.
2. Prices from that feed override ClawRouter's built-in prices, and the spending caps are computed from them. A remote feed must not be able to lower or raise a cap. Keep prices local, or only accept remote prices within a bounded range of the built-in ones.
3. The compiled dist/ diff is about 54k lines and was built from code as of Oct 3, so it can't be reviewed and doesn't match current main. Please drop dist/ from the PR; we'll build it in release.

[VickyXAI]

Thanks for this. Rather than send it back to you, we finished the review items in-house and merged it with your commits kept as they are:

• Merged current main (v0.12.286) into the branch. The three success-path conflicts now use main's sessionSpend.recordSuccess(...), with your catalog estimate() and catalog.freeIds.
• Strict cap. freeIds is now ClawRouter's own free/* products only. A row the gateway lists as free is still priced at 0, but it no longer switches off the strict cap or the balance preflight, so its real 402 quote is checked. src/proxy.catalog-free-cap.test.ts covers this.
• No remote policy fetch by default. The bundled snapshot orders new models; BLOCKRUN_MODEL_CATALOG_URL still opts in to a remote one.
• Refresh failures are logged once per distinct error.
• No-change refreshes are skipped. A refresh that changes nothing keeps the same view, so routing isn't rebuilt and openclaw.json isn't rewritten every tick. The cache TTL is now shorter than the refresh interval.

Full suite passes (1205 tests) and CI is green. It ships in the next release, with you credited in the changelog.