diff --git a/AWESOME.md b/AWESOME.md index b2d5192..f4a511a 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: **May 24, 2026, tracking OpenClaw 2026.5.22 stable + 2026.5.24-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: **June 2026, tracking OpenClaw 2026.6.4 stable + 2026.6.11-beta.1**. ## Contents @@ -34,11 +34,11 @@ ## Guides & tutorials -- **[OpenClaw Optimization Guide](./README.md)** — this repo. 33 parts, refreshed for the late-May 2026 release wave. -- **[Late-May 2026 Field Guide](./part33-late-april-2026-field-guide.md)** — the fast catch-up map from 2026.4.15 to 2026.5.22/2026.5.24-beta.1. +- **[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). - **[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 → May 2026](./part26-migration-guide.md)** — opinionated upgrade paths. +- **[Migration Guide — v3 → v4 → June 2026](./part26-migration-guide.md)** — opinionated upgrade paths. - **[Toolbrain OpenClaw Best Practices 2026](https://toolbrain.net/openclaw-best-practices-optimization-guide/)** — useful external checklist on task-aware routing, compaction, skill bloat, and cost controls. Treat syntax examples as illustrative; verify against current OpenClaw config docs. - **[The OpenClaw Playbook](https://www.openclawplaybook.ai/)** — community/operator playbook focused on identity, persistent memory, daily operations, and autonomous coding. Commercial resource; useful signal on where power users are taking always-on agents. @@ -69,7 +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. Define retention before enabling. +- **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. - **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). @@ -93,6 +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. - **[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. @@ -111,7 +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. +- **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. - **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 f1c660a..67dc3de 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.5.24 beta](https://img.shields.io/badge/OpenClaw-2026.5.24--beta.1-2ea44f)](./part33-late-april-2026-field-guide.md) -[![Stable baseline: 2026.5.22](https://img.shields.io/badge/stable-2026.5.22-blue)](./part26-migration-guide.md) +[![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) [![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,24 +11,24 @@ [![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)](./LICENSE) [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](./CONTRIBUTING.md) -> **Late-May 2026 sweep.** Stable baseline: **OpenClaw 2026.5.22**. Beta tracked: **2026.5.24-beta.1**. This refresh updates the mid-May guidance for the latest release wave: Gateway startup/perf caching, the source-only Meeting Notes plugin, the bundled Policy plugin, Codex/MCP scoping, voice-run control, adaptive image compression, iMessage/WhatsApp approval reactions, xAI/OpenRouter routing upgrades, and stricter secret/tool-policy checks. +> **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. *By Terp — [Terp AI Labs](https://x.com/OnlyTerp)* --- -## Start With The Late-May 2026 Reality Check +## Start With The June 2026 Reality Check -OpenClaw changed more from mid-May through 2026.5.24-beta.1 than most agent projects change in a quarter. If you last read this guide around 2026.5.12/2026.5.14, these are the new rules: +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: 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. **Codex is now a policy/MCP surface, not just a model route.** Keep canonical `openai/gpt-*` model refs, but also scope user MCP servers with `mcp.servers..codex.agents`, set Codex tool approval defaults deliberately, and test deny-all sender policies against native Codex tools. -3. **Policy checks moved into the product.** The bundled Policy plugin adds channel-conformance checks, `openclaw policy check`, doctor findings, attestations, drift checks, and opt-in repair. Use it before exposing shared channels. -4. **Voice and meetings are now operating surfaces.** Discord voice can follow configured users, realtime callers can ask status/cancel/steer/follow-up mid-consult, and Meeting Notes moved into a source-only external plugin with Discord voice as the first live source. -5. **Fast Gateway startup is now real, but session hygiene is still your job.** 2026.5.18-5.24 cache plugin/channel/provider metadata aggressively, but long-running agents still need transcript guards, cron/session isolation, and deliberate `/new` or rotation policy. -6. **Provider routing got more specific.** xAI supports remote-friendly device-code OAuth, OpenRouter honors provider-level `params.provider` routing policy, and `agents.list[].experimental.localModelLean` can now be set per agent. +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. -Read **[Part 33 — Late-May 2026 Field Guide](./part33-late-april-2026-field-guide.md)** first if you want the latest tricks before the deep dives. +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. ## The Harness Thesis @@ -156,26 +156,22 @@ Alongside the 33 parts themselves, this repo now includes the tooling that turns --- -## What Changed In This Release (Late-May 2026 Refresh) +## What Changed In This Release (June 2026 Refresh) -- **Updated [Part 33 — Late-May 2026 Field Guide](./part33-late-april-2026-field-guide.md)** — concise upgrade map from 2026.4.15 through 2026.5.22 stable / 2026.5.24-beta.1: Gateway performance caching, Meeting Notes, Policy plugin checks, Codex/MCP scoping, Discord voice, image-quality controls, iMessage approvals, and current security hardening. -- **Codex guidance corrected again** — native Codex still means canonical `openai/gpt-*` model refs, but the real late-May work is MCP projection scoping, `codex.defaultToolsApprovalMode`, named OAuth profiles, and deny-all tool policy verification. -- **Configuration patterns refreshed** — the template now shows `agents.defaults.imageQuality`, per-agent `localModelLean`, channel room-event settings, `mcp.servers..codex.agents`, OpenRouter provider routing, and meeting-notes/policy plugin stubs. -- **Security guidance tightened** — skill-file read/executable allowlist compatibility is gone, symlinked credential files fail closed, doctor warns on plaintext secret-bearing config, and channel conformance belongs in the Policy plugin. -- **Operator workflow updated** — use `openclaw policy check`, `openclaw tasks maintenance --json`, named Codex auth profiles, realtime voice status/cancel/steer controls, and explicit session/transcript hygiene for long-running agents. +- **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. -### Previous 2026.4.15 refresh +### Previous Late-May 2026 refresh -- **Task Brain control plane** (new [Part 24](./part24-task-brain-control-plane.md)) — unified task ledger, semantic approval categories, agent-initiated denies, fail-closed plugin defaults. Shipped as the structural fix for the March CVE wave. -- **ClawHub skills marketplace** (new [Part 23](./part23-clawhub-skills-marketplace.md)) — 13K+ community skills, 1,184 removed for being malicious. Install policy, signing, scope-limiting, sleeper-update mitigation. -- **v4.0 Architecture Overview** (new [Part 25](./part25-architecture-overview.md)) — the primer that should have existed since the rewrite. -- **Migration Guide** (new [Part 26](./part26-migration-guide.md)) — opinionated v3 → v4 → v2026.3 → v2026.4 → v2026.4.15 upgrade paths with rollback plans. -- **Gotchas & FAQ** (new [Part 27](./part27-gotchas-and-faq.md)) — symptom-indexed troubleshooting, most questions answered in one page. -- **Glossary & Terminology** (new [Part 28](./part28-glossary-and-terminology.md)) — every term this guide uses (MOC, autoDream, Task Brain, ACP, Ralph loop, ClawHavoc, memory-lancedb, LightRAG, semantic approvals, `localModelLean`…) on one page, cross-linked to the part that introduces each. -- **Decision trees on every part** — each part (README-embedded and external) now opens with a "Read this if / Skip if" callout so you can route yourself through the guide instead of reading it linearly. -- **Part 16 (custom autoDream) retired** — the file has been removed. Memory-core's native dreaming ([Part 22](#part-22-built-in-dreaming)) is the official path since 2026.4+; see the short retirement note in Part 22 below if you're coming from the old pattern. -- Updates across existing parts for: memory-lancedb cloud storage, GitHub Copilot embedding provider, `localModelLean` flag, compaction reserve-token floor cap, gateway auth hot-reload, approvals secret redaction, `memory_get` canonical-only, Model Auth status card. -- **v2026.4.15 stable (April 16, 2026)** — **Claude Opus 4.7** is the new default Anthropic selection (`opus` aliases + Claude CLI defaults + bundled image understanding all point at it); **dreaming default flipped `inline` → `separate`** so phase blocks land in `memory/dreaming/{phase}/YYYY-MM-DD.md` instead of polluting daily memory files; **`memory_get` excerpts are now capped by default** with explicit continuation metadata + trimmed startup/skills prompt budgets; **gateway tool-name normalize-collision rejection** (client tools that collide with a built-in get `400 invalid_request_error`, closing a local-media trust-inheritance hole); plus Gemini TTS in the bundled `google` plugin, Control UI false-positive Model Auth fix, webchat localRoots containment, and Matrix pairing-auth tightening. +- **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](./part25-architecture-overview.md)** and **[Part 26 — Migration Guide](./part26-migration-guide.md)**. --- @@ -228,7 +224,7 @@ Not every part applies to every reader. Jump directly to the pillar that matches | I want to… | Start with | |-------------|-----------| -| **Catch up on the latest changes** | [33 May Field Guide](./part33-late-april-2026-field-guide.md) · [26 Migration Guide](./part26-migration-guide.md) · [27 Gotchas & FAQ](./part27-gotchas-and-faq.md) | +| **Catch up on the latest changes** | [33 June Field Guide](./part33-late-april-2026-field-guide.md) · [26 Migration Guide](./part26-migration-guide.md) · [27 Gotchas & FAQ](./part27-gotchas-and-faq.md) | | **Make my agent faster** | [1 Speed](#part-1-speed-stop-being-slow) · [2 Context Engineering](#part-2-context-engineering--the-discipline) · [3 Cron Bloat](#part-3-cron-session-bloat-the-hidden-killer) · [6 Models](#part-6-models-what-to-actually-use) | | **Stop it forgetting things** | [4 Memory](#part-4-memory-stop-forgetting-everything) · [9 Vault](#part-9-vault-memory-system-stop-losing-knowledge-between-sessions) · [10 Embeddings](./part10-state-of-the-art-embeddings.md) · [22 Built-In Dreaming](#part-22-built-in-dreaming) · [31 LLM Wiki Pattern](./part31-the-llm-wiki-pattern-in-openclaw.md) | | **Reduce cost** | [5 Orchestration](#part-5-orchestration-stop-doing-everything-yourself) · [6 Models](#part-6-models-what-to-actually-use) · [8 One-Shotting](#part-8-one-shotting-big-tasks-stop-iterating-start-researching) · [22 Memory you can afford](#part-22-built-in-dreaming) | @@ -251,9 +247,9 @@ Not every part applies to every reader. Jump directly to the pillar that matches - [26. Migration Guide](./part26-migration-guide.md) — upgrade paths + rollback plans - [27. Gotchas & FAQ](./part27-gotchas-and-faq.md) — symptom → fix table + frequently asked questions - [28. Glossary & Terminology](./part28-glossary-and-terminology.md) — every term this guide assumes, on one page -- [33. Late-May 2026 Field Guide](./part33-late-april-2026-field-guide.md) — what changed after 2026.4.15 and what to do now +- [33. June 2026 Field Guide](./part33-late-april-2026-field-guide.md) — what changed after 2026.5.22 and what to do now - [14. Quick Checklist](#part-14-quick-checklist) — 30-minute setup -- [17. The One-Shot Prompt](#part-17-the-one-shot-prompt) — automation prompt, updated for May defaults +- [17. The One-Shot Prompt](#part-17-the-one-shot-prompt) — automation prompt, updated for current defaults **⚡ Speed & context** 1. [Speed — Stop Being Slow](#part-1-speed-stop-being-slow) — trim context, add fallbacks, reasoning mode, `localModelLean` @@ -269,7 +265,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. [Late-May 2026 Field Guide](./part33-late-april-2026-field-guide.md) — Gateway perf, Policy plugin, Meeting Notes, provider routing, voice steering, browser/Codex updates +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 **🤝 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 642a4d7..8d7f39c 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.5.22 stable and 2026.5.24 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.4 stable and 2026.6.11 beta.** > 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 85bc362..8f59b5c 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.5.22 stable and 2026.5.24 beta. +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_url: https://onlyterp.github.io/openclaw-optimization-guide/ repo_url: https://github.com/OnlyTerp/openclaw-optimization-guide repo_name: OnlyTerp/openclaw-optimization-guide @@ -86,7 +86,7 @@ extra: nav: - Home: README.md - Start here: - - Late-May 2026 field guide: part33-late-april-2026-field-guide.md + - June 2026 field guide: part33-late-april-2026-field-guide.md - Architecture overview: part25-architecture-overview.md - Migration guide: part26-migration-guide.md - Gotchas & FAQ: part27-gotchas-and-faq.md diff --git a/part25-architecture-overview.md b/part25-architecture-overview.md index 9ea0fe4..741fbd7 100644 --- a/part25-architecture-overview.md +++ b/part25-architecture-overview.md @@ -151,8 +151,11 @@ Short form, so you know what era a given piece of advice applies to: | **v2026.5.14-beta.1** | 2026-05-14 | `/queue steer` default, `agents.defaults.runRetries`, Telnyx realtime calls, Codex command/migration fixes, bundled `codex-cli` backend removal/repair, WhatsApp status reactions, per-sender tool policies, nested sub-agent sessions | Queue/Codex/per-sender beta that shaped the current May line. | | **v2026.5.18 stable** | 2026-05-18 | Node 22.19 floor, Gateway/plugin startup polish, browser modal dialogs, Codex app-server/MCP fixes, typed tool plugin CLI, Docker/Podman `OPENCLAW_IMAGE_APT_PACKAGES`, and broad channel/runtime hardening | First stable rollup after 5.12; verify Node and image-build args. | | **v2026.5.20 stable** | 2026-05-21 | Policy plugin, Discord voice follow/bootstrap context, per-agent `localModelLean`, xAI device-code OAuth, OpenRouter provider routing, skill exec approval hardening, secret symlink fail-closed behavior, plaintext-secret doctor warnings | Security/policy release; run `openclaw policy check` before shared channels. | -| **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 | **This guide's current 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 | Latest beta; test on a copied profile before exposing to users. | +| **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. | 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 4a3328b..c3c73a9 100644 --- a/part26-migration-guide.md +++ b/part26-migration-guide.md @@ -1,21 +1,22 @@ # Part 26: Migration Guide -> Updated in the late-May 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 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. -> **Read this if** you're on anything older than 2026.5.22, or planning an upgrade. +> **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. ## 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.5.22 | -| **v4.0.x** | v2026.3.31-beta.1 (Task Brain) | Reach 2026.4.27 through Paths 2–6 | 2026.5.22 | -| **v2026.3.x** | Apply Task Brain approval policy | Reach 2026.4.27 through Paths 3–6 | 2026.5.22 | -| **v2026.4.x pre-4.15** | Skip straight to 2026.4.15 | Reach 2026.4.27 through Paths 5–6 | 2026.5.22 | -| **v2026.4.15** | Remove subscription-era model assumptions | Apply provider-catalog changes | 2026.5.22 | -| **v2026.4.27** | Apply memory/messaging beta changes | Upgrade to 2026.5.22 | Optional 2026.5.24-beta.1 | -| **v2026.4.29-beta.1** | Migrate Codex/queue assumptions | Upgrade to 2026.5.22 | Optional 2026.5.24-beta.1 | +| **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 | 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. @@ -229,7 +230,7 @@ This is the former May stable baseline. Do this as the compatibility checkpoint, ## Path 9: v2026.5.12 stable → v2026.5.14-beta.1 -Former beta jump. Today, treat this as the queue/Codex/per-sender migration checkpoint, then continue to Path 10 for the current stable baseline. +Former beta jump. Today, treat this as the queue/Codex/per-sender migration checkpoint, then continue through Path 10 and Path 12 for the current stable baseline. **What changes (the ones you should act on immediately):** @@ -254,7 +255,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 -This is the current stable baseline for this guide. It rolls up the 2026.5.16, 2026.5.18, 2026.5.20, and 2026.5.22 trains. +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. **What changes (the ones you should act on immediately):** @@ -300,6 +301,29 @@ 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 + +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. + +**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`. + +**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. + ## Rollback Plan (Every Path) If something goes sideways: @@ -309,7 +333,7 @@ If something goes sideways: openclaw gateway stop # Install previous version (example: pin via your package manager) -npm install -g openclaw@2026.5.22 # adjust for your install method / previous pin +npm install -g openclaw@2026.6.4 # 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 9c4ebf8..1bea99a 100644 --- a/part33-late-april-2026-field-guide.md +++ b/part33-late-april-2026-field-guide.md @@ -1,9 +1,9 @@ -# Part 33: Late-May 2026 Field Guide +# Part 33: June 2026 Field Guide -> **Read this if** you last tuned OpenClaw around 2026.5.12/2026.5.14 and want the current tricks without re-reading every release note. +> **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 releases changed the operator playbook in eight places: Gateway startup, provider routing, memory/session hygiene, shared-channel policy, browser/Codex automation, voice/meeting capture, plugin/security boundaries, and media handling. This page is the catch-up map. +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. ## Version Map @@ -19,10 +19,13 @@ OpenClaw's late-May releases changed the operator playbook in eight places: Gate | **2026.5.16 beta train** | Per-agent bootstrap profiles, localized setup, Telegram ambient `room_event`, `openclaw cron run --wait`, xAI Grok OAuth, Codex context-engine thread projection, Codex MCP server scoping, and `codex.defaultToolsApprovalMode`. | | **2026.5.18 stable** | Stable rollup after 5.12: Control UI/Mac app polish, realtime Android/Discord/OpenAI voice follow-ups, Telegram/Discord delivery repairs, Codex/OpenAI app-server context/MCP/tool progress fixes, plugin SDK hardening, provider routing fixes, Node 22.19 floor, Docker/Podman `OPENCLAW_IMAGE_APT_PACKAGES`, and broad security robustness. | | **2026.5.20 stable** | Policy plugin lands (`openclaw policy check`, attestations, doctor lint/repair), Discord voice can follow configured users, bounded voice bootstrap context, per-agent `experimental.localModelLean`, xAI device-code OAuth, OpenRouter provider routing policy, stricter skill-file exec approvals, secret symlink fail-closed behavior, and plaintext-secret doctor warnings. | -| **2026.5.22 stable** | Current 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** | Latest beta sweep: 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.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. | -If you want boring stability today, run **2026.5.22**. If you actively use WebUI/Discord voice steering, iMessage approval reactions, adaptive image compression, or named Codex OAuth profile storage, test **2026.5.24-beta.1** on a copy of your profile first. +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. ## 1. Stop Assuming Claude Subscription Usage @@ -252,6 +255,28 @@ The late-May voice work is not just "talk to the bot": - 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 } + } + } + } + } + } +} +``` 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. @@ -318,6 +343,8 @@ 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. + ## 13. Security Notes Worth Acting On - **Outbound proxy routing** exists in 2026.4.27, but only with strict `http://` forward-proxy validation and loopback gateway bypass. Use it for corporate egress, not as a vague privacy toggle. @@ -333,6 +360,9 @@ 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. Per-sender minimum: @@ -349,11 +379,106 @@ 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 + +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: + +```json5 +{ + agents: { + list: [ + { + id: "orchestrator", + budget: { + dailyUsd: 25, + monthlyUsd: 400, + onExceed: "degrade" // "warn" | "degrade" | "stop" + } + } + ] + } +} +``` + +- `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. + +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. + +## 15. Schedule Policy Checks And Export Attestations + +The Policy plugin (2026.5.20) was a manual command. 2026.6.4 makes it something you can automate and audit over time: + +```bash +openclaw policy check --export attestation.json +openclaw cron add policy-check --schedule "0 8 * * *" --command "policy check --export attestation.json" +``` + +- 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. + +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 + +May gave you routing policy; 2026.6.4 adds health-checked failover so a degraded provider demotes itself instead of failing every turn: + +```json5 +{ + models: { + providers: { + "anthropic": { + health: { + checkIntervalMs: 60000, + failureThreshold: 3, + demoteForMs: 300000 // route around it for 5 min after 3 failures + } + } + } + } +} +``` + +- 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. + +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. + +## 17. Tune Recall Parallelism And Dreaming Schedules + +Three memory levers landed for long-running agents: + +- `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. + +The recall/schedule keys live under the `memory-core` plugin config, alongside the dreaming block (see [templates/openclaw.example.json](./templates/openclaw.example.json)): + +```json5 +{ + plugins: { + entries: { + "memory-core": { + config: { + recall: { maxParallel: 3 }, + dreaming: { schedule: "0 3 * * *" } + } + } + } + } +} +``` + +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. + ## The Newcomer Baseline If someone finds this repo today and asks "what should I run?", tell them: -1. Install stable **2026.5.22** unless they specifically need 2026.5.24-beta.1 voice steering, iMessage approval reactions, or image-quality controls. +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. 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. @@ -364,8 +489,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, define transcript retention and redaction before enabling auto-capture. +12. If you use voice/meetings, set `meetingNotes.retentionDays` and redaction rules 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. ## What To Delete From Old Runbooks @@ -384,3 +511,7 @@ 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.) diff --git a/templates/README.md b/templates/README.md index 785ee1e..a95a223 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.5.22 stable** and the **2026.5.24-beta.1** policy/meeting-notes/voice/image changes. See [Part 26 — Migration Guide](../part26-migration-guide.md) if you're on an older version. +> 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. ## What's in this directory diff --git a/templates/openclaw.example.json b/templates/openclaw.example.json index ae2476d..6646849 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.5.22 stable / 2026.5.24-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.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.", "agents": { "defaults": { @@ -15,6 +15,12 @@ "_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." }, "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": { @@ -56,9 +62,14 @@ "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.", "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." @@ -93,9 +104,14 @@ "meeting-notes": { "enabled": false, "config": { - "autoStart": false + "retentionDays": 30, + "redact": ["email", "phone", "api-key"], + "sources": { + "discordVoice": { "autoStart": false }, + "googleMeet": { "autoStart": false } + } }, - "_comment": "2026.5.22+: source-only external plugin. Define retention/redaction before enabling Discord voice capture." + "_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." } } }, @@ -132,6 +148,15 @@ "models": { "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)." + }, "openrouter": { "type": "openrouter", "params": { @@ -177,6 +202,12 @@ "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." + } } },