2026년 OpenClaw 텔레그램: 원격 물리 Mac에서 롱 폴링 vs 웹훅—HTTPS 역프록시, 등록·409/TLS 타임아웃 재현 Runbook(openclaw.json+FAQ)

2. 자주 겪는 문제

1. 웹훅에 필요한 공인 HTTPS를 과소평가함. 텔레그램은 검증 가능한 체인과 도달 가능한 HTTPS(보통 443)를 기대합니다. 자체 서명, 중간 인증서 누락, LAN에서만 풀리는 DNS는 TLS 오류나 무반응으로 이어집니다.
2. HTTP 409는 무작위가 아님. 스테이징·프로덕션이 한 봇 토큰을 공유하거나, 예전 노드가 deleteWebhook 없이 남아 있으면 setWebhook 충돌이 납니다. 근본 원인은 등록 상태이지 OpenClaw 비즈니스 로직이 아닙니다.
3. 롱 폴링도 비용이 있다. 국경 간 RTT와 장시간 유지 연결은 지터를 키우고, 일부 회선은 스로틀링합니다. PoC에는 좋지만 프로덕션은 보통 웹훅과 건강한 엣지로 돌아옵니다.

3. 롱 폴링 vs 웹훅 매트릭스

ZoneMac 원격 노드에 대한 가벼운 「아키텍처 사인오프」 용도로 쓰세요.

4. openclaw.json 스니펫(예시)

구조 예시일 뿐이며, 키 이름·중첩은 사용 중인 OpenClaw 버전과 일치해야 합니다. 프로덕션 파일은 백업 후 기존 gateway·자격 증명 블록과 수동 병합하세요. 게이트웨이를 컨테이너에 둘지 베어메탈에 둘지는 팀의 배포 표준과 헬스 프로브 가용성에 맞추면 됩니다.

4.1 텔레그램 채널: 웹훅 + 로컬 리스너

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botTokenRef": "env:TELEGRAM_BOT_TOKEN",
      "transport": "webhook",
      "webhook": {
        "publicUrl": "https://bot.example.com/openclaw/telegram/webhook",
        "path": "/openclaw/telegram/webhook",
        "secretTokenRef": "env:TELEGRAM_WEBHOOK_SECRET",
        "maxConnections": 40,
        "dropPendingUpdates": false
      },
      "localServer": {
        "bind": "127.0.0.1",
        "port": 18789,
        "readTimeoutSeconds": 30,
        "writeTimeoutSeconds": 30
      }
    }
  },
  "gateway": {
    "reverseProxy": {
      "trustedProxies": ["10.0.0.0/8"],
      "forwardedHeaders": ["X-Forwarded-For", "X-Forwarded-Proto"]
    }
  }
}

롱 폴링을 쓸 때는 transport를 "longPolling"(또는 해당 릴리스 동등 설정)으로 두고 timeout·allowed_updates 등 getUpdates 옵션을 채웁니다. 텔레그램이 예전 URL로 웹훅을 가리키지 않도록 정리하세요.

4.2 역프록시(Caddy 스케치)

# TLS는 엣지에서 종료; Mac의 127.0.0.1:18789로 프록시.
# OpenClaw와 Host/경로 일치 유지; 본문 크기 한도는 게이트웨이 가이드에 맞출 것.

bot.example.com {
  reverse_proxy 127.0.0.1:18789 {
    header_up X-Forwarded-Proto {scheme}
    header_up X-Forwarded-For {remote_host}
  }
}

5. 7단계 Runbook(원격 물리 Mac)

1. 전송 방식을 고정합니다. 활성 경로는 하나만. 롱 폴링에서 웹훅으로 바꿀 때는 이중 전달을 피하기 위해 먼저 폴링 프로세스를 중지합니다.
2. TLS를 끝에서 끝으로 검증합니다. 인터넷에서 443을 테스트합니다. 전체 체인, SNI, 방화벽(현행 텔레그램 문서의 소스 대역)을 확인합니다.
3. openclaw.json을 병합합니다. cp openclaw.json openclaw.json.bak.$(date +%Y%m%d%H%M) 후 publicUrl·시크릿 참조·로컬 바인드를 설정합니다.
4. 오래된 웹훅 상태를 정리합니다. getWebhookInfo → URL이 잘못됐으면 deleteWebhook → 한 곳에서 setWebhook으로 409를 줄입니다.
5. 리로드 후 프로세스 건강을 확인합니다. 배포 방식에 맞게 리로드하고, 리슨 포트와 launchd 로그에 크래시 루프가 없는지 봅니다.
6. 양·음성 테스트. 테스트 메시지를 보내고, 잘못된 secret_token 요청은 빠르게 실패해야 하며 pending_update_count를 주시합니다.
7. 아카이브합니다. 도메인, 인증서 갱신 담당, setWebhook 파라미터, 롱 폴링으로의 롤백 절차를 기록합니다.

6. 409·TLS 타임아웃 트리아지

7. 인용 가능한 수치·체크 항목

• getUpdates 롱 폴: Bot API 문서상 timeout은 보통 0–50초; RTT가 큰 링크에서는 보수적으로 시작합니다.
• 로컬 HTTP: 예시 127.0.0.1:18789는 루프백에만 머무르고, 프록시가 TLS와 공개 면을 담당합니다—SSH 우선 ZoneMac 노드와 맞습니다.
• 웹훅 동시성: maxConnections를 게이트웨이 워커·상위 모델 QPS와 함께 예산화해 인그레스가 코어보다 빨리 받아들이지 않게 합니다.

8. FAQ

9. 요약과 Mac mini가 이 스택에 맞는 이유

롱 폴링과 웹훅의 선택은 「최신이냐」가 아니라 프로덕션급 HTTPS와 단일 등록 소스를 받아들일지입니다. 웹훅은 관측성을 getWebhookInfo 쪽으로 밀고, 롱 폴링은 아웃바운드 경로와 프로세스 감시에 복잡도가 남습니다.

ZoneMac 원격 물리 Mac에서 Mac mini M4급 노드는 대기 전력이 수 와트 수준이고, Unix 네이티브 서비스와 역프록시·OpenClaw를 한 기기에서 launchd 친화적으로 돌리기 좋아 무인 게이트웨이에 맞습니다. Gatekeeper·SIP·FileVault 같은 macOS 하드닝은 Windows 범용 호스트 대비 장기 노출 부담을 줄여 줍니다.

텔레그램 인그레스·TLS·OpenClaw를 조용하고 예측 가능한 하드웨어에서 돌리고 싶다면 Mac mini M4는 가격 대비 안정성이 강한 출발점입니다. ZoneMac으로 원격 물리 Mac을 받아 이 Runbook을 실제 금속 위에서 리허설해 보세요.