​

에이전트 루프 (OpenClaw)

에이전트 루프는 에이전트의 전체 ‘실제’ 실행을 의미합니다. 즉, 입력 → 컨텍스트 구성 → 모델 추론 → 도구 실행 → 응답 스트리밍 → 영속화의 흐름입니다. 이는 메시지를 행동과 최종 응답으로 전환하면서 세션 상태를 일관되게 유지하는 권위 있는 경로입니다. OpenClaw 에서 루프는 세션당 단일하고 직렬화된 실행이며, 모델이 사고하고, 도구를 호출하고, 출력을 스트리밍하는 동안 수명주기 및 스트림 이벤트를 방출합니다. 이 문서는 그 실제 루프가 처음부터 끝까지 어떻게 연결되는지를 설명합니다.

​

진입점

• Gateway RPC: agent 및 agent.wait.
• CLI: agent 명령.

​

작동 방식 (상위 수준)

1. agent RPC 가 매개변수를 검증하고, 세션을 확인(sessionKey/sessionId)하며, 세션 메타데이터를 영속화한 뒤 즉시 { runId, acceptedAt } 를 반환합니다.
2. agentCommand 가 에이전트를 실행합니다:
   • 모델 + thinking/verbose 기본값을 결정
   • Skills 스냅샷 로드
   • runEmbeddedPiAgent (pi-agent-core 런타임) 호출
   • 내장 루프가 수명주기 종료/오류를 방출하지 않을 경우 수명주기 종료/오류를 방출
3. runEmbeddedPiAgent:
   • 세션별 + 전역 큐를 통해 실행을 직렬화
   • 모델 + 인증 프로필을 확인하고 pi 세션을 구성
   • pi 이벤트를 구독하고 어시스턴트/도구 델타를 스트리밍
   • 타임아웃을 강제 적용 -> 초과 시 실행 중단
   • 페이로드 + 사용량 메타데이터 반환
4. subscribeEmbeddedPiSession 는 pi-agent-core 이벤트를 OpenClaw agent 스트림으로 브리지합니다:
   • 도구 이벤트 => stream: "tool"
   • 어시스턴트 델타 => stream: "assistant"
   • 수명주기 이벤트 => stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait 는 waitForAgentJob 를 사용합니다:
   • runId 에 대해 수명주기 종료/오류를 대기
   • { status: ok|error|timeout, startedAt, endedAt, error? } 반환

​

큐잉 + 동시성

• 실행은 세션 키(세션 레인)별로 직렬화되며, 선택적으로 전역 레인을 통과합니다.
• 이는 도구/세션 경합을 방지하고 세션 히스토리를 일관되게 유지합니다.
• 메시징 채널은 이 레인 시스템에 입력되는 큐 모드(collect/steer/followup)를 선택할 수 있습니다. 자세한 내용은 Command Queue를 참고하십시오.

​

세션 + 워크스페이스 준비

• 워크스페이스를 확인하고 생성합니다. 샌드박스화된 실행의 경우 샌드박스 워크스페이스 루트로 리디렉션될 수 있습니다.
• Skills 를 로드(또는 스냅샷에서 재사용)하여 환경과 프롬프트에 주입합니다.
• 부트스트랩/컨텍스트 파일을 확인하여 시스템 프롬프트 리포트에 주입합니다.
• 세션 쓰기 락을 획득하며, 스트리밍 전에 SessionManager 을 열고 준비합니다.

​

프롬프트 구성 + 시스템 프롬프트

• 시스템 프롬프트는 OpenClaw 기본 프롬프트, Skills 프롬프트, 부트스트랩 컨텍스트, 실행별 오버라이드를 조합하여 생성됩니다.
• 모델별 한계와 컴팩션 예약 토큰이 강제 적용됩니다.
• 모델이 실제로 보는 내용은 System prompt를 참고하십시오.

​

훅 포인트 (개입 가능한 지점)

OpenClaw 에는 두 가지 훅 시스템이 있습니다:

• 내부 훅 (Gateway 훅): 명령 및 수명주기 이벤트를 위한 이벤트 기반 스크립트.
• 플러그인 훅: 에이전트/도구 수명주기와 게이트웨이 파이프라인 내부의 확장 지점.

​

내부 훅 (Gateway 훅)

• agent:bootstrap: 시스템 프롬프트가 확정되기 전에 부트스트랩 파일을 구성하는 동안 실행됩니다. 이를 사용해 부트스트랩 컨텍스트 파일을 추가/제거할 수 있습니다.
• 명령 훅: /new, /reset, /stop, 그리고 기타 명령 이벤트 (Hooks 문서 참고).

설정과 예시는 Hooks를 참고하십시오.

​

플러그인 훅 (에이전트 + 게이트웨이 수명주기)

이 훅들은 에이전트 루프 또는 게이트웨이 파이프라인 내부에서 실행됩니다:

• before_agent_start: 실행 시작 전에 컨텍스트를 주입하거나 시스템 프롬프트를 오버라이드합니다.
• agent_end: 완료 후 최종 메시지 목록과 실행 메타데이터를 검사합니다.
• before_compaction / after_compaction: 컴팩션 사이클을 관찰하거나 주석을 추가합니다.
• before_tool_call / after_tool_call: 도구 매개변수/결과를 가로챕니다.
• tool_result_persist: 세션 전사에 기록되기 전에 도구 결과를 동기적으로 변환합니다.
• message_received / message_sending / message_sent: 인바운드 + 아웃바운드 메시지 훅.
• session_start / session_end: 세션 수명주기 경계.
• gateway_start / gateway_stop: 게이트웨이 수명주기 이벤트.

훅 API 와 등록 세부사항은 Plugins를 참고하십시오.

​

스트리밍 + 부분 응답

• 어시스턴트 델타는 pi-agent-core 에서 스트리밍되어 assistant 이벤트로 방출됩니다.
• 블록 스트리밍은 text_end 또는 message_end 에서 부분 응답을 방출할 수 있습니다.
• 추론 스트리밍은 별도의 스트림으로 또는 블록 응답 형태로 방출될 수 있습니다.
• 청킹 및 블록 응답 동작은 Streaming을 참고하십시오.

​

도구 실행 + 메시징 도구

• 도구 시작/업데이트/종료 이벤트는 tool 스트림으로 방출됩니다.
• 도구 결과는 로깅/방출 전에 크기 및 이미지 페이로드에 대해 정제됩니다.
• 메시징 도구 전송은 중복 어시스턴트 확인을 억제하기 위해 추적됩니다.

​

응답 구성 + 억제

• 최종 페이로드는 다음으로 구성됩니다:
  • 어시스턴트 텍스트 (및 선택적 추론)
  • 인라인 도구 요약 (verbose 이고 허용된 경우)
  • 모델 오류 시 어시스턴트 오류 텍스트
• NO_REPLY 는 무음 토큰으로 취급되며 외부로 나가는 페이로드에서 필터링됩니다.
• 메시징 도구 중복은 최종 페이로드 목록에서 제거됩니다.
• 렌더링 가능한 페이로드가 남지 않았고 도구 오류가 발생한 경우, 대체 도구 오류 응답이 방출됩니다 (메시징 도구가 이미 사용자에게 보이는 응답을 전송한 경우는 제외).

​

컴팩션 + 재시도

• 자동 컴팩션은 compaction 스트림 이벤트를 방출하며 재시도를 트리거할 수 있습니다.
• 재시도 시, 중복 출력 방지를 위해 메모리 내 버퍼와 도구 요약이 초기화됩니다.
• 컴팩션 파이프라인은 Compaction을 참고하십시오.

​

이벤트 스트림 (현재)

• lifecycle: subscribeEmbeddedPiSession 에 의해 방출됨 (및 대체 경로로 agentCommand)
• assistant: pi-agent-core 에서 스트리밍되는 델타
• tool: pi-agent-core 에서 스트리밍되는 도구 이벤트

​

채팅 채널 처리

• 어시스턴트 델타는 채팅 delta 메시지로 버퍼링됩니다.
• 채팅 final 는 수명주기 종료/오류 시 방출됩니다.

​

타임아웃

• agent.wait 기본값: 30초 (대기만). timeoutMs 매개변수로 오버라이드합니다.
• 에이전트 런타임: agents.defaults.timeoutSeconds 기본값 600초; runEmbeddedPiAgent 중단 타이머에서 강제 적용됩니다.

​

조기에 종료될 수 있는 지점

• 에이전트 타임아웃 (중단)
• AbortSignal (취소)
• Gateway 연결 해제 또는 RPC 타임아웃
• agent.wait 타임아웃 (대기 전용, 에이전트는 중단하지 않음)