[기초 1부] OpenClaw.AI 마스터 클래스: Gemini와 Docker로 만드는 나만의 자율형 AI 에이전트

[공지] 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 기능을 비활성화해 주시기 바랍니다.

감사합니다!