2026-04-21 헤드리스 임대 클라우드 Mac에서 OpenClaw 서브에이전트 & 채널 바인딩 문제 해결
Discord 스레드가 서브에이전트에 닿지 않거나 Telegram 대기열이 조용한데 게이트웨이가 127.0.0.1:18789에서 듣고 있다면 바인딩+세션 문제이지 모델 장애가 아니다. SSH만 있는 임대 Apple Silicon에서는 GUI로 매핑을 고칠 수 없다. 이 2026-04-21 런북은 openclaw doctor, 채널 프로브, 세션 디렉터리 점검, 제어된 게이트웨이 재시작 순으로 진행하고 헬스 프로브, nginx 인그레스, 게이트웨이 업그레이드/롤백으로 이어진다. 패키지 레이아웃에 초점을 둔 Skills & ClawHub 고정 글과 역할을 나눈다.
분류할 가치가 있는 증상
| 관찰 | 가능한 층 | 첫 조치 |
|---|---|---|
| 게이트웨이는 건강, 채널은 침묵 | 토큰, webhook, 페어링 | 채널 상태 프로브 + 페어링 목록 |
| 세션을 언급하는 서브에이전트 스폰 오류 | 파일시스템 경로 검증 | sessions 권한과 설정 확인 |
| npm 업그레이드 후 플래핑 | 오래된 글로벌 설치 vs 실행 중 바이너리 | 게이트웨이 중지 후 openclaw --version 비교 |
doctor, 상태, 로그 상관
openclaw doctor로 시작해 stdout을 로그 파이프로 보낸다. 중복 LaunchAgent 가이드와 대조한다.
openclaw doctor 2>&1 | tee /tmp/openclaw-doctor-$CI_BUILD_ID.log
채널 바인딩 & 멘션 게이트
openclaw.json이 올바른 채널 ID를 에이전트 ID에 매핑하는지 확인한다. requireMention은 암묵적 구독을 기대할 때 조용히 트래픽을 떨어뜨린다. 공개 인그레스는 nginx에서 TLS 종단과 보수적 속도 제한을 유지한다.
세션 경로 & 서브에이전트 저장
업스트림은 세션 파일이 구성된 sessions 루트 아래에 있어야 한다고 엄격히 검증한다. 업그레이드 후 경로 오류가 나오면 시크릿 & launchd에 따라 OPENCLAW_STATE_DIR 등을 조정한다.
떼죽음 없는 게이트웨이 바운스
- 인그레스 일시중지 — 업스트림은 503과
Retry-After. - 중지 — CLI 또는 문서의
launchctl. - 시작 — 로컬 헬스 통과 후 외부 개방.
Nginx, 헬스, 리전 페일오버
로컬 curl 후 nginx를 다시 켜고 오류율을 본다. 리전 Mac이 불건강하면 한 대를 반복 재시작하지 말고 가격에 나온 두 번째 노드로 옮긴다.
관련 런북
메시 접근은 Tailscale 메시. 컨테이너 대 네이티브 npm은 Docker 대 네이티브 npm. 구조화 로그는 프로덕션 로깅과 필드를 맞춘다.
FAQ: 클라우드 Mac의 서브에이전트
| 질문 | 답 |
|---|---|
| 서브에이전트가 게이트웨이 사용자를 공유해야 하나? | 환경마다 상태 디렉터리를 분리하는 편이 안전—한 Mac이라도 세션 크로스토크를 피한다. |
| 페어링 승인을 자동화할 수 있나? | 조직 리스크 허용 범위 안에서만—채팅 브리지 장치 승인 소유자를 기록한다. |
| 인시던트는 어디에 추적? | 게이트웨이 로그와 공급자 대시보드를 상호연관—티켓에 semver+Git SHA. |
한 줄: 채널 바인딩은 방화벽 규칙처럼—명시적 ID, 경로, 재시작—npm 글로벌을 건드릴 때마다 롤백 tarball을 준비한다.
