OnlyTerp/openclaw-optimization-guide

OpenClaw Optimization Guide

Make your OpenClaw AI agent faster, smarter, cheaper, and actually safe to run in production.

July 2026 sweep. Stable baseline: OpenClaw 2026.6.11 (released 2026-06-30). This refresh covers the 2026.6.8–2026.6.11 trains — automatic fast mode, working failover, per-agent cost visibility, prompt-cache retention, cron fallback controls, and channel-delivery self-recovery — and corrects the previous revision, which referenced a "2026.6.4" release and several config keys that were never shipped. See the correction note in Part 33.

By Terp — Terp AI Labs

---

Start With The July 2026 Reality Check

The June trains (2026.6.8 → 2026.6.11) were about making OpenClaw dependable. If you last read this guide in mid-June, these are the new rules:

1. Claude subscription-era advice is dead. Anthropic's April 4 policy change broke the old "Claude Pro/Max covers OpenClaw" path. Treat Claude as paid API / Bedrock / provider-routed usage unless your own install proves otherwise. 2. Cost visibility is per-agent now. openclaw gateway usage-cost --agent (or --all) shows spend per configured agent; cron it daily and treat spend jumps as context regressions. (There is no per-agent budget-cap config key — an earlier revision of this guide claimed one in error.) 3. Failover actually fires. Provider overloads are classified correctly, usage-limit responses route to fallbacks, and individual cron jobs can carry their own --fallbacks list (or run strict with --fallbacks ""). None of it helps without at least two configured lanes. 4. Fast mode is automatic. /fast auto (2026.6.10) runs short conversational turns in the provider's fast lane and returns to normal mode for longer work, with correct status through retries and fallback switches. 5. Long sessions got cheaper. Tool-heavy sessions now retain prompt-cache savings as results accumulate (2026.6.11) — one more reason to keep sessions long-lived and compaction healthy instead of resetting constantly. 6. Stuck channels self-recover. Telegram/WhatsApp queues that wedge after a crash or long-running task resume automatically in 2026.6.11. "Restart the gateway" should leave your runbooks.

Read Part 33 — June 2026 Field Guide first if you want the latest tricks before the deep dives.

The Harness Thesis

Most agent capability comes from the harness, not the weights.

The exact percentage is rhetoric. The operator lesson is concrete: model swaps help, but the big wins come from context budgets, memory discipline, tool permissions, flow control, provider routing, hooks, and verification loops.

flowchart LR
    subgraph Model["The Model (weights)"]
        M[Claude Opus 4.7
or your choice]
    end
    subgraph Harness["The Harness (operator-controlled) — this guide"]
        direction TB
        Inst[Instructions
SOUL/AGENTS/MEMORY/skills]
        Ctx[Context engineering
budgets + progressive disclosure]
        Tools[Tools + approvals
semantic categories]
        Guard[Guardrails
hooks, Task Brain, redaction]
        Mem[Memory layer
memory-core + LightRAG + dreaming]
        Orch[Orchestration
5 coordination patterns]
    end
    Model -.-> Harness
    Harness -.-> Results[Production results]

You usually cannot change the weights. You can change everything else: context, memory, tools, approvals, verification, cost controls, and orchestration. The rest of this guide is that operator-controlled layer.

Jump straight to the payoff

| Do this | For this outcome | |---|---| | Grade your setup → | 50-item Production Readiness Scorecard, score out of 100, shareable. | | Copy the reference config → | Working SOUL / AGENTS / MEMORY / TOOLS templates plus a conservative example config. | | See the numbers → | Reproducible benchmark methodology + harness + run template. | | Browse the ecosystem → | Curated list of skills, tools, papers, talks, adjacent projects. | | Hit a wall? → | Gotchas & FAQ, symptom-indexed. Most questions answered in one page. |

---

File Hierarchy At A Glance

OpenClaw's file layout maps 1:1 to Karpathy's three-tier LLM Wiki pattern published April 10, 2026. If you only remember one diagram from this guide, make it this one:

flowchart TB
    subgraph Raw["Raw sources — immutable, agent read-only"]
        Vault["vault/*"]
        Daily["memory/YYYY-MM-DD.md"]
    end
    subgraph Curated["Curated summaries — injected on every message"]
        Soul["SOUL.md
identity"]
        Agents["AGENTS.md
operational rules"]
        Mem["MEMORY.md
durable facts"]
        Dreams["DREAMS.md
reflection diary"]
        Skills["skills/*
on-demand playbooks"]
    end
    subgraph Artifacts["Generated artifacts — one-shot output"]
        PRs["PRs / commits"]
        Reports["Reports / transcripts"]
    end
    Raw -. memory_search .-> Agent((Agent))
    Curated --> Agent
    Agent --> Artifacts
    Agent -. Deep-phase promote .-> Mem
    Artifacts -. auto-capture .-> Daily

| File | Purpose | Size cap | Written by | Read when | |------|---------|---------:|------------|-----------| | SOUL.md | Identity, invariants, non-negotiables | < 1 KB | Human | Every message | | AGENTS.md | Operational rules, decision trees, tool routing | < 2 KB | Human + agent (auditable) | Every message | | MEMORY.md | Durable facts promoted from short-term (pointer index) | < 3 KB | Agent via memory promote | Every message | | DREAMS.md | Human-readable reflection diary | latest N entries | Built-in Dreaming | Every message | | skills/ | Named playbooks | per-skill small | Human + SkillClaw | On activation | | vault/ | Raw source notes, transcripts, links | unbounded | Auto-capture + humans | On memory_search | | memory/YYYY-MM-DD.md | Daily short-term rollup | rolling | Auto-capture | On memory_search |

Full reasoning and update rules in Part 31 — The LLM Wiki Pattern In OpenClaw.

---

Who This Is For

• Running any OpenClaw agent in production. If your bot handles real work, the speed, memory, and security parts are non-optional.
• Just hit "why is my agent slow?" for the first time. Part 1 and Part 2 are where to start.
• Coming from v3.x or early v4.0. Start with Part 26 — Migration Guide, then Part 25 — Architecture Overview.
• Building multi-agent systems. Part 5 — Orchestration and Part 24 — Task Brain are your backbone.
• Already read half the guide and forget what's where. Jump to Part 27 — Gotchas & FAQ or the themed map below.

---

Start Here (In This Order)

1. Part 25 — Architecture Overview — 15-minute primer on what OpenClaw actually is under the hood (gateway, Task Brain, memory layer, skills, surfaces). 2. Part 14 — Quick Checklist — 30-minute setup checklist covering the 80/20. 3. Part 17 — The One-Shot Prompt — copy-paste prompt that automates the whole setup. 4. Part 27 — Gotchas & FAQ — keep this open while you work. Half your questions are here.

---

What You Get (Numbers From Our Production Deployment)

| Metric | Before | After | Source | |--------|-------:|------:|--------| | Context file size (SOUL + AGENTS + MEMORY) | ~15 KB | ~5 KB | Part 1 | | Memory search latency | 2–5s (cloud) | <100ms (local) | Part 4, Part 10 | | Compaction crash rate | loops on 16K models | fixed in 4.15+ | Part 15 | | Coding-agent token usage | baseline | –60% | Part 19 — Repowise | | Sessions before audit trail | 0 surfaces | all surfaces | Part 24 — Task Brain |

Full numbers in benchmarks/.

---

Companion resources shipped with the guide

Alongside the 33 parts themselves, this repo now includes the tooling that turns "I read the guide" into "I can audit and reproduce the results":

• SCORECARD.md — The OpenClaw Production Readiness Scorecard. 50 items across Speed / Memory / Orchestration / Security / Observability, 2 points each, max 100. Designed to be copy-pasted into your own repo and shared publicly.
• AWESOME.md — A curated, opinionated list of OpenClaw resources: skills worth installing, memory and orchestration tools, observability stacks, research papers, talks, communities, adjacent ecosystems.
• templates/ — A starter kit: tiny SOUL.md / AGENTS.md / MEMORY.md / TOOLS.md templates, a vault/ skeleton, and an example config that documents both legacy JSON blocks and the newer provider-catalog direction.
• benchmarks/METHODOLOGY.md + benchmarks/harness/ + benchmarks/runs/TEMPLATE.md — A reproducible benchmark methodology (4 pillars, 3 reference environments) plus a contract for submitting your own numbers via PR.
• CODE_OF_CONDUCT.md · SECURITY.md · SUPPORT.md — Community standards so you know how to file issues, report problems, and get help.
• GitHub Pages site — rendered from this repo via MkDocs-material: .

---

What Changed In This Release (July 2026 Refresh)

• Correction. The June refresh referenced a "2026.6.4 stable" release and config keys (agents.list[].budget, models.providers..health, policy check --export, memory promote --dry-run, memory.recall.maxParallel, sandbox.network.allow, /context map --diff, secrets.rotation.maxAgeDays, meetingNotes.retentionDays) that do not exist in any published OpenClaw release. Those sections have been rewritten around shipped features, and the templates have been fixed. Details in the correction note at the top of Part 33.
• Rebaselined on 2026.6.11 stable — the version map now tracks the real June trains: 2026.6.8, 2026.6.9, 2026.6.10, 2026.6.11.
• New Part 33 tips — per-agent cost visibility (openclaw gateway usage-cost), scheduled policy check --json attestations, working failover + per-cron-job --fallbacks, safe-by-default memory promote / --apply workflow, and automatic fast mode (/fast auto).
• Security guidance updated — secrets redacted from debug output, admin-only HTTP session/model overrides, package-source redirect/lookalike-path hardening, actionable plugins.allow trust warnings, @owner/ skill verification, and key-free web-search providers staying opt-in.
• Ops quality-of-life — official openclaw/openclaw Docker Hub mirror, Slack router relay mode for multi-gateway deployments, openclaw agent --message-file, and cron deleteAfterRun transcript cleanup.

Previous Late-May 2026 refresh

• Updated Part 33 field guide — upgrade map from 2026.4.15 through 2026.5.22 stable / 2026.5.24-beta.1: Gateway performance caching, Meeting Notes, the bundled Policy plugin, Codex/MCP scoping, Discord voice, image-quality controls, iMessage approvals, and security hardening.
• Codex guidance — native Codex means canonical openai/gpt-* model refs; the operational work is MCP projection scoping, codex.defaultToolsApprovalMode, named OAuth profiles, and deny-all tool policy verification.
• Security guidance tightened — skill-file read/executable allowlist compatibility removed, symlinked credential files fail closed, doctor warns on plaintext secret-bearing config, and channel conformance belongs in the Policy plugin.

Earlier refreshes (Task Brain, ClawHub, the v4.0 architecture/migration/glossary primers, and the 2026.4.15 line) are captured in the version tables in Part 25 — Architecture Overview and Part 26 — Migration Guide.

---

How The Pieces Fit Together

flowchart LR
    You[You]
    subgraph Surfaces
        Canvas[Canvas UI]
        CLI[CLI / IDE]
        Cron[Cron / ACP]
    end
    subgraph Gateway["Gateway daemon (Task Brain)"]
        Ledger[Task ledger]
        Approvals[Semantic approvals]
        Auth[Auth / secrets]
    end
    subgraph Agents
        Main[Main agent]
        Workers[Sub-agents]
    end
    subgraph Memory["Memory layer"]
        MemCore[memory-core
MEMORY.md + DREAMS.md]
        Lance[memory-lancedb
vector search]
        Light[LightRAG
graph RAG]
    end
    subgraph Capabilities
        Hub[ClawHub skills]
        Hooks[Hooks]
        Tools[Tools]
    end
You --> Surfaces
    Surfaces --> Gateway
    Gateway --> Agents
    Agents --> Memory
    Agents --> Capabilities
    Capabilities -. register with .-> Gateway
    Memory -. feed .-> Agents

Full breakdown of each block in Part 25 — Architecture Overview.

---

Navigate By Goal

Not every part applies to every reader. Jump directly to the pillar that matches what you're trying to do:

| I want to… | Start with | |-------------|-----------| | Catch up on the latest changes | 33 June Field Guide · 26 Migration Guide · 27 Gotchas & FAQ | | Make my agent faster | 1 Speed · 2 Context Engineering · 3 Cron Bloat · 6 Models | | Stop it forgetting things | 4 Memory · 9 Vault · 10 Embeddings · 22 Built-In Dreaming · 31 LLM Wiki Pattern | | Reduce cost | 5 Orchestration · 6 Models · 8 One-Shotting · 22 Memory you can afford | | Handle real codebases | 18 LightRAG · 19 Repowise · 21 Real-time Sync | | Harden for production | 15 Infra Hardening · 23 ClawHub · 24 Task Brain · 29 Hook Catalog | | See what my agents are doing | 20 Observability · 24 Task Brain audit | | Automate self-improvement | 11 Auto-Capture Hook · 12 Self-Improving System · 13 Memory Bridge · 32 Self-evolving skills (SkillClaw) | | Run autonomous / overnight work | 5 Orchestration patterns · 30 Ralph Loop · 15 Worktrees · 26 Spec-Driven Development | | Enforce safety the agent can't ignore | 29 Hook Catalog · 24 Task Brain · 15 Infra Hardening | | Upgrade from an older version | 26 Migration Guide | | Look up a term you don't know | 28 Glossary | | Debug something weird | 27 Gotchas & FAQ |

---

Full Table of Contents

🎯 Primers & references

• 25. Architecture Overview — the 15-min mental map of v4.0+
• 26. Migration Guide — upgrade paths + rollback plans
• 27. Gotchas & FAQ — symptom → fix table + frequently asked questions
• 28. Glossary & Terminology — every term this guide assumes, on one page
• 33. June 2026 Field Guide — what changed after 2026.5.22 and what to do now
• 14. Quick Checklist — 30-minute setup
• 17. The One-Shot Prompt — automation prompt, updated for current defaults

⚡ Speed & context 1. Speed — Stop Being Slow — trim context, add fallbacks, reasoning mode, localModelLean 2. Context Engineering — The Discipline — quadratic scaling, pruning, compaction, 5-min cache TTL trap 3. Cron Session Bloat — The Hidden Killer — session file accumulation, cleanup

🧠 Memory 4. Memory — Stop Forgetting Everything — 3-tier memory, Ollama, lancedb cloud storage, Copilot embeddings 9. Vault Memory System — folders, MOCs, claim-named notes, wiki-links 10. State-of-the-Art Embeddings — qwen3-embedding, GPU tier, Windows path, Copilot provider 11. Auto-Capture Hook — automatic knowledge extraction after every session 12. Self-Improving System — micro-learning loop, HOT/WARM/COLD tiers 13. Memory Bridge — give Codex / Claude Code access to your vault 22. Built-In Dreaming (memory-core) — official 3-phase consolidation, DREAMS.md, memory-you-can-afford (LightMem + vbfs) 31. The LLM Wiki Pattern In OpenClaw — Karpathy's three-tier pattern mapped onto SOUL/AGENTS/MEMORY/skills 33. June 2026 Field Guide — per-agent cost visibility, scheduled Policy attestations, working failover + cron fallbacks, memory promotion review, automatic fast mode

🤝 Orchestration & models 5. Orchestration — sub-agents-as-GC, Anthropic's 5 coordination patterns, CEO/COO/Worker, verification 6. Models — What To Actually Use — provider comparison, pricing, local, localModelLean 7. Web Search — Tavily, Brave, Serper, Gemini grounding 8. One-Shotting Big Tasks — research-first methodology 30. The Ralph Loop In OpenClaw — autonomous while true wrappers, PRD.json, overnight runs 32. Self-Evolving Skills With SkillClaw — skill population evolution, Mem²Evolve

🧩 Knowledge graph & codebase 18. LightRAG — Graph RAG — entities + relationships, Web UI, REST, LangFuse tracing 19. Repowise — Codebase Intelligence — 60% fewer tokens, 4x faster coding agents 21. Real-Time Knowledge Sync — event-driven file watcher, <6s vault → LightRAG sync

🔒 Hardening & security 15. Infrastructure Hardening — compaction crash loops, GPU contention, secrets, gateway crash-loop fix, reserve-token cap, auth hot-reload, approval redaction, parallel OpenClaw with git worktrees 23. ClawHub Skills Marketplace — marketplace, malware, install policy 24. Task Brain Control Plane — unified task ledger, semantic approvals, trust boundaries 29. The Hook Catalog — 8 copy-paste hooks, exit-code semantics, deterministic enforcement

🔭 Observability 20. Agent Observability — LangFuse, reranker, n8n, workflow automation

📖 Reference 25. Architecture Overview (v4.0+) — gateway / agents / memory / skills / surfaces primer 26. Migration Guide — opinionated upgrade paths with rollback 27. Common Gotchas & FAQ — symptom-indexed troubleshooting 28. Glossary & Terminology — every term this guide assumes, on one page

---

📊 Benchmarks — real numbers from a production system (context savings, search latency, reindex results, SWE-bench rankings)

📁 Example Vault — populated mini-vault showing MOCs, wiki-links, Agent Notes, and .learnings/ after 2 weeks of use

🤝 Contributing — how to propose corrections, new parts, and version-bump PRs

---

The Problem

If you're running a stock OpenClaw setup, you're probably dealing with:

• Freezing and hitting context limits. Bloated workspace files exhaust the context window mid-response.
• Slow responses. 15-20KB+ of context injected every message = hundreds of milliseconds of latency per reply.
• Forgetting everything. New session = blank slate. No memory of yesterday's work or decisions.
• Inconsistent behavior. Without clear rules, personality drifts between sessions.
• Doing everything the expensive way. Main model writes code, does research, AND orchestrates - all at top-tier pricing.
• Flying blind. No web search means guessing at anything after training cutoff.
• Wrong model choice. Using whatever was default without considering the tradeoffs.

What This Fixes

After this setup:

| Metric | Before | After | |--------|--------|-------| | Context per msg | 15-20 KB | 4-5 KB | | Time to respond | 4-8 sec | 1-2 sec | | Memory recall | Forgets daily | Remembers weeks | | Token cost/msg | ~5,000 tokens | ~1,500 tokens | | Long sessions | Degrades | Stable | | Concurrent tasks | One at a time | Multiple parallel |

How