diff --git a/SCORECARD.md b/SCORECARD.md index b5a1380..642a4d7 100644 --- a/SCORECARD.md +++ b/SCORECARD.md @@ -65,7 +65,7 @@ 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` 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)* +- [ ] Approval policy is set at the control-plane choke point — by semantic intent, not raw tool names or skill-shell preludes. On 2026.4.15+ verify the shipping knobs (`tools.exec.security`, `tools.exec.ask`, `tools.fs.workspaceOnly`) with `openclaw exec-policy show`. *→ [Part 24](./part24-task-brain-control-plane.md#semantic-approval-categories)* - [ ] `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/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)* diff --git a/part11-auto-capture-hook.md b/part11-auto-capture-hook.md index 242e925..0384c63 100644 --- a/part11-auto-capture-hook.md +++ b/part11-auto-capture-hook.md @@ -168,3 +168,29 @@ ByteRover captures more (every turn vs session end), but at the cost of trusting **Want to use a different model?** Replace the `extractNotes()` function with any API that returns the same JSON structure. **Want it to fire more often?** Add `"message:received"` to the events list in `HOOK.md` — but be careful, this fires on every single message. + +--- + +## Troubleshooting + +**`Extraction failed: sessionKey is not defined` (or `[auto-capture] Hook triggered: …`).** + +Those two log lines do **not** come from the handler in this repo. The current [`handler.ts`](./hooks/auto-capture/handler.ts) logs `[auto-capture] Triggered: on ` and `[auto-capture] Error: `, and it always defines the binding before logging: + +```ts +const session = getSessionForAction(event); +const sessionKey = session?.sessionKey ?? 'unknown'; +``` + +So `sessionKey is not defined` is a `ReferenceError` from a *different* handler — almost always one of: + +1. **A stale or hand-edited copy** of the handler where the `const sessionKey = …` line was dropped or the event-shape destructuring was changed. Re-copy [`hooks/auto-capture/handler.ts`](./hooks/auto-capture/handler.ts) verbatim, then `openclaw gateway restart`. +2. **OpenClaw's built-in `session-memory` hook (or some other community auto-capture)**, not this one — see the warning at the top of this part. The wording `Hook triggered:` / `Extraction failed:` is the giveaway; this hook never prints those strings. Disable the built-in/other hook and enable only this one. + +Confirm which hook is actually live: + +```bash +openclaw hooks list # should show: 🧠 auto-capture ✓ (and nothing else doing extraction) +``` + +If you copied the file correctly and still see the error, you're running a cached build — restart the gateway so the new handler is loaded. diff --git a/part24-task-brain-control-plane.md b/part24-task-brain-control-plane.md index 8bda8ce..16b0241 100644 --- a/part24-task-brain-control-plane.md +++ b/part24-task-brain-control-plane.md @@ -44,6 +44,17 @@ Task Brain replaces name-based allowlisting with **semantic approval categories* ## Semantic Approval Categories +> **Version accuracy (verify against your binary).** The semantic-category model below describes how Task Brain reasons about approvals at the control-plane choke point. Depending on your installed version, you may **not** find a literal `agents.*.approvals` block of `read-only.*` / `execution.*` / `control-plane.*` string tokens, and you may not find an `openclaw flows` command — both surfaced in the v2026.3.31-beta.1 [control-plane release post](https://openclawai.io/blog/openclaw-task-brain-v2026-3-31-control-plane-security) but renamed/reshaped across the 4.x line. As of 2026.4.15 stable / 2026.4.19-beta.2, inspect and set policy with the shipping knobs instead, then confirm with `openclaw tasks --help` and `openclaw exec-policy show`: +> +> | Guide concept (semantic model) | Verified shipping knob (2026.4.15+) | +> |--------------------------------|--------------------------------------| +> | `execution.shell` / `execution.code` allow vs ask | `tools.exec.security` (`full` / `allowlist` / `none`) and `tools.exec.ask` (`always` / `on-miss` / `off`) | +> | `write.fs.outside-workspace` deny | `tools.fs.workspaceOnly` (bool) | +> | Per-channel tool profile | `tools.profile` (e.g. `messaging`) and `tools.toolsBySender` (see below) | +> | Read the live policy / audit it | `openclaw exec-policy show`, `openclaw exec-policy preset `, `ocplatform security audit [--deep]` | +> +> Treat the per-category `approvals` JSON in this part as the **intended control-plane model** (and the shape the Control UI exposes), not as a guaranteed config-file key in every build. Thanks to [#8](https://github.com/OnlyTerp/openclaw-optimization-guide/issues/8) for the field report. + Every tool invocation is now classified into one of a small fixed set of categories. The canonical ones: | Category | Meaning | Examples | diff --git a/part27-gotchas-and-faq.md b/part27-gotchas-and-faq.md index 1b9ac93..99cb85a 100644 --- a/part27-gotchas-and-faq.md +++ b/part27-gotchas-and-faq.md @@ -160,6 +160,18 @@ Skills are genuinely useful, but the marketplace has a malware problem. Our reco Both. For the **orchestrator** you want a frontier model (Claude, GPT, Gemini Pro) — the quality difference is huge on planning. For **workers**, local models on a decent GPU are absolutely viable and save real money. See [Part 6](./README.md#part-6-models-what-to-actually-use) for tier-by-tier guidance. +### Anthropic ended the Claude subscription path — has that changed your model strategy? Do you still run Opus as the orchestrator? + +Yes, the economics changed; the architecture didn't. Anthropic's April 4, 2026 policy change ended the old "Claude Pro/Max covers OpenClaw" route, so Claude is now explicit **paid API / Bedrock / provider-routed** usage with budget caps — not a flat-rate subscription (see the [README hero note](./README.md) and the ["May upgrade broke my old workflow" table](#the-may-upgrade-broke-my-old-workflow) at the top of this part, plus the [Version Map in Part 33](./part33-late-april-2026-field-guide.md#version-map)). + +What that means in practice: + +- **A frontier orchestrator is still worth it** — the planning-quality gap is large. Opus 4.7 remains a strong default *if you have a paid route and caps set*. But it's no longer the only sensible default: a frontier GPT or Gemini Pro orchestrator is fine, and the right pick is now "best planner you have metered access to," not "whatever the subscription covered." +- **Push more work down to cheaper/local models.** Because every orchestrator token is now metered, the [orchestrator/worker split](./README.md#part-6-models-what-to-actually-use) matters more: frontier model plans, Gemini/DeepSeek/Kimi/local workers execute. This is the single biggest lever on the new bill. +- **Always configure non-Anthropic fallbacks** so an auth/rate-limit blip doesn't halt every agent, and set per-agent budget caps. See ["My expensive model keeps getting rate-limited"](#my-expensive-model-keeps-getting-rate-limited) above. + +So: still a frontier orchestrator, still the same CEO/COO/worker shape — just metered, capped, and with the worker tier doing more of the volume. + ### How do I know if I should use reasoning mode? Turn it on for the orchestrator when tasks are ambiguous or multi-step. Turn it off for workers doing well-defined execution. Reasoning adds latency and cost; it shines on "what should we do" questions, not "go do this" tasks.