Gateway lock

마지막 업데이트: 2025-12-11

이유

• 동일한 host의 base 포트당 하나의 gateway 인스턴스만 실행되도록 보장합니다. 추가 gateway는 격리된 profile과 고유한 포트를 사용해야 합니다.
• 오래된 lock 파일을 남기지 않고 충돌/SIGKILL을 견딥니다.
• Control 포트가 이미 점유되어 있을 때 명확한 오류와 함께 빠르게 실패합니다.

메커니즘

• Gateway는 시작 시 독점 TCP listener를 사용하여 WebSocket listener (기본값 ws://127.0.0.1:18789)를 즉시 바인딩합니다.
• 바인딩이 EADDRINUSE로 실패하면 시작 시 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")를 throw합니다.
• OS는 충돌 및 SIGKILL을 포함한 모든 프로세스 종료 시 listener를 자동으로 해제합니다. 별도의 lock 파일이나 정리 단계가 필요하지 않습니다.
• 종료 시 gateway는 WebSocket 서버와 기본 HTTP 서버를 닫아 포트를 즉시 해제합니다.

오류 surface

• 다른 프로세스가 포트를 보유하고 있으면 시작 시 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")를 throw합니다.
• 다른 바인딩 실패는 GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")로 표시됩니다.

운영 노트

• 포트가 다른 프로세스에 의해 점유된 경우 오류는 동일합니다. 포트를 해제하거나 openclaw gateway --port <port>로 다른 포트를 선택하세요.
• macOS app은 여전히 gateway를 생성하기 전에 자체 경량 PID 가드를 유지합니다. 런타임 lock은 WebSocket 바인딩에 의해 강제됩니다.