Fundamentals

에이전트 루프

에이전트 루프는 메시지를 작업과 응답으로 변환하는 세션별 직렬 실행입니다. 입력 수신, 컨텍스트 구성, 모델 추론, 도구 실행, 스트리밍, 영속화로 이루어집니다.

진입점

Gateway RPC: agent 및 agent.wait.
CLI: openclaw agent.

실행 순서

agent RPC는 매개변수를 검증하고, 세션(sessionKey/sessionId)을 확인하며, 세션 메타데이터를 영속화한 후 { runId, acceptedAt }를 즉시 반환합니다.
agentCommand는 해당 턴을 실행합니다. 모델과 thinking/verbose/trace 기본값을 확인하고, Skills 스냅샷을 로드하며, runEmbeddedAgent를 호출한 후, 내장 루프가 아직 내보내지 않았다면 대체 수명 주기 종료/오류를 내보냅니다.
runEmbeddedAgent: 세션별 큐와 전역 큐를 통해 실행을 직렬화하고, 모델과 인증 프로필을 확인하며, OpenClaw 세션을 구성하고, 런타임 이벤트를 구독하며, 어시스턴트/도구 델타를 스트리밍하고, 실행 제한 시간을 적용하여 만료 시 중단하며, 사용량 메타데이터와 함께 페이로드를 반환합니다. Codex app-server 턴의 경우, 승인된 턴이 종료 이벤트 전에 app-server 진행 상황 생성을 멈추면 해당 턴도 중단합니다.
subscribeEmbeddedAgentSession은 런타임 이벤트를 agent 스트림에 연결합니다. 도구 이벤트는 stream: "tool", 어시스턴트 델타는 stream: "assistant", 수명 주기 이벤트는 stream: "lifecycle"(phase: "start" | "end" | "error")로 전달합니다.
agent.wait(waitForAgentRun)는 runId의 수명 주기 종료/오류를 기다린 후 { status: ok|error|timeout, startedAt, endedAt, error? }를 반환합니다.

큐 처리 및 동시성

실행은 세션 키별로(세션 레인) 직렬화되며, 선택적으로 전역 레인을 거쳐 도구/세션 경합을 방지합니다. 메시징 채널은 이 레인 시스템에 작업을 공급하는 큐 모드(steer/followup/collect/interrupt)를 선택합니다. 명령 큐를 참조하십시오.

트랜스크립트 쓰기는 세션 파일에 대한 세션 쓰기 잠금으로 추가 보호됩니다. 이 잠금은 프로세스를 인식하는 파일 기반 잠금이므로, 프로세스 내부 큐를 우회하거나 다른 프로세스에서 발생한 쓰기도 감지합니다. 작성자는 세션이 사용 중이라고 보고하기 전에 최대 session.writeLock.acquireTimeoutMs(기본값 60000ms, 환경 변수 재정의 OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS)까지 기다립니다.

세션 쓰기 잠금은 기본적으로 재진입할 수 없습니다. 하나의 논리적 작성자를 유지하면서 의도적으로 동일한 잠금 획득을 중첩하는 헬퍼는 allowReentrant: true를 명시적으로 설정해야 합니다.

세션 및 워크스페이스 준비

워크스페이스를 확인하고 생성합니다. 샌드박스 실행은 샌드박스 워크스페이스 루트로 리디렉션될 수 있습니다.
Skills를 로드하거나 스냅샷에서 재사용하여 환경 및 프롬프트에 삽입합니다.
부트스트랩/컨텍스트 파일을 확인하여 시스템 프롬프트에 삽입합니다.
스트리밍이 시작되기 전에 세션 쓰기 잠금을 획득하고 세션 트랜스크립트 대상을 준비합니다. 이후의 모든 트랜스크립트 재작성, Compaction 또는 잘라내기 경로는 SQLite 트랜스크립트 행을 변경하기 전에 동일한 잠금을 획득해야 합니다.

프롬프트 구성

시스템 프롬프트는 OpenClaw의 기본 프롬프트, Skills 프롬프트, 부트스트랩 컨텍스트 및 실행별 재정의로 구성됩니다. 모델별 제한과 Compaction 예약 토큰이 적용됩니다. 모델에 표시되는 내용은 시스템 프롬프트를 참조하십시오.

훅

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

내부 훅(Gateway 훅): 명령 및 수명 주기 이벤트를 위한 이벤트 기반 스크립트입니다.
Plugin 훅: 에이전트/도구 수명 주기 및 Gateway 파이프라인 내부의 확장 지점입니다.

내부 훅(Gateway 훅)

agent:bootstrap: 시스템 프롬프트가 확정되기 전 부트스트랩 파일을 구성하는 동안 실행됩니다. 부트스트랩 컨텍스트 파일을 추가하거나 제거하는 데 사용합니다.
명령 훅: /new, /reset, /stop 및 기타 명령 이벤트입니다(훅 문서 참조).

설정 및 예시는 훅을 참조하십시오.

Plugin 훅

다음 훅은 에이전트 루프 또는 Gateway 파이프라인 내부에서 실행됩니다.

훅	실행 시점
`before_model_resolve`	세션 전(`messages` 없음)에 실행되어 확인 전에 제공자/모델을 결정론적으로 재정의합니다.
`before_prompt_build`	세션 로드 후(`messages` 포함)에 실행되어 제출 전에 `prependContext`, `systemPrompt`, `prependSystemContext` 또는 `appendSystemContext`를 삽입합니다. 턴별 동적 텍스트에는 `prependContext`를 사용하고, 시스템 프롬프트 영역에 속하는 안정적인 지침에는 시스템 컨텍스트 필드를 사용합니다.
`before_agent_start`	어느 단계에서든 실행될 수 있는 레거시 호환성 훅입니다. 위의 명시적 훅을 사용하는 것이 좋습니다.
`before_agent_reply`	인라인 작업 이후 LLM 호출 전에 실행됩니다. Plugin이 해당 턴을 처리하여 합성 응답을 반환하거나 응답을 완전히 억제할 수 있습니다.
`agent_end`	완료 후 최종 메시지 목록 및 실행 메타데이터와 함께 실행됩니다.
`before_compaction` / `after_compaction`	Compaction 주기를 관찰하거나 주석을 추가합니다.
`before_tool_call` / `after_tool_call`	도구 매개변수/결과를 가로챕니다.
`before_install`	운영자 설치 정책이 실행된 후, 현재 프로세스에 Plugin 훅이 로드되어 있을 때 스테이징된 Skills/Plugin 설치 자료에 대해 실행됩니다.
`tool_result_persist`	도구 결과가 OpenClaw 소유 세션 트랜스크립트에 기록되기 전에 동기적으로 변환합니다.
`message_received` / `message_sending` / `message_sent`	수신 및 발신 메시지 훅입니다.
`session_start` / `session_end`	세션 수명 주기 경계입니다.
`gateway_start` / `gateway_stop`	Gateway 수명 주기 이벤트입니다.

발신/도구 가드에 대한 훅 결정 규칙은 다음과 같습니다.

before_tool_call: { block: true }는 최종 결정이며 우선순위가 낮은 핸들러의 실행을 중지합니다. { block: false }는 아무 작업도 하지 않으며 이전 차단을 해제하지 않습니다.
before_install: 위와 동일한 최종 결정/무동작 의미를 가집니다. CLI 설치 및 업데이트 경로에 적용되어야 하는 운영자 소유의 설치 허용/차단 결정에는 before_install이 아닌 security.installPolicy를 사용하십시오.
message_sending: { cancel: true }는 최종 결정이며 우선순위가 낮은 핸들러의 실행을 중지합니다. { cancel: false }는 아무 작업도 하지 않으며 이전 취소를 해제하지 않습니다.

훅 API 및 등록에 대한 자세한 내용은 Plugin 훅을 참조하십시오.

하네스는 이러한 훅을 조정할 수 있습니다. Codex app-server 하네스는 문서화되어 미러링된 표면의 호환성 계약으로 OpenClaw Plugin 훅을 유지합니다. Codex 네이티브 훅은 별도의 저수준 Codex 메커니즘입니다.

스트리밍

어시스턴트 델타는 에이전트 런타임에서 assistant 이벤트로 스트리밍됩니다.
블록 스트리밍은 text_end 또는 message_end에서 부분 응답을 내보낼 수 있습니다.
추론 스트리밍은 별도의 스트림이거나 응답을 차단할 수 있습니다.
청크 처리 및 블록 응답 동작은 스트리밍을 참조하십시오.

도구 실행

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

응답 구성

최종 페이로드는 어시스턴트 텍스트(선택적 추론 포함), 인라인 도구 요약(verbose이고 허용되는 경우), 모델 오류 시 어시스턴트 오류 텍스트로 구성됩니다.

정확한 무응답 토큰 NO_REPLY는 발신 페이로드에서 필터링됩니다.
메시징 도구의 중복 항목은 최종 페이로드 목록에서 제거됩니다.
렌더링 가능한 페이로드가 남아 있지 않고 도구에서 오류가 발생한 경우, 메시징 도구가 이미 사용자에게 표시되는 응답을 전송하지 않았다면 대체 도구 오류 응답이 내보내집니다.

Compaction 및 재시도

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

이벤트 스트림

lifecycle: subscribeEmbeddedAgentSession에서 내보냅니다(agentCommand에서 대체 이벤트로 내보내기도 함).
assistant: 에이전트 런타임에서 스트리밍되는 델타입니다.
tool: 에이전트 런타임에서 스트리밍되는 도구 이벤트입니다.

Gateway는 수명 주기 및 도구 시작/종료 이벤트를 크기가 제한된 메타데이터 전용 감사 원장에 투영합니다. 이 투영은 프롬프트, 메시지, 도구 인수, 도구 결과 또는 원시 오류를 트랜스크립트/런타임 경로 외부로 복사하지 않고 출처와 결과 코드를 기록합니다.

채팅 채널 처리

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

제한 시간

시간 제한	기본값	참고
`agent.wait`	30s	대기 전용이며, `timeoutMs` 매개변수로 재정의할 수 있습니다. 기본 실행은 중지하지 않습니다.
에이전트 런타임 (`agents.defaults.timeoutSeconds`)	172800s (48h)	`runEmbeddedAgent`의 중단 타이머가 적용합니다. 실행 시간 예산을 무제한으로 설정하려면 `0`으로 지정하십시오. 모델 스트림 활성 상태 감시 타이머는 계속 적용됩니다.
Cron 격리 에이전트 턴	cron에서 관리	스케줄러는 실행이 시작될 때 자체 타이머를 시작하고, 구성된 기한에 실행을 중단한 다음, 시간 제한을 기록하기 전에 제한된 정리 작업을 실행하여 오래된 하위 세션 때문에 레인이 계속 멈춰 있지 않도록 합니다.
모델 유휴 시간 제한	클라우드 120s, 자체 호스팅 300s	유휴 시간 내에 응답 청크가 도착하지 않으면 OpenClaw가 모델 요청을 중단합니다. `models.providers.<id>.timeoutSeconds`는 느린 로컬/자체 호스팅 제공자를 위해 이 유휴 감시 타이머를 연장하지만, 전체 에이전트 실행을 제어하는 더 짧은 유한 `agents.defaults.timeoutSeconds` 또는 실행별 시간 제한이 있으면 해당 제한을 넘지 않습니다. 무제한 실행 시간 예산에서도 제공자 분류별 유휴 감시 타이머는 유지됩니다. 명시적인 모델/에이전트 시간 제한 없이 Cron으로 트리거된 클라우드 모델 실행에도 동일한 기본값이 적용됩니다. 명시적인 Cron 실행 시간 제한이 있으면 외부 Cron 기한 전에 구성된 모델 폴백을 계속 실행할 수 있도록 클라우드 모델 스트림 중단의 상한이 60s로 설정됩니다. 실제 로컬 엔드포인트(루프백/비공개 baseUrl)에서 Cron으로 트리거된 실행은 로컬 유휴 제한 제외를 유지하며, 네트워크 baseUrl을 사용하는 자체 호스팅 제공자에는 암시적인 300s 감시 타이머가 적용됩니다. 명시적인 Cron 실행 시간 제한이 있으면 로컬/자체 호스팅 중단의 상한은 해당 시간 제한입니다. 느린 로컬 제공자에는 `models.providers.<id>.timeoutSeconds`를 설정하십시오.
제공자 HTTP 요청 시간 제한	`models.providers.<id>.timeoutSeconds`	해당 제공자의 연결, 헤더, 본문, SDK 요청 시간 제한, 보호된 가져오기 중단 처리 및 모델 스트림 유휴 감시 타이머에 적용됩니다. 전체 에이전트 런타임 시간 제한을 늘리기 전에 느린 로컬/자체 호스팅 제공자(예: Ollama)에 사용하십시오. 모델 요청을 더 오래 실행해야 하는 경우 에이전트/런타임 시간 제한을 최소한 그만큼 길게 유지하십시오.

멈춘 세션 진단

진단이 활성화되면 diagnostics.stuckSessionWarnMs(기본값 120000 ms)는 관찰된 응답, 도구, 상태, 차단 또는 ACP 진행 없이 오랫동안 processing 상태인 세션을 분류합니다.

활성 임베디드 실행, 모델 호출 및 도구 호출은 session.long_running으로 보고됩니다. 소유자가 있는 무응답 모델 호출은 느리거나 스트리밍하지 않는 제공자가 너무 일찍 멈춘 것으로 표시되지 않도록 diagnostics.stuckSessionAbortMs까지 session.long_running 상태를 유지합니다.
최근 진행이 없는 활성 작업은 session.stalled로 보고됩니다. 소유자가 있는 모델 호출은 중단 임계값에 도달하거나 이를 넘으면 session.stalled로 전환됩니다. 소유자가 없는 오래된 모델/도구 활동은 장기 실행 상태로 숨겨지지 않습니다.
session.stuck은 소유자가 없는 오래된 모델/도구 활동이 있는 유휴 대기 세션을 포함하여 복구 가능한 오래된 세션 관리 상태에만 사용됩니다.

diagnostics.stuckSessionAbortMs의 기본값은 최소 5분이며 경고 임계값의 3배입니다. 오래된 세션 관리 상태는 복구 게이트를 통과한 직후 영향을 받은 세션 레인을 해제합니다. 멈춘 임베디드 실행은 중단 임계값 이후에만 중단 및 정리되므로, 단순히 느린 실행을 끊지 않고 대기 중인 작업이 재개됩니다. 복구 시 요청됨/완료됨 결과가 구조화된 형태로 발생합니다. 동일한 처리 세대가 여전히 현재 상태인 경우에만 진단 상태가 유휴로 표시되며, 세션이 변경되지 않은 동안 반복되는 session.stuck 진단에는 백오프가 적용됩니다.

조기에 종료될 수 있는 경우

에이전트 시간 제한(중단)
AbortSignal(취소)
Gateway 연결 해제 또는 RPC 시간 제한
agent.wait 시간 제한(대기 전용이며 에이전트를 중지하지 않음)