OpenClaw 한국어 문서

Appearance

커맨드 큐 (2026-01-16) ​

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

이유 ​

  • 자동 응답 실행은 비용이 많이 들고 (LLM 호출) 여러 인바운드 메시지가 가까운 시간에 도착하면 충돌할 수 있습니다.
  • 직렬화는 공유 리소스 (세션 파일, 로그, CLI stdin) 경쟁을 피하고 업스트림 속도 제한 가능성을 줄입니다.

작동 방식 ​

  • 레인 인식 FIFO 큐는 구성 가능한 동시성 상한 (구성되지 않은 레인의 기본값 1; main 기본값 4, subagent 기본값 8)으로 각 레인을 드레인합니다.
  • runEmbeddedPiAgent는 세션 키 (레인 session:<key>)로 큐에 넣어 세션당 하나의 활성 실행만 보장합니다.
  • 각 세션 실행은 전체 병렬성이 agents.defaults.maxConcurrent로 제한되도록 전역 레인 (기본값 main)에 큐에 넣어집니다.
  • 상세 로깅이 활성화된 경우, 큐에 넣어진 실행이 시작 전에 ~2초 이상 대기했다면 짧은 알림을 내보냅니다.
  • 타이핑 표시기는 큐에 넣을 때 즉시 실행됩니다 (채널이 지원하는 경우). 따라서 차례를 기다리는 동안 사용자 경험은 변경되지 않습니다.

큐 모드 (채널별) ​

인바운드 메시지는 현재 실행을 조종하거나, 후속 턴을 기다리거나, 둘 다 할 수 있습니다:

  • steer: 즉시 현재 실행에 주입합니다 (다음 도구 경계 후 보류 중인 도구 호출 취소). 스트리밍이 아닌 경우, followup으로 폴백합니다.
  • followup: 현재 실행이 끝난 후 다음 에이전트 턴에 큐에 넣습니다.
  • collect: 큐에 넣어진 모든 메시지를 단일 followup 턴으로 통합합니다 (기본값). 메시지가 다른 채널/스레드를 대상으로 하면 라우팅을 보존하기 위해 개별적으로 드레인합니다.
  • steer-backlog (별칭 steer+backlog): 지금 조종 하고 후속 턴을 위해 메시지를 보존합니다.
  • interrupt (레거시): 해당 세션의 활성 실행을 중단한 다음 최신 메시지를 실행합니다.
  • queue (레거시 별칭): steer와 동일합니다.

Steer-backlog는 조종된 실행 후 후속 응답을 받을 수 있으므로, 스트리밍 표면에서 중복처럼 보일 수 있습니다. 인바운드 메시지당 하나의 응답을 원하면 collect/steer를 사용하십시오.

/queue collect를 독립 실행형 커맨드로 보내거나 (세션별) messages.queue.byChannel.discord: "collect"를 설정하십시오.

기본값 (구성에서 설정되지 않은 경우):

  • 모든 표면 → collect

messages.queue를 통해 전역 또는 채널별로 구성하십시오:

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

큐 옵션 ​

옵션은 followup, collect, steer-backlog (그리고 followup으로 폴백될 때 steer)에 적용됩니다:

  • debounceMs: followup 턴을 시작하기 전에 조용해질 때까지 기다립니다 ("계속, 계속" 방지).
  • cap: 세션당 최대 큐에 넣어진 메시지 수.
  • drop: 오버플로 정책 (old, new, summarize).

Summarize는 삭제된 메시지의 짧은 목록을 유지하고 합성 followup 프롬프트로 주입합니다. 기본값: debounceMs: 1000, cap: 20, drop: summarize.

세션별 오버라이드 ​

  • /queue <mode>를 독립 실행형 커맨드로 보내어 현재 세션의 모드를 저장하십시오.
  • 옵션을 결합할 수 있습니다: /queue collect debounce:2s cap:25 drop:summarize
  • /queue default 또는 /queue reset은 세션 오버라이드를 지웁니다.

범위 및 보장 ​

  • 게이트웨이 응답 파이프라인을 사용하는 모든 인바운드 채널 (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat 등)의 자동 응답 에이전트 실행에 적용됩니다.
  • 기본 레인 (main)은 인바운드 + 메인 하트비트에 대한 프로세스 전체입니다. 세션을 병렬로 허용하려면 agents.defaults.maxConcurrent를 설정하십시오.
  • 백그라운드 작업이 인바운드 응답을 차단하지 않고 병렬로 실행될 수 있도록 추가 레인 (예: cron, subagent)이 존재할 수 있습니다. 이 분리된 실행은 백그라운드 태스크로 추적됩니다.
  • 세션별 레인은 한 번에 하나의 에이전트 실행만 주어진 세션을 건드리도록 보장합니다.
  • 외부 종속성 또는 백그라운드 워커 스레드 없음. 순수 TypeScript + 프로미스.

트러블슈팅 ​

  • 커맨드가 막힌 것처럼 보이면 상세 로그를 활성화하고 "queued for …ms" 줄을 찾아 큐가 드레인되고 있는지 확인하십시오.
  • 큐 깊이가 필요하면 상세 로그를 활성화하고 큐 타이밍 줄을 관찰하십시오.