mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-14 21:03:23 +02:00
70df2b8fe2
Summary: - Default active-run queueing to steer while preserving explicit followup/collect modes. - Keep `/steer` fallback behavior and migrate retired queue steering config. - Await Codex app-server steering acceptance so rejected/aborted steering can fall back safely. - Route active subagent announcements through intentional acceptance-aware steering, with legacy queue helpers deprecated for delivery decisions. Verification: - git diff --check - rg -n "^(<<<<<<<|=======|>>>>>>>|\|\|\|\|\|\|\|)" CHANGELOG.md docs src extensions || true - pnpm test src/agents/subagent-announce-dispatch.test.ts src/agents/subagent-announce-delivery.test.ts src/agents/pi-embedded-runner/runs.test.ts src/agents/subagent-announce.format.e2e.test.ts src/agents/subagent-announce.test.ts - pnpm test src/auto-reply/reply/commands-steer.test.ts src/auto-reply/reply/queue/settings.test.ts src/auto-reply/reply/queue-policy.test.ts src/auto-reply/reply/agent-runner.runreplyagent.e2e.test.ts src/auto-reply/reply/get-reply-run.media-only.test.ts extensions/codex/src/app-server/run-attempt.test.ts -- -t "queued steering|explicit all-mode steering|flushes pending default queued steering|rejects queued steering|resolveActiveRunQueueAction|resolveQueueSettings|handleSteerCommand" Co-authored-by: fuller-stack-dev <263060202+fuller-stack-dev@users.noreply.github.com>
123 lines
6.6 KiB
Markdown
123 lines
6.6 KiB
Markdown
---
|
|
summary: "Auto-reply queue modes, defaults, and per-session overrides"
|
|
read_when:
|
|
- Changing auto-reply execution or concurrency
|
|
- Explaining /queue modes or message steering behavior
|
|
title: "Command queue"
|
|
---
|
|
|
|
We serialize inbound auto-reply runs (all channels) through a tiny in-process queue to prevent multiple agent runs from colliding, while still allowing safe parallelism across sessions.
|
|
|
|
## Why
|
|
|
|
- Auto-reply runs can be expensive (LLM calls) and can collide when multiple inbound messages arrive close together.
|
|
- Serializing avoids competing for shared resources (session files, logs, CLI stdin) and reduces the chance of upstream rate limits.
|
|
|
|
## How it works
|
|
|
|
- A lane-aware FIFO queue drains each lane with a configurable concurrency cap (default 1 for unconfigured lanes; main defaults to 4, subagent to 8).
|
|
- `runEmbeddedPiAgent` enqueues by **session key** (lane `session:<key>`) to guarantee only one active run per session.
|
|
- Each session run is then queued into a **global lane** (`main` by default) so overall parallelism is capped by `agents.defaults.maxConcurrent`.
|
|
- When verbose logging is enabled, queued runs emit a short notice if they waited more than ~2s before starting.
|
|
- Typing indicators still fire immediately on enqueue (when supported by the channel) so user experience is unchanged while we wait our turn.
|
|
|
|
## Defaults
|
|
|
|
When unset, all inbound channel surfaces use:
|
|
|
|
- `mode: "steer"`
|
|
- `debounceMs: 500`
|
|
- `cap: 20`
|
|
- `drop: "summarize"`
|
|
|
|
Same-turn steering is the default. A prompt that arrives mid-run is injected
|
|
into the active runtime when the run can accept steering, so no second session
|
|
run is started. If the active run cannot accept steering, OpenClaw waits for the
|
|
active run to finish before starting the prompt.
|
|
|
|
## Queue modes
|
|
|
|
`/queue` controls what normal inbound messages do while a session already has
|
|
an active run:
|
|
|
|
- `steer`: inject messages into the active runtime. Pi delivers all pending steering messages **after the current assistant turn finishes executing its tool calls**, before the next LLM call; Codex app-server receives one batched `turn/steer`. If the run is not actively streaming or steering is unavailable, OpenClaw waits until the active run ends before starting the prompt.
|
|
- `followup`: do not steer. Enqueue each message for a later agent turn after the current run ends.
|
|
- `collect`: do not steer. Coalesce queued messages into a **single** followup turn after the quiet window. If messages target different channels/threads, they drain individually to preserve routing.
|
|
- `interrupt`: abort the active run for that session, then run the newest message.
|
|
|
|
For runtime-specific timing and dependency behavior, see
|
|
[Steering queue](/concepts/queue-steering). For the explicit `/steer <message>`
|
|
command, see [Steer](/tools/steer).
|
|
|
|
Configure globally or per channel via `messages.queue`:
|
|
|
|
```json5
|
|
{
|
|
messages: {
|
|
queue: {
|
|
mode: "steer",
|
|
debounceMs: 500,
|
|
cap: 20,
|
|
drop: "summarize",
|
|
byChannel: { discord: "collect" },
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
## Queue options
|
|
|
|
Options apply to queued delivery. `debounceMs` also sets the Codex steering
|
|
quiet window in `steer` mode:
|
|
|
|
- `debounceMs`: quiet window before draining queued followups or collect batches; in Codex `steer` mode, quiet window before sending batched `turn/steer`. Bare numbers are milliseconds; units `ms`, `s`, `m`, `h`, and `d` are accepted by `/queue` options.
|
|
- `cap`: max queued messages per session. Values below `1` are ignored.
|
|
- `drop: "summarize"`: default. Drop the oldest queued entries as needed, keep compact summaries, and inject them as a synthetic followup prompt.
|
|
- `drop: "old"`: drop the oldest queued entries as needed, without preserving summaries.
|
|
- `drop: "new"`: reject the newest message when the queue is already full.
|
|
|
|
Defaults: `debounceMs: 500`, `cap: 20`, `drop: summarize`.
|
|
|
|
## Precedence
|
|
|
|
For mode selection, OpenClaw resolves:
|
|
|
|
1. Inline or stored per-session `/queue` override.
|
|
2. `messages.queue.byChannel.<channel>`.
|
|
3. `messages.queue.mode`.
|
|
4. Default `steer`.
|
|
|
|
For options, inline or stored `/queue` options win over config. Then
|
|
channel-specific debounce (`messages.queue.debounceMsByChannel`), plugin
|
|
debounce defaults, global `messages.queue` options, and built-in defaults are
|
|
applied. `cap` and `drop` are global/session options, not per-channel config
|
|
keys.
|
|
|
|
## Per-session overrides
|
|
|
|
- Send `/queue <steer|followup|collect|interrupt>` as a standalone command to store the queue mode for the current session.
|
|
- Options can be combined: `/queue collect debounce:0.5s cap:25 drop:summarize`
|
|
- `/queue default` or `/queue reset` clears the session override.
|
|
|
|
## Scope and guarantees
|
|
|
|
- Applies to auto-reply agent runs across all inbound channels that use the gateway reply pipeline (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, etc.).
|
|
- Default lane (`main`) is process-wide for inbound + main heartbeats; set `agents.defaults.maxConcurrent` to allow multiple sessions in parallel.
|
|
- Additional lanes may exist (e.g. `cron`, `cron-nested`, `nested`, `subagent`) so background jobs can run in parallel without blocking inbound replies. Isolated cron agent turns hold a `cron` slot while their inner agent execution uses `cron-nested`; both use `cron.maxConcurrentRuns`. Shared non-cron `nested` flows keep their own lane behavior. These detached runs are tracked as [background tasks](/automation/tasks).
|
|
- Per-session lanes guarantee that only one agent run touches a given session at a time.
|
|
- No external dependencies or background worker threads; pure TypeScript + promises.
|
|
|
|
## Troubleshooting
|
|
|
|
- If commands seem stuck, enable verbose logs and look for "queued for ...ms" lines to confirm the queue is draining.
|
|
- If you need queue depth, enable verbose logs and watch for queue timing lines.
|
|
- Codex app-server runs that accept a turn and then stop emitting progress are interrupted by the Codex adapter so the active session lane can release instead of waiting for the outer run timeout.
|
|
- When diagnostics are enabled, sessions that remain in `processing` past `diagnostics.stuckSessionWarnMs` with no observed reply, tool, status, block, or ACP progress are classified by current activity. Active work logs as `session.long_running`; active work with no recent progress logs as `session.stalled`; `session.stuck` is reserved for stale session bookkeeping with no active work, and only that path can release the affected session lane so queued work drains. Repeated `session.stuck` diagnostics back off while the session remains unchanged.
|
|
|
|
## Related
|
|
|
|
- [Session management](/concepts/session)
|
|
- [Steering queue](/concepts/queue-steering)
|
|
- [Steer](/tools/steer)
|
|
- [Retry policy](/concepts/retry)
|