diff --git a/AWESOME.md b/AWESOME.md index 8cbdc85..b2d5192 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 14, 2026, tracking OpenClaw 2026.5.12 stable + 2026.5.14-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: **May 24, 2026, tracking OpenClaw 2026.5.22 stable + 2026.5.24-beta.1**. ## Contents @@ -34,8 +34,8 @@ ## Guides & tutorials -- **[OpenClaw Optimization Guide](./README.md)** — this repo. 33 parts, refreshed for the May 2026 release wave. -- **[May 2026 Field Guide](./part33-late-april-2026-field-guide.md)** — the fast catch-up map from 2026.4.15 to 2026.5.12/2026.5.14-beta.1. +- **[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. - **[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. @@ -69,6 +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. +- **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). - **[Repowise](https://github.com/repowise/repowise)** — structural index for codebases. Feeds workers a map instead of re-reading files. See [Part 19](./part19-repowise-codebase-intelligence.md). @@ -90,6 +92,7 @@ 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`. - **[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. @@ -102,17 +105,22 @@ See [Part 23 — ClawHub Skills Marketplace](./part23-clawhub-skills-marketplace - **Trend Micro — Atomic Stealer via OpenClaw skills** (Mar 2026) — 39 skills distributing macOS infostealer. - **Kaspersky OpenClaw audit** — 512 vulns, 8 critical including `CVE-2026-25253` (1-click RCE) and WebSocket shared-auth scope escalation at CVSS 9.9. - **This repo, [Part 15 — Infrastructure Hardening](./part15-infrastructure-hardening.md)** — operational hardening checklist. +- **`security.audit.suppressions`** — 2026.5.18 config escape hatch for reviewed audit findings. Use owner/reason/expiry; do not suppress unknown warnings. ## Control plane & governance - **[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. +- **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 - **[Canvas](https://clawdocs.org/canvas)** — the first-party control UI. Model Auth card, approvals, memory browser. -- **Webchat** — the browser surface. 2026.4.15 stable tightened localRoots containment on audio. +- **Webchat** — the browser surface. 2026.4.15 stable tightened localRoots containment on audio; 2026.5.24-beta.1 voice callers can status/cancel/steer/follow-up active runs. - **Matrix bridge** — chat-in-Matrix surface. Pairing-auth tightened in 2026.4.15 stable; DM pairing-store entries can no longer authorize room control. +- **iMessage / WhatsApp approvals** — thumbs-up/thumbs-down reactions are convenient `allow-once`/deny controls, but still require trusted approver policy. +- **Discord voice follow / wake-name gating** — 2026.5.20+ voice sessions can follow configured users; 2026.5.24-beta.1 adds wake-name gating and mid-consult run controls. ## Research papers diff --git a/README.md b/README.md index 74367e9..c40342d 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.14 beta](https://img.shields.io/badge/OpenClaw-2026.5.14--beta.1-2ea44f)](./part33-late-april-2026-field-guide.md) -[![Stable baseline: 2026.5.12](https://img.shields.io/badge/stable-2026.5.12-blue)](./part26-migration-guide.md) +[![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) [![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,23 +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) -> **May 14, 2026 sweep.** Stable baseline: **OpenClaw 2026.5.12**. Beta tracked: **2026.5.14-beta.1**. This refresh updates the late-April guidance for the May release wave: leaner provider/plugin installs, canonical Codex app-server routing, `/queue steer` defaults, `/context map`, provider-owned local services, per-sender tool policies, Telegram/WhatsApp/voice reliability, `agents.defaults.runRetries`, and the current security/provenance posture. +> **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. *By Terp — [Terp AI Labs](https://x.com/OnlyTerp)* --- -## Start With The May 2026 Reality Check +## Start With The Late-May 2026 Reality Check -OpenClaw changed more from late April through mid-May than most agent projects change in a quarter. If you last read this guide around 2026.4.15/2026.4.29, these are the new rules: +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: 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 routing changed again.** Use canonical `openai/gpt-*` model refs such as `openai/gpt-5.5` for the native Codex app-server route; `openai-codex` is an auth/profile surface, not a durable model prefix, and the bundled `codex-cli` backend is gone in 2026.5.14-beta.1. -3. **Provider catalogs and plugin installs are leaner.** Bedrock, Slack, Anthropic Vertex, OpenShell sandbox, WhatsApp, and related cones moved out of core installs. Audit manifests and install only the providers/channels you use. -4. **Messaging now steers by default.** `/queue steer` is the default for active runs; use `/queue followup`, `/queue collect`, or `/queue interrupt` only when that behavior is intentional. Keep `messages.visibleReplies` on for shared channels. -5. **Context and local runtime control improved.** `/context map` shows a treemap of prompt contributors after a real run, `models.providers..localService` can start local model servers on demand, and `agents.defaults.runRetries` lets embedded Pi runs retry boundedly. +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. -Read **[Part 33 — 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 — Late-May 2026 Field Guide](./part33-late-april-2026-field-guide.md)** first if you want the latest tricks before the deep dives. ## The Harness Thesis @@ -155,13 +156,13 @@ Alongside the 33 parts themselves, this repo now includes the tooling that turns --- -## What Changed In This Release (May 2026 Refresh) +## What Changed In This Release (Late-May 2026 Refresh) -- **Updated [Part 33 — May 2026 Field Guide](./part33-late-april-2026-field-guide.md)** — concise upgrade map from 2026.4.15 through 2026.5.12 stable / 2026.5.14-beta.1: Codex app-server routing, queue steering defaults, provider-local services, externalized plugins, Telegram/WhatsApp/voice fixes, `/context map`, and current security hardening. -- **Codex guidance corrected** — native Codex now means canonical `openai/gpt-*` model refs with the Codex app-server runtime and `openai-codex` auth profiles; legacy `codex-cli` backend assumptions and durable `openai-codex/*` model refs are called out as migration debt. -- **Configuration patterns refreshed** — the template now shows `messages.queue`, `agents.defaults.runRetries`, `tools.toolsBySender`, and a provider-level `localService` skeleton instead of only late-April model/memory flags. -- **Security guidance tightened** — per-sender schema stripping, requester-bound gateway approvals, structured SecretRefs for provider keys, Windows home-root sandbox blocks, and manifest-first plugin audits are now called out. -- **Operator workflow updated** — `/context list`, `/context detail`, and `/context map` are recommended for prompt-budget audits; `/queue steer` is the default; Telnyx realtime voice and WhatsApp status reactions are noted as beta/watch items. +- **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. ### Previous 2026.4.15 refresh @@ -250,7 +251,7 @@ 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. May 2026 Field Guide](./part33-late-april-2026-field-guide.md) — what changed after 2026.4.15 and what to do now +- [33. Late-May 2026 Field Guide](./part33-late-april-2026-field-guide.md) — what changed after 2026.4.15 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 @@ -268,7 +269,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. [May 2026 Field Guide](./part33-late-april-2026-field-guide.md) — Active Memory filters, people wiki, provider catalogs, run steering, browser/Codex updates +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 **🤝 Orchestration & models** 5. [Orchestration](#part-5-orchestration-stop-doing-everything-yourself) — sub-agents-as-GC, Anthropic's 5 coordination patterns, CEO/COO/Worker, verification @@ -456,19 +457,22 @@ Every enabled plugin adds overhead. If you're not using `memory-lancedb`, `memor ### Lean Mode for Weak Local Models -New in 2026.4.15: if you're running a small local model (≤14B params, 16K-32K context) and the default tool set is eating your whole prompt, flip the lean flag: +New in 2026.4.15 and refined in 2026.5.20: if you're running a small local model (≤14B params, 16K-32K context) and the default tool set is eating the prompt, prefer per-agent lean mode for the small worker. Use the global default only when every agent on that profile is local/small: ```json { "agents": { - "defaults": { - "experimental": { "localModelLean": true } - } + "list": [ + { + "id": "local-worker", + "experimental": { "localModelLean": true } + } + ] } } ``` -This drops the heavyweight default tools (browser, cron, message) from the system prompt. You keep `memory_search`, `exec`, `sessions_spawn`, and the essentials — which is everything most local setups actually use. 2026.4.29 also relaxed fixed preflight cutoffs so small local models use guard thresholds derived from their effective context window instead of hard-coded 16K/32K floors. +This drops heavyweight default tools (browser, cron, message) from that worker's system prompt. You keep `memory_search`, `exec`, `sessions_spawn`, and the essentials — which is everything most local setups actually use. 2026.4.29 also relaxed fixed preflight cutoffs so small local models use guard thresholds derived from their effective context window instead of hard-coded 16K/32K floors. ### Ollama Housekeeping @@ -1037,7 +1041,7 @@ If you have a GPU, local models via Ollama = unlimited inference at zero cost. - **TerpBot (Nemotron 30B fine-tuned)** - Custom fine-tune on clean 9.4K examples. 235 tok/s on 5090, 91.93% MMLU-Pro Math. Not public — but Nemotron 30B base is: `ollama pull nemotron-30b` - **NVIDIA Nemotron Nano 4B** - Punches above its weight, 128K context, fits on any GPU. `ollama pull nemotron-nano` -> **2026.4.15 — if you drive a small local model, turn on `localModelLean`.** Set `agents.defaults.experimental.localModelLean: true` and the gateway stops injecting the heavyweight default tools (browser, cron, message) into the system prompt. You keep `memory_search`, `exec`, `sessions_spawn` — i.e. the tools a local model can actually *use*. Frees ~3KB of prompt, which on a 16K-context 14B model is the difference between "fits one retrieval result" and "crashes out of context." Leave this off for frontier models — you want them to have everything. +> **2026.5.20 — if one worker is small/local, use per-agent `localModelLean`.** Set `agents.list[].experimental.localModelLean: true` on the small worker and the gateway stops injecting heavyweight default tools (browser, cron, message) into that worker prompt. You keep `memory_search`, `exec`, `sessions_spawn` — i.e. the tools a local model can actually use. Frees ~3KB of prompt without starving frontier orchestrators. ### Claude Subscription Path Retired @@ -1471,7 +1475,7 @@ Run through this in 30 minutes: - [ ] **ClawHub hygiene** — every installed skill reviewed, source repo pinned, auto-update disabled (Part 23) - [ ] **Task Brain** — semantic approval categories configured; `control-plane.*` kept approval-required (Part 24) - [ ] `openclaw tasks list` runs clean — no orphaned or denied tasks lingering (Part 24) -- [ ] 2026.4.15 upgrade: `agents.defaults.experimental.localModelLean` set correctly for your model tier (Part 6) +- [ ] 2026.5.20 upgrade: per-agent `agents.list[].experimental.localModelLean` set correctly for small local workers (Part 6) - [ ] 2026.4.15 upgrade: `memory_get` not called with arbitrary paths anywhere in your skills/hooks (Part 4/22) - [ ] Control UI Model Auth card checked — OAuth tokens healthy, no rate-limit red flags diff --git a/SCORECARD.md b/SCORECARD.md index e4a912d..b5a1380 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.12 stable and 2026.5.14 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.5.22 stable and 2026.5.24 beta.** > Share your score: *"My OpenClaw Production Readiness Scorecard: XX / 100 — [github.com/OnlyTerp/openclaw-optimization-guide](https://github.com/OnlyTerp/openclaw-optimization-guide)"* @@ -28,7 +28,7 @@ Do your agents respond in seconds, not minutes? If every turn feels sluggish, co - [ ] Reasoning mode is OFF on the default model, ON only for orchestration. *→ [Part 6](./README.md#part-6-models-what-to-actually-use)* - [ ] Compaction runs on a cheap non-reasoning model (e.g. Cerebras `gpt-oss-120b`), not on Gemini Flash or an Opus/GPT key. *→ [Part 15](./part15-infrastructure-hardening.md)* - [ ] Cron output is isolated (`memory/cron/` or suppressed) so bulk scheduled runs don't flood session memory. *→ [Part 3](./README.md#part-3-cron-session-bloat-the-hidden-killer)* -- [ ] For small local models (≤14B), `agents.defaults.experimental.localModelLean: true` is set. *→ [Part 6](./README.md#part-6-models-what-to-actually-use)* +- [ ] For small local worker agents (≤14B), `agents.list[].experimental.localModelLean: true` is set only on those workers. *→ [Part 6](./README.md#part-6-models-what-to-actually-use)* ## Pillar 2 — Memory (20 points) @@ -64,13 +64,13 @@ Does the frontier model plan while cheap workers execute, or is your orchestrato If a compromised skill ships tomorrow, how much of your system does it reach? -- [ ] Task Brain is live (`openclaw tasks list` returns output). *→ [Part 24](./part24-task-brain-control-plane.md)* -- [ ] Approval policy uses **semantic categories** (`read-only.*`, `execution.*`, `write.*`, `control-plane.*`), not raw tool names. *→ [Part 24](./part24-task-brain-control-plane.md)* +- [ ] Task Brain is live (`openclaw tasks list` and `openclaw tasks maintenance --json` return useful output). *→ [Part 24](./part24-task-brain-control-plane.md)* +- [ ] Approval policy uses **semantic categories** (`read-only.*`, `execution.*`, `write.*`, `control-plane.*`), not raw tool names or skill-shell preludes. *→ [Part 24](./part24-task-brain-control-plane.md)* - [ ] `control-plane.*` is set to `deny` for every non-admin agent. *→ [Part 24](./part24-task-brain-control-plane.md)* -- [ ] `write.fs.outside-workspace` is `deny` by default, and `tools.toolsBySender` strips mutation/runtime tools from public senders. *→ [Part 24](./part24-task-brain-control-plane.md)* +- [ ] `write.fs.outside-workspace` is `deny` by default, and `tools.toolsBySender` strips mutation/runtime/Codex/MCP tools from public senders. *→ [Part 24](./part24-task-brain-control-plane.md)* - [ ] `skills.autoUpdate` is **OFF**. *→ [Part 23](./part23-clawhub-skills-marketplace.md)* -- [ ] Every installed ClawHub skill is pinned to a commit or tag, not a branch. *→ [Part 23](./part23-clawhub-skills-marketplace.md)* -- [ ] You've read the source of every ClawHub skill you have installed. *→ [Part 23](./part23-clawhub-skills-marketplace.md)* +- [ ] Every installed ClawHub skill/plugin is pinned to a commit or tag, not a branch, and typed tool plugins pass `openclaw plugins validate`. *→ [Part 23](./part23-clawhub-skills-marketplace.md)* +- [ ] You've read the source/manifest of every ClawHub skill or plugin you have installed, including embedding/source-provider contracts. *→ [Part 23](./part23-clawhub-skills-marketplace.md)* - [ ] Credentials live in environment variables or OS keychain, not in `openclaw.json`, `AGENTS.md`, or `memory/`. *→ [Part 15](./part15-infrastructure-hardening.md)* - [ ] Approval UI shows redacted secrets (`sk-***`) — you upgraded to 2026.4.15+. *→ [Part 15](./part15-infrastructure-hardening.md)* - [ ] Canvas **Model Auth status card** shows all providers green; you've tested auth hot-reload and Codex OAuth repair if used. *→ [Part 15](./part15-infrastructure-hardening.md)* @@ -82,13 +82,13 @@ When something breaks at 3am, can you answer "what ran, with what permissions, a - [ ] Every ACP call, cron job, and sub-agent spawn shows up in `openclaw tasks list` / `openclaw tasks flow list` (i.e. nothing runs outside Task Brain). *→ [Part 24](./part24-task-brain-control-plane.md)* - [ ] Gateway startup script has stale-process cleanup so a zombie doesn't block port 18789. *→ [Part 15](./part15-infrastructure-hardening.md)* - [ ] Compaction `reserveTokens` is capped to the model's context window (auto in 2026.4.15+; verify anyway). *→ [Part 15](./part15-infrastructure-hardening.md)* -- [ ] You run `openclaw doctor` after every upgrade and commit the output. *→ [Part 26](./part26-migration-guide.md)* -- [ ] LangFuse / OpenTelemetry / equivalent LLM tracing is enabled for at least one agent. *→ [Part 20](./part20-observability-and-services.md)* +- [ ] You run `openclaw doctor` and `openclaw policy check` after every upgrade/shared-channel change and archive the output. *→ [Part 26](./part26-migration-guide.md)* +- [ ] Native diagnostics plus LangFuse / OpenTelemetry / equivalent LLM tracing are enabled for at least one agent. *→ [Part 20](./part20-observability-and-services.md)* - [ ] Auto-capture hook is running; you've confirmed it produces inbox notes. *→ [Part 11](./part11-auto-capture-hook.md)* - [ ] Self-improving system is on: `.learnings/corrections.md`, `.learnings/ERRORS.md`, `.learnings/LEARNINGS.md` are being written to. *→ [Part 12](./part12-self-improving-system.md)* - [ ] Real-time knowledge sync (file watcher → vector index) is running. *→ [Part 21](./part21-realtime-knowledge-sync.md)* -- [ ] You have a one-command rollback plan from your current version to the previous one. *→ [Part 26](./part26-migration-guide.md)* -- [ ] You've tested rollback at least once, and active-run queue mode (`steer`/`followup`/`collect`/`interrupt`) is documented for shared channels. *→ [Part 26](./part26-migration-guide.md)* +- [ ] You have a one-command rollback plan from your current version to the previous one, including plugin/Meeting Notes/voice rollout. *→ [Part 26](./part26-migration-guide.md)* +- [ ] You've tested rollback at least once, active-run queue mode is documented for shared channels, and Meeting Notes retention is documented if enabled. *→ [Part 26](./part26-migration-guide.md)* --- diff --git a/benchmarks/METHODOLOGY.md b/benchmarks/METHODOLOGY.md index d7615ab..b308dec 100644 --- a/benchmarks/METHODOLOGY.md +++ b/benchmarks/METHODOLOGY.md @@ -10,9 +10,9 @@ We publish numbers from three deliberately different setups, so readers can see | Label | Machine | OpenClaw version | Purpose | |---|---|---|---| -| **Prod** | Windows 11, RTX 5090 (24 GB VRAM), 128 GB RAM, AMD Ryzen 9 7950X | 2026.5.12 stable | Real 14-agent production deployment (TerpHQ). "Best case with local embedding server." | -| **Baseline** | MacBook Pro M3 Max (36 GB), stock OpenClaw + Ollama | 2026.5.12 stable | Typical developer laptop. Most readers land near this. | -| **Minimal** | Linux VM, 8 GB RAM, no GPU, cloud embedding | 2026.5.12 stable | Low-end. Shows the floor of what the guide still buys you. | +| **Prod** | Windows 11, RTX 5090 (24 GB VRAM), 128 GB RAM, AMD Ryzen 9 7950X | 2026.5.22 stable | Real 14-agent production deployment (TerpHQ). "Best case with local embedding server." | +| **Baseline** | MacBook Pro M3 Max (36 GB), stock OpenClaw + Ollama | 2026.5.22 stable | Typical developer laptop. Most readers land near this. | +| **Minimal** | Linux VM, 8 GB RAM, no GPU, cloud embedding | 2026.5.22 stable | Low-end. Shows the floor of what the guide still buys you. | Readers' numbers will fall somewhere in the envelope defined by these three. If yours are wildly outside that envelope, open an issue — that's the kind of data we want. diff --git a/benchmarks/README.md b/benchmarks/README.md index 0accba4..c0bd93d 100644 --- a/benchmarks/README.md +++ b/benchmarks/README.md @@ -63,10 +63,19 @@ All benchmarks from a production system running on Windows with RTX 5090 (embedd | scout | 2 files, 24 chunks, 768-dim | 947 files, 24,738 chunks, 4096-dim | | godmode | 16 files, 180 chunks, 768-dim | 962 files, 24,860 chunks, 4096-dim | -## SWE-bench Coding Model Rankings (March 2026) +## Gateway Startup / Model Listing + +| Metric | May-14-era build | 2026.5.22+ target | +|--------|------------------|-------------------| +| `/models` listing with large provider catalog | Can take seconds on cold path | Hot path should be effectively immediate after startup metadata caching | +| Gateway startup idle work | Plugin/channel/provider metadata loaded eagerly | Startup-idle plugin work, ACPX runtime, metadata snapshots, and auth-state maps are cached/lazy-loaded | +| Operator action | N/A | Benchmark `openclaw models list` and startup after every plugin/provider expansion | + + +## SWE-bench Coding Model Rankings (May 2026) | Rank | Model | Score | |------|-------|-------| -| #1 | Claude Opus 4.6 | 1549 | -| #2 | Claude Opus 4.6 (thinking) | 1545 | +| #1 | Claude Opus 4.7 | 1549 | +| #2 | Claude Opus 4.7 (thinking) | 1545 | | #3 | Claude Sonnet 4.6 | 1524 | | #6 | GPT-5.4 | 1457 | \ No newline at end of file diff --git a/benchmarks/harness/README.md b/benchmarks/harness/README.md index 1e233f7..60074d7 100644 --- a/benchmarks/harness/README.md +++ b/benchmarks/harness/README.md @@ -29,7 +29,7 @@ Each invocation writes to `benchmarks/runs/_scratch/$(date +%Y%m%dT%H%M%S)/` so ## Environment assumptions -- OpenClaw 2026.5.12 stable (or newer) running locally. `openclaw doctor` returns clean. +- OpenClaw 2026.5.22 stable (or newer) running locally. `openclaw doctor` returns clean. - The reference config at [`templates/openclaw.example.json`](../../templates/openclaw.example.json) is in `~/.openclaw/openclaw.json` (or the harness will refuse to run). - Local Ollama at `http://localhost:11434` with `qwen3-embedding:0.6b` pulled. diff --git a/benchmarks/runs/TEMPLATE.md b/benchmarks/runs/TEMPLATE.md index e1c42db..da36e04 100644 --- a/benchmarks/runs/TEMPLATE.md +++ b/benchmarks/runs/TEMPLATE.md @@ -5,7 +5,7 @@ - **Date:** 2026-MM-DD - **Author:** @your-handle -- **OpenClaw version:** 2026.5.12 stable (or whatever you're on — be exact) +- **OpenClaw version:** 2026.5.22 stable (or whatever you're on — be exact) - **Scorecard score:** XX / 100 — link to your scorecard snapshot if public - **Outcome:** `improved` / `no-improvement` / `regressed` / `partial` diff --git a/mkdocs.yml b/mkdocs.yml index b6bd655..85bc362 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.12 stable and 2026.5.14 beta. +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_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: - - May 2026 field guide: part33-late-april-2026-field-guide.md + - Late-May 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/part10-state-of-the-art-embeddings.md b/part10-state-of-the-art-embeddings.md index e52c365..5f27d68 100644 --- a/part10-state-of-the-art-embeddings.md +++ b/part10-state-of-the-art-embeddings.md @@ -44,6 +44,13 @@ OpenClaw 2026.4.15 added a `copilot` memory-search provider. If your org already **Gotcha:** Copilot embeddings share rate limits with Copilot chat completions. If you also use Copilot as an agent model, heavy memory-search traffic can starve chat — watch the new Model Auth card in Control UI for rate-limit pressure and keep a local fallback configured. + +### Plugin embedding providers (OpenClaw 2026.5.22+) + +2026.5.22 adds a generic embedding-provider plugin contract (`contracts.embeddingProviders` + `api.registerEmbeddingProvider(...)`). That means embeddings are no longer only a memory-core internal or one-off provider key. + +Use it when you are packaging a real provider plugin or routing embeddings through an OpenAI-compatible service. For most users, the operational answer is unchanged: keep the hot memory-search path local on Ollama/Qwen and use cloud/plugin embeddings only when corporate policy or shared infrastructure requires it. + ### Current memory-search changes OpenClaw 2026.4.24+ exposes raw `vectorScore` and `textScore` on hybrid memory search results, alongside the combined `score`. Use those fields when a result feels "wrong": diff --git a/part15-infrastructure-hardening.md b/part15-infrastructure-hardening.md index fac9d67..c4193a7 100644 --- a/part15-infrastructure-hardening.md +++ b/part15-infrastructure-hardening.md @@ -55,6 +55,26 @@ If you pointed `compaction.model` at a small local model (a 14B Qwen with a 16K- Current builds also add transcript-byte guards (`maxActiveTranscriptBytes`) so a huge active transcript cannot keep feeding compaction forever. Set it explicitly on busy agents; tune upward only after reviewing real transcript sizes. +### Late-May Session Survival Pattern + +Community operators running large multi-agent fleets found that compaction config is only one layer. The current production pattern is: + +1. Set `maxActiveTranscriptBytes` before huge JSONL transcripts become normal. +2. Enable memory flush / capture so useful state survives `/new` and session rotation. +3. Separate heartbeat and cron output from human chat memory. +4. Prune old session files on a schedule instead of letting `agents/*/sessions` grow forever. +5. Audit `*.trajectory.jsonl` or equivalent usage traces to find real token spenders, not guessed ones. + +2026.5.20 also adds a default 30-second timeout to `before_compaction` and `after_compaction` hooks, so a hung hook no longer blocks compaction completion. Still keep hook handlers idempotent and fast. + +--- + +## Audit Suppressions Are Not A Trash Can + +2026.5.18 includes `security.audit.suppressions` for findings you intentionally accept. Use it for reviewed false positives or temporary exceptions with owners and expiry dates; do not use it to silence unknown warnings. + +Minimum rule: every suppression needs a reason, owner, and review date in the same PR that adds it. If `openclaw doctor` warns about plaintext provider keys or sensitive headers, fix the config instead of suppressing it. + --- ## The Gemini Flash Trap @@ -422,6 +442,9 @@ For sandbox isolation stronger than worktrees can provide (agent should not see - [ ] Embedding server on dedicated GPU (not shared with gaming/inference) - [ ] Embedding model quantized to INT8 if VRAM-constrained - [ ] No Gemini Flash in any infrastructure role +- [ ] `before_compaction` / `after_compaction` hooks complete quickly and tolerate the 30s timeout +- [ ] `security.audit.suppressions` entries have owners, reasons, and review dates +- [ ] Session pruning / rotation is configured for long-running channel agents - [ ] `.gitignore` in `.openclaw/` blocking secrets, sqlite, sessions - [ ] No credentials written in memory/session files (rule in AGENTS.md) - [ ] Existing git history scanned for leaked secrets diff --git a/part20-observability-and-services.md b/part20-observability-and-services.md index d86fbb5..cbe54f5 100644 --- a/part20-observability-and-services.md +++ b/part20-observability-and-services.md @@ -15,6 +15,20 @@ Running multiple agents without observability is flying blind. You don't know: - Where latency bottlenecks are - Whether your search is returning relevant results + +## OpenClaw Native Diagnostics (Late May 2026) + +Recent OpenClaw builds added useful operator telemetry before you reach for an external dashboard: + +- Sanitized `secrets.prepare` timeline spans show Gateway secret-startup latency without exposing provider names, secret ids, or values. +- Bounded skill usage metrics/spans include tool source and owner labels across core, plugin, MCP, and channel tools without leaking raw paths or session ids. +- QA-Lab smoke aliases now prove trace, metric, and log export, including Prometheus. +- `openclaw tasks maintenance --json` reports why stale-running tasks were retained or marked for reconciliation. + +Use native diagnostics first for "why is startup slow / which tool surface is noisy / why is this task wedged?" Then export to LangFuse/OTel for long-window trend analysis. + +--- + ## LangFuse — Agent Tracing [LangFuse](https://langfuse.com) is open-source LLM observability. Self-host it in Docker for free. diff --git a/part23-clawhub-skills-marketplace.md b/part23-clawhub-skills-marketplace.md index 971c926..2f34a8d 100644 --- a/part23-clawhub-skills-marketplace.md +++ b/part23-clawhub-skills-marketplace.md @@ -26,6 +26,8 @@ Three things changed when ClawHub launched: 3. **Scale.** 13,000+ skills published in the first ~30 days. That's community velocity. It's also impossible to curate. > **2026.3.31-beta.1 hardening:** Plugin installs now **fail-closed** by default if the built-in security scan flags dangerous code. Forcing an install requires the deliberately awkward `--dangerously-force-unsafe-install` flag. Combine this with an approval policy that denies `control-plane.skills` (see [Part 24](./part24-task-brain-control-plane.md)) and you cover the structural half of the ClawHavoc problem. +> +> **2026.5.20 hardening:** the old `cat SKILL.md && printf ... && ` approval compatibility path is gone. Skill files must be read with the read tool, and only the real skill executable is auto-allowed. ## The Catch: ClawHavoc (1,184 Malicious Skills in Month One) @@ -54,6 +56,19 @@ Red flags: - runtime dependency repair that pulls packages from unexpected registries - channel configs for surfaces the skill never mentioned + +### Tool plugins are not "just skills" + +2026.5.18 added typed simple tool-plugin authoring via `defineToolPlugin` plus: + +```bash +openclaw plugins init +openclaw plugins validate +openclaw plugins build +``` + +Treat these like code packages, not prompt snippets. Validate manifests in CI, review generated metadata, and pin the source/ref before installing in production. If all you need is instructions, ship a skill; if you expose new tools, use the plugin CLI and Task Brain policy review. + ### 1. Auto-update: OFF by default ```json5 diff --git a/part24-task-brain-control-plane.md b/part24-task-brain-control-plane.md index f74a513..8bda8ce 100644 --- a/part24-task-brain-control-plane.md +++ b/part24-task-brain-control-plane.md @@ -152,6 +152,22 @@ Rules: - Deny runtime and filesystem mutation for wildcard/public senders. - Per-agent `agents.list[].tools.toolsBySender` can override the global sender match when needed. +### Late-May sender/tool caveat + +2026.5.22 removed the old sender-owner tool gating path. Do not assume a legacy owner flag protects channel users. Test the real sender identity from each adapter and verify the restricted schema actually strips runtime, filesystem, Codex, MCP, dynamic, and app-default tools for wildcard/public senders. + + +## Policy Plugin Checks + +Task Brain decides whether an action is allowed. The 2026.5.20 Policy plugin checks whether shared channel policy is configured sanely before actions are requested. Run it before opening Discord/Telegram/Slack/iMessage surfaces to more users: + +```bash +openclaw policy check +openclaw doctor +``` + +Look for channel conformance findings, accepted-attestation drift, and repair suggestions. Treat opt-in repair like a config migration: review the diff, back up config, then apply deliberately. + ## Agent-Initiated Denies (new in v2026.3.31-beta.1) Task Brain added the inverse of the approval flow: an agent can now **refuse to do something you asked it to do** and have that refusal be a first-class event. @@ -180,6 +196,17 @@ Another 2026.3.31-beta.1 hardening: plugins now default to **fail-closed**. Pre- This trades a bit of friction for "we don't have unintended silent bypasses." It's the right trade for a production setup. +Late-May hardening removed the old `cat SKILL.md && printf ... && ` allowlist compatibility path. Load skill files with the read tool and approve the actual executable, not a shell prelude that happens to mention the skill file. + + +## Sub-Agent Bootstrap Narrowing + +2026.5.22 narrows default delegated worker context to `AGENTS.md` and `TOOLS.md`. Persona, identity, user, memory, heartbeat, and setup files are no longer injected into sub-agent sessions by default. + +That is good for cost and privacy, but it changes orchestration prompts. If a worker needs customer context, project memory, or a persona constraint, pass a bounded summary in the spawn task instead of assuming inherited bootstrap. Treat sub-agent prompts as self-contained work orders. + +`openclaw tasks maintenance --json` also now explains stale-running maintenance decisions, including backing-session, cron, CLI, and wedged-subagent state. Put it in weekly ops review. + ## Reading Your Task Ledger A weekly habit worth building: @@ -195,7 +222,7 @@ openclaw tasks show openclaw tasks cancel ``` -For longer-horizon auditing (7-day window, category filters, denied/approved breakdowns), subcommand flags have moved between betas — run `openclaw tasks --help` against your installed version for the exact set. Current docs expose `tasks list/show/cancel/audit/maintenance` and `tasks flow list/show/cancel`. Category filtering and denied-flow rollups are primarily visible through the **Control UI** task/flow panels, not via CLI flags. +For longer-horizon auditing (7-day window, category filters, denied/approved breakdowns), subcommand flags have moved between betas — run `openclaw tasks --help` against your installed version for the exact set. Current docs expose `tasks list/show/cancel/audit/maintenance` and `tasks flow list/show/cancel`. Run `openclaw tasks maintenance --json` when a task looks stale; recent builds include retained/reconcile reasons for backing sessions, cron, CLI, and wedged sub-agents. Category filtering and denied-flow rollups are primarily visible through the **Control UI** task/flow panels, not via CLI flags. You'll find: diff --git a/part25-architecture-overview.md b/part25-architecture-overview.md index 8fdb735..9ea0fe4 100644 --- a/part25-architecture-overview.md +++ b/part25-architecture-overview.md @@ -147,8 +147,12 @@ Short form, so you know what era a given piece of advice applies to: | **v2026.4.24 beta** | 2026-04-24 | Google Meet recovery, realtime voice consults, DeepSeek V4, browser coordinate clicks, 60s browser budgets, per-profile headless overrides, manifest-backed model rows, `/models add` deprecation | The provider-catalog/browser automation line begins here. | | **v2026.4.27 stable** | 2026-04-27 | DeepInfra provider, Codex Computer Use setup/status/install, manifest-first plugin catalogs, Docker GPU passthrough, outbound proxy routing, non-image chat attachments | Late-April stable baseline; required before the May migration makes sense. | | **v2026.4.29-beta.1** | 2026-04-29 | Active-run steering, visible-reply enforcement, people-aware wiki metadata, Active Memory chat filters, partial recall on timeout, NVIDIA provider, Bedrock Opus 4.7 parity, OpenGrep scanning | Memory + messaging beta that shaped the May defaults. | -| **v2026.5.12 stable** | 2026-05-14 | Leaner externalized provider/channel installs, Telegram resilience, Codex app-server/runtime fallback fixes, pnpm 11 plugin install support, ACP fallbacks, Control UI/WebChat/TUI delivery polish, broad gateway/browser/Slack/sandbox/transcript hardening | **This guide's current stable baseline.** | -| **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 | Latest beta; test on a copied profile before exposing to users. | +| **v2026.5.12 stable** | 2026-05-14 | Leaner externalized provider/channel installs, Telegram resilience, Codex app-server/runtime fallback fixes, pnpm 11 plugin install support, ACP fallbacks, Control UI/WebChat/TUI delivery polish, broad gateway/browser/Slack/sandbox/transcript hardening | Former May baseline. | +| **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. | 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 2e7a6db..4a3328b 100644 --- a/part26-migration-guide.md +++ b/part26-migration-guide.md @@ -1,21 +1,21 @@ # Part 26: Migration Guide -> Updated in the May 2026 refresh. Opinionated, battle-tested upgrade paths from older OpenClaw versions to current. If something in this guide doesn't apply to your version yet, start here. +> 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. -> **Read this if** you're on anything older than 2026.5.12, or planning an upgrade. +> **Read this if** you're on anything older than 2026.5.22, 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.12 | -| **v4.0.x** | v2026.3.31-beta.1 (Task Brain) | Reach 2026.4.27 through Paths 2–6 | 2026.5.12 | -| **v2026.3.x** | Apply Task Brain approval policy | Reach 2026.4.27 through Paths 3–6 | 2026.5.12 | -| **v2026.4.x pre-4.15** | Skip straight to 2026.4.15 | Reach 2026.4.27 through Paths 5–6 | 2026.5.12 | -| **v2026.4.15** | Remove subscription-era model assumptions | Apply provider-catalog changes | 2026.5.12 | -| **v2026.4.27** | Apply memory/messaging beta changes | Upgrade to 2026.5.12 | Optional 2026.5.14-beta.1 | -| **v2026.4.29-beta.1** | Migrate Codex/queue assumptions | Upgrade to 2026.5.12 | Optional 2026.5.14-beta.1 | +| **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 | 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. @@ -117,7 +117,7 @@ Small jump. This is the version the guide is currently tested on. - `memory_get` restricted to MEMORY.md + DREAMS.md only (path-traversal hardening against the qmd backend). - Memory-lancedb can persist to S3-compatible cloud storage. - GitHub Copilot embedding provider. -- `agents.defaults.experimental.localModelLean: true` drops heavyweight default tools for weak local models. +- `agents.defaults.experimental.localModelLean: true` drops heavyweight default tools for weak local models; 2026.5.20 also supports per-agent `agents.list[].experimental.localModelLean`. - New Model Auth card in Canvas UI shows OAuth token health + rate-limit pressure. **Steps:** @@ -183,7 +183,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 and then continue to 2026.5.12 stable. +Former beta jump. If you're upgrading today, treat this as the conceptual migration step for memory/messaging behavior and then continue to 2026.5.22 stable. **What changes (the ones you should act on immediately):** @@ -207,7 +207,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 current stable baseline for this guide. Do this before experimenting with 2026.5.14-beta.1. +This is the former May stable baseline. Do this as the compatibility checkpoint, then continue to Path 10 before experimenting with 2026.5.24-beta.1. **What changes (the ones you should act on immediately):** @@ -229,7 +229,7 @@ This is the current stable baseline for this guide. Do this before experimenting ## Path 9: v2026.5.12 stable → v2026.5.14-beta.1 -Beta jump. Do this in a separate profile unless you specifically need queue steering defaults, Telnyx voice, Codex migration repair, per-sender tool tiers, or embedded Pi retry controls. +Former beta jump. Today, treat this as the queue/Codex/per-sender migration checkpoint, then continue to Path 10 for the current stable baseline. **What changes (the ones you should act on immediately):** @@ -249,7 +249,56 @@ Beta jump. Do this in a separate profile unless you specifically need queue stee 3. Add `agents.defaults.runRetries` for embedded/remote Pi runners that can fail transiently. 4. If you had `codex-cli/*` refs, replace them with canonical `openai/gpt-*` model refs and verify with a tiny Codex task. 5. If you try Telnyx voice, do it on a test number first and keep transcript/media retention explicit. -6. Roll back to 2026.5.12 if steering semantics or channel progress reactions surprise users. +6. Roll back to 2026.5.12 if steering semantics or channel progress reactions surprise users, then continue through Path 10 when ready. + + +## 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. + +**What changes (the ones you should act on immediately):** + +- Minimum Node.js 22 line is now **22.19**. Upgrade Node before blaming OpenClaw startup. +- The old skill exec allowlist compatibility path is gone. Skill files must be loaded with the read tool; only the real executable is auto-allowed. +- Sub-agent default bootstrap narrows to `AGENTS.md` and `TOOLS.md`; persona, identity, user, memory, heartbeat, and setup files are not delegated by default. +- The bundled Policy plugin adds `openclaw policy check`, channel conformance attestations, doctor lint findings, and opt-in repair. +- `agents.list[].experimental.localModelLean` lets one small/local worker run lean without forcing every agent into lean mode. +- `OPENCLAW_IMAGE_APT_PACKAGES` replaces `OPENCLAW_DOCKER_APT_PACKAGES` as the runtime-neutral Docker/Podman image build arg. +- Meeting Notes is a source-only external plugin with Discord voice as the first live source and `openclaw meeting-notes` CLI access. +- xAI device-code OAuth works on remote/headless hosts; OpenRouter honors provider-level `params.provider` routing. +- Gateway/plugin/model/channel metadata hot paths are cached aggressively. Startup is faster, but unused plugins are still attack surface. +- Generic `contracts.embeddingProviders` and `api.registerEmbeddingProvider(...)` make embeddings a plugin capability. + +**Steps:** + +1. Upgrade Node to 22.19+ and then install OpenClaw 2026.5.22. +2. Run `openclaw doctor`, `openclaw policy check`, and `openclaw tasks maintenance --json` before inviting channel users back. +3. Audit every skill that relied on shelling through `cat SKILL.md && printf ...`; convert it to read the skill file explicitly. +4. Review sub-agent prompts. If a worker needed SOUL/USER/MEMORY context, pass the needed summary explicitly instead of assuming inherited bootstrap. +5. Move Docker/Podman custom package builds to `OPENCLAW_IMAGE_APT_PACKAGES`; keep the old var only for pinned legacy images. +6. Add per-agent `experimental.localModelLean` only to small local workers; leave frontier orchestrators full-context. +7. If you enable Meeting Notes, define meeting retention/redaction first and start with a single Discord voice source. +8. If you use OpenRouter/xAI, re-check auth/routing with a tiny run before production traffic. + +## Path 11: v2026.5.22 stable → v2026.5.24-beta.1 + +Beta jump. Use a copied profile unless you specifically need iMessage approval reactions, realtime voice run steering, adaptive image compression, or named Codex OAuth profiles. + +**What changes:** + +- `agents.defaults.imageQuality` controls adaptive image compression: `token-efficient`, `balanced`, or `high-detail`. +- WebUI and Discord voice callers can ask status, cancel, steer, or queue follow-up work during active consults. +- Discord voice adds wake-name gating with agent-name defaults. +- iMessage thumbs mirror WhatsApp-style approvals: thumbs-up for `allow-once`, thumbs-down for deny. +- Named Codex OAuth profile storage makes multi-auth OpenAI/Codex hosts less brittle. + +**Steps:** + +1. Set `agents.defaults.imageQuality` deliberately; use `balanced` until you know a worker needs high-detail images. +2. Test a voice consult's status/cancel/steer path before exposing it to normal users. +3. Confirm iMessage/WhatsApp approval reactions are limited to trusted approvers, not every group participant. +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. ## Rollback Plan (Every Path) @@ -260,7 +309,7 @@ If something goes sideways: openclaw gateway stop # Install previous version (example: pin via your package manager) -npm install -g openclaw@2026.5.12 # adjust for your install method / previous pin +npm install -g openclaw@2026.5.22 # adjust for your install method / previous pin # Restore config cp ~/.openclaw/openclaw.json.pre-upgrade.YYYYMMDD ~/.openclaw/openclaw.json diff --git a/part27-gotchas-and-faq.md b/part27-gotchas-and-faq.md index f93ce9b..1b9ac93 100644 --- a/part27-gotchas-and-faq.md +++ b/part27-gotchas-and-faq.md @@ -1,6 +1,6 @@ # Part 27: Common Gotchas & FAQ -> Updated in the May 2026 refresh. Every "I wasted a day on this" distilled into one page. Skim this before you debug; half your questions are answered here. +> Updated in the late-May 2026 refresh. Every "I wasted a day on this" distilled into one page. Skim this before you debug; half your questions are answered here. > **Read this if** something is broken, confusing, or behaving weirdly and you want to check the common-causes list before deep-diving. > **Skip if** nothing is broken — come back when it is. @@ -14,10 +14,12 @@ | Claude worked last month and now costs money / fails auth | Anthropic's April 4 cutoff ended the old subscription-backed path for many OpenClaw users. Move to explicit API/Bedrock/provider routing, set budget caps, add non-Anthropic fallbacks. See [Part 33](./part33-late-april-2026-field-guide.md). | | `/models add` no longer works | It was deprecated in 2026.4.24 after provider-catalog work. Use `/models` or `openclaw models list` to inspect, then edit config/catalogs deliberately. | | Active Memory recalls the wrong group chat | Broad recall enabled without chat filters. Add `allowedChatIds` / `deniedChatIds`; deny public channels by default. | -| Agent replies invisibly or in the wrong channel during long runs | Shared channel not enforcing the visible reply path. Enable `messages.visibleReplies`; set `messages.queue.mode` intentionally (`steer` is the 2026.5.14-beta.1 default). | +| Agent replies invisibly or in the wrong channel during long runs | Shared channel not enforcing the visible reply path. Enable `messages.visibleReplies`; set `messages.queue.mode` intentionally (`steer` is the current May-line default). | | Follow-up messages now alter the current run instead of waiting | You are on `/queue steer`. Switch to `/queue followup` for old one-at-a-time behavior or `/queue collect` for batched later turns. | | Codex model refs stopped resolving | Legacy `codex-cli/*` or durable `openai-codex/*` refs. Use canonical `openai/gpt-*` refs exposed by your Codex app-server provider catalog and run `openclaw doctor --fix` for OAuth repair. | -| Public channel users can trigger tools they should not see | Missing per-sender policy. Add `tools.toolsBySender` deny rules for `*`, guest IDs, and public channel senders. | +| Public channel users can trigger tools they should not see | Missing per-sender policy. Add `tools.toolsBySender` deny rules for `*`, guest IDs, and public channel senders, then run `openclaw policy check`. | +| Old skill command stopped being auto-approved | The `cat SKILL.md && printf ...` exec allowlist compatibility path is gone. Read the skill file with the read tool and approve only the real executable. | +| Sub-agent no longer knows persona/user/memory context | 2026.5.22 narrows worker bootstrap to `AGENTS.md` + `TOOLS.md`. Include needed context in the spawn task explicitly. | | Bedrock/Slack/WhatsApp disappeared after a lean install | May builds externalize more provider/channel cones. Install the provider/plugin you actually use and audit its manifest. | | Browser automation clicks miss dynamic UI | Selector-only automation on overlays/canvas/shadow DOM. Use coordinate clicks sparingly and document viewport assumptions. | @@ -51,6 +53,8 @@ | Orchestrator doing work it should delegate | Add the sub-agent rules to AGENTS.md. See [Part 5](./README.md#part-5-orchestration-stop-doing-everything-yourself). | | Compaction model is Gemini Flash (rate-limited) | Switch compaction to Cerebras `gpt-oss-120b`. See [Part 15](./part15-infrastructure-hardening.md). | | Local model loaded but not used | `ollama ps` + `ollama stop ` for ones you're not using. | +| One small worker needs lean mode but the orchestrator gets worse | Use `agents.list[].experimental.localModelLean` on that worker only; do not force global lean mode. | +| Gateway starts faster but tokens/cost still explode | Startup metadata caching does not fix session bloat. Audit trajectory/session JSONL, compaction, cron output, and memory flush. | ### "Compaction crashes in a loop" diff --git a/part28-glossary-and-terminology.md b/part28-glossary-and-terminology.md index 675b9d9..a7e472a 100644 --- a/part28-glossary-and-terminology.md +++ b/part28-glossary-and-terminology.md @@ -173,7 +173,7 @@ Graph-RAG layer that turns your vault into a **knowledge graph of entities + rel ## localModelLean -Flag at `agents.defaults.experimental.localModelLean: true` (added in **2026.4.15**) that drops heavyweight default tools (browser, cron, message) from weaker local models. Lets small quantized models actually function instead of burning tokens parsing tool definitions they'll never use. +Flag at `agents.defaults.experimental.localModelLean: true` (added in **2026.4.15**) or `agents.list[].experimental.localModelLean: true` (per-agent in **2026.5.20**) that drops heavyweight default tools (browser, cron, message) from weaker local models. Lets small quantized workers function instead of burning tokens parsing tool definitions they will never use. - **Covered in:** [Part 1 — Speed](./README.md#part-1-speed-stop-being-slow), [Part 6 — Models](./README.md#part-6-models-what-to-actually-use). diff --git a/part29-hook-catalog.md b/part29-hook-catalog.md index b291032..7eb3419 100644 --- a/part29-hook-catalog.md +++ b/part29-hook-catalog.md @@ -21,7 +21,7 @@ The practical rule from Amit Kothari's April 2026 post on hook debugging: *"If a ## Lifecycle Events & Exit Codes -Modern agent harnesses (OpenClaw, Claude Code, Cursor) converged on similar lifecycle grammars, but the names are not identical. The Claude-style event names below are useful mental models; OpenClaw-native hook registration uses lower-case event names such as `command:new`, `command`, `command:stop`, `session:compact:before`, `session:compact:after`, `agent:bootstrap`, `message:received`, `message:preprocessed`, `message:sent`, and `gateway:startup`. +Modern agent harnesses (OpenClaw, Claude Code, Cursor) converged on similar lifecycle grammars, but the names are not identical. The Claude-style event names below are useful mental models; OpenClaw-native hook registration uses lower-case event names such as `command:new`, `command`, `command:stop`, `session:compact:before`, `session:compact:after`, `agent:bootstrap`, `message:received`, `message:preprocessed`, `message:sent`, and `gateway:startup`. 2026.5.20+ gives `before_compaction`/`after_compaction`-style plugin handlers a default 30s timeout, so handlers must finish quickly and tolerate cancellation. | Claude-style event | OpenClaw-native event(s) | Typical use | |--------------------|--------------------------|-------------| diff --git a/part33-late-april-2026-field-guide.md b/part33-late-april-2026-field-guide.md index ad8c5ed..9c4ebf8 100644 --- a/part33-late-april-2026-field-guide.md +++ b/part33-late-april-2026-field-guide.md @@ -1,9 +1,9 @@ -# Part 33: May 2026 Field Guide +# Part 33: Late-May 2026 Field Guide -> **Read this if** you last tuned OpenClaw around 2026.4.15/2026.4.29 and want the current tricks without re-reading every release note. +> **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. > **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-April and May releases changed the operator playbook in six places: providers, memory, messaging, browser/Codex automation, local runtime management, and plugin/security boundaries. This page is the catch-up map. +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. ## Version Map @@ -14,12 +14,15 @@ OpenClaw's late-April and May releases changed the operator playbook in six plac | **2026.4.24-beta.1** | Google Meet, realtime voice consults, DeepSeek V4, browser coordinate clicks, 60s browser action budgets, per-profile headless overrides, manifest-backed model rows, `/models add` deprecation. | | **2026.4.27 stable** | DeepInfra provider, Codex Computer Use setup/status/install commands, manifest-first plugin catalogs, Docker GPU passthrough, outbound proxy routing, non-image chat attachments. | | **2026.4.29-beta.1** | Active-run steering, visible-reply enforcement, people-aware wiki metadata, Active Memory chat filters, partial recall on timeout, NVIDIA provider, Bedrock Opus 4.7 parity, OpenGrep scanning. | -| **2026.5.4–2026.5.7** | Early May hardening: provider manifest/runtime repairs, safer channel/session routing, pnpm 11 plugin support groundwork, and continued Codex app-server fixes. | -| **2026.5.9–2026.5.10 beta** | Externalized plugin/provider cones begin landing; Codex app-server migration bugs and Control UI session visibility improve. | -| **2026.5.12 stable** | Current stable baseline: leaner installs, Telegram resilience, safer plugin installs/updates, Codex app-server/runtime fallback improvements, Control UI/WebChat/TUI delivery fixes, ACP fallbacks, and gateway/browser/Slack/sandbox/transcript hardening. | -| **2026.5.14-beta.1** | Latest beta sweep: `/queue steer` default, `agents.defaults.runRetries`, Telnyx realtime calls, Codex app-server command fixes, bundled `codex-cli` backend removal/repair, WhatsApp status reactions, per-sender tool tiers, and nested sub-agent sessions in Control UI. | +| **2026.5.12 stable** | Former May baseline: leaner installs, Telegram resilience, safer plugin installs/updates, Codex app-server/runtime fallback improvements, Control UI/WebChat/TUI delivery fixes, ACP fallbacks, and gateway/browser/Slack/sandbox/transcript hardening. | +| **2026.5.14-beta.1** | Queue-steering beta: `/queue steer` default, `agents.defaults.runRetries`, Telnyx realtime calls, Codex app-server command fixes, bundled `codex-cli` backend removal/repair, WhatsApp status reactions, per-sender tool tiers, and nested sub-agent sessions in Control UI. | +| **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. | -If you want boring stability today, run **2026.5.12**. If you actively use mid-turn steering, Telnyx realtime voice, Codex migration repair, or per-sender tool tiers, test **2026.5.14-beta.1** on a copy of your profile first. +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. ## 1. Stop Assuming Claude Subscription Usage @@ -84,8 +87,33 @@ Why this matters: - Suppression rules prevent stale Codex/OpenAI-compatible rows from being selected when a runtime cannot actually serve them. - Plugin startup gets cheaper because catalogs can be read without loading provider runtimes. - Local model servers become explicit dependencies with health checks and idle shutdowns. +- OpenRouter can honor provider-level `params.provider` routing policy, with model/agent params overriding it. +- xAI/Grok can use device-code OAuth on remote/headless hosts instead of brittle localhost callback tunnels. -## 3. Use Active Memory Filters Before You Enable Broad Recall +Late-May provider rule: every provider route needs **auth shape + routing policy + budget cap**. A model ref alone is not production config. + +## 3. Gateway Startup Is Faster, But Audit What You Enabled + +2026.5.18-5.24 moved a lot of startup work off the hot path: + +- Channel catalogs and bundled-channel metadata are cached process-locally. +- Plugin metadata snapshots are reused by startup, config, model, channel, setup, and secret readers. +- Startup-idle plugin work, Gateway method handlers, and the embedded ACPX runtime lazy-load later. +- Plugin SDK public-surface alias maps are cached instead of walking the filesystem repeatedly. +- Gateway watch CPU profiles rotate so benchmarks do not accumulate unbounded artifacts. + +Do not interpret faster startup as permission to enable everything. The SOTA setup is still: + +```text +openclaw plugins list +openclaw models list +openclaw channels list +openclaw doctor +``` + +Then remove plugins/channels/providers that are not used. Faster unused code is still unused attack surface. + +## 4. Use Active Memory Filters Before You Enable Broad Recall Current memory builds make recall much more useful in real messaging environments: @@ -106,7 +134,9 @@ Recommended policy: The people wiki is powerful and easy to misuse. If the agent says something about a person, ask for provenance. Prefer "source evidence says..." over unaudited biographical summaries. -## 4. Turn On Visible-Reply Enforcement For Shared Channels +Late-May session warning: long-running coding/ops agents can still accumulate huge JSONL transcripts and lose effective context when sessions are reset or compacted badly. Keep `compaction.maxActiveTranscriptBytes`, cron/session isolation, and explicit `/new` or rotation policy in your runbook. Treat "the gateway is faster now" and "my session memory is healthy" as separate checks. + +## 5. Turn On Visible-Reply Enforcement For Shared Channels 2026.4.29 adds `messages.visibleReplies`, with channel-specific overrides still available under `messages.groupChat.visibleReplies`. Use it when humans expect all visible output to go through the message tool instead of raw transcript text or partial side-channel replies. @@ -125,11 +155,12 @@ Good default: Pair it with active-run steering: -- Queue mode `steer` injects follow-ups at the next model boundary and is the default in 2026.5.14-beta.1. +- Queue mode `steer` injects follow-ups at the next model boundary and is the default in the current May line. - Use `/queue followup` for old "finish this run, then process the next message" behavior. - Use `/queue collect` when users tend to send several small corrections that should become one later turn. - Use `/queue interrupt` only when cancellation is safer than steering. - Spawned sub-agent events now expose `spawnedBy`, so clients can route child-session updates without extra lookups. +- For ambient Telegram/Discord rooms, use `messages.groupChat.ambientTurns: "room_event"` only when you want quiet room context; room events should speak visibly only through the message tool. This matters most in Slack, Telegram, Discord, Matrix, Teams, and other channels where a long-running agent can receive human corrections while it is still working. @@ -149,7 +180,25 @@ Config shape: } ``` -## 5. Browser Automation Is Less Fragile Now +## 6. Add Policy Checks Before Shared Channels + +2026.5.20 adds the bundled Policy plugin. Use it to make channel conformance visible instead of hoping config and docs match reality: + +```bash +openclaw policy check +openclaw doctor +``` + +What to check: + +- Channel allowlists match the people who can actually approve/run tools. +- Accepted attestations have not drifted. +- Doctor findings flag missing or unsafe channel policy. +- Opt-in repair is reviewed before it mutates config. + +This complements Task Brain. Task Brain decides whether a tool/action is allowed; Policy checks whether the channel surface is configured to request actions safely. + +## 7. Browser Automation Is Less Fragile Now Current browser changes are practical: @@ -157,10 +206,12 @@ Current browser changes are practical: - `browser.actionTimeoutMs` defaults to a healthier 60s budget, so real browser waits stop failing at the client transport boundary. - `browser.profiles..headless` lets one profile run headless without forcing every browser profile headless. - Already-open Google Meet tabs can be recovered instead of duplicated. +- Browser snapshots now surface pending/recent modal dialogs and `openclaw browser dialog --dialog-id` can answer them. +- `openclaw browser evaluate --timeout-ms` lets long page functions extend evaluate/request budgets deliberately. Operator rule: use selectors when they are reliable; use coordinate clicks when the DOM is dynamic, canvas-based, or behind a shadow/overlay mess. Record the viewport assumption in the skill so future agents do not click blind. -## 6. Codex App-Server Is The Durable Path +## 8. Codex App-Server Is The Durable Path 2026.4.27 shipped Codex Computer Use setup/status/install commands: @@ -178,6 +229,10 @@ May 2026 changed the migration advice: - The bundled `codex-cli` backend is removed in 2026.5.14-beta.1; legacy `codex-cli/*` refs should repair to the app-server route. - Use `openclaw doctor --fix` when Codex OAuth/profile state is wedged. - Keep Memory Bridge/`CONTEXT.md` for Codex workers; app-server routing fixes runtime plumbing, not institutional memory. +- Scope user MCP servers to specific OpenClaw agent ids with `mcp.servers..codex.agents`; empty or invalid scopes should fail closed. +- Set Codex native tool approval defaults explicitly with `codex.defaultToolsApprovalMode` (`auto`, `prompt`, or `approve`) instead of inheriting surprising defaults. +- On restricted senders, verify deny-all policies also disable native code mode, built-in environments, user MCP projection, dynamic tools, and Codex app defaults. +- Use named OAuth profiles (`openclaw models auth login --profile-id ...`) when one host runs multiple Codex/OpenAI auth lanes. Use this for: @@ -187,7 +242,44 @@ Use this for: Keep using [Part 13 — Memory Bridge](./part13-memory-bridge.md) when Codex needs your vault context. -## 7. Plugin Manifests Are The New Audit Surface +## 9. Voice And Meeting Notes Are First-Class Inputs Now + +The late-May voice work is not just "talk to the bot": + +- Discord voice sessions can follow configured users into voice channels with allowed-channel checks and bounded reconciliation. +- Discord/OpenAI realtime follow-ups keep hearing turns while a consult is active. +- 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. + +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. + +## 10. Tune Media/Image Cost Deliberately + +2026.5.24-beta.1 adds adaptive model-aware image compression with: + +```json5 +{ + agents: { + defaults: { + imageQuality: "balanced" + } + } +} +``` + +Use: + +| Mode | Use when | +|------|----------| +| `token-efficient` | Screenshots, quick UI checks, cheap worker agents | +| `balanced` | Default for mixed browser/media work | +| `high-detail` | Visual debugging, charts, design review, OCR-heavy work | + +Also note the media stack stopped auto-probing Gemini CLI and treats Antigravity CLI as a lower-priority image/video fallback after configured provider APIs. Do not rely on hidden CLI probes as your media strategy. + +## 11. Plugin Manifests Are The New Audit Surface Recent plugin work moved metadata out of runtime code: @@ -198,12 +290,16 @@ Recent plugin work moved metadata out of runtime code: - `channelConfigs` - runtime-dependency repair metadata - descriptor-only setup via `setup.requiresRuntime: false` +- `contracts.embeddingProviders` +- SDK source-provider contracts such as Meeting Notes When auditing a provider/plugin now, read the manifest first. The manifest tells you what models it claims, what auth methods it needs, which aliases it introduces, and which runtime dependencies it will repair. Runtime code still matters, but the manifest is the fast first pass. May 2026 made this more important because more channel/provider cones are externalized. A lean core install is good; the tradeoff is that Bedrock, Slack, Anthropic Vertex, OpenShell sandbox, WhatsApp, and similar plugins now deserve first-class dependency review when you add them back. -## 8. Use `/context map` Before You Trim Blindly +Generic `contracts.embeddingProviders` and `api.registerEmbeddingProvider(...)` make embeddings a plugin capability, not only memory-core internals. Keep local Ollama/Qwen as the default, but expect OpenAI-compatible explicit embedding providers to become cleaner. + +## 12. Use `/context map` Before You Trim Blindly Context debugging moved from vibes to inspection: @@ -222,7 +318,7 @@ 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. -## 9. Security Notes Worth Acting On +## 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. - **OpenGrep scanning** lands in 2026.4.29-beta.1. Add it to first-party plugin development once the rulepack stabilizes. @@ -233,6 +329,10 @@ If there is no cached run report yet, run one normal turn first; do not trust es - **Structured SecretRefs** replace raw provider key text in more plugin manifests. If a plugin still wants literal keys in config, treat that as a smell. - **Schema stripping and requester-bound gateway approvals** are now part of the control-plane hardening path. Keep custom channel adapters honest about sender identity; never trust message text to declare who sent it. - **Windows sandbox hardening** blocks home-root mounts. If your local automation assumed `C:\Users\` was writable from sandboxed runs, narrow it to a workspace path. +- **Skill exec compatibility is gone.** Skill files must be loaded with the read tool; the old `cat SKILL.md && printf ...` allowlist path was removed. +- **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. Per-sender minimum: @@ -253,7 +353,7 @@ Keys are explicit sender identities from the channel adapter (`channel: Updated for **OpenClaw 2026.5.12 stable** and the **2026.5.14-beta.1** queue/Codex/provider changes. See [Part 26 — Migration Guide](../part26-migration-guide.md) if you're on an older version. +> 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. ## What's in this directory @@ -49,8 +49,8 @@ Full setup in [setup.sh](../setup.sh) / [setup.ps1](../setup.ps1) at the repo ro ## When this kit does *not* match what you should run - **Single-agent personal-dev setup:** you can skip the Task Brain approval block and pin one model. -- **Local-only setup on a 14B-or-smaller model:** flip `agents.defaults.experimental.localModelLean: true` in `openclaw.json`; use provider-level `localService` only if OpenClaw should own the model daemon lifecycle. +- **Local-only setup on a 14B-or-smaller model:** prefer `agents.list[].experimental.localModelLean: true` for that worker only; use provider-level `localService` only if OpenClaw should own the model daemon lifecycle. - **Latest provider-catalog setup:** use `/models` / `openclaw models list` to inspect manifest-backed provider rows, but do not rely on deprecated `/models add` for durable config. -- **Shared channels:** set `messages.queue.mode` intentionally and use `tools.toolsBySender` before exposing runtime/filesystem tools to public users. +- **Shared channels:** set `messages.queue.mode` intentionally, use `tools.toolsBySender`, and run `openclaw policy check` before exposing runtime/filesystem tools to public users. - **Team deployment with multi-user approvals:** override `taskBrain.approvals` per-agent — see [Part 24](../part24-task-brain-control-plane.md). - **Large vault (500+ files):** add LightRAG ([Part 18](../part18-lightrag-graph-rag.md)) and Repowise ([Part 19](../part19-repowise-codebase-intelligence.md)). diff --git a/templates/openclaw.example.json b/templates/openclaw.example.json index 01fe915..ae2476d 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.12 stable / 2026.5.14-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.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.", "agents": { "defaults": { @@ -15,6 +15,8 @@ "_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, + "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": { "model": "cerebras/gpt-oss-120b", "reserveTokens": 8000, @@ -37,7 +39,16 @@ "experimental": { "localModelLean": false } - } + }, + "list": [ + { + "id": "local-worker", + "experimental": { + "localModelLean": true + }, + "_comment": "2026.5.20+: prefer per-agent lean mode for small local workers instead of forcing the orchestrator lean globally." + } + ] }, "plugins": { @@ -74,6 +85,17 @@ "queryMode": "balanced", "_comment": "Enable per surface. Deny public/group channels until you have a retention policy." } + }, + "policy": { + "enabled": true, + "_comment": "2026.5.20+: run openclaw policy check before inviting shared-channel users." + }, + "meeting-notes": { + "enabled": false, + "config": { + "autoStart": false + }, + "_comment": "2026.5.22+: source-only external plugin. Define retention/redaction before enabling Discord voice capture." } } }, @@ -89,9 +111,10 @@ } }, "groupChat": { - "visibleReplies": true + "visibleReplies": true, + "ambientTurns": "room_event" }, - "_comment": "2026.5.14-beta.1+: steer is the default active-run queue mode. Use collect/followup/interrupt only when that queue behavior is intentional. Keep visible output in shared channels through the message tool." + "_comment": "Current May line: steer is the default active-run queue mode. Use collect/followup/interrupt only when intentional. ambientTurns=room_event should collect context quietly; visible replies still go through message tools." }, "tools": { @@ -109,6 +132,16 @@ "models": { "providers": { + "openrouter": { + "type": "openrouter", + "params": { + "provider": { + "order": ["Fireworks", "Together"], + "allow_fallbacks": true + } + }, + "_comment": "2026.5.20+: provider-level OpenRouter routing policy; model/agent params can override." + }, "ollama-local": { "type": "ollama", "endpoint": "http://localhost:11434", @@ -123,6 +156,30 @@ } }, + "mcp": { + "servers": { + "repo-tools": { + "command": "repo-mcp", + "codex": { + "agents": ["coding-agent"] + }, + "_comment": "2026.5.16+: scope user MCP projection into native Codex to named OpenClaw agents. Do not expose every MCP server to every Codex run." + } + } + }, + + "codex": { + "defaultToolsApprovalMode": "prompt", + "_comment": "2026.5.16+: make native Codex tool approvals explicit (auto | prompt | approve)." + }, + + "security": { + "audit": { + "suppressions": [], + "_comment": "2026.5.18+: only suppress reviewed audit findings with owner/reason/expiry in your real config." + } + }, + "skills": { "autoUpdate": false, "updateNotify": true,