OpenClaw Performance

Waste is work a request does not need. Big speedups come from deleting waste, not from doing the same work faster. A cache is the last resort: it hides waste until its key, invalidation or hit rate breaks, and the waste returns.

1. Measure

Write the acceptance rule in the PR before the first run: flow, workload, metric, cold or warm, samples, and the change that counts as a win or a regression.

Flow	Committed workload
CLI startup	pnpm test:startup:bench (:check holds the budget)
Gateway startup / restart	scripts/bench-gateway-startup.ts, scripts/bench-gateway-restart.ts, scripts/perf/post-restart-burst-measure.ts
Chat turn, frames per turn	scripts/bench-channel-turn.mts, scripts/perf/transcript-broadcast-measure.ts
Control UI cold load	scripts/bench-control-ui-cold-load.ts, pnpm ui:check-performance (:base compares)
Session list, multi-agent shape	scripts/perf/team-shape-fixture.ts, src/gateway/session-list-viewers.perf.test.ts
Concurrency, SQLite state	scripts/bench-gateway-concurrency.ts, pnpm test:sqlite:perf

• Counts first: operations per action (SQL statements, RPCs and frames, file reads, catalog or registry loads, spawns, renders) before wall time. Counts hold steady on a loaded host. A count that should be zero is the bug.
• Real flow: an isolated Gateway on the head under test, real transport, the slow path included. A mock Gateway, a stale build or a dev server measures something else.
• Samples: baseline and candidate interleaved (ABAB), at least 5 each, cold and warm apart; median and p95 with spread, run serially, host load recorded.
• Rerunnable: only committed scripts count; extend an existing one when none fits.
• Profile: node --cpu-prof per thread, or a browser performance trace, on the hot path.

Done when the flow has a committed workload, a baseline table and a written rule.

2. Find waste

Ask of every counted operation: does this request need it? Recurring OpenClaw waste:

• Eager work on the critical path: a registry lookup imported the plugin loader (#133518, 47.07 s → 10.36 s); optional runtimes loaded at startup (#119374).
• Per-row or per-call recompute: a sync read per archived row (#156665, 56,700 reads → 0); log patterns resolved per frame (#150042, 539 → 17 ms per 10,000 frames).
• Re-checking admitted state: schema, admission or freshness checks on warm handles (#166102, #172676; 14 PRs in the SQLite admission chain).
• Full rescan per streamed delta: every token reprocessed the whole reply (#158526, 5,342 → 1 ms CPU at 256 KiB).
• Re-reading your own write: two database backups per lookup (#161551, 772.8 → 7.7 ms); Doctor rescanned and backed up what it had just checked (#174665, ~26 → 3.0 s).
• Repeated catalog or registry builds: a per-agent catalog rebuild at startup (#116261, 24.9 → 5.0 s); rebuilds per miss or TTL (#127178, #167008).
• Waiting on optional data: the Usage page waited on provider plans and retried unrelated reads (#176358).
• Defensive copies and wrapping: structuredClone per turn (#172940, 1.685 MiB → 0); per-value boundary wrapping (#163818, 11,571 → 500 ns/event).
• Spawn or fan-out per call: a child process per resolution (#155779, 100 → 0).
• Render cascades and full payloads: a render per update (#159400, 250 → 79); full rows resent for one delta (#165404, 21.75 → 0.95 MB).

Done when each dominant count traces to the code that issues it, with a yes or no on "needed".

3. Fix in this order

1. Delete the waste. Deletes rarely come back; a failed delete removed a guard, so keep every check that protects a contract and prove the contract still holds.
2. Once at the owner: callers consume the owner's recorded fact.
3. Carry the prepared fact through the hot path.
4. Batch independent work, and prove the batch keeps frames, latency tails and cold start steady: coalescing was reverted three times (#162560, #173901, #175092).
5. Cache, with a written reason why steps 1–4 do not apply. Follow root "Cache identity", invalidate from the owner's writes, bound the size, and add an interleaved work-count test. Three of four cache re-fixes were silent misses: readers evicting each other (#115369 → #174741), a budget that thrashed (#149773 → #149879).

A worker move or a deferral relocates cost; count main-thread and total work both.

Done when the waste is gone from the counts, or the PR says which step stopped and why.

4. Land

• Rerun the step 1 workload on baseline and candidate under the same rule.
• Every user-facing metric holds or improves: latency, p95/p99, frames, cold start, CPU, memory, counts. A worse metric needs the owner's explicit acceptance in the PR. A 20% move in one cell is a stop, never "within spread": five of six reverted performance PRs showed their regression in their own body.
• Revert changes without a measurable gain.
• Proof lives in the PR, not in new tests: the before/after counts are the evidence. Extend a flow's existing work-count test only when this waste has come back before; test-audit owns test value.
• PR evidence: workload command, acceptance rule, before/after table (counts and times, median and p95, samples), waste removed, and any metric that moved the wrong way.

Done when the table meets the rule written in step 1.

Related

Test-suite speed: openclaw-test-performance. Test heap growth: openclaw-test-heap-leaks. CI capacity: openclaw-ci-limits.