brief

OpenClaw ACP 프로토콜의 메시지 정규화와 Lane Queue·Skills-as-Markdown 아키텍처 분석

핵심 요약

OpenClaw ACP는 클라이언트 세션을 Gateway 세션 키에 매핑하여 Gateway의 라우팅 테이블로 관리하며, indication 메시지에 세션 키를 포함시켜 서버에 등록하는 구조를 취한다. 이 매핑을 통해 여러 IDE가 동시에 동일한 에이전트 세션을 공유하고 상태를 일관되게 유지할 수 있으며, 네트워크 환경에서 직접 연결 없이도 안정된 통신 채널을 확보한다.

이 글의 핵심 주장과 근거

핵심 주장

OpenClaw의 acp spawn 명령어는 ACP 프로토콜을.bootstrap하여.codex 및 claude ACP 어댑터를 초기화하며, 이는 OpenClaw가 ACP 런타임에 연결되기 위해 먼저 ACP를 부트스트랩해야 한다는 전제 조건을 갖는다.

직접 근거: [1] ZeroInput 직접 경험

핵심 주장

Gateway 재시작 시 ACP 세션이 사멸 처리되어 재시도 루프에 빠지고 복구되지 않는 치명적 취약점이 존재하며,-identity reconciliation 결과가 resolved=0 failed=N으로 모든 세션이 영구 실패하는 현상이 확인되었다.

출처: [1] Tistory

세션 라우팅과 Gateway 연동 구조

OpenClaw ACP는 각 클라이언트 세션을 고유한 Gateway 세션 키에 매핑한다. 이 매핑은 Gateway가 관리하는 라우팅 테이블에 저장되며, 클라이언트는 자신의 세션 키를 indication 메시지에 포함시켜 서버에 등록한다. 이렇게 함으로써 여러 IDE가 동시에 동일한 에이전트 세션을 공유하고 상태를 일관되게 유지할 수 있다. 매핑을 통해 네트워크 환경에서 직접적인 연결 없이도 안정된 통신 채널을 확보한다.

WebSocket 기반 프롬프트 전달 메커니즘

IDE와 Gateway 사이의 메시지는 기본적으로 stdio 스트림을 통해 교환되지만, 중요한 프롬프트와 실행 결과는 WebSocket 연결을 사용한다. WebSocket은 양방향 비동기 채널로, IDE가 입력한 사용자 입력을 즉시 전송하고 Gateway가 생성한 출력(예: 컴파일 로그, 테스트 결과)을 실시간으로 전달한다. 이 구조는 대용량 출력이 필요한 상황에서 특히 유용하며, Lane Queue 메커니즘을 통해 우선순위가 높은 프롬프트가 먼저 처리되도록 보장한다.

Skills-as-Markdown 적용과 정규화 흐름

Skills-as-Markdown 아키텍처는 각 기술을 마크다운 형식으로 표현하여 재사용 가능하고 가독성 높은 문서로 전환한다. 기술 요소는 명시적인 마크업을 통해 정의되며, ACP 세션 내에서 자동 실행 또는 검증이 가능하다. 정규화 과정은 라인 단위 파싱 후 Lane Queue에 배치해 우선순위를 정렬하고, 최종적으로 표준화된 마크다운 콘텐츠로 변환한다. 이를 통해 팀 간 이해도를 높이고 자동화 파이프라인에서도 쉽게 파싱할 수 있다.