한 포트에 묶인 OpenClaw 게이트웨이를 바로 재시작하면 진행 중인 도구 호출·스트리밍 토큰·웹훅 확인이 중간에 끊깁니다. 2026년 운영에서는 구 바이너리를 살린 채 새 빌드를 다른 루프백 포트에서 받고, nginx upstream 가중치로 신규 TCP만 서서히 옮긴 뒤 오래된 프로세스만 종료하는 트래픽 드레인이 신뢰의 기본선이 됩니다. TLS·터널 배치는 리버스 프록시·터널 하드닝, 드레인이 실패해 하드 재시작으로 떨어질 때는 LaunchAgent 복구와 함께 문서화하세요.
이 글은 macOS에서의 포트 예시, 초 단위 기본값, openclaw doctor에 맞춘 검증, 롤백 연습까지 한 번에 쓸 수 있게 구성했습니다.
즉시 재시작이 신뢰를 깨는 이유
사용자는 500보다 “이유 없이 끊김”을 더 싫어합니다. 활성 keep-alive 소켓이 끊기면 헬스는 곧바로 초록이어도 “어시스턴트 오프라인” 배너가 남습니다. 드레인은 TCP 의미를 유지해 기존 연결은 끝까지 보내고 신규만 그린으로 보냅니다.
금융·컴플라이언스 팀도 중요하게 봅니다. 멱등 키 없이 자동 재시도하면 청구 이벤트가 중복될 수 있어, 120초 드레인은 사후 조정보다 저렴합니다.
사내 PoC 단계에서는 개발자가 편의상 재시작을 반복하기 쉬운데, 운영으로 올릴 때 드레인 런북이 없으면 야간 온콜이 매번 같은 분류에 시간을 씁니다. Git 태그, nginx reload 시각, 그린 SHA를 런북에 고정하세요.
블루·그린·nginx 위치
블루를 127.0.0.1:8787, 그린을 127.0.0.1:8788에 바인딩하는 예입니다. 공개 트래픽은 443의 nginx가 받고 upstream에 두 루프백을 넣습니다. 정상 시 블루 가중 100, 배포 시 10포인트씩 옮기며 오류 예산을 봅니다.
| 단계 | 블루 | 그린 | 운영 초점 |
|---|---|---|---|
| 정상 | 100 | 0 | 기준 지표 |
| 카나리 | 90 | 10 | 오류율 동등 |
| 중간 | 50 | 50 | 지연 히스토그램 |
| 완료 | 0 | 100 | 블루 소켓 드레인 |
채널 어댑터에 세션 고정이 필요하면 ip_hash나 스티키 쿠키를 검토하되, 신구 버전이 같은 해시 공간을 쓰는지 먼저 확인하세요.
nginx 설정 스케치
upstream은 두 개, 연결이 치우치면 least_conn. OpenClaw 로그에 원 호스트를 남기려면 proxy_set_header Host 등을 빼먹지 마세요.
upstream openclaw_gateway {
least_conn;
server 127.0.0.1:8787 weight=90 max_fails=3 fail_timeout=10s;
server 127.0.0.1:8788 weight=10 max_fails=3 fail_timeout=10s;
}
server {
listen 443 ssl;
location / {
proxy_pass http://openclaw_gateway;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_read_timeout 300s;
}
}nginx -t && nginx -s reload는 서브초이지만 워커 정책에 따라 유휴 연결에 영향이 있을 수 있어 유지보수 창 규칙을 따로 두세요.
끝에서 끝까지 맞출 타임아웃
nginx proxy_read_timeout이 300초인데 게이트웨이 내부 모델 한도가 60초면 스트림이 중간에 잘립니다. SRE와 벤더가 보는 단일 스프레드시트를 만드세요.
웹소켓·스트리밍 HTTP는 해당 location에 proxy_buffering off가 필요합니다. 기본 4MB 버퍼가 차면 멈춘 것처럼 보입니다.
드레인 중 fail_timeout을 너무 짧게 잡으면 CPU 스파이크 때 그린이 불필요하게 제외되고, 너무 길면 불량 빌드가 남습니다. M4급에서 병렬 에이전트를 돌리는 전제로 스테이징에서 실측하세요.
검증·카나리아·롤백
첫 10% 전에 루프백으로 합성 채팅을 돌려 블루 대비 첫 토큰 시간을 봅니다. 8% 이상 나쁘면 중단합니다.
nginx 액세스 로그와 OpenClaw 구조화 로그에 상관 ID가 없으면 사후 분석이 의견 싸움이 됩니다.
롤백은 가중 100/0으로 되돌리고 그린 프로세스를 종료하면 됩니다. 매월 한 번은 연습해 근육 기억을 남기세요.
스테이징에서 그린만 의도적으로 지연시키는 플래그로 대시보드가 색별 알람을 내는지도 함께 확인하세요. 프로덕션에서는 플래그를 빼먹으면 노이즈가 됩니다.
macOS 프로세스·포트
색마다 LaunchAgent 레이블을 분리해 launchctl kickstop 대상을 혼동하지 않게 합니다. StandardOutPath도 분리하지 않으면 JSON 로그가 섞입니다.
lsof -nP -iTCP:8787 -sTCP:LISTEN로 리스너를 확인하고, 핫 리로드 후 좀비 포트가 없는지 봅니다.
열·launchd 동선을 맞추려면 노트북보다 클라우드 Mac mini(MacHTML 기준 약 $16.9/일)가 낫습니다. SSH로 설정을 고치고 VNC로 메뉴 바 아이콘을 볼 수 있습니다.
한 호스트를 여러 팀이 쓰면 홈·API 키가 섞이지 않게 게이트웨이 설정 디렉터리를 격리하세요. 드레인은 공정성 버그를 고쳐 주지 않습니다.
가중치 이동 중 관측
전환 중 10초마다 색별 활성 upstream 연결, 색별 5xx, 합성 프로브의 p95 첫 토큰 시간을 냅니다. 한 축에 그리면 이상이 바로 보입니다.
Grafana에 nginx reload 시각과 그린 Git SHA를 주석으로 남기면 나중에 지연 증가를 단계와 연결하기 쉽습니다.
그린 5xx가 블루보다 0.5포인트 이상 크고 3분 넘게 지속되면 자동 롤백을 검토하세요. YAML 복잡도보다 사고 비용이 큰 경우가 많습니다.
이중 리스너 보안
루프백이 두 개면 0.0.0.0 오바인드 실수 위험이 커집니다. 배포 후 리스닝 주소를 grep하는 검사를 CI에 넣으세요.
시크릿 로테이션은 양쪽 색이 모두 갱신된 뒤 가중치를 움직입니다. 한쪽만 오래된 키면 그린으로 붙는 순간 조용히 실패합니다.
관리자 전용 디버그 경로는 양 빌드에서 끄고, 버전 간 플래그 불일치를 공격면으로 남기지 마세요.
멀티테넌트·노이즈 이웃
테넌트별 한도는 OpenClaw 설정과 nginx limit_req 존이 일치해야 합니다. 그린이 동시성을 실수로 두 배로 올리면 드레인해도 공정성은 돌아오지 않습니다.
대규모 전환은 디스크 스냅샷 cron과 겹치지 않게 잡으세요. APFS COW 스파이크가 꼬리 지연을 붙입니다.
첫 프로덕션 드레인 때 Grafana 짧은 녹화는 다음 온콜 교육에 그대로 쓸 수 있습니다.
FAQ
드레인하면 오류가 사라지나요?
아니요. 앱 버그는 남지만 트랜스포트 리셋 한 계열은 줄입니다.
Unix 소켓은?
가능합니다. nginx unix: upstream에서도 같은 가중 논리를 씁니다.
상위 모델 mTLS는?
양 색에서 동일한 종단/패스스루 정책을 유지하세요. 섞이면 핸드셰이크 로그만 난해해집니다.
상시 게이트웨이에는 전용 하드 경제도 중요합니다. Mac mini는 대기 전력이 낮고 전환 중에도 두 색 프로세스 여유를 두기 쉽습니다. MacHTML 렌탈은 조달 없이 검증 호스트를 늘리고, 프로덕션과 분리된 nginx 리허설 전용 머신을 둘 수 있습니다.