> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openclaw.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Loop

# 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](/ko-KR/concepts/queue)를 참조하세요.

## 세션 + 작업 공간 준비

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

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

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

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

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

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

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

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

설정 및 예시는 [Hooks](/ko-KR/automation/hooks)를 참조하세요.

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

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

* **`before_model_resolve`**: 세션 전 (no `messages`)에 실행되어 결정적으로 프로바이더/모델을 모델 해결 전에 오버라이드합니다.
* **`before_prompt_build`**: 세션 로드 후 (with `messages`) 실행되어 프롬프트 제출 전 `prependContext`, `systemPrompt`, `prependSystemContext`, `appendSystemContext`를 주입합니다. 턴마다 바뀌는 동적 텍스트에는 `prependContext`를, 시스템 프롬프트 영역에 안정적으로 유지돼야 하는 지침에는 system-context 필드를 사용하십시오.
* **`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](/ko-KR/tools/plugin#plugin-hooks)를 참조하세요.

## 스트리밍 + 부분 응답

* 어시스턴트 델타는 pi-agent-core에서 스트리밍되며 `assistant` 이벤트로 출력됩니다.
* 블록 스트리밍은 `text_end` 또는 `message_end`에서 부분 응답을 출력할 수 있습니다.
* 추론 스트리밍은 별도의 스트림 또는 블록 응답으로 출력될 수 있습니다.
* 조각 및 블록 응답 동작에 대해서는 [Streaming](/ko-KR/concepts/streaming)을 참조하세요.

## 도구 실행 + 메시징 도구

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

## 응답 형성 + 억제

* 최종 페이로드는 다음으로 구성됩니다:
  * 어시스턴트 텍스트 (그리고 선택적인 추론)
  * 인라인 도구 요약 (상세 + 허용 시)
  * 모델 오류 발생 시 어시스턴트 오류 텍스트
* `NO_REPLY`는 무음 토큰으로 처리되며 출력 페이로드에서 필터링됩니다.
* 메시징 도구의 중복 항목은 최종 페이로드 목록에서 제거됩니다.
* 렌더 가능한 페이로드가 남지 않고 도구가 오류를 발생시키면 대체 도구 오류 응답이 출력됩니다
  (메시징 도구가 이미 사용자에게 보이는 응답을 보낸 경우는 제외).

## 압축 + 재시도

* 자동 압축은 `compaction` 스트림 이벤트를 발생시키고 재시도를 트리거할 수 있습니다.
* 재시도 시, 메모리 내 버퍼 및 도구 요약이 중복 출력 방지를 위해 리셋됩니다.
* 압축 파이프라인에 대해서는 [Compaction](/ko-KR/concepts/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` 타임아웃 (대기 전용, 에이전트는 중지되지 않음)