Summary

• Bound ClawRouter usage success responses with the shared readResponseWithLimit helper before JSON parsing.
• Add a focused regression test for oversized successful usage payloads.
• Preserve existing non-OK behavior: HTTP errors still report only the status code and do not expose upstream bodies.

What Problem This Solves

ClawRouter usage is an external provider usage boundary with a configurable baseUrl. The non-OK path already avoids exposing upstream bodies, but the successful path used bare response.json(), allowing a misconfigured or hostile usage endpoint to make OpenClaw buffer an unbounded JSON body before extracting a tiny budget summary.

User Impact

• Why it matters / User impact: A ClawRouter-compatible endpoint can return an arbitrarily large successful /v1/usage response. Before this patch, a provider usage refresh could spend memory on the full body even though the UI only needs budget and summary fields.
• User-visible behavior after fix: Normal ClawRouter budget summaries still render the same way, while oversized success bodies fail fast with a bounded-read error.

Origin / follow-up

• Follows: fix(google): bound OAuth token error response reads #99605, which bounded Google OAuth token error response reads.
• Gap this fills: The same bounded-read pattern had not been applied to ClawRouter usage successful responses; extensions/clawrouter/usage.ts still used bare response.json() on the success path.
• Consistency: This uses the shared plugin SDK readResponseWithLimit wrapper, matching the existing extension/provider bounded-response pattern rather than adding a ClawRouter-only reader.

Competition / linked PR analysis

• Linked issue: N/A — this is a follow-up to a recently merged bounded-read PR, not a closing-issue PR.
• Related open PR scan: Searched open PRs for clawrouter usage response limit OR bounded read OR response.json; result was [] in open-pr-conflict-search.json.
• Competition assessment: No open PR was found for this ClawRouter usage success-response gap.

Real behavior proof

• Behavior or issue addressed: ClawRouter usage success responses are now read through a 1 MiB cap before JSON parsing, so an oversized successful /v1/usage body is rejected instead of being fully parsed by response.json().
• Real environment tested: Local Node HTTP server on 127.0.0.1 with production fetchClawRouterUsage, real fetch, and configurable baseUrl; no mock fetch and no external credentials.
• Exact steps or command run after this patch:

source /media/vdb/code/ai/aispace/openclaw-followup-99605-evidence/context.env
cd "$TASK_WORKTREE"
TASK_WORKTREE="$TASK_WORKTREE" node --import tsx "$EVIDENCE_DIR/clawrouter-local-http-proof.mjs"
node scripts/run-vitest.mjs extensions/clawrouter/usage.test.ts
pnpm lint:extensions
pnpm test:extensions:package-boundary
pnpm exec oxfmt --check extensions/clawrouter/usage.ts extensions/clawrouter/usage.test.ts
git diff --check

• Evidence after fix:

HEAD=fd5e8db719073f0a462c8f7d23f8fb39074c1e3b
baseUrl=http://127.0.0.1:40871
oversizedResponseBytes=1048659
oversizedResult=ClawRouter usage response exceeds 1048576 bytes
normalResult={"provider":"clawrouter","displayName":"ClawRouter","windows":[{"label":"Monthly budget","usedPercent":25,"resetAt":1785542400000}],"summary":"12 requests · 34,567 tokens · $25.00 used","plan":"Managed monthly budget"}

Test Files  1 passed (1)
Tests  4 passed (4)
[test] passed 1 Vitest shard in 14.87s

extension package boundary check passed
mode: all
compiled plugins: 117
canary plugins: 2

Checking formatting...
All matched files use the correct format.
Finished in 108ms on 2 files using 8 threads.

• Observed result after fix: The oversized successful usage response rejects at 1048576 bytes, and a normal managed monthly budget response still maps to the same ProviderUsageSnapshot fields.
• What was not tested: No live ClawRouter service account was used; the defect is the client-side bounded read of an untrusted usage HTTP response, and the after-fix proof exercises that boundary with a local HTTP server and real fetch.
• Fix classification: Root cause fix.

Review findings addressed

• N/A — this is a new follow-up PR with no existing review findings.

Regression Test Plan

• Target test file: extensions/clawrouter/usage.test.ts
• Scenario locked in: A successful /v1/usage response larger than 1 MiB rejects before JSON parsing, while a normal managed monthly budget response still maps to the expected ProviderUsageSnapshot.
• Why this is the smallest reliable guardrail: The regression test covers the previously unbounded success path, and the local HTTP proof uses production fetchClawRouterUsage with real fetch so the body-size guard is exercised at the HTTP response boundary.
• node scripts/run-vitest.mjs extensions/clawrouter/usage.test.ts
• pnpm lint:extensions
• pnpm test:extensions:package-boundary
• pnpm exec oxfmt --check extensions/clawrouter/usage.ts extensions/clawrouter/usage.test.ts
• git diff --check

Risk / Compatibility

• Risk labels considered: provider-usage, external HTTP boundary, availability/resource-exhaustion.
• Risk explanation: The success body cap can reject a ClawRouter-compatible endpoint that returns more than 1 MiB from /v1/usage, but expected usage payloads contain only budget and summary fields and are far smaller than the cap.
• Why acceptable: The configurable baseUrl makes the response untrusted; failing fast on an oversized usage body is safer than buffering unbounded JSON, and normal response mapping is covered by both the regression test and local HTTP proof.
• Patch quality notes: The test follows the existing ClawRouter test style by passing a typed fetchFn dependency; this is the function's public seam for exercising success and error response paths without changing production API shape.

Merge risk

Low. The diff is limited to ClawRouter usage parsing and one focused regression test. The only behavior change is rejecting unexpectedly large successful usage JSON before parsing.

What was not changed

• What did NOT change: ClawRouter URL normalization, authorization headers, provider catalog behavior, streaming/chat behavior, non-OK error body redaction, and normal usage snapshot formatting.
• Scope boundary: This patch only changes the ClawRouter usage success-response read path and its regression coverage; it does not alter provider catalog fetching, chat completion streaming, auth setup, or any shared response-limit helper behavior.

Architecture / source-of-truth check

• Architecture / source-of-truth check: fetchClawRouterUsage is the source-of-truth owner for ClawRouter usage snapshots. The fix is applied at that external HTTP response boundary before JSON parsing, not downstream in UI formatting or provider catalog code.

Root Cause

• Root cause: The ClawRouter usage success path trusted response.json() to consume /v1/usage, so a configurable provider usage endpoint could return an unbounded successful JSON body.
• Why this is root-cause fix: The patch replaces the unbounded body read at the owner boundary with the shared capped reader before JSON parsing, while preserving the existing snapshot mapping and non-OK behavior.

Maintainer-ready confidence

• Maintainer-ready confidence: High. The patch is small, follows an existing bounded-read pattern, includes a regression test, and has after-fix proof through a real local HTTP response path using production code.