[공지] OpenClaw 최신 버전 Bonjour 관련 오류 안내 및 해결 방법
1. 증상 안내
제가 오늘 날짜 기준(2026-04-27)으로 docker pull로 OpenClaw 이미지를 최신 버전(2026.4.x)으로 업데이트한 이후, 일부 환경에서 Gateway 컨테이너가 계속 재시작되는 현상이 발생하고 있습니다.
openclaw-gateway 로그에 아래와 비슷한 메시지가 반복되면 이 이슈에 해당합니다.
[plugins] bonjour: advertised gateway fqdn=... state=announcing
[plugins] bonjour: restarting advertiser (service stuck in announcing ...)
[openclaw] Unhandled promise rejection: CIAO ANNOUNCEMENT CANCELLED
openclaw-gateway exited with code 1 (restarting)이 경우:
- openclaw-gateway 컨테이너가 몇 초마다 올라갔다가 바로 종료되고,
- 대시보드 접속 및 텔레그램 연동이 정상적으로 되지 않을 수 있습니다.
2. 원인 – Bonjour(mDNS) 광고 과정 버그
OpenClaw Gateway는 기본적으로 Bonjour(mDNS) 를 사용해 같은 네트워크에서 이 인스턴스를 자동으로 찾을 수 있게(advertise) 해 둡니다.
일부 Docker / WSL / 네트워크(공유기, 회사망 등) 환경에서:
- Bonjour advertise 상태가announcing 단계에서 멈춘 뒤,
- CIAO ANNOUNCEMENT CANCELLED라는 에러가 발생하고,
- 이 예외가 제대로 처리되지 않아 Gateway 프로세스가 크래시 루프에 빠지는 버그가 있습니다.
현재 관련 패치가 진행 중이며, 그 전까지는 아래 방법으로 우회해 사용할 수 있습니다.
3. 해결 방법 – Bonjour 기능 비활성화 (권장)
1부/2부 실습은 로컬 한 대에서만 사용하는 구조라 Bonjour가 꼭 필요하지 않습니다.
따라서 환경 변수로 Bonjour를 끄는 것을 권장드립니다.
3-1. docker-compose.yml 사용하는 경우
openclaw-gateway 서비스에 다음 환경 변수를 추가하세요.
services:
openclaw-gateway:
image: ghcr.io/openclaw/openclaw:latest
environment:
- OPENCLAW_DISABLE_BONJOUR=1
# 나머지 OPENCLAW 관련 설정들...변경 후 아래 명령으로 재시작합니다.
docker compose down
docker compose up -d이 설정을 적용하면:
- Gateway가 Bonjour/mDNS 광고를 시도하지 않게 되어,
- CIAO ANNOUNCEMENT CANCELLED 에러 경로를 타지 않고 안정적으로 실행됩니다.
- 1부/2부에서 사용하는 브라우저 접속(대시보드)과 텔레그램 연동에는 영향을 주지 않습니다.
4. 향후 안내
- 이 이슈는 OpenClaw의 Bonjour 플러그인과 특정 네트워크/Docker 환경의 궁합 문제로, 향후 릴리스에서 개선될 예정입니다.
- 패치 이후에도,
- 로컬 한 대에서만 사용하는 경우에는 계속 OPENCLAW_DISABLE_BONJOUR=1를 유지하셔도 되고,
- 여러 기기에서 OpenClaw 인스턴스를 자동 검색해야 할 때만 Bonjour를 다시 활성화하시면 됩니다.
최근 이미지를 다시 pull 받은 뒤 갑자기 Gateway가 계속 꺼지는 현상을 겪으신 1부/2부 수강자 분들은,
위 설정을 적용해 Bonjour 기능을 비활성화해 주시기 바랍니다.
감사합니다!