mirror of
https://github.com/openclaw/openclaw.git
synced 2026-10-24 07:58:39 +00:00
22dd373b2e
## What Problem This Solves
Advisor almost never interjects when an agent goes off course. Corrections waited until every tool call settled, then passed through a second verifier fork, and the verifier rejected most real corrections, so in practice the agent kept looping, polling or drifting without hearing anything.
## User Impact
With Advisor enabled, an agent that repeats a failing step, polls finished work, works around a blocker it could fix, or drifts beyond the request gets one short correction in its active run, before its next step. Advisor stays off by default and its config keys are unchanged.
## Why This Change Was Made
Advisor is now one review and one steer, using primitives core already has:
- Count tool calls in user-triggered runs. When `everyToolCalls` or `everyMinutes` is due, fork the session (`forkSession`) and ask whether the agent is on track.
- On `CORRECTION`, steer the active run (`steerActiveRun`). The advice joins the requester's own run, so its permissions and sender restrictions still apply. If the run already ended, or steering is refused (for example `hooks.allowPromptInjection=false`), nothing is delivered. The run ending also cancels a review still in flight.
- The plugin reference now documents the single-pass review.
- A due review forks only once every running tool call has its real result (Codex native tools: their item completion; outer Code Mode calls: their recorded output; a raw call and a native child that share an ID settle separately). The original dispatch-time recheck is kept: a review queued before another call starts stands down and stays due until that call's result, because a live unfinished-call fork once produced synthetic aborted results and false retry advice., because Codex fills a missing output with a synthetic `aborted` result in forks.
- Removed: the verifier stage, the old settlement bookkeeping, Codex item bookkeeping, the next-turn injection fallback and the reply parser's word and token rules. The model decides; code only reads the `NO_CHANGE`/`CORRECTION` shape.
- The default instructions say plainly what "off course" means.
The plugin drops from about 1,600 to about 420 lines including tests (+339/−1617 overall).
## Evidence
- Focused tests: `pnpm vitest run extensions/advisor` (12 passed; the outer-call, shared-ID receipt and dispatch-recheck cases each fail without their fix) and `src/plugins/contracts/boundary-invariants.test.ts` (12 passed). `ui:i18n:verify` and the config-doc baseline check pass.
- Live, isolated Gateway, `openai/gpt-6.1-sol` on the Codex harness, Advisor at `everyToolCalls: 3`. Task: poll a check script whose config has a typo. Rows 18–20: the third identical failure. Row 21: the Advisor steer, stored after the tool result with `sourceTool: plugin:advisor`. Row 22: the agent switches from re-running to inspecting the config, fixes the key, and reports READY. Gateway log: `advisor: steered active run`.
- Built-in OpenClaw runtime (`agentRuntime.id: "openclaw"`), same setup with the Control UI: reviews fork with a warm cache (17–25k cached input tokens, 75 uncached), and corrections are stored between tool calls while the run keeps going.
- Steer-only head, built-in runtime, test-only `reviewInstructions` that force a correction: the steer is stored at row 26 directly after a tool result (`sourceTool: plugin:advisor`), the run continues at row 28, and the log shows `advisor: steered active run`. No other turn is started.
- Codex harness, three 15-second commands in a row with `everyToolCalls: 1`: each review forked within 1 ms of the command's `commandExecution` item completing (10:00:51.3, 10:01:08.1) and never while a command was running.
- Codex Code Mode, one outer call that runs a command, waits 15 seconds, then runs another (`everyToolCalls: 1`): the child command finished at 10:21:48.3 while the outer call stayed open; the review forked only after the outer call recorded its output at 10:22:06.5.
- Permission boundary, isolated Gateway: with `hooks.allowPromptInjection=false` and test-only `reviewInstructions` that force a correction, every correction logged `correction not delivered (blocked by plugins.entries.advisor.hooks.allowPromptInjection=false)`.
- Replay of a real 4-hour coding session (62 review points at the default 10-tool-call trigger, real transcript history): Advisor proposed the same course change the user later asked for about 20 minutes earlier in two of four user interventions ("stop debugging unrelated Gateway startup and implement the fix"; "stop expanding the evidence bundle").
Labs description on this branch:
**Merge danger:** two-way door. A revert restores the previous plugin entirely; nothing migrates and no state is written. Blast radius is limited to users who turned on the Advisor lab: their agents can receive one short steered correction per review while a run is active.
Co-authored-by: Ayaan Zaidi <hi@obviy.us>
1.8 KiB
1.8 KiB
| summary | read_when | title | |
|---|---|---|---|
| Experimental: reviews ongoing agent work on the session's own model and offers one short correction. |
|
Advisor plugin reference |
Experimental: reviews ongoing agent work on the session's own model and offers one short correction.
Distribution
- Package:
@openclaw/advisor - Install route: included in OpenClaw
Surface
This plugin declares no channels, providers, commands, or contracts.
Review instructions
Open the plugin's Settings → Reviews → Review instructions field to change what Advisor reviews and when it stays quiet. The multiline field shows the built-in guidance as placeholder text. Leave it blank to keep using the current default without storing a copy.
The optional plugins.entries.advisor.config.reviewInstructions string accepts
up to 4,000 characters. Leading and trailing whitespace is trimmed;
whitespace-only values use the default. Changes apply to the next review without
restarting the Gateway.
Custom instructions replace only the guidance. A fixed prefix keeps tools
disabled and treats the conversation as evidence, not instructions. A fixed
output contract asks for a first line of NO_CHANGE or CORRECTION, followed
by one short correction. There is no second verification pass: a well-formed
CORRECTION steers the active run directly, and any other reply delivers
nothing. If the run already ended, the correction is dropped.