진입점
- Gateway RPC:
agent및agent.wait. - CLI:
openclaw agent.
실행 순서
agentRPC는 매개변수를 검증하고, 세션(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_tool_call:{ block: true }는 최종 결정이며 우선순위가 낮은 핸들러의 실행을 중지합니다.{ block: false }는 아무 작업도 하지 않으며 이전 차단을 해제하지 않습니다.before_install: 위와 동일한 최종 결정/무동작 의미를 가집니다. CLI 설치 및 업데이트 경로에 적용되어야 하는 운영자 소유의 설치 허용/차단 결정에는before_install이 아닌security.installPolicy를 사용하십시오.message_sending:{ cancel: true }는 최종 결정이며 우선순위가 낮은 핸들러의 실행을 중지합니다.{ cancel: false }는 아무 작업도 하지 않으며 이전 취소를 해제하지 않습니다.
스트리밍
- 어시스턴트 델타는 에이전트 런타임에서
assistant이벤트로 스트리밍됩니다. - 블록 스트리밍은
text_end또는message_end에서 부분 응답을 내보낼 수 있습니다. - 추론 스트리밍은 별도의 스트림이거나 응답을 차단할 수 있습니다.
- 청크 처리 및 블록 응답 동작은 스트리밍을 참조하십시오.
도구 실행
- 도구 시작/업데이트/종료 이벤트는
tool스트림으로 내보내집니다. - 도구 결과는 로깅/방출 전에 크기 및 이미지 페이로드에 대해 정리됩니다.
- 메시징 도구 전송은 중복 어시스턴트 확인 메시지를 억제하도록 추적됩니다.
응답 구성
최종 페이로드는 어시스턴트 텍스트(선택적 추론 포함), 인라인 도구 요약(verbose이고 허용되는 경우), 모델 오류 시 어시스턴트 오류 텍스트로 구성됩니다.- 정확한 무응답 토큰
NO_REPLY는 발신 페이로드에서 필터링됩니다. - 메시징 도구의 중복 항목은 최종 페이로드 목록에서 제거됩니다.
- 렌더링 가능한 페이로드가 남아 있지 않고 도구에서 오류가 발생한 경우, 메시징 도구가 이미 사용자에게 표시되는 응답을 전송하지 않았다면 대체 도구 오류 응답이 내보내집니다.
Compaction 및 재시도
자동 Compaction은compaction 스트림 이벤트를 내보내며 재시도를 트리거할 수 있습니다. 재시도 시 출력 중복을 방지하기 위해 메모리 내 버퍼와 도구 요약이 초기화됩니다. Compaction을 참조하십시오.
이벤트 스트림
lifecycle:subscribeEmbeddedAgentSession에서 내보냅니다(agentCommand에서 대체 이벤트로 내보내기도 함).assistant: 에이전트 런타임에서 스트리밍되는 델타입니다.tool: 에이전트 런타임에서 스트리밍되는 도구 이벤트입니다.
채팅 채널 처리
어시스턴트 델타는 채팅delta 메시지로 버퍼링됩니다. 수명 주기 종료/오류 시 채팅 final이 내보내집니다.
제한 시간
멈춘 세션 진단
진단이 활성화되면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시간 제한(대기 전용이며 에이전트를 중지하지 않음)
관련 문서
- 도구 - 사용 가능한 에이전트 도구
- 훅 - 에이전트 수명 주기 이벤트로 트리거되는 이벤트 기반 스크립트
- Compaction - 긴 대화를 요약하는 방식
- 실행 승인 - 셸 명령의 승인 게이트
- 사고 - 사고/추론 수준 구성