이미 Gateway를 운용하는 팀은 Slack·Discord·Telegram을 설치하지 못해서 실패하는 경우는 드뭅니다. 관리 콘솔에는 채널이 연결된 것으로 보이나 대화는 블랙홀처럼 느껴지고, 메시지가 도착하지 않거나 한 방향으로만 흐르는 상황에서 막힙니다. 본문은 《설치 후 doctor 트러블슈팅》《Docker 네트워크 트리아지》《프로바이더 페일오버》와 짝을 이룹니다. 먼저 Gateway와 모델 상태를 확인한 뒤, 플랫폼별 OAuth 범위·봇 권한·이벤트 구독·Telegram 프라이버시 모드를 순서대로 점검합니다. 당번에 쓸 여섯 가지 증상 태그, 삼층 트리아지 매트릭스, 복사해 실행할 진단 블록, 여섯 단계 런북, Grafana에 올릴 만한 채널 KPI 세 가지를 제시합니다.
채널 이슈는 종종 「모델이 고장 났다」 또는 「compose 네트워크 문제다」로 잘못 분류됩니다. 이미지나 network_mode를 바꾸기 전에 아래 목록으로 동작을 라벨링하고 Docker 네트워크 트리아지 표와 대조하여, 두 갈래 변경이 동시에 이루어져 근본 원인을 지워 버리지 않도록 합니다.
.env 마운트 없이 컨테이너가 재시작된 경우가 많습니다.이 여섯 클래스를 최근 allowedOrigins 수정과 같은 변경 티켓의 이미지 롤아웃과 함께 기록하면 당번이 오 분 안에 분기를 고를 수 있습니다.
이 매트릭스는 어느 층을 먼저 살필지 정하는 것이며 배타적이지 않습니다. 각 행은 구체적인 다음 명령이나 로그 키워드에 매핑되어야 합니다. 종이에 세 열을 그립니다. 사용자에게 보이는 증상, Gateway 로그에서 가장 먼저 보이는 이상, 업스트림 모델 HTTP 코드입니다. 가운데 열이 비어 있으면 프로바이더를 건드리기 전에 멈춥니다. 오른쪽 열에 429가 먼저이면 OAuth를 열 번 재인증해도 과금 문제는 해결되지 않습니다.
Docker 네트워크 글과 함께 읽을 때 컨테이너 안에서 채널 프로브가 실패하는 경우를 제0층으로 둡니다. 동일 compose 네트워크에서 CLI가 Gateway에 닿는지 먼저 확인한 뒤 이 표를 씁니다. 그렇지 않으면 Slack 웹훅 콘솔은 건강해 보이는데 호스트에는 타임아웃만 보일 수 있습니다.
| 관측 | 우선 의심할 층 | 다음 단계(요약) |
|---|---|---|
| 헬스 체크는 녹색, 인바운드 로그는 없음 | 채널 인그레스 | 플랫폼별 재인증, 이벤트 구독 URL·Socket Mode·Intent 확인, Telegram 프라이버시와 @멘션 |
| 인바운드는 있으나 라우팅에 빈 에이전트 또는 정책 거부 | 라우팅·정책 | groupPolicy·채널 바인딩·멘션 규칙을 검사하고 OpenClaw 에이전트 매핑을 맞춥니다 |
| 인바운드와 라우팅은 정상, 응답 단계에서 실패 | 모델·쿼터 | 429·5xx·타임아웃을 보고 프로바이더 페일오버 글에 따라 키나 모델을 전환합니다 |
| 컨테이너만 실패, 호스트 CLI는 성공 | 네트워크·시크릿 마운트 | Docker 네트워크 트리아지로 돌아가 compose 환경과 볼륨을 확인합니다 |
이 지표는 「봇이 멈춘 것 같다」를 알림 가능한 숫자로 바꿉니다. 필드 이름은 Gateway 로깅과 맞춥니다. 초 단위 잡음보다 시간 단위 버킷을 선호하여 야간 호출이 의미를 잃지 않게 합니다.
2026년 커뮤니티 문서도 여전히 openclaw channels status --probe를 강조합니다. 프로브 결과를 위 세 비율 옆에 그려 「재연결하고 기도」류의 재현 불가 수정을 피합니다. Gateway 헬스 체크 글에서 HTTP 프로브를 이미 썼다면, 프로브 URL이 실제 채널 콜백과 동일한 리버스 프록시 경로를 따르는지 확인합니다. 루프백만 두르고 공개 콜백은 다른 인증서 체인을 쓰면 「모니터는 전부 녹색, 사용자는 전부 적색」이 됩니다.
수동 대조 습관을 더합니다. 매주 사용자 메시지 열 건을 샘플링하여 플랫폼 메시지 ID·Gateway 요청 ID·모델 트레이스 ID가 로그 전반에 나타나는지 확인합니다. 링크가 빠지면 구조화 로깅이 깨진 것이므로 확장 전에 필드를 고칩니다.
# 예시 순서(환경에 맞게 sudo / docker exec 접두어 추가) openclaw gateway status openclaw channels status --probe openclaw logs --follow | rg -i "slack|discord|telegram|429|oauth|deny" # Telegram: BotFather 프라이버시 모드와 그룹에서 @멘션 필요 여부 # Discord: Developer Portal 특권 Intent(Message Content 등)
참고: 《세 플랫폼 설치 가이드》로 동일 머신에서 최소 대화를 재현하지 못했다면 채널과 compose를 병렬로 바꾸지 않는 것이 좋습니다. 병렬 수정은 근본 원인을 가립니다.
allowedOrigins나 TLS 인증서가 바뀌었다면 이전 인증서 지문으로 롤백하는 방법을 문서화하여 OAuth 콜백과 CORS가 동시에 깨지지 않게 합니다.gateway status가 doctor 글과 일치하는지 확인합니다. systemd나 launchd를 쓰면 재시작 정책을 검증합니다. 빈번한 재시작은 채널 WebSocket에 플랫폼 측 속도 제한을 걸 수 있습니다.벤더 콘솔마다 아래 항목을 실행합니다. 오래된 스크린샷을 믿지 않습니다. 스테이징과 프로덕션 워크스페이스를 모두 쓴다면 콜백 호스트명 열을 따로 두어 스테이징 인증서가 프로덕션 DNS에 묶이지 않게 합니다.
세 플랫폼 모두 안정적인 이그레스 IP를 중시합니다. 가정용 회선이나 출구 노드가 바뀌는 VPN은 웹훅을 이상 트래픽처럼 보이게 할 수 있습니다. 멀티리전 클라우드 Mac 가이드의 고정 리전과 감사 가능한 이그레스와 맞습니다. 팀이 봇에 의존하기 전에 도달 가능성을 증명할 호스트로 제어 평면을 옮깁니다.
절전·VPN·로컬 프록시는 이그레스 IP와 TLS 지문을 바꿔 OAuth 콜백과 벤더 허용 목록을 무작위로 실패시킵니다. 공유 노트북으로는 토큰 로테이션과 감사 필드를 한곳에 모을 수 없습니다. 당번이 볼 수 있고 이그레스가 안정적인 실행면에서 Gateway와 채널 워커를 돌립니다 팀 에이전트 정책과 맞춥니다.
상시 서비스·고정 콜백 도메인·예측 가능한 이그레스가 필요한 토폴로지에서는 MACCOME이 싱가포르·일본·한국·홍콩·미 동부·미 서부에 Mac Mini M4·M4 Pro 클라우드 호스트를 제공하며 Gateway와 Apple 도구를 함께 두기에 적합합니다. 채널 트리아지 후 《SSH 대 VNC 가이드》와 고객 센터를 보고 대여 요금과 리전 페이지로 임대 기간을 연장합니다.
파일럿 패턴: 전용 테스트 호스트에서 채널 하나로 24시간 IER과 RCR을 돌린 뒤 프로덕션 워크스페이스를 엽니다. 큰 커뮤니티를 한꺼번에 켜서 즉시 적색이 되는 상황을 피합니다.
자주 묻는 질문
Docker 네트워크 트리아지 글과 어떻게 다른가요?
네트워크 글은 CLI에서 Gateway까지의 도달성을 다룹니다. 본문은 메시지 플랫폼 인그레스와 인증을 다룹니다. compose를 의심하면 먼저 《Docker 네트워크 트리아지》를 읽습니다.
상위 OpenClaw FAQ도 읽어야 하나요?
읽습니다. 토큰과 Intent 목록을 상위 문서와 교차 확인합니다. 《세 플랫폼 설치 가이드》와 고객 센터의 접근 문구를 함께 봅니다.
클라우드 Mac의 리전과 임대 조건은 어디서 고르나요?
Gateway를 두기 전에 《멀티리전 대여 가이드》와 대여 요금을 읽습니다.