Command queue

Command queue 문서는 OpenClaw 공식 문서(concepts/queue)를 한국어로 정리한 가이드입니다. Auto-reply queue modes, defaults, and per-session overrides 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Auto-reply queue modes, defaults, and per-session overrides

한국어 가이드 범위: concepts/queue 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Why
동작 방식
Defaults
Queue modes
Queue options
Steer and streaming
Precedence
Per-session overrides
Queued-turn cancellation
Scope and guarantees
트러블슈팅
관련 문서

상세 내용

본문

OpenClaw serializes 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.

동작 방식

주요 항목:

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).
runEmbeddedAgent 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 the run waits its turn.

Defaults

When unset, all inbound channel surfaces use:

주요 항목:

mode: "steer"
debounceMs: 500
cap: 20
drop: "summarize"

Queue modes

/queue controls what normal inbound messages do while a session already has an active run:

주요 항목:

steer: inject messages into the active runtime. OpenClaw 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.

{
  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.

Steer and streaming

When channel streaming is partial or block, steering can look like several short visible replies while the active run reaches runtime boundaries:

주요 항목:

partial: the preview may finalize early, then a new preview starts after steering is accepted.
block: draft-sized blocks can create the same sequential appearance.
Without streaming, steering falls back to a followup after the active run when the runtime cannot accept same-turn steering.

Precedence

Inline or stored per-session /queue override. 2. messages.queue.byChannel.. 3. messages.queue.mode. 4. Default steer.

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.

Queued-turn cancellation

While a prompt sits in the followup/collect queue (for example a TUI or webchat chat.send arriving while another turn is active), Gateway keeps a

주요 항목:

chat.abort with a specific runId cancels that turn while it is still
chat.abort for a session without runId cancels **authorized queued turns
Clearing the entire session queue without per-requester checks is not the
Queued waits are not projected as active agent runs for sessions.list and

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. Shared non-cron nested flows keep their own lane behavior. These detached runs are tracked as background 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.

트러블슈팅

주요 항목:

If commands seem stuck, enable verbose logs and look for "queued for ...ms" lines to confirm the queue is draining.
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 the built-in warning threshold with no observed reply, tool, status, block, or ACP progress are classified by current activity:
Active work with recent progress logs as session.long_running. Owned silent model calls also stay session.long_running until the built-in abort threshold so slow or non-streaming providers are not reported as stalled too early.
Active work with no recent progress logs as session.stalled; owned model calls, blocked tool calls, and stalled embedded runs switch to session.stalled at or after the abort threshold. Ownerless stale model/tool activity is not hidden as long-running.
session.stuck is reserved for recoverable stale session bookkeeping, including idle queued sessions with stale ownerless model/tool activity.
session.stuck always triggers recovery that can release the affected session lane. A session.stalled classification past the abort threshold (blocked tool call, stalled model call, or stalled embedded run) can also trigger active-abort recovery, so both classifications can unstick a queue, not only session.stuck.
Repeated session.stuck and session.long_running warning log lines back off exponentially while the session remains unchanged; recovery attempts still run on every heartbeat tick regardless of that backoff.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/queue
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  messages: {
    queue: {
      mode: "steer",
      debounceMs: 500,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

Command queue

핵심 요약

Auto-reply queue modes, defaults, and per-session overrides

한국어 가이드 범위: concepts/queue 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Why
동작 방식
Defaults
Queue modes
Queue options
Steer and streaming
Precedence
Per-session overrides
Queued-turn cancellation
Scope and guarantees
트러블슈팅
관련 문서

상세 내용

본문

OpenClaw serializes 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.

동작 방식

주요 항목:

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).
runEmbeddedAgent 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 the run waits its turn.

Defaults

When unset, all inbound channel surfaces use:

주요 항목:

mode: "steer"
debounceMs: 500
cap: 20
drop: "summarize"

Queue modes

/queue controls what normal inbound messages do while a session already has an active run:

주요 항목:

steer: inject messages into the active runtime. OpenClaw 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.

{
  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.

Steer and streaming

When channel streaming is partial or block, steering can look like several short visible replies while the active run reaches runtime boundaries:

주요 항목:

partial: the preview may finalize early, then a new preview starts after steering is accepted.
block: draft-sized blocks can create the same sequential appearance.
Without streaming, steering falls back to a followup after the active run when the runtime cannot accept same-turn steering.

Precedence

Inline or stored per-session /queue override. 2. messages.queue.byChannel.. 3. messages.queue.mode. 4. Default steer.

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.

Queued-turn cancellation

While a prompt sits in the followup/collect queue (for example a TUI or webchat chat.send arriving while another turn is active), Gateway keeps a

주요 항목:

chat.abort with a specific runId cancels that turn while it is still
chat.abort for a session without runId cancels **authorized queued turns
Clearing the entire session queue without per-requester checks is not the
Queued waits are not projected as active agent runs for sessions.list and

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. Shared non-cron nested flows keep their own lane behavior. These detached runs are tracked as background 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.

트러블슈팅

주요 항목:

If commands seem stuck, enable verbose logs and look for "queued for ...ms" lines to confirm the queue is draining.
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 the built-in warning threshold with no observed reply, tool, status, block, or ACP progress are classified by current activity:
Active work with recent progress logs as session.long_running. Owned silent model calls also stay session.long_running until the built-in abort threshold so slow or non-streaming providers are not reported as stalled too early.
Active work with no recent progress logs as session.stalled; owned model calls, blocked tool calls, and stalled embedded runs switch to session.stalled at or after the abort threshold. Ownerless stale model/tool activity is not hidden as long-running.
session.stuck is reserved for recoverable stale session bookkeeping, including idle queued sessions with stale ownerless model/tool activity.
session.stuck always triggers recovery that can release the affected session lane. A session.stalled classification past the abort threshold (blocked tool call, stalled model call, or stalled embedded run) can also trigger active-abort recovery, so both classifications can unstick a queue, not only session.stuck.
Repeated session.stuck and session.long_running warning log lines back off exponentially while the session remains unchanged; recovery attempts still run on every heartbeat tick regardless of that backoff.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/queue
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  messages: {
    queue: {
      mode: "steer",
      debounceMs: 500,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

Command queue

핵심 요약

문서 구성

상세 내용

본문

Why

동작 방식

Defaults

Queue modes

Queue options

Steer and streaming

Precedence

Per-session overrides

Queued-turn cancellation

Scope and guarantees

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Command queue

핵심 요약

문서 구성

상세 내용

본문

Why

동작 방식

Defaults

Queue modes

Queue options

Steer and streaming

Precedence

Per-session overrides

Queued-turn cancellation

Scope and guarantees

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드