에이전트 루프(OpenClaw)

에이전트 루프는 에이전트의 완전한 "실제" 실행입니다. 즉, 섭취 → 컨텍스트 조립 → 모델 추론 → 도구 실행 → 스트리밍 응답 → 지속성. 메시지를 바꾸는 권위 있는 경로입니다 세션 상태를 일관되게 유지하면서 작업과 최종 응답으로 전환합니다.

OpenClaw에서 루프는 수명 주기 및 스트림 이벤트를 내보내는 세션당 단일 직렬화된 실행입니다. 모델이 생각하는 대로 도구를 호출하고 출력을 스트리밍합니다. 이 문서에서는 실제 루프가 어떻게 작동하는지 설명합니다. 종단 간 유선 연결.

진입점

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

작동 방식(상위 수준)

1. agent RPC는 매개변수의 유효성을 검사하고, 세션(sessionKey/sessionId)을 확인하고, 세션 메타데이터를 유지하고, 즉시 { runId, acceptedAt }를 반환합니다.
2. agentCommand 에이전트를 실행합니다.
   • 모델 + 사고/자세한 기본값 해결
   • 스킬 스냅샷 로드
   • runEmbeddedPiAgent 호출(pi-agent-core 런타임)
   • 내장된 루프가 오류를 발생시키지 않는 경우 수명 주기 종료/오류를 발생시킵니다.
3. runEmbeddedPiAgent:
   • 세션별 + 전역 대기열을 통해 실행을 직렬화합니다.
   • 모델 + 인증 프로필을 확인하고 파이 세션을 구축합니다.
   • 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? }를 반환합니다.

대기열 + 동시성

• 실행은 세션 키(세션 레인)별로 직렬화되며 선택적으로 전역 레인을 통해 직렬화됩니다.
• 이는 도구/세션 경합을 방지하고 세션 기록을 일관되게 유지합니다.
• 메시징 채널은 이 차선 시스템에 공급하는 대기열 모드(수집/조향/후속 조치)를 선택할 수 있습니다. 명령 대기열을 참조하세요.

세션 + 작업공간 준비

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

프롬프트 어셈블리 + 시스템 프롬프트

• 시스템 프롬프트는 OpenClaw의 기본 프롬프트, 스킬 프롬프트, 부트스트랩 컨텍스트 및 실행별 재정의로 구축됩니다.
• 모델별 제한 및 압축 예약 토큰이 시행됩니다.
• 모델이 보는 내용은 시스템 프롬프트를 참조하세요.

훅 포인트(요청할 수 있는 곳)

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

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

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

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

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

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

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

• 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: 게이트웨이 수명주기 이벤트.

Hook API 및 등록 세부정보는 플러그인을 참조하세요.

스트리밍 + 부분 응답

• 어시스턴트 델타는 pi-agent-core에서 스트리밍되고 assistant 이벤트로 방출됩니다.
• 블록 스트리밍은 text_end 또는 message_end에서 부분 응답을 내보낼 수 있습니다.
• 추론 스트리밍은 별도의 스트림으로 내보내거나 블록 응답으로 내보낼 수 있습니다.
• 청크 및 차단 응답 동작은 스트리밍을 참조하세요.

도구 실행 + 메시징 도구

• 도구 시작/업데이트/종료 이벤트는 tool 스트림에서 발생합니다.
• 도구 결과는 로깅/내보내기 전에 크기 및 이미지 페이로드에 대해 정리됩니다.
• 중복된 보조 확인을 억제하기 위해 메시징 도구 전송이 추적됩니다.

응답 형성 + 억제

• 최종 페이로드는 다음에서 조립됩니다.
  • 보조 텍스트(및 선택적 추론)
  • 인라인 도구 요약(상세 + 허용되는 경우)
  • 모델 오류 시 보조 오류 텍스트
• NO_REPLY는 자동 토큰으로 처리되며 나가는 페이로드에서 필터링됩니다.
• 메시징 도구 중복이 최종 페이로드 목록에서 제거됩니다.
• 렌더링 가능한 페이로드가 남아 있지 않고 도구에 오류가 발생한 경우 대체 도구 오류 응답이 표시됩니다. (메시징 도구가 이미 사용자에게 표시되는 응답을 보낸 경우는 제외)

압축 + 재시도

• 자동 압축은 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 시간 초과(대기 전용, 에이전트를 중지하지 않음)