From 0f6f9b034d71db935c35dc07c27840136e2aeecd Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 1 Jul 2026 21:21:34 +0000 Subject: [PATCH] July 2026 refresh: rebaseline on 2026.6.11 stable, correct unshipped 2026.6.4 claims Co-Authored-By: Rob --- AWESOME.md | 16 +-- README.md | 35 +++-- SCORECARD.md | 2 +- mkdocs.yml | 2 +- part25-architecture-overview.md | 6 +- part26-migration-guide.md | 64 +++++---- part33-late-april-2026-field-guide.md | 200 ++++++++++++-------------- templates/README.md | 2 +- templates/openclaw.example.json | 39 +---- 9 files changed, 163 insertions(+), 203 deletions(-) diff --git a/AWESOME.md b/AWESOME.md index f4a511a..d17ffa5 100644 --- a/AWESOME.md +++ b/AWESOME.md @@ -2,7 +2,7 @@ **A curated list of resources for getting the most out of OpenClaw.** Skills, guides, talks, templates, tools, research. Contributions welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). -> This list is opinionated. Inclusion here means we've actually used it on a production OpenClaw deployment or seen it solve a real problem. Broken or abandoned links are removed aggressively. Last curated: **June 2026, tracking OpenClaw 2026.6.4 stable + 2026.6.11-beta.1**. +> This list is opinionated. Inclusion here means we've actually used it on a production OpenClaw deployment or seen it solve a real problem. Broken or abandoned links are removed aggressively. Last curated: **July 2026, tracking OpenClaw 2026.6.11 stable**. ## Contents @@ -35,7 +35,7 @@ ## Guides & tutorials - **[OpenClaw Optimization Guide](./README.md)** — this repo. 33 parts, refreshed for the June 2026 release wave. -- **[June 2026 Field Guide](./part33-late-april-2026-field-guide.md)** — the fast catch-up map from 2026.5.22 to the 2026.6.4 stable baseline (2026.6.11-beta.1 tracked). +- **[June 2026 Field Guide](./part33-late-april-2026-field-guide.md)** — the fast catch-up map from 2026.5.22 to the 2026.6.11 stable baseline. - **[Official "Getting Started" path](https://clawdocs.org/start)** — the minimum-viable setup. Read this first if you're brand new. - **[The OpenClaw CVE flood, Feb–Mar 2026](https://www.tryopenclaw.ai/blog/openclaw-cve-flood-march-2026/)** — the definitive writeup on the **ClawHavoc** supply-chain campaign. - **[Migration Guide — v3 → v4 → June 2026](./part26-migration-guide.md)** — opinionated upgrade paths. @@ -69,8 +69,8 @@ See [Part 23 — ClawHub Skills Marketplace](./part23-clawhub-skills-marketplace - **[memory-core](https://github.com/openclaw/memory-core)** — the built-in memory plugin with native dreaming (3 phases). Replaced the custom-autoDream patterns in v4. - **[memory-lancedb](https://github.com/openclaw/memory-lancedb)** — LanceDB vector store. 2026.4.15-beta.1 added cloud storage mode. - **Active Memory filters** — current builds support per-conversation `allowedChatIds` / `deniedChatIds`, partial recall on timeout, and people-aware wiki provenance views. -- **Meeting Notes plugin** — 2026.5.22 source-only external plugin for date-sharded meeting transcripts, manual imports, CLI reads, and Discord voice as the first live source. 2026.6.4 adds Google Meet live capture plus `meetingNotes.retentionDays`/redaction. Define retention before enabling. -- **Recall + dreaming tuning** — 2026.6.4 ships `memory promote --dry-run` (review what dreaming would promote before it mutates); 2026.6.11-beta.1 adds `memory.recall.maxParallel` and scheduled dreaming (`memory.dreaming.schedule`) so consolidation runs off-hours. +- **Meeting Notes plugin** — 2026.5.22 source-only external plugin for date-sharded meeting transcripts, manual imports, CLI reads, and Discord voice as the first live source. Define retention and redaction policy before enabling any live capture. +- **Memory promotion review** — `openclaw memory promote` is dry-run by default; preview candidates, use `memory promote-explain ""` to understand scoring, then `--apply` deliberately. `memory status --deep` probes vector-store and embedding readiness; `--fix` repairs stale recall locks. - **Generic embedding provider contract** — 2026.5.22 plugin SDK surface (`contracts.embeddingProviders`, `api.registerEmbeddingProvider`) that should make explicit OpenAI-compatible embedding providers cleaner. - **[Ollama](https://ollama.com/)** — local embedding runtime. `qwen3-embedding:0.6b` is the right default for most setups. - **[LightRAG](https://github.com/HKUDS/LightRAG)** — graph + vector hybrid RAG. The right upgrade once your vault crosses ~500 files. See [Part 18](./part18-lightrag-graph-rag.md). @@ -94,8 +94,8 @@ See [Part 23 — ClawHub Skills Marketplace](./part23-clawhub-skills-marketplace ## Observability & evaluation - **OpenClaw native diagnostics** — late-May builds add sanitized `secrets.prepare` spans, bounded skill usage metrics, tool source/owner labels, Prometheus smoke aliases, and richer `tasks maintenance --json`. -- **Per-agent budget caps** — 2026.6.4 `agents.list[].budget` (`dailyUsd`/`monthlyUsd`, `onExceed: warn|degrade|stop`) turns cost governance into config instead of after-the-fact token-report reading. See [Part 33](./part33-late-april-2026-field-guide.md). -- **`/context map --diff`** — 2026.6.11-beta.1 compares the current prompt treemap against the previous run's snapshot to catch context regressions. +- **Per-agent cost visibility** — 2026.6.11 `openclaw gateway usage-cost --agent ` / `--all` shows spend per configured agent; cron it daily and diff. Pair with `/usage full` footers for in-channel per-turn cost. See [Part 33](./part33-late-april-2026-field-guide.md). +- **Automatic fast mode** — 2026.6.10 `/fast auto` runs short conversational turns in the provider's fast lane and returns to normal mode for longer work; `/fast status` shows the effective state through fallback switches. - **[LangFuse](https://langfuse.com/)** — the lightest-weight LLM tracing that actually works end-to-end with OpenClaw surfaces. - **[OpenTelemetry LLM instrumentation](https://opentelemetry.io/docs/specs/semconv/gen-ai/)** — the standards track. Pair with LangFuse or Grafana Tempo. - **Canvas Model Auth status card** — built into 2026.4.15-beta.1+. The one dashboard you actually read every day. @@ -114,8 +114,8 @@ See [Part 23 — ClawHub Skills Marketplace](./part23-clawhub-skills-marketplace - **[Task Brain](./part24-task-brain-control-plane.md)** — OpenClaw's control plane. Semantic approval categories, agent-initiated denies, unified task flow registry. - **Approval policy reference** — [templates/openclaw.example.json](./templates/openclaw.example.json) ships with a starting-point policy block. -- **Policy plugin** — bundled in 2026.5.20. Run `openclaw policy check` for channel conformance checks, attestations, doctor findings, and opt-in repair. 2026.6.4 adds `--export` attestations you can schedule and diff for drift gating. -- **Provider health checks** — 2026.6.4 `models.providers..health` adds interval probes with bounded automatic lane demotion, so a failing provider routes around itself instead of failing every turn. +- **Policy plugin** — bundled in 2026.5.20. Run `openclaw policy check` for channel conformance checks, doctor findings, and opt-in repair; `policy check --json` emits stable attestation hashes you can schedule, store, and diff for drift gating. +- **Per-job cron fallbacks** — 2026.6.11 `openclaw cron edit --fallbacks ...` gives individual scheduled jobs their own fallback models (or a strict no-fallback run with `--fallbacks ""`), so overnight provider incidents degrade instead of killing the schedule. - **Task maintenance JSON** — `openclaw tasks maintenance --json` now explains stale-running retention/reconcile decisions for cron, CLI, backing sessions, and wedged sub-agents. ## UI surfaces & clients diff --git a/README.md b/README.md index 67dc3de..797b31c 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,8 @@ **Make your OpenClaw AI agent faster, smarter, cheaper, and actually safe to run in production.** -[![Current sweep: 2026.6.11 beta](https://img.shields.io/badge/OpenClaw-2026.6.11--beta.1-2ea44f)](./part33-late-april-2026-field-guide.md) -[![Stable baseline: 2026.6.4](https://img.shields.io/badge/stable-2026.6.4-blue)](./part26-migration-guide.md) +[![Current sweep: July 2026](https://img.shields.io/badge/OpenClaw-2026.6.11-2ea44f)](./part33-late-april-2026-field-guide.md) +[![Stable baseline: 2026.6.11](https://img.shields.io/badge/stable-2026.6.11-blue)](./part26-migration-guide.md) [![33 parts](https://img.shields.io/badge/parts-33-blue)](#full-table-of-contents) [![Scorecard](https://img.shields.io/badge/scorecard-50_items-8957e5)](./SCORECARD.md) [![Awesome](https://img.shields.io/badge/awesome-list-fc60a8)](./AWESOME.md) @@ -11,22 +11,22 @@ [![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)](./LICENSE) [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](./CONTRIBUTING.md) -> **June 2026 sweep.** Stable baseline: **OpenClaw 2026.6.4**. Beta tracked: **2026.6.11-beta.1**. This refresh advances the late-May guidance to the current line: per-agent budget caps, scheduled Policy attestations with drift gating, provider health checks with automatic failover, Google Meet live capture for Meeting Notes with retention/redaction, recall/dreaming tuning, `/context map --diff`, sandbox egress allowlists, and `openclaw doctor` secret-rotation + MCP-scope lint. +> **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](./part33-late-april-2026-field-guide.md). *By Terp — [Terp AI Labs](https://x.com/OnlyTerp)* --- -## Start With The June 2026 Reality Check +## Start With The July 2026 Reality Check -The late-May betas are now stable, and early-June added four cost/safety levers worth wiring in. If you last read this guide around 2026.5.22/2026.5.24, these are the new rules: +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. **Budgets belong in config.** 2026.6.4 makes per-agent `agents.list[].budget` caps first-class with `onExceed: warn|degrade|stop`. Give the orchestrator a cap and let `degrade` reroute routine work to cheap lanes automatically. -3. **Policy checks should be scheduled, not one-shot.** `openclaw policy check --export` produces diffable attestations; schedule it (and wire it into CI) so channel-policy drift is caught instead of discovered. Opt-in repair stays a human step. -4. **Provider routing now self-heals.** Add `models.providers..health` checks so a failing lane demotes itself for a bounded window instead of failing every turn — but only if you configured fallback lanes. -5. **Voice/meetings need retention, not just capture.** Discord voice and the new Google Meet live source feed Meeting Notes; set `meetingNotes.retentionDays` and redaction rules before auto-capture so transcripts expire and scrub sensitive fields. -6. **Memory and context got tunable.** `memory.recall.maxParallel`, scheduled dreaming, `memory promote --dry-run`, and `/context map --diff` let you tune recall, consolidation, and context regressions deliberately instead of by feel. +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](./part33-late-april-2026-field-guide.md)** first if you want the latest tricks before the deep dives. @@ -156,14 +156,13 @@ Alongside the 33 parts themselves, this repo now includes the tooling that turns --- -## What Changed In This Release (June 2026 Refresh) +## What Changed In This Release (July 2026 Refresh) -- **Updated [Part 33 — June 2026 Field Guide](./part33-late-april-2026-field-guide.md)** — advances the catch-up map to the current **2026.6.4 stable** baseline (2026.6.11-beta.1 tracked) and adds four new tips: budget caps, scheduled Policy attestations, provider health checks/failover, and recall/dreaming tuning. -- **Cost governance is now first-class** — per-agent `agents.list[].budget` caps with `onExceed: warn|degrade|stop` replace "read the token report afterward." The orchestrator gets a cap; `degrade` reroutes routine work to cheap lanes. -- **Policy and routing self-audit** — `openclaw policy check --export` produces diffable, schedulable attestations, and `models.providers..health` checks demote a failing provider for a bounded window instead of failing every turn. -- **Voice/meetings gain retention** — Google Meet joins Discord voice as a Meeting Notes live source, with `meetingNotes.retentionDays` and redaction rules so transcripts expire and scrub sensitive fields. -- **Memory/context tuning** — `memory.recall.maxParallel`, scheduled dreaming, `memory promote --dry-run`, and `/context map --diff` make recall, consolidation, and context-regression checks deliberate. -- **Security additions** — sandbox egress allowlists (`sandbox.network.allow`), secret-rotation reminders, and unscoped-Codex-MCP lint are now `openclaw doctor` findings. +- **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](./part33-late-april-2026-field-guide.md). +- **Rebaselined on [2026.6.11 stable](https://github.com/openclaw/openclaw/releases)** — 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 @@ -265,7 +264,7 @@ Not every part applies to every reader. Jump directly to the pillar that matches 13. [Memory Bridge](./part13-memory-bridge.md) — give Codex / Claude Code access to your vault 22. [Built-In Dreaming (memory-core)](#part-22-built-in-dreaming) — official 3-phase consolidation, DREAMS.md, memory-you-can-afford (LightMem + vbfs) 31. [The LLM Wiki Pattern In OpenClaw](./part31-the-llm-wiki-pattern-in-openclaw.md) — Karpathy's three-tier pattern mapped onto SOUL/AGENTS/MEMORY/skills -33. [June 2026 Field Guide](./part33-late-april-2026-field-guide.md) — budget caps, scheduled Policy attestations, provider health/failover, Meeting Notes retention, recall/dreaming tuning +33. [June 2026 Field Guide](./part33-late-april-2026-field-guide.md) — per-agent cost visibility, scheduled Policy attestations, working failover + cron fallbacks, memory promotion review, automatic fast mode **🤝 Orchestration & models** 5. [Orchestration](#part-5-orchestration-stop-doing-everything-yourself) — sub-agents-as-GC, Anthropic's 5 coordination patterns, CEO/COO/Worker, verification diff --git a/SCORECARD.md b/SCORECARD.md index 8d7f39c..4ea1428 100644 --- a/SCORECARD.md +++ b/SCORECARD.md @@ -1,6 +1,6 @@ # The OpenClaw Production Readiness Scorecard -**Score your OpenClaw setup against the patterns in the [OpenClaw Optimization Guide](./README.md). 50 items across 5 pillars. 2 points each. 100 possible. Updated for OpenClaw 2026.6.4 stable and 2026.6.11 beta.** +**Score your OpenClaw setup against the patterns in the [OpenClaw Optimization Guide](./README.md). 50 items across 5 pillars. 2 points each. 100 possible. Updated for OpenClaw 2026.6.11 stable.** > Share your score: *"My OpenClaw Production Readiness Scorecard: XX / 100 — [github.com/OnlyTerp/openclaw-optimization-guide](https://github.com/OnlyTerp/openclaw-optimization-guide)"* diff --git a/mkdocs.yml b/mkdocs.yml index 8f59b5c..99e74c6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ site_name: OpenClaw Optimization Guide -site_description: Make your OpenClaw AI agent faster, smarter, cheaper, and actually safe to run in production. Updated for OpenClaw 2026.6.4 stable and 2026.6.11 beta. +site_description: Make your OpenClaw AI agent faster, smarter, cheaper, and actually safe to run in production. Updated for OpenClaw 2026.6.11 stable. site_url: https://onlyterp.github.io/openclaw-optimization-guide/ repo_url: https://github.com/OnlyTerp/openclaw-optimization-guide repo_name: OnlyTerp/openclaw-optimization-guide diff --git a/part25-architecture-overview.md b/part25-architecture-overview.md index 741fbd7..85e8d68 100644 --- a/part25-architecture-overview.md +++ b/part25-architecture-overview.md @@ -154,8 +154,10 @@ Short form, so you know what era a given piece of advice applies to: | **v2026.5.22 stable** | 2026-05-24 | Gateway perf caching, Meeting Notes plugin, sanitized secret/tool telemetry, generic embedding-provider contract, narrowed subagent bootstrap, xAI/Grok web-search auth reuse, session-store helper modernization | Former stable baseline. | | **v2026.5.24-beta.1** | 2026-05-24 | iMessage approval reactions, WebUI/Discord voice status/cancel/steer/follow-up controls, Discord wake-name gating, adaptive `agents.defaults.imageQuality`, named Codex OAuth profiles | Beta, superseded by 2026.5.26 stable. | | **v2026.5.26 stable** | 2026-05-26 | Promotes the 5.24 beta line to stable: approval reactions, adaptive `imageQuality`, named Codex OAuth profiles, and WebUI/Discord voice status/cancel/steer/follow-up controls | Stable-promotes 5.24-beta.1. | -| **v2026.6.4 stable** | 2026-06-04 | Per-agent `agents.list[].budget` caps, scheduled `openclaw policy check --export` attestations + drift gating, provider `health` checks with automatic lane demotion, Google Meet live capture for Meeting Notes with retention/redaction, `memory promote --dry-run`, doctor MCP-scope + secret-rotation lint | **This guide's current stable baseline.** | -| **v2026.6.11-beta.1** | 2026-06-11 | `/context map --diff` regression tracking, `memory.recall.maxParallel`, scheduled dreaming, sandbox egress allowlists (`sandbox.network.allow`), per-channel `imageQuality` overrides, Codex app-server session reuse | Latest beta; test on a copied profile before exposing to users. | +| **v2026.6.8 stable** | 2026-06-16 | Rich Telegram delivery, WhatsApp ACP bindings, GLM-5.2 + Claude Haiku 4.5 catalog entries, `/usage` full footer templates, key-free web-search opt-ins, embedding batch splitting, SQLite WAL avoided on network filesystems | Mid-June stable, following 2026.6.5/2026.6.6. (No 2026.6.4 release ever shipped — a previous revision of this table listed one in error.) | +| **v2026.6.9 stable** | 2026-06-21 | Standalone official provider plugins on npm, Codex Hosted Search + automatic plugin approvals, secrets redacted from debug output, admin-only HTTP session/model overrides, thinking-only turn retries, session-history repair | Security and recovery hardening. | +| **v2026.6.10 stable** | 2026-06-24 | Automatic fast mode (`/fast auto`), correct overload classification for fallback routing, session-transcript SDK contract, cross-channel session identity fixes | Fast-mode and failover correctness. | +| **v2026.6.11 stable** | 2026-06-30 | Stuck channel-queue self-recovery, per-contact DM models, per-job cron `--fallbacks` + `deleteAfterRun` cleanup, prompt-cache retention in tool-heavy sessions, `gateway usage-cost --agent/--all`, `agent --message-file`, Slack router relay, Docker Hub mirror, actionable `plugins.allow` trust warnings | **This guide's current stable baseline.** | If you're on something older than v4.0, the first upgrade is not reading this guide — it's moving to v4.0+. See [Part 26 — Migration Guide](./part26-migration-guide.md). diff --git a/part26-migration-guide.md b/part26-migration-guide.md index d53a61d..5503372 100644 --- a/part26-migration-guide.md +++ b/part26-migration-guide.md @@ -1,22 +1,24 @@ # Part 26: Migration Guide -> Updated in the June 2026 refresh. Opinionated, battle-tested upgrade paths from older OpenClaw versions to current. If something in this guide does not apply to your version yet, start here. +> Updated in the July 2026 refresh. Opinionated, battle-tested upgrade paths from older OpenClaw versions to current. If something in this guide does not apply to your version yet, start here. -> **Read this if** you're on anything older than 2026.6.4, or planning an upgrade. -> **Skip if** you're already on current-beta and don't maintain older instances. +> **Read this if** you're on anything older than 2026.6.11, or planning an upgrade. +> **Skip if** you're already on current stable and don't maintain older instances. + +> **Correction (July 2026).** A previous revision of this guide referenced a "2026.6.4" release. No such version was ever published — the June stable line runs 2026.6.1 → 2026.6.5 → 2026.6.6 → 2026.6.8 → 2026.6.9 → 2026.6.10 → 2026.6.11. Path 12 below has been rewritten for the real releases. ## TL;DR By Version | You're on | Do this first | Then | Finally | |-----------|--------------|------|---------| -| **v3.x** | Full v4.0 upgrade (not a drop-in) | Reach 2026.4.27 through Paths 1–6 | 2026.6.4 | -| **v4.0.x** | v2026.3.31-beta.1 (Task Brain) | Reach 2026.4.27 through Paths 2–6 | 2026.6.4 | -| **v2026.3.x** | Apply Task Brain approval policy | Reach 2026.4.27 through Paths 3–6 | 2026.6.4 | -| **v2026.4.x pre-4.15** | Skip straight to 2026.4.15 | Reach 2026.4.27 through Paths 5–6 | 2026.6.4 | -| **v2026.4.15** | Remove subscription-era model assumptions | Apply provider-catalog changes | 2026.6.4 | -| **v2026.4.27** | Apply memory/messaging beta changes | Upgrade to 2026.6.4 | Optional 2026.6.11-beta.1 | -| **v2026.4.29-beta.1** | Migrate Codex/queue assumptions | Upgrade to 2026.6.4 | Optional 2026.6.11-beta.1 | -| **v2026.5.22 / 2026.5.24-beta.1** | Apply June budget/policy/health changes | Upgrade to 2026.6.4 via Path 12 | Optional 2026.6.11-beta.1 | +| **v3.x** | Full v4.0 upgrade (not a drop-in) | Reach 2026.4.27 through Paths 1–6 | 2026.6.11 | +| **v4.0.x** | v2026.3.31-beta.1 (Task Brain) | Reach 2026.4.27 through Paths 2–6 | 2026.6.11 | +| **v2026.3.x** | Apply Task Brain approval policy | Reach 2026.4.27 through Paths 3–6 | 2026.6.11 | +| **v2026.4.x pre-4.15** | Skip straight to 2026.4.15 | Reach 2026.4.27 through Paths 5–6 | 2026.6.11 | +| **v2026.4.15** | Remove subscription-era model assumptions | Apply provider-catalog changes | 2026.6.11 | +| **v2026.4.27** | Apply memory/messaging beta changes | Upgrade to 2026.6.11 via Path 12 | — | +| **v2026.4.29-beta.1** | Migrate Codex/queue assumptions | Upgrade to 2026.6.11 via Path 12 | — | +| **v2026.5.22 / 2026.5.24-beta.1** | Apply June reliability/cost changes | Upgrade to 2026.6.11 via Path 12 | — | Each step is described below. Don't skip steps — the CVE wave fixes and Task Brain model changes are not optional for anyone running more than a personal-dev setup. @@ -184,7 +186,7 @@ This is the first late-April stability jump. It is worth doing before moving to ## Path 7: v2026.4.27 stable → v2026.4.29-beta.1 -Former beta jump. If you're upgrading today, treat this as the conceptual migration step for memory/messaging behavior, then continue through Path 8, Path 10, and Path 12 to the current 2026.6.4 stable baseline. +Former beta jump. If you're upgrading today, treat this as the conceptual migration step for memory/messaging behavior, then continue through Path 8, Path 10, and Path 12 to the current 2026.6.11 stable baseline. **What changes (the ones you should act on immediately):** @@ -208,7 +210,7 @@ Former beta jump. If you're upgrading today, treat this as the conceptual migrat ## Path 8: v2026.4.29-beta.1 → v2026.5.12 stable -This is the former May stable baseline. Do this as the compatibility checkpoint, then continue through Path 10 and Path 12 to the current 2026.6.4 stable baseline (test 2026.5.24-beta.1 only if you need a specific feature before it lands stable). +This is the former May stable baseline. Do this as the compatibility checkpoint, then continue through Path 10 and Path 12 to the current 2026.6.11 stable baseline (test 2026.5.24-beta.1 only if you need a specific feature before it lands stable). **What changes (the ones you should act on immediately):** @@ -255,7 +257,7 @@ Former beta jump. Today, treat this as the queue/Codex/per-sender migration chec ## Path 10: v2026.5.14-beta.1 / v2026.5.12 → v2026.5.22 stable -Former stable baseline. It rolls up the 2026.5.16, 2026.5.18, 2026.5.20, and 2026.5.22 trains. After this, continue to Path 12 for the current 2026.6.4 baseline. +Former stable baseline. It rolls up the 2026.5.16, 2026.5.18, 2026.5.20, and 2026.5.22 trains. After this, continue to Path 12 for the current 2026.6.11 baseline. **What changes (the ones you should act on immediately):** @@ -301,28 +303,30 @@ Beta jump. Use a copied profile unless you specifically need iMessage approval r 4. If you use multiple OpenAI/Codex auth lanes, migrate to named profiles and run one tiny Codex task per profile. 5. Roll back to 2026.5.22 if voice steering or approval reactions surprise users. -## Path 12: v2026.5.22 / v2026.5.24-beta.1 → v2026.6.4 stable +## Path 12: v2026.5.22 / v2026.5.24-beta.1 → v2026.6.11 stable -This is the current stable baseline for this guide. It promotes the 5.24 beta line (in 2026.5.26) and adds the June cost/safety levers. +This is the current stable baseline for this guide. It promotes the 5.24 beta line (in 2026.5.26) and rolls up the June trains (2026.6.1 → 2026.6.5 → 2026.6.6 → 2026.6.8 → 2026.6.9 → 2026.6.10 → 2026.6.11). **What changes (act on these immediately):** -- Per-agent budgets are first-class: `agents.list[].budget` with `dailyUsd`/`monthlyUsd` and `onExceed: warn|degrade|stop`. -- `openclaw policy check --export attestation.json` produces diffable attestations; drift against the last accepted attestation is now a reviewable change. -- `models.providers..health` adds interval probes with bounded automatic lane demotion (`failureThreshold`, `demoteForMs`). -- Meeting Notes gains Google Meet live capture plus `meetingNotes.retentionDays` and redaction rules. -- `memory promote --dry-run` lets you preview what dreaming would promote into `MEMORY.md` before it mutates anything. (`memory.recall.maxParallel` and additional dreaming schedule controls are 2026.6.11-beta.1, not 2026.6.4 stable — see step 7.) -- `openclaw doctor` adds secret-rotation reminders (`secrets.rotation.maxAgeDays`) and flags unscoped `mcp.servers..codex.agents`. +- Automatic fast mode: `/fast auto` runs short conversational turns in the provider's fast lane and returns to normal mode for longer work (2026.6.10). +- Failover correctness: provider overloads classify correctly, usage-limit responses route to fallbacks, and individual cron jobs can set their own fallback models with `openclaw cron edit --fallbacks ...` or run strict with `--fallbacks ""` (2026.6.10–11). +- Per-agent cost visibility: `openclaw gateway usage-cost --agent ` / `--all` (2026.6.11). +- Prompt-cache retention in long tool-heavy sessions cuts repeated-history cost automatically (2026.6.11). +- Stuck Telegram/WhatsApp queues recover without a gateway restart (2026.6.11). +- Security posture: secrets are redacted from debug/config output, HTTP session/model override surfaces require admin, package-source redirects and lookalike paths are rejected, and plugin trust warnings include ready-to-copy `plugins.allow` examples (2026.6.9–11). +- Key-free web-search providers (Parallel Free, DuckDuckGo, Ollama, Codex Hosted Search) are explicit opt-ins, never silent fallbacks (2026.6.8–9). +- Official provider plugins are standalone npm packages, and there is an official `openclaw/openclaw` Docker Hub mirror alongside GHCR (2026.6.9–11). **Steps:** -1. Install OpenClaw 2026.6.4 and run `openclaw doctor` + `openclaw policy check`. -2. Add a `budget` cap to your orchestrator with `onExceed: degrade`; confirm you have at least two fallback lanes for it to degrade onto. -3. Add `health` checks to your primary provider and verify a forced failure demotes the lane instead of failing turns. -4. Schedule `openclaw policy check --export` (cron or CI) and store the first attestation as your baseline. Keep `--fix` manual. -5. If you use Meeting Notes, set `retentionDays` and redaction rules before enabling the Google Meet source. -6. Resolve any new doctor findings for plaintext/stale secrets and unscoped Codex MCP servers. -7. Optionally test 2026.6.11-beta.1 on a copied profile for `/context map --diff`, `memory.recall.maxParallel`, dreaming schedule controls, sandbox egress allowlists, and per-channel image-quality overrides. +1. Install OpenClaw 2026.6.11 and run `openclaw doctor` + `openclaw policy check`. +2. Confirm every production agent has at least two fallback lanes; give long-running cron jobs explicit `--fallbacks`. +3. Cron `openclaw gateway usage-cost --all` daily and store the output; treat spend jumps as context regressions. +4. Schedule `openclaw policy check --json` (cron or CI) and store the first attestation output as your baseline. Keep repair manual. +5. Set `/fast auto` where quick conversational traffic dominates; verify with `/fast status` after a fallback switch. +6. Resolve any new doctor findings, and fix `plugins.allow` entries using the plugin ids the trust warning now prints. +7. Delete "restart the gateway when Telegram wedges" from your runbooks after verifying recovery on your install. ## Rollback Plan (Every Path) @@ -333,7 +337,7 @@ If something goes sideways: openclaw gateway stop # Install previous version (example: pin via your package manager) -npm install -g openclaw@2026.6.4 # adjust for your install method / previous pin +npm install -g openclaw@2026.6.10 # adjust for your install method / previous pin # Restore config cp ~/.openclaw/openclaw.json.pre-upgrade.YYYYMMDD ~/.openclaw/openclaw.json diff --git a/part33-late-april-2026-field-guide.md b/part33-late-april-2026-field-guide.md index 1bea99a..fda5462 100644 --- a/part33-late-april-2026-field-guide.md +++ b/part33-late-april-2026-field-guide.md @@ -3,7 +3,9 @@ > **Read this if** you last tuned OpenClaw around 2026.5.22/2026.5.24 and want the current tricks without re-reading every release note. > **Skip if** you're pinned before 2026.4.15 and still need the basics — start with [Part 26 — Migration Guide](./part26-migration-guide.md). -OpenClaw's late-May and early-June releases turned a lot of last month's *betas* into stable defaults and added four operator levers worth wiring in now: first-class budget caps, scheduled policy attestations, provider health-checked failover, and recall/dreaming tuning. This page is the catch-up map from the late-May line to the current **2026.6.4 stable** baseline. +OpenClaw's June releases were about dependability: channel delivery that recovers instead of wedging, provider failover that actually fires, automatic fast mode, prompt-cache savings in long tool-heavy sessions, and per-agent cost visibility. This page is the catch-up map from the late-May line to the current **2026.6.11 stable** baseline (released 2026-06-30). + +> **Correction (July 2026).** A previous revision of this page referenced a "2026.6.4 stable" release and several config keys (`agents.list[].budget`, `models.providers..health`, `policy check --export`, `memory.recall.maxParallel`, `sandbox.network.allow`, `/context map --diff`, `secrets.rotation.maxAgeDays`). No 2026.6.4 release was ever published to npm or GitHub, and those keys do not exist in shipped builds. Tips 14–17 below have been rewritten around features that are actually in the release line. We apologize for the error; the working-config templates have been corrected as well. ## Version Map @@ -22,10 +24,13 @@ OpenClaw's late-May and early-June releases turned a lot of last month's *betas* | **2026.5.22 stable** | Former stable baseline: Gateway startup/perf metadata caching, external Meeting Notes plugin with Discord voice source, docs/config clarifications, sanitized secret/tool telemetry, generic embedding-provider plugin contract, bounded subagent bootstrap context, xAI/Grok web-search auth reuse, session-store helper modernization, protobuf advisory refresh, and plugin dispatch caching. | | **2026.5.24-beta.1** | Beta sweep, now superseded by 2026.5.26 stable: iMessage thumb approval reactions, WebUI/Discord voice status/cancel/steer/follow-up controls, Discord wake-name gating, adaptive `agents.defaults.imageQuality`, meeting-notes startup cleanup, named Codex OAuth profile storage, image/Antigravity media guidance, and more Gateway hot-path caching. | | **2026.5.26 stable** | Promotes the 5.24 beta line: iMessage/WhatsApp approval reactions, adaptive `imageQuality`, named Codex OAuth profiles, and WebUI/Discord voice status/cancel/steer/follow-up controls all go stable, plus meeting-notes startup cleanup and broader Gateway hot-path caching. | -| **2026.6.4 stable** | **Current stable baseline.** First-class per-agent budget caps (`agents.list[].budget`), scheduled `openclaw policy check` with exportable attestations and drift gating, provider health checks with automatic lane demotion, Google Meet live capture as a second Meeting Notes source with retention/redaction config, `memory promote --dry-run`, and `openclaw doctor` MCP-scope + secret-rotation lint. | -| **2026.6.11-beta.1** | Latest beta sweep: `/context map --diff` regression tracking, tunable parallel partial recall (`memory.recall.maxParallel`), dreaming schedule controls, sandbox egress allowlists (`sandbox.network.allow`), per-channel `imageQuality` overrides, and Codex app-server session reuse. | +| **2026.6.5 / 2026.6.6 stable** | Early-June stabilization of the 5.x line. (There was no 2026.6.4 release — the line goes 2026.6.1 → 2026.6.5.) | +| **2026.6.8 stable** | Rich Telegram delivery (tables, lists, blockquotes), WhatsApp ACP bindings, GLM-5.2 and Claude Haiku 4.5 catalog entries, `/usage` full footer templates, key-free web-search providers become explicit opt-ins, split oversized embedding batches, SQLite WAL avoided on network filesystems. | +| **2026.6.9 stable** | Official provider plugins become standalone npm packages, Codex Hosted Search, Codex automatic plugin approvals + GPT-5.3 Spark OAuth routing, secrets redacted from debug/config output, HTTP session/model override surfaces require admin, retries for thinking-only/empty turns, session-history repair. | +| **2026.6.10 stable** | **Automatic fast mode** (`/fast auto`): short conversational turns run in the provider's fast lane and longer work returns to normal mode, with correct status through retries and fallback switches. Also: Zhipu/GLM overload responses route to the right fallback, session transcript SDK contract, cross-channel session identity fixes, `gtimeout` support for Docker/Podman setup. | +| **2026.6.11 stable** | **Current stable baseline.** Reliability sweep: stuck Telegram/WhatsApp queues recover automatically, per-contact DM model assignment, per-job cron fallback models + `deleteAfterRun` transcript cleanup, prompt-cache retention in long tool-heavy sessions, `openclaw gateway usage-cost` for one or all agents, `openclaw agent --message-file`, Slack router relay mode for multi-gateway deployments, official `openclaw/openclaw` Docker Hub mirror, plugin trust warnings with ready-to-copy `plugins.allow` examples, `openclaw skills update --all` honoring install safety policy. | -If you want boring stability today, run **2026.6.4**. If you actively need `/context map --diff`, sandbox egress allowlists, per-channel image-quality overrides, or Codex app-server session reuse, test **2026.6.11-beta.1** on a copy of your profile first. +If you want boring stability today, run **2026.6.11**. It is explicitly a "fix the rough edges" release; there is little reason to stay on an older June build. ## 1. Stop Assuming Claude Subscription Usage @@ -254,31 +259,9 @@ The late-May voice work is not just "talk to the bot": - WebUI and Discord voice callers can ask active run status, cancel, steer, or queue follow-up work mid-consult. - Discord voice bootstraps bounded `IDENTITY.md`, `USER.md`, and `SOUL.md` context by default; set `voice.realtime.bootstrapContextFiles: []` if that is too much. - Discord wake-name gating can default to the agent name. -- Meeting Notes is now a source-only external plugin with auto-start capture config, manual transcript imports, read-only `openclaw meeting-notes` CLI access, and Discord voice as the first live source. -- 2026.6.4 adds **Google Meet live capture as a second source** plus explicit `meetingNotes.retentionDays` and redaction-rule config, so transcripts can expire and scrub sensitive fields instead of living forever. - -Retention config shape (under the `meeting-notes` plugin config): - -```json5 -{ - plugins: { - entries: { - "meeting-notes": { - config: { - retentionDays: 30, - redact: ["email", "phone", "api-key"], - sources: { - discordVoice: { autoStart: false }, - googleMeet: { autoStart: false } - } - } - } - } - } -} -``` +- Meeting Notes is a source-only external plugin with auto-start capture config, manual transcript imports, read-only `openclaw meeting-notes` CLI access, and Discord voice as the first live source. A Google Meet extension exists alongside it for live-capture workflows. -Operator rule: voice and meeting notes are memory inputs. Decide retention, transcript redaction, and which meetings are allowed before auto-capture. Do not pipe every voice room into durable memory by default. +Operator rule: voice and meeting notes are memory inputs. Decide retention, transcript redaction, and which meetings are allowed to be captured *before* enabling any live source, and keep `autoStart` off until that policy exists. Check the plugin's own docs for the exact retention/redaction options in your installed version rather than trusting config keys from a guide. Do not pipe every voice room into durable memory by default. ## 10. Tune Media/Image Cost Deliberately @@ -343,7 +326,9 @@ Context debugging moved from vibes to inspection: If there is no cached run report yet, run one normal turn first; do not trust estimates as if they were measured prompt data. -2026.6.11-beta.1 adds `/context map --diff`, which compares the current treemap against the previous run's snapshot so you can catch context regressions (a skill that doubled in size, a re-injected file that crept back in) instead of eyeballing two maps side by side. +To catch context regressions (a skill that doubled in size, a re-injected file that crept back in), save the `/context detail` output from a known-good run and diff against it after config changes. There is no built-in treemap diff yet; the snapshot-and-compare habit is the current substitute. + +Related cost lever in 2026.6.11: long, tool-heavy sessions now retain prompt-cache savings as tool results accumulate, instead of resending rewritten history every turn. You get this for free on upgrade — but it is one more reason to keep sessions long-lived and compaction healthy rather than resetting constantly. ## 13. Security Notes Worth Acting On @@ -360,9 +345,12 @@ If there is no cached run report yet, run one normal turn first; do not trust es - **Secret symlinks fail closed.** Credential loaders for Telegram, LINE, Zalo, IRC, and Nextcloud Talk reject symlinked secret files when `rejectSymlink: true` is used. - **Plaintext secrets are doctor findings.** `openclaw doctor` warns on model provider API keys and sensitive provider headers stored literally in `openclaw.json`. - **Approval reactions are convenience, not governance.** iMessage and WhatsApp thumbs are useful for `allow-once`/deny, but explicit approver allowlists and `/approve allow-always` discipline still matter. -- **Sandbox egress allowlists** land in 2026.6.11-beta.1. `sandbox.network.allow` lets sandboxed runs reach only named hosts instead of the open internet; default-deny and add the domains a task actually needs. -- **Secret rotation reminders** are now doctor findings in 2026.6.4. `openclaw doctor` flags credentials older than `secrets.rotation.maxAgeDays` so stale long-lived keys surface in routine health checks. -- **Unscoped Codex MCP servers are doctor findings.** 2026.6.4 lints `mcp.servers..codex.agents`: an MCP server projected to every agent instead of a named scope is flagged, not silently trusted. +- **Secrets are redacted from debug output.** 2026.6.9 scrubs secrets from debug/config command output, and 2026.6.11 keeps Slack tokens and similar credentials out of logs. Still treat pasted diagnostics as sensitive until you've read them. +- **HTTP session/model overrides require admin.** Since 2026.6.9, internal HTTP surfaces that override sessions or models demand admin privileges instead of trusting any caller that can reach the port. +- **Package-source redirects can't leak tokens.** 2026.6.10 stops authenticated package-source tokens from following an allowed redirect to another origin, and 2026.6.11 rejects lookalike sibling paths on trusted package sources. +- **Plugin trust warnings are now actionable.** 2026.6.11 prints a ready-to-copy `plugins.allow` example plus the commands to list and inspect plugin ids. Resolve the warning by allowlisting the real plugin id — do not blanket-trust to make the message go away. +- **Skill updates honor install safety policy.** `openclaw skills update --all` now updates only tracked ClawHub skills under your configured safety policy, and ClawHub verification accepts the same `@owner/` reference used for installs — verify the publisher, not a bare slug. +- **Key-free web search is opt-in.** Parallel Free, DuckDuckGo, Ollama, and Codex Hosted Search stay explicit opt-ins instead of silently becoming fallbacks when no API-backed search provider is configured. Decide your search egress deliberately. Per-sender minimum: @@ -379,106 +367,100 @@ Per-sender minimum: Keys are explicit sender identities from the channel adapter (`channel::`, `id:`, `e164:`, `username:`, `name:`, or `*`). Do not build a policy off display names parsed from chat text. -## 14. Put Budget Caps In Config, Not In Your Head +## 14. Watch Cost Per Agent, Not Per Gateway -2026.6.4 makes per-agent budgets first-class instead of something you reconstruct from token reports after the fact. Set them where the agent is defined: +There is no per-agent hard budget cap in config today (a previous revision of this guide claimed one — see the correction at the top). What 2026.6.11 does give you is per-agent cost *visibility*, which is the prerequisite for any budget discipline: -```json5 -{ - agents: { - list: [ - { - id: "orchestrator", - budget: { - dailyUsd: 25, - monthlyUsd: 400, - onExceed: "degrade" // "warn" | "degrade" | "stop" - } - } - ] - } -} +```bash +openclaw gateway usage-cost # default agent +openclaw gateway usage-cost --agent research # one configured agent +openclaw gateway usage-cost --all # every agent ``` -- `warn` surfaces a doctor/notification finding but keeps running. -- `degrade` forces the agent onto its cheapest configured fallback lane for the rest of the window. -- `stop` fails closed and pauses the agent until the window resets or you raise the cap. +Pair it with the `/usage full` footer (native full-footer renderer since 2026.6.8) so per-turn cost is visible in the channel where the work happens, not just in a report you read later. + +Operator routine: -Operator rule: give the orchestrator a real cap and let `degrade` push routine work onto cheap workers automatically. This pairs with the provider routing in Tip 2 — a budget cap without fallback lanes just stops your agent. +1. Run `usage-cost --all` daily (cron it) and diff against yesterday. +2. Any agent whose spend jumped gets a `/context map` check — cost regressions are usually context regressions. +3. Keep expensive models off worker agents; route routine work to cheap lanes (Tip 1) so an orchestrator-only cap is enforced by routing, not by hope. -## 15. Schedule Policy Checks And Export Attestations +## 15. Schedule Policy Checks And Keep The JSON -The Policy plugin (2026.5.20) was a manual command. 2026.6.4 makes it something you can automate and audit over time: +The Policy plugin (2026.5.20) is still the conformance layer, and its findings flow through `doctor --lint` as the shared gate. There is no `--export` flag; the machine-readable path is `--json`, whose output includes stable attestation hashes: ```bash -openclaw policy check --export attestation.json -openclaw cron add policy-check --schedule "0 8 * * *" --command "policy check --export attestation.json" +openclaw policy check +openclaw policy check --json > attestation.json +openclaw policy check --severity-min error ``` -- Exported attestations are diffable, so drift between today's channel config and the last accepted attestation becomes a reviewable change, not a surprise. -- Wire the export into CI for shared instances: fail the pipeline if `openclaw policy check` reports new findings. -- Keep opt-in repair (`--fix`) out of the scheduled job. Detection can be automatic; mutation should stay a human review step. +- Store each `--json` output; the stable hashes make drift between today's config and the last accepted state a diffable, reviewable change. +- Wire it into CI for shared instances: fail the pipeline if `policy check` reports new findings, and treat a clean `doctor --lint` as the final conformance signal. +- Keep repair manual. Detection can be automatic; mutation should stay a human review step. This closes the gap between "we ran policy check once during setup" and "our channel policy is still correct three weeks later." -## 16. Add Provider Health Checks And Failover Lanes +## 16. Trust Failover Again — But Only With Real Fallback Lanes -May gave you routing policy; 2026.6.4 adds health-checked failover so a degraded provider demotes itself instead of failing every turn: +There is no provider health-probe config block (another correction — see the top of this page). What the June line did instead is fix the failover machinery so configured fallbacks actually fire for the right reasons: -```json5 -{ - models: { - providers: { - "anthropic": { - health: { - checkIntervalMs: 60000, - failureThreshold: 3, - demoteForMs: 300000 // route around it for 5 min after 3 failures - } - } - } - } -} +- Provider overloads are classified correctly (e.g. Zhipu/GLM overload responses now trigger the configured fallback path instead of the wrong failover branch, 2026.6.10). +- Usage-limit responses from Claude-CLI- and Codex-backed lanes route to fallback models instead of erroring the turn (2026.6.11). +- Scheduled cron runs and auto-replies keep fast-mode and retry state consistent through fallback model switches (2026.6.10–11). +- Individual cron jobs can declare their own fallback models, run with fallbacks disabled, or inherit the default — from the CLI, without editing payload data (2026.6.11). +- Local model services still support a `healthUrl` readiness probe under `models.providers..localService` before the provider is considered ready. + +None of this helps if you configured a single lane. Keep at least two non-Anthropic fallbacks on every production agent (Tip 1), and give long-running cron jobs an explicit cheap fallback so an overnight provider incident degrades quality instead of silently killing the schedule. + +```bash +openclaw cron edit nightly-report --fallbacks "openrouter/gpt-4.1-mini,openai/gpt-5" +openclaw cron edit nightly-report --fallbacks "" # strict: no fallbacks +openclaw cron edit nightly-report --clear-fallbacks # inherit configured chain again ``` -- The Gateway probes each provider on the interval and temporarily demotes a lane that crosses the failure threshold. -- Demotion is automatic and bounded; the lane is re-promoted after `demoteForMs` so a brief outage does not permanently reroute you. -- This only helps if you actually configured fallback lanes (Tip 1). A single-provider setup has nowhere to fail over to. +## 17. Review Memory Promotions Before Applying Them -Operator rule: every production agent should have at least two non-Anthropic lanes plus health checks, so an Anthropic incident degrades quality instead of taking the agent offline. +The promotion workflow is safe by default: `openclaw memory promote` is a **dry run** unless you pass `--apply`. Use that, plus the explain and status commands, when you suspect dreaming is promoting noise: -## 17. Tune Recall Parallelism And Dreaming Schedules +```bash +openclaw memory promote --limit 10 --min-score 0.75 # preview candidates (no mutation) +openclaw memory promote-explain "router vlan" # why would/wouldn't this promote? +openclaw memory promote --apply # actually write to MEMORY.md +openclaw memory status --deep # probe vector store + embedding readiness +openclaw memory status --fix # repair stale recall locks / promotion metadata +``` -Three memory levers landed for long-running agents: +(A previous revision documented a `--dry-run` flag and a `memory.recall.maxParallel` key; neither exists. Dry-run is the default, and recall parallelism is not operator-tunable.) -- `memory promote --dry-run` (**2026.6.4 stable**) shows what the Deep phase *would* promote into `MEMORY.md` before it mutates anything — use it when you suspect dreaming is promoting noise. -- `memory.recall.maxParallel` (**2026.6.11-beta.1**) bounds how many memory sub-agents run concurrently. Raise it on a fast local embedding tier for snappier recall; lower it on shared hardware to stop recall from starving foreground turns. -- Dreaming schedule controls (**2026.6.11-beta.1**) refine when consolidation runs (building on the existing `dreaming.schedule` key), so it lands in a predictable off-hours window rather than mid-conversation. +Operator rules: -The recall/schedule keys live under the `memory-core` plugin config, alongside the dreaming block (see [templates/openclaw.example.json](./templates/openclaw.example.json)): +- Preview before `--apply`; a noisy promotion pass pollutes the pointer index every future turn pays for. +- Run `memory status --deep` after provider or embedding changes; plain `memory status` deliberately skips live probes. +- Windows + QMD users: 2026.6.11 fixes absolute-path handling, and `memory status` now reports dreaming state correctly — re-check memory health after upgrading rather than trusting older "broken on Windows" notes. -```json5 -{ - plugins: { - entries: { - "memory-core": { - config: { - recall: { maxParallel: 3 }, - dreaming: { schedule: "0 3 * * *" } - } - } - } - } -} +## 18. Let Automatic Fast Mode Handle The Routine Turns + +2026.6.10 adds automatic fast mode. Instead of manually toggling `/fast on` for quick questions and forgetting to turn it off before real work, `auto` runs short conversational turns in the provider's fast lane and returns to normal mode for longer work: + +```text +/fast auto # session override: automatic fast mode +/fast status # show the current effective state +/fast default # clear the session override, inherit the configured default ``` -Operator rule: schedule dreaming for off-hours and verify promotions with `--dry-run` before trusting them; a busy promote step that runs mid-turn is a latency and quality regression, not a feature. +Details worth knowing: + +- `/fast status` shows the *effective* value the session is actually using, including through fallback-model switches — trust it over your memory of what you configured. +- On direct Anthropic routes, fast mode maps to service tiers (`on` → `service_tier=auto`, `off` → `standard_only`); on MiniMax it rewrites to the highspeed variant. Know what lane you're actually buying. +- Pair `auto` with cheap worker lanes: fast mode reduces latency, not per-token price. Routing still owns cost. +- New in the same line: `openclaw agent --message-file task.md` sends long or code-heavy prompts without shell-quoting games — useful for cron and CI wrappers. ## The Newcomer Baseline If someone finds this repo today and asks "what should I run?", tell them: -1. Install stable **2026.6.4** unless they specifically need 2026.6.11-beta.1 `/context map --diff`, sandbox egress allowlists, or per-channel image-quality overrides. +1. Install stable **2026.6.11** (or newer). It is a reliability release; there is no reason to start on an older June build. 2. Use `qwen3-embedding:0.6b` locally for embeddings. 3. Use Opus/Sonnet only behind explicit paid budget caps. 4. Put Kimi K2.6, DeepSeek V4 Flash, DeepInfra, or local models behind worker/fallback lanes. @@ -489,10 +471,10 @@ If someone finds this repo today and asks "what should I run?", tell them: 9. Run `openclaw policy check` and fix channel findings before inviting other users. 10. Use visible-reply enforcement and intentional queue modes in group/channel surfaces. 11. Audit manifests and per-sender tool policies before installing provider/plugins. -12. If you use voice/meetings, set `meetingNotes.retentionDays` and redaction rules before enabling auto-capture. +12. If you use voice/meetings, decide transcript retention and redaction before enabling auto-capture. 13. Use `/context map` after one real run before optimizing prompt bloat. -14. Set per-agent `budget` caps with `onExceed: degrade` so cost overruns reroute instead of surprising you. -15. Schedule `openclaw policy check --export` and add provider `health` checks so policy drift and provider outages are caught automatically. +14. Cron `openclaw gateway usage-cost --all` daily so per-agent cost drift is caught early. +15. Schedule `openclaw policy check --json` and keep the attestation output so policy drift is a diffable change, and give production cron jobs explicit fallback models. ## What To Delete From Old Runbooks @@ -511,7 +493,9 @@ Delete or rewrite advice that says: - "One OpenRouter route is enough; provider routing policy is optional." - "A Codex model ref alone proves MCP/tool policy is safe." - "Image quality should always be high-detail." -- "Track per-agent spend by reading token reports after the fact." (Use `agents.list[].budget` caps instead.) -- "Running `openclaw policy check` once at setup is enough." (Schedule it and export attestations.) -- "One provider with routing policy can't go down." (Add `health` checks and failover lanes.) -- "Meeting/voice transcripts can live forever." (Set `meetingNotes.retentionDays` and redaction rules.) +- "Track spend only at the gateway level." (Cron `openclaw gateway usage-cost --all` and watch per-agent drift.) +- "Running `openclaw policy check` once at setup is enough." (Schedule it and keep the `--json` attestation output.) +- "One provider with routing policy can't go down." (Configure real fallback lanes, including per-cron-job fallbacks.) +- "Meeting/voice transcripts can live forever." (Define retention and redaction before enabling capture.) +- "Fast mode is a manual toggle you must remember." (`/fast auto` handles the routine cases since 2026.6.10.) +- "Restart the gateway when a Telegram/WhatsApp chat wedges." (2026.6.11 recovers stuck queues automatically; if you still need restarts, that's a bug report, not a runbook step.) diff --git a/templates/README.md b/templates/README.md index a95a223..8a7cbcb 100644 --- a/templates/README.md +++ b/templates/README.md @@ -2,7 +2,7 @@ A working-by-default starter bundle that matches the patterns documented in the [OpenClaw Optimization Guide](../README.md). Copy these files into a fresh OpenClaw workspace and you're running the guide's baseline setup. -> Updated for **OpenClaw 2026.6.4 stable** (budget caps, scheduled policy attestations, provider health checks, Meeting Notes retention) and tracking **2026.6.11-beta.1**. See [Part 26 — Migration Guide](../part26-migration-guide.md) if you're on an older version. +> Updated for **OpenClaw 2026.6.11 stable**. A previous revision referenced a "2026.6.4" release and budget/health config blocks that were never shipped; those have been removed from the example config. See [Part 26 — Migration Guide](../part26-migration-guide.md) if you're on an older version. ## What's in this directory diff --git a/templates/openclaw.example.json b/templates/openclaw.example.json index 6646849..f254c60 100644 --- a/templates/openclaw.example.json +++ b/templates/openclaw.example.json @@ -1,6 +1,6 @@ { "$schema": "https://openclaw.dev/schema/openclaw.schema.json", - "_comment": "Reference config from the OpenClaw Optimization Guide. Updated for the 2026.6.4 stable / 2026.6.11-beta.1 era. Copy to ~/.openclaw/openclaw.json (or your project root) and edit. Never commit real credentials — use env var references like ${ANTHROPIC_API_KEY}. Treat this as a starting point; provider catalogs/manifests should own durable model rows where possible.", + "_comment": "Reference config from the OpenClaw Optimization Guide. Updated for the 2026.6.11 stable era. Copy to ~/.openclaw/openclaw.json (or your project root) and edit. Never commit real credentials — use env var references like ${ANTHROPIC_API_KEY}. Treat this as a starting point; provider catalogs/manifests should own durable model rows where possible.", "agents": { "defaults": { @@ -12,15 +12,9 @@ "google/gemini-3-flash", "openai/gpt-5.5" ], - "_comment": "`opus` aliases resolve to Claude Opus 4.7 on current Anthropic/Bedrock routes. Codex app-server routes should use canonical openai/gpt-* refs from your local provider catalog; do not pin durable openai-codex/* or codex-cli/* model refs. Do not assume Claude Pro/Max subscription usage covers OpenClaw after the April 4 cutoff; set budget caps on paid routes." + "_comment": "`opus` aliases resolve to Claude Opus 4.7 on current Anthropic/Bedrock routes. Codex app-server routes should use canonical openai/gpt-* refs from your local provider catalog; do not pin durable openai-codex/* or codex-cli/* model refs. Do not assume Claude Pro/Max subscription usage covers OpenClaw after the April 4 cutoff; watch spend with `openclaw gateway usage-cost --all`." }, "runRetries": 1, - "budget": { - "dailyUsd": 25, - "monthlyUsd": 400, - "onExceed": "degrade" - }, - "_budget_comment": "2026.6.4+: per-agent budget caps. onExceed: warn | degrade | stop. `degrade` reroutes to the cheapest fallback lane — only useful if fallbacks are configured. Override per agent in agents.list[].budget.", "imageQuality": "balanced", "_imageQuality_comment": "2026.5.24-beta.1: token-efficient | balanced | high-detail. Keep balanced unless a worker truly needs high-detail OCR/vision.", "compaction": { @@ -62,14 +56,10 @@ "memory-core": { "enabled": true, "config": { - "recall": { - "maxParallel": 3, - "_comment": "2026.6.11-beta.1+: bound concurrent memory sub-agents. Raise on a fast local embedding tier; lower on shared hardware so recall doesn't starve foreground turns. Not available on 2026.6.4 stable yet." - }, "dreaming": { "enabled": true, "schedule": "0 3 * * *", - "_schedule_comment": "Off-hours dreaming schedule (cron). 2026.6.11-beta.1 adds finer schedule controls. Verify promotions with `memory promote --dry-run` (2026.6.4+) before trusting them.", + "_schedule_comment": "Off-hours dreaming schedule (cron). Preview promotions with `openclaw memory promote` (dry-run by default; pass --apply to write) before trusting them.", "storage": { "mode": "separate", "_comment": "Current default. Phase blocks land in memory/dreaming/{phase}/YYYY-MM-DD.md. Flip to `inline` if you want them in the daily memory file." @@ -103,15 +93,7 @@ }, "meeting-notes": { "enabled": false, - "config": { - "retentionDays": 30, - "redact": ["email", "phone", "api-key"], - "sources": { - "discordVoice": { "autoStart": false }, - "googleMeet": { "autoStart": false } - } - }, - "_comment": "2026.5.22+ source-only external plugin; 2026.6.4 adds Google Meet live capture plus retentionDays/redaction. Define retention before enabling any live source." + "_comment": "2026.5.22+ source-only external plugin (Discord voice first live source). Define retention and redaction policy before enabling any live capture; check the plugin's own docs for its current config options." } } }, @@ -150,12 +132,7 @@ "providers": { "anthropic": { "type": "anthropic", - "health": { - "checkIntervalMs": 60000, - "failureThreshold": 3, - "demoteForMs": 300000 - }, - "_comment": "2026.6.4+: health-checked failover. A lane that crosses failureThreshold is demoted for demoteForMs, then re-promoted. Only helps if fallback lanes exist (see agents.defaults.model.fallbacks)." + "_comment": "Failover comes from agents.defaults.model.fallbacks, not a provider health block. 2026.6.10–11 fixed overload classification and usage-limit fallback routing — keep at least two fallback lanes configured." }, "openrouter": { "type": "openrouter", @@ -202,12 +179,6 @@ "audit": { "suppressions": [], "_comment": "2026.5.18+: only suppress reviewed audit findings with owner/reason/expiry in your real config." - }, - "secrets": { - "rotation": { - "maxAgeDays": 90, - "_comment": "2026.6.4+: openclaw doctor warns on credentials older than this so stale long-lived keys surface in routine health checks." - } } },