OnlyTerp/openclaw-optimization-guide: an operator's manual for the OpenClaw harness
Make your OpenClaw AI agent faster, smarter, and cheaper. Speed optimization, memory architecture, context management, model selection, and one-shot development guide.
At a glance
- What is it?
- The repository is a 33-part MIT-licensed guide to tuning an OpenClaw agent through context budgets, memory discipline, provider routing and cost controls rather than model swaps. Its useful parts are the file-size caps, the usage-cost command and the failover rules; its weak parts are the factual corrections it has had to issue about its own config keys.
- Who is it for?
- Adopt the guide if you already run OpenClaw and want concrete file-size caps, the gateway usage-cost command and failover flags rather than model-swap advice. Skip it if you use a different agent framework, since the file layout, commands and release train are OpenClaw-specific.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 76 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: agent quality is set by the harness, not the model
The guide opens with a thesis it calls the harness thesis: most agent capability comes from the harness, not the weights. The README admits the exact percentage is rhetoric, then states the operator lesson plainly. Model swaps help, but the large gains come from context budgets, memory discipline, tool permissions, flow control, provider routing, hooks and verification loops. That framing is the reason the repository exists. It is aimed at people who already run an OpenClaw agent and are paying for it, or who have watched long sessions degrade, rather than at people choosing a framework. The diagram in the README splits the system into a model box (Claude Opus 4.7 is the example) and a harness box containing instructions, context engineering, tools and approvals, guardrails, a memory layer and orchestration. The argument is that you usually cannot change the weights, so the guide spends its length on the layer you can change. That is a defensible editorial position, and it explains why the repository is mostly prose, templates and a scorecard rather than code.
How the file hierarchy actually works
The concrete mechanism in the README is a three-tier file layout that it says maps to Karpathy's LLM Wiki pattern, published April 10, 2026. Raw sources (vault/ and memory/YYYY-MM-DD.md) are immutable and agent read-only. Curated summaries are injected on every message. Generated artifacts are one-shot output. The table gives size caps per file: SOUL.md under 1 KB, AGENTS.md under 2 KB, MEMORY.md under 3 KB, DREAMS.md capped at the latest N entries, skills/ small per skill, vault/ unbounded, and daily memory files rolling. The data flow is stated as well: the agent reaches raw sources through memory_search, curated files are pushed into the agent, and the agent writes artifacts. Promotion runs in one direction, from short-term to durable, via a memory promote step in what the guide calls the deep phase, and artifacts are auto-captured back into the daily file. Those caps are the most actionable numbers in the material. If your SOUL.md has grown past 1 KB, the guide's position is that you are paying for it on every message. The design choice worth flagging is that everything in the curated tier is injected on every message, so the caps are a direct cost control, not a style preference.
Getting it running: commands, flags and config keys
The README does not describe an install step for the guide itself, because it is documentation rather than a package. The commands it gives are OpenClaw commands. Cost visibility is per-agent: openclaw gateway usage-cost --agent <id> or --all. The guide recommends running that daily and treating spend jumps as context regressions, which ties the cost command back to the file-size caps above. Failover is configured per lane and per job: individual cron jobs can carry their own --fallbacks list, or run strict with --fallbacks "". The README states that failover only helps with at least two configured lanes, which is the kind of constraint that saves an afternoon. Fast mode is toggled with /fast auto, described as arriving in 2026.6.10, which runs short conversational turns in the provider's fast lane and returns to normal mode for longer work. The templates directory is offered as a starting point, with working SOUL, AGENTS, MEMORY and TOOLS templates plus a conservative example config. The README also points at part27-gotchas-and-faq.md as a symptom-indexed FAQ, and at SCORECARD.md for a 50-item readiness score out of 100. One caveat sits in the README itself: it states there is no per-agent budget-cap config key, correcting an earlier revision that claimed one.
Where the guide is weakest: self-corrections and unverified claims
The July 2026 sweep note is unusually candid and is also the strongest reason for caution. It says the refresh corrects the previous revision, which referenced a 2026.6.4 release and several config keys that were never shipped. A documentation project that has had to retract config keys is telling you something about how fast the underlying product moves. The README also states that Anthropic's April 4 policy change broke the old path where a Claude Pro or Max subscription covered OpenClaw usage, and that Claude should be treated as paid API, Bedrock or provider-routed unless your own install proves otherwise. That is a policy claim about a third party, not something this repository can guarantee. The benchmarks directory claims reproducible methodology, but the material supplied here does not include a result, so there is no number to check. Treat the scorecard as a checklist, not a measurement. The guide is also version-pinned: the stable baseline is OpenClaw 2026.6.11, released 2026-06-30, and the badge in the README shows a current sweep dated July 2026. If your installed OpenClaw predates the 2026.6.8 to 2026.6.11 trains, several of the behaviours described (automatic fast mode, cron fallback controls, channel self-recovery) may not exist on your machine.
The wrong tool for most readers
This is not a general guide to building agents, and it does not pretend to be. Every mechanism in it assumes OpenClaw's file conventions (SOUL.md, AGENTS.md, MEMORY.md, DREAMS.md, skills/, vault/) and OpenClaw's CLI. If you run a different framework, the harness thesis may still be true, but the caps, the promote step and the usage-cost command will not transfer. It is also the wrong tool if you want a library to import. The repository is a guide with templates and a scorecard; the primary language field says JavaScript, but the material supplied here shows no runtime code, only markdown, Mermaid diagrams and a template directory. Anyone arriving from the topics list expecting an optimization package will be disappointed. The third case where it is the wrong tool is a single-user hobby setup where cost and latency are not yet a problem. The advice assumes you have multiple configured provider lanes, cron jobs worth tuning and a memory layer worth pruning. Without those, the guide is reading material rather than a fix.
What to use instead, and how the approach differs
The obvious alternative is the upstream OpenClaw documentation. The difference in approach is scope and stance. Upstream documentation describes what each config key and command does; this guide argues about which ones matter, gives budget caps per file, and states opinions such as keeping sessions long-lived because tool-heavy sessions retain prompt-cache savings as results accumulate in 2026.6.11. A second alternative is a general context-engineering write-up, of which there are many. Those tend to be model-agnostic and stop at principles. This guide goes the other way: it is narrow, version-pinned and prescriptive, down to a 1 KB ceiling on SOUL.md and a specific cron pattern around openclaw gateway usage-cost. The trade is portability for specificity. If OpenClaw changes its file conventions in a later train, the caps in this guide become stale, whereas a principles-level article would survive. The corollary is that the guide's value is highest right after a release train it covers, and decays from there. The README's own correction note is evidence for that decay rate.
Maintenance cost and licence
The repository is MIT licensed, which permits reuse and modification of the templates and text with the usual attribution and warranty conditions; that is a statement about the licence text, not legal advice, and anyone redistributing the templates should read LICENSE directly. Maintenance cost is the real question. The guide tracks OpenClaw release trains, and the README shows it reissuing a sweep for 2026.6.8 through 2026.6.11 with corrections to prior claims. That implies a reader who pins advice to a version and rechecks after each upgrade. The practical cost is small if you treat the guide as a checklist you run against your own install: check your file sizes against the caps, run the usage-cost command, confirm you have at least two provider lanes before relying on failover. It is larger if you copy the example config wholesale without checking it against your OpenClaw version, which is exactly the failure the correction note describes. There are no releases listed for the repository, so versioning of the guide itself is done through dated sweeps and the part-numbered files rather than tags.
Editorial conclusion
Adopt the guide if you already run OpenClaw and want concrete file-size caps, the gateway usage-cost command and failover flags rather than model-swap advice. Skip it if you use a different agent framework, since the file layout, commands and release train are OpenClaw-specific. Before trusting any config key, verify it against your installed OpenClaw version: the guide itself retracted keys it had previously claimed.
Community notes