​

Agent Loop (OpenClaw)

에이전틱 루프는 에이전트의 완전한 “실제” 실행입니다: 수집 → 컨텍스트 조립 → 모델 추론 → 도구 실행 → 스트리밍 응답 → 지속성. 이는 메시지를 실행과 최종 응답으로 변환하는 권위 있는 경로이며, 세션 상태를 일관되게 유지합니다. OpenClaw에서는 루프가 세션당 단일 직렬 실행으로, 모델이 사고하고, 도구를 호출하고, 출력을 스트리밍할 때 라이프사이클 및 스트림 이벤트를 발생시킵니다. 이 문서는 그러한 진정한 루프가 어떻게 종단 간 연결되는지를 설명합니다.

​

진입점

• 게이트웨이 RPC: agent 및 agent.wait.
• CLI: agent 명령어.

​

작동 방식 (고수준)

1. agent RPC는 매개변수를 검증하고, 세션(sessionKey/sessionId)을 해결하며, 세션 메타데이터를 지속하고, { runId, acceptedAt }을 즉시 반환합니다.
2. agentCommand는 에이전트를 실행합니다:
   • 모델과 사고/상세 기본값을 해결합니다.
   • 스킬 스냅샷을 로드합니다.
   • 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? }을 반환합니다.

​

큐잉 + 병행성

• 실행은 세션 키(세션 경로)별로 직렬화되며, 선택적으로 글로벌 경로를 통해 직렬화됩니다.
• 이는 도구/세션 경합을 방지하고 세션 기록을 일관되게 유지합니다.
• 메시징 채널은 이 경로 시스템에 피드할 수 있는 큐 모드(수집/조정/후속)를 선택할 수 있습니다. Command Queue를 참조하세요.

​

세션 + 작업 공간 준비

• 작업 공간이 해결되고 생성됩니다; 샌드박스 격리 실행은 샌드박스 작업 공간 루트로 리디렉션될 수 있습니다.
• 스킬이 로드되거나 (또는 스냅샷에서 재사용되어) 환경 및 프롬프트에 주입됩니다.
• 부트스트랩/컨텍스트 파일이 해결되고 시스템 프롬프트 보고서에 주입됩니다.
• 세션 쓰기 잠금이 획득됩니다; SessionManager가 열리고 스트리밍 전 준비됩니다.

​

프롬프트 조립 + 시스템 프롬프트

• 시스템 프롬프트는 OpenClaw의 기본 프롬프트, 스킬 프롬프트, 부트스트랩 컨텍스트, 실행당 오버라이드로 구성됩니다.
• 모델별 제한 및 압축 예약 토큰이 강제 적용됩니다.
• 모델이 보는 것을 확인하려면 System prompt를 참조하세요.

​

후크 포인트 (가로챌 수 있는 지점)

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

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

​

내부 후크 (게이트웨이 후크)

• agent:bootstrap: 시스템 프롬프트가 완료되기 전에 부트스트랩 파일을 구성하는 동안 실행됩니다. 부트스트랩 컨텍스트 파일을 추가/제거하는 데 사용하세요.
• 명령 후크: /new, /reset, /stop, 및 기타 명령 이벤트 (후크 문서 참조).

설정 및 예시는 Hooks를 참조하세요.

​

플러그인 후크 (에이전트+게이트웨이 라이프사이클)

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

• before_model_resolve: 세션 전 (no messages)에 실행되어 결정적으로 프로바이더/모델을 모델 해결 전에 오버라이드합니다.
• before_prompt_build: 세션 로드 후 (with messages) 실행되어 프롬프트 제출 전 prependContext/systemPrompt를 주입합니다.
• 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 스트림에서 출력됩니다.
• 도구 결과는 크기 및 이미지 페이로드에 대한 로그/출력을 위해 정리됩니다.
• 메시징 도구 전송은 중복 어시스턴트 확인을 억제하기 위해 추적됩니다.

​

응답 형성 + 억제

• 최종 페이로드는 다음으로 구성됩니다:
  • 어시스턴트 텍스트 (그리고 선택적인 추론)
  • 인라인 도구 요약 (상세 + 허용 시)
  • 모델 오류 발생 시 어시스턴트 오류 텍스트
• 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 (취소)
• 게이트웨이 연결 끊김 또는 RPC 타임아웃
• agent.wait 타임아웃 (대기 전용, 에이전트는 중지되지 않음)