2026년 OpenClaw 다중 채널 게이트웨이 트러블슈팅: openclaw doctor, 헬스 프로브·Telegram/Discord 연결 실패—openclaw.json 핫 리로드, 18789 포트 충돌, 원격 물리 Mac 런북(FAQ)
원격 물리 Mac에서 Telegram과 Discord 채널을 동시에 쓰다 「한쪽만 살아 있고 한쪽은 죽었다」거나 헬스가 들쭉날쭉할 때, 이 글은 openclaw doctor와 프로브로 원인을 설정·포트·네트워크 층으로 고정합니다. 증상→조치 의사결정 매트릭스, 붙여 넣을 수 있는 7단계 런북, SLO 문서에 바로 넣을 수 있는 임계값 3가지, FAQ를 담았습니다. Gateway 데몬·헬스 주기는 2026년 OpenClaw Gateway 7×24 끊김과 데몬 트러블슈팅: install-daemon, launchd와 openclaw health 재현 가능 런북과 맞춰 읽고, 스킬·워크스페이스 불일치가 겹칠 때는 2026년 원격 물리 Mac에서 OpenClaw Workspace Skills 로드 실패 런북을 함께 두면 온콜 시간이 줄어듭니다.
1. 반복되는 세 가지 고통 포인트(다중 채널 게이트웨이가 무너지는 곳)
1) 핫 리로드 경계가 불명확: openclaw.json만 고치면 즉시 반영될 거라 기대하지만, 웹훅 시크릿·TLS 인증서 경로·봇 토큰은 여전히 이전 프로세스에 남아 있을 수 있습니다. 파일은 맞는데 로그만 낡은 오류가 나오는 패턴입니다.
2) 18789 포트와 중복 인스턴스: 로컬 진단·관리 HTTP(본문에서는 흔한 기본값으로 18789를 씁니다. 실제 포트로 바꿔 적용하세요)가 다른 Gateway, 오래된 launchd 작업, 대화형 세션과 겹치면 프로브가 connection refused와 503 폭발 사이를 오가며 상위 Telegram/Discord 장애처럼 보입니다.
3) 비대칭 채널 실패: Telegram은 롱 폴링, Discord는 WebSocket과 REST가 섞입니다. 기업 이그레스·시스템 프록시·HTTP(S)_PROXY가 launchd와 로그인 셸에서 다르면 「한 채널만 타임아웃, 다른 쪽은 정상」 같은 그럴듯한 오탐이 납니다.
채널 설정을 전부 다시 쓰기 전에, 벤더 권장 디렉터리와 설치 버전이 문서와 맞는지 확인하세요. 버전 스큐는 doctor 출력을 네트워크 탓으로 읽게 만드는 가장 빠른 지름길입니다.
2. 증상→조치 의사결정 매트릭스(재부팅 전에 분류)
아래 표로 openclaw doctor와 프로브 출력을 교차 검증해 「세 번 재시작한 뒤 이유를 묻는」 상황을 줄입니다.
| 보이는 현상 | 먼저 할 일 | 유력한 원인 묶음 |
|---|---|---|
| doctor가 로컬 HTTP 다운이라 하고 127.0.0.1:18789 curl 실패 | 리스너 매핑, 남은 프로세스 종료, install-daemon으로 plist 재설치 | 포트 충돌·리슨 없음 |
| 두 채널 모두 빨강, doctor 네트워크 구간 전체 실패 | 비대화형 환경에서 DNS·프록시·아웃바운드 방화벽 검증 | 이그레스·프록시 |
| Discord만 실패, Telegram은 정상 | 토큰·인텐트 검증, launchd와 동일 사용자로 discord.com TLS/SNI 프로브 | 자격·권한·API 경로 |
| JSON 변경이 「반쯤」만 반영됨 | 필드를 콜드 스타트 vs 핫 리로드로 나누고 doctor로 동작 차이 재확인 | 리로드 대상이 아닌 필드 |
3. 원격 물리 Mac 7단계 런북(플레이북에 그대로 붙여 넣기)
- 기준 스냅샷:
openclaw doctor전체 로그와 Gateway 시맨틱 버전을 저장하고,openclaw.json은shasum등으로 해시해 롤백 diff를 쉽게 만듭니다. - 헬스 프로브 안정화: 준비 URL을 3초 간격으로 최소 10회 이상 호출합니다. 한 번 초록인 것은 복구가 아닙니다. launchd KeepAlive 백오프 구간과 관측을 맞춥니다.
- 18789 리슨 매트릭스:
lsof -nP -iTCP:18789 -sTCP:LISTEN(환경에 맞게 포트 교체). OpenClaw 관련 PID가 여러 개면 주 인스턴스 하나만 남깁니다. - 채널별 스모크: Telegram은 가벼운 getMe류 호출, Discord는 로그의 샤드·소켓 상태 또는 최소 REST HEAD. 단일 「전체 건강」 불린 뒤에 한 채널 실패를 숨기지 마세요.
- 핫 리로드 vs 콜드 스타트: JSON 키마다 런타임 갱신 가능 vs 재시작 필요를 태그하고, 후자는 SIGHUP 난사보다 제어 재시작을 택합니다.
- 제어 재시작:
launchctl또는 프로젝트의install-daemon흐름으로 중지, 리스너 0 확인 후 기동, 구조화 로그 첫 200줄을 즉시 tail합니다. - 인시던트 종료: 30분 안에 doctor·프로브·채널별 실제 사용자 메시지 1건씩을 다시 수행하고, 티켓에 스크린샷 세 장이면 충분히 닫을 수 있습니다.
launchd, install-daemon, openclaw health의 대응 관계를 더 깊게 펼치려면 기존 7×24 Gateway 데몬 가이드와 이 런북을 겹쳐 두세요. 프로브 주기와 KeepAlive 백오프 표현은 한 줄씩 맞추는 것이 좋습니다.
4. 인용 가능한 임계값·체크리스트(SLO 문서용)
- 프로브 간격: 게이트웨이급 준비 상태는 30~60초마다 폴링합니다. ~15초 이하면 GC 스파이크에 오탐이 납니다.
- 연속 성공 규칙: 「건강」 선언 전 HTTP 2xx를 5회 연속 요구하지 않으면 플래핑 추격에 빠집니다.
- 회귀 창: 설정 변경 후 30분 안에 양쪽 채널 모두 종단 간 메시지로 검증하는 것을 인시던트 종료 최소 기준으로 둡니다.
5. FAQ
openclaw.json을 수정한 뒤 항상 Gateway를 재시작해야 하나요?
채널 자격 증명, 웹훅, TLS 관련 필드는 보통 전체 프로세스 재시작이 필요합니다. 일부 버전은 리스너가 아닌 토글만 핫 리로드하지만, 운영에서는 openclaw doctor 후 제어 재시작으로 반쯝 로드된 리스너를 피하세요.
18789 포트 경합은 실무에서 어떻게 보이나요?
관리·진단 HTTP가 바인딩에 실패하거나 성능이 떨어지고, 프로브는 connection refused를 돌려줄 수 있습니다. lsof로 PID를 찾고 남은 Gateway 작업을 끈 뒤 포트가 비면 한 번에 재시작합니다.
Telegram은 되는데 Discord만 실패합니다. 먼저 볼 설정 세 덩어리는?
봇 토큰과 인텐트, 기업 프록시 허용 목록의 Discord API 엔드포인트, launchd가 쓰는 계정과 동일한 맥락에서 discord.com DNS 해석입니다. curl -I와 채널별 doctor를 함께 쓰면 TLS/DNS와 앱 버그를 분리합니다.
6. 이 게이트웨이 스택을 Mac mini에서 돌리기 쉬운 이유
다중 채널 점검은 환경이 조금만 달라도 실패합니다. 대화형 셸은 인터넷에 닿는데 launchd 작업은 프록시나 사용자 CA 신뢰가 없는 식입니다. Apple Silicon macOS는 장시간 Node 프로세스와 통합 메모리로 밤새 트래픽 때 메모리 스파이크 미스터리를 줄입니다. Mac mini M4는 유휴 시 대략 4W에 가까워 옷장·랙 무인 게이트웨이에 잘 맞고, Gatekeeper·SIP·FileVault로 전형적인 Windows 유틸리티 호스트보다 공격 면이 작습니다.
전 세계 사용자에게 Telegram과 Discord를 펼칠 때, 감사 가능하고 리전에 고정된 물리 Mac 풀에 게이트웨이를 두면 단일 리전 이그레스 드라마와 「노트북에선 재현되는데 서버에선 아니다」 논쟁을 줄입니다.
조용하고 서늘하며 예측 가능한 하드웨어에서 이 런북을 돌리려면 Mac mini M4가 가격 대비 안정성 측면에서 가장 균형 잡힌 출발점 중 하나입니다. 지금 ZoneMac 노드를 살펴보고 운영 첫날부터 doctor 프로브를 프로덕션급 macOS에 맞추세요.
OpenClaw 24/7용 물리 Mac이 필요하신가요?
ZoneMac은 리전 선택 가능한 Mac mini 용량으로 무인 게이트웨이, CI, 감사 친화 운영을 지원합니다.