openclaw - 💡(How to fix) Fix Clarify "active-run steering" vs "follow-up queueing" across docs and help text [3 comments, 2 participants]

Summary

OpenClaw currently supports real active-run steering, but the terminology makes it easy to misread the feature as "just queue a message for later."

The main confusion is that the implementation and docs use queue language in multiple ways:

• active-run steering has a short-lived steering queue so messages can be injected at runtime boundaries
• follow-up queueing stores messages for a later agent turn
• /queue steer configures future normal busy messages to steer active runs
• /steer <message> is an explicit one-off command that bypasses the stored queue mode

Those are all valid concepts, but the current wording makes outside readers ask whether OpenClaw has actual steering at all. Recent external comparisons have started describing OpenClaw as "queue only" and Hermes/Codex-style systems as having real steering. Current OpenClaw behavior is more capable than that, so the docs should make the distinction impossible to miss.

Current behavior to explain

From current source/docs:

• Normal inbound messages default to steer while a run is actively streaming.
• /queue steer controls future normal inbound messages.
• /steer <message> and /tell <message> explicitly target the current session active run.
• Steering is boundary-based:
  • it does not interrupt an already-running tool call
  • Pi injects messages before the next LLM call after the active tool-call batch
  • native Codex app-server sends turn/steer
• If the runtime cannot accept steering, OpenClaw falls back to running the prompt after the active run, rather than dropping it.

Where the wording is confusing

The phrase "queue" currently appears in ways that can mean either:

1. "hold this for a later standalone turn"
2. "hold this for the active runtime's next steering boundary"

Those are very different user experiences. The first is delayed follow-up. The second is active-run steering.

Even function names and implementation concepts such as queueEmbeddedPiMessageWithOutcomeAsync can make the feature sound like deferred queueing when, in steer mode, it is actually the active-run steering delivery path.

Suggested docs changes

Add one canonical explanation and reuse it in:

• docs/concepts/queue.md
• docs/concepts/queue-steering.md
• docs/concepts/messages.md
• docs/tools/steer.md
• docs/tools/slash-commands.md
• docs/plugins/codex-harness-runtime.md
• config help for messages.queue.mode

Suggested wording:

OpenClaw has two different busy-message paths. Active-run steering sends new user input into the already-running session at the next supported runtime boundary. Follow-up queueing waits until the active run finishes and starts a later turn. The word "queue" appears in both paths internally, but /queue steer is active-run steering, not the same as /queue followup or /queue collect.

Also add a small comparison table:

Suggested FAQ entry

Add a FAQ entry like:

Does OpenClaw only queue messages while the agent is busy?

No. In the default steer mode, OpenClaw tries to inject busy-time messages into the active run at the next supported runtime boundary. If steering is unavailable for that runtime or current turn type, OpenClaw waits and runs the prompt after the active run. Use /queue followup or /queue collect when you want messages to wait by default.

Acceptance criteria

• A new user can tell the difference between active-run steering and deferred follow-up queueing without reading source.
• /queue steer and /steer <message> are described as related but different controls.
• The docs explicitly say steering is real active-run injection, but boundary-based rather than in-flight tool interruption.
• The native Codex harness docs explicitly mention turn/steer.
• The wording does not imply that OpenClaw only has a later-turn queue.

Labels

Suggested labels:

• docs
• agents
• commands
• gateway