---
read_when:
    - 자동 회신 실행 또는 동시성 변경
    - /queue 모드 또는 메시지 조정 동작 설명
summary: 자동 응답 대기열 모드, 기본값 및 세션별 재정의
title: 명령 대기열
x-i18n:
    generated_at: "2026-07-12T00:42:24Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 309d149545aaba91d2248dd6354d82e3cb7ddd489817a5f84acbb0269a0815ec
    source_path: concepts/queue.md
    workflow: 16
---

OpenClaw은 여러 에이전트 실행이 충돌하지 않도록 작은 프로세스 내 큐를 통해 인바운드 자동 응답 실행(모든 채널)을 직렬화하면서도, 세션 간에는 안전한 병렬 처리를 허용합니다.

## 필요한 이유

- 자동 응답 실행에는 많은 비용(LLM 호출)이 들 수 있으며, 여러 인바운드 메시지가 짧은 간격으로 도착하면 충돌할 수 있습니다.
- 직렬화하면 공유 리소스(세션 파일, 로그, CLI 표준 입력)를 두고 경합하는 상황을 방지하고 업스트림 속도 제한에 걸릴 가능성을 줄일 수 있습니다.

## 작동 방식

- 레인 인식 FIFO 큐가 구성 가능한 동시 실행 한도에 따라 각 레인을 비웁니다(구성되지 않은 레인의 기본값은 1이며, `main`의 기본값은 4, `subagent`의 기본값은 8).
- `runEmbeddedAgent`는 **세션 키**(레인 `session:<key>`)별로 큐에 추가하여 세션당 활성 실행이 하나만 존재하도록 보장합니다.
- 이후 각 세션 실행은 **전역 레인**(기본값은 `main`)에 큐잉되므로 전체 병렬 처리 수준은 `agents.defaults.maxConcurrent`로 제한됩니다.
- 상세 로깅이 활성화된 경우, 큐에 추가된 실행은 시작 전 약 2초 넘게 대기하면 짧은 알림을 출력합니다.
- 입력 중 표시기는 큐에 추가되는 즉시 계속 표시되므로(채널에서 지원하는 경우), 실행이 차례를 기다리는 동안에도 사용자 경험은 달라지지 않습니다.

## 기본값

설정하지 않으면 모든 인바운드 채널 표면에서 다음을 사용합니다.

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

동일 턴 조정이 기본값입니다. 실행 도중 프롬프트가 도착하면 해당 실행이 조정을 수락할 수 있는 경우 활성 런타임에 주입되므로 두 번째 세션 실행이 시작되지 않습니다. 활성 실행이 조정을 수락할 수 없으면 OpenClaw은 활성 실행이 끝날 때까지 기다린 후 프롬프트를 시작합니다.

## 큐 모드

`/queue`는 세션에 이미 활성 실행이 있을 때 일반 인바운드 메시지를 처리하는 방식을 제어합니다.

- `steer`: 메시지를 활성 런타임에 주입합니다. OpenClaw은 다음 LLM 호출 전에 **현재 어시스턴트 턴이 도구 호출 실행을 마친 후** 대기 중인 모든 조정 메시지를 전달하며, Codex app-server는 일괄 처리된 `turn/steer` 하나를 수신합니다. 실행이 활발하게 스트리밍 중이 아니거나 조정을 사용할 수 없으면 OpenClaw은 활성 실행이 끝날 때까지 기다린 후 프롬프트를 시작합니다.
- `followup`: 조정하지 않습니다. 현재 실행이 끝난 후 처리할 이후 에이전트 턴을 위해 각 메시지를 큐에 추가합니다.
- `collect`: 조정하지 않습니다. 대기 시간 구간이 지난 후 큐에 추가된 메시지를 **단일** 후속 턴으로 병합합니다. 메시지가 서로 다른 채널이나 스레드를 대상으로 하면 라우팅을 유지하기 위해 개별적으로 처리합니다.
- `interrupt`: 해당 세션의 활성 실행을 중단한 후 가장 최신 메시지를 실행합니다.

런타임별 타이밍 및 종속성 동작은 [조정 큐](/ko/concepts/queue-steering)를 참조하세요. 명시적 `/steer <message>` 명령은 [조정](/ko/tools/steer)을 참조하세요.

`messages.queue`를 통해 전역 또는 채널별로 구성합니다.

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

## 큐 옵션

옵션은 큐잉된 전달에 적용됩니다. `debounceMs`는 `steer` 모드에서 Codex 조정 대기 시간 구간도 설정합니다.

- `debounceMs`: 큐잉된 후속 메시지나 수집 배치를 처리하기 전의 대기 시간 구간입니다. Codex `steer` 모드에서는 일괄 처리된 `turn/steer`를 보내기 전의 대기 시간 구간입니다. 단위 없는 숫자는 밀리초이며, `/queue` 옵션에서는 `ms`, `s`, `m`, `h`, `d` 단위를 사용할 수 있습니다.
- `cap`: 세션별 큐잉 메시지의 최대 개수입니다. `1` 미만의 값은 무시됩니다.
- `drop: "summarize"`(기본값): 필요에 따라 가장 오래된 큐 항목을 삭제하고, 간결한 요약을 보존하여 합성 후속 프롬프트로 주입합니다.
- `drop: "old"`: 요약을 보존하지 않고 필요에 따라 가장 오래된 큐 항목을 삭제합니다.
- `drop: "new"`: 큐가 이미 가득 찬 경우 가장 최신 메시지를 거부합니다.

기본값: `debounceMs: 500`, `cap: 20`, `drop: summarize`.

## 조정 및 스트리밍

채널 스트리밍이 `partial` 또는 `block`이면 활성 실행이 런타임 경계에 도달하는 동안 조정이 여러 개의 짧고 가시적인 응답처럼 보일 수 있습니다.

- `partial`: 미리보기가 일찍 완료된 후 조정이 수락되면 새 미리보기가 시작될 수 있습니다.
- `block`: 초안 크기의 블록에서도 동일하게 순차적으로 표시될 수 있습니다.
- 스트리밍을 사용하지 않고 런타임이 동일 턴 조정을 수락할 수 없는 경우, 활성 실행이 끝난 후 후속 처리로 대체됩니다.

`steer`는 실행 중인 도구를 중단하지 않습니다. 가장 최신 메시지가 현재 실행을 중단해야 하는 경우 `/queue interrupt`를 사용하세요.

## 우선순위

모드를 선택할 때 OpenClaw은 다음 순서로 결정합니다.

1. 인라인 또는 저장된 세션별 `/queue` 재정의.
2. `messages.queue.byChannel.<channel>`.
3. `messages.queue.mode`.
4. 기본값 `steer`.

옵션의 경우 인라인 또는 저장된 `/queue` 옵션이 구성보다 우선합니다. 그런 다음 채널별 디바운스(`messages.queue.debounceMsByChannel`), Plugin 디바운스 기본값, 전역 `messages.queue` 옵션, 내장 기본값 순으로 적용됩니다. `cap`과 `drop`은 전역/세션 옵션이며 채널별 구성 키가 아닙니다.

## 세션별 재정의

- `/queue <steer|followup|collect|interrupt>`를 독립 실행형 명령으로 보내 현재 세션의 큐 모드를 저장합니다.
- 옵션을 함께 사용할 수 있습니다: `/queue collect debounce:0.5s cap:25 drop:summarize`
- `/queue default` 또는 `/queue reset`은 세션 재정의를 지웁니다.

## 큐잉된 턴 취소

프롬프트가 followup/collect 큐에 있는 동안(예: 다른 턴이 활성 상태일 때 도착한 TUI 또는 웹 채팅 `chat.send`) Gateway는 큐잉된 콘텐츠가 실행되거나 삭제될 때까지 해당 클라이언트 `runId`에 대한 **Gateway 소유 취소 ID**를 유지합니다. 이 ID는 오버플로 요약에 병합된 콘텐츠를 따라갑니다.

- 특정 `runId`가 지정된 `chat.abort`는 해당 턴이 아직 큐에 있는 동안 요청자에게 권한이 있으면 이를 취소합니다(활성 실행과 동일한 소유권 규칙 적용).
- `runId` 없이 세션에 대해 실행한 `chat.abort`는 **권한이 있는 큐잉된 턴을 먼저** 취소한 후 권한이 있는 활성 실행을 중단합니다. 이 순서를 통해 큐 처리가 작업을 절반만 중지된 세션으로 승격하는 것을 방지합니다.
- 요청자별 검사 없이 전체 세션 큐를 지우는 방식은 소유자가 여러 명인 세션의 중지 경로가 아닙니다.
- 큐 대기는 `sessions.list`에서 활성 에이전트 실행으로 표시되지 않으며 활성 실행 제한 시간 의미 체계를 소유하지 않습니다. 활성 단계만 이를 소유합니다.

클라이언트(TUI 포함)는 실행 도중 도착한 프롬프트를 전달하고 Gateway가 큐 모드를 적용하도록 합니다. Esc/`/stop`은 세션 범위 중단을 사용하므로 로컬 핸들을 잃더라도 아직 큐에 있는 프롬프트가 실행되는 상황을 방지할 수 있습니다.

## 범위 및 보장 사항

- Gateway 응답 파이프라인을 사용하는 모든 인바운드 채널(WhatsApp 웹, Telegram, Slack, Discord, Signal, iMessage, 웹 채팅 등)의 자동 응답 에이전트 실행에 적용됩니다.
- 기본 레인(`main`)은 인바운드 및 기본 Heartbeat에 대해 프로세스 전체에서 공유됩니다. 여러 세션을 병렬로 허용하려면 `agents.defaults.maxConcurrent`를 설정하세요.
- 백그라운드 작업이 인바운드 응답을 차단하지 않고 병렬로 실행될 수 있도록 추가 레인(예: `cron`, `cron-nested`, `nested`, `subagent`)이 존재할 수 있습니다. 격리된 Cron 에이전트 턴은 내부 에이전트 실행이 `cron-nested`를 사용하는 동안 `cron` 슬롯을 점유하며, 둘 다 `cron.maxConcurrentRuns`를 사용합니다. 공유되는 Cron 이외의 `nested` 흐름은 자체 레인 동작을 유지합니다. 이러한 분리된 실행은 [백그라운드 작업](/ko/automation/tasks)으로 추적됩니다.
- 세션별 레인은 한 번에 하나의 에이전트 실행만 특정 세션에 접근하도록 보장합니다.
- 외부 종속성이나 백그라운드 워커 스레드가 없으며, 순수 TypeScript와 프로미스만 사용합니다.

## 문제 해결

- 명령이 멈춘 것처럼 보이면 상세 로그를 활성화하고 "queued for ...ms" 줄을 확인하여 큐가 처리되고 있는지 확인하세요.
- 턴을 수락한 후 진행 상황 출력을 중단하는 Codex app-server 실행은 Codex 어댑터에 의해 중단되므로, 활성 세션 레인은 외부 실행 제한 시간을 기다리는 대신 해제될 수 있습니다.
- 진단이 활성화된 경우, 관찰된 응답, 도구, 상태, 블록 또는 ACP 진행 상황 없이 `diagnostics.stuckSessionWarnMs`를 초과하여 `processing` 상태로 남아 있는 세션은 현재 활동에 따라 분류됩니다.
  - 최근 진행 상황이 있는 활성 작업은 `session.long_running`으로 기록됩니다. 소유자가 있는 무응답 모델 호출도 느리거나 스트리밍하지 않는 제공자가 너무 일찍 중단된 것으로 보고되지 않도록 `diagnostics.stuckSessionAbortMs`까지 `session.long_running`으로 유지됩니다.
  - 최근 진행 상황이 없는 활성 작업은 `session.stalled`로 기록됩니다. 소유자가 있는 모델 호출, 차단된 도구 호출 및 멈춘 임베디드 실행은 중단 임계값에 도달하거나 이를 초과하면 `session.stalled`로 전환됩니다. 소유자가 없는 오래된 모델/도구 활동은 장기 실행으로 숨겨지지 않습니다.
  - `session.stuck`은 소유자가 없는 오래된 모델/도구 활동이 있는 유휴 큐잉 세션을 포함하여 복구 가능한 오래된 세션 상태 기록에만 사용됩니다.
  - `session.stuck`은 항상 영향을 받은 세션 레인을 해제할 수 있는 복구를 트리거합니다. `diagnostics.stuckSessionAbortMs`를 초과한 `session.stalled` 분류(차단된 도구 호출, 멈춘 모델 호출 또는 멈춘 임베디드 실행)도 활성 중단 복구를 트리거할 수 있으므로 `session.stuck`뿐만 아니라 두 분류 모두 큐의 멈춤을 해제할 수 있습니다.
  - 세션이 변경되지 않은 상태로 유지되는 동안 반복되는 `session.stuck` 및 `session.long_running` 경고 로그 줄에는 지수 백오프가 적용됩니다. 복구 시도는 이 백오프와 관계없이 매 Heartbeat 틱마다 계속 실행됩니다.

## 관련 항목

- [세션 관리](/ko/concepts/session)
- [조정 큐](/ko/concepts/queue-steering)
- [조정](/ko/tools/steer)
- [재시도 정책](/ko/concepts/retry)
