OpenClaw 게이트웨이 중복 실행 방지: 포트 충돌 해결 가이드

개발을 하다 보면 같은 포트에 여러 프로세스가 동시에 뜨려고 해서 설정이 꼬이는 상황을 자주 겪게 됩니다. 특히 프로그램이 갑자기 종료된 후에 지워지지 않은 잠금 파일 때문에 재시작이 안 되면 정말 번거롭죠. Gateway lock은 이런 문제를 깔끔하게 해결해 줍니다.

Gateway lock

왜 필요한가요?

• 동일한 호스트의 기본 포트당 하나의 Gateway 인스턴스만 실행되도록 보장하며, 크래시나 SIGKILL이 발생해도 찌꺼기 잠금 파일을 남기지 않습니다.
• 컨트롤 포트가 이미 점유되어 있다면 명확한 에러 메시지와 함께 즉시 실행을 멈춰서 혼선을 방지합니다.

작동 원리

• Gateway는 시작할 때 독점적인 TCP 리스너를 사용하여 WebSocket 리스너(기본값 ws://127.0.0.1:18789)를 즉시 바인딩합니다.
• 바인딩이 EADDRINUSE 에러로 실패하면, 시작 시 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")를 던집니다.
• OS는 크래시나 SIGKILL을 포함한 모든 프로세스 종료 시 리스너를 자동으로 해제합니다. 별도의 잠금 파일이나 정리 단계가 필요 없어서 깔끔해요.
• 종료 시 Gateway는 WebSocket 서버와 하위 HTTP 서버를 닫아 포트를 즉시 해제합니다.

에러 케이스

• 다른 프로세스가 포트를 점유하고 있다면, 시작 시 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")가 발생합니다.
• 그 외의 바인딩 실패는 GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")로 나타납니다.

운영 참고 사항

• 포트가 다른 프로세스에 의해 점유된 경우에도 에러는 동일합니다. 포트를 비우거나 openclaw gateway --port <port> 명령어로 다른 포트를 선택하면 됩니다.
• macOS 앱은 Gateway를 실행하기 전에 자체적인 경량 PID 가드를 유지하지만, 실제 런타임 잠금은 WebSocket 바인딩을 통해 강제됩니다.

관련 문서

• Multiple Gateways — 고유한 포트로 여러 인스턴스 실행하기
• Troubleshooting — EADDRINUSE 및 포트 충돌 진단하기

다음 단계

• Multiple Gateways
• Troubleshooting

AI Setup Assistant