HTTPS를 켠 직후 바로 드러나는 세 가지 장애 모드
첫째, 오리진 불일치. http://127.0.0.1:18789와 https://agents.example.com은 다릅니다. allowedOrigins는 스킴·슬래시까지 엄격 비교, 403 가짜 인증처럼 보일 수 있음.
둘째, Upgrade 소실. Upgrade·Connection "upgrade" 누락 시 WebSocket 즉시 끊김. 동일 포트 HTTP/2 주의.
셋째, TLS 이중 종단 금지. 공개→프록시 TLS, 백엔드는 루프백 HTTP가 단순.
위협 모델: 프로덕션이 OpenClaw 앞에 리버스 프록시를 두는 이유
프로덕션은 에지에서 ACME·TLS 정책·요청 상한과 중앙 로그를 처리한 뒤 루프백으로 전달합니다. Nginx는 기존 스택, Caddy는 자동 HTTPS에 유리. WebSocket은 반드시 실측.
바인딩은 루프백 우선. 호환 토큰·채널 비밀 분리. X-Forwarded-For는 직전 프록시만 신뢰. Webhook 선인증. 환경별 allowedOrigins·공유 요청 ID.
결정 매트릭스: OpenClaw 게이트웨이용 Nginx 대 Caddy
| 에지 | 적합한 경우 | WebSocket 운용 | 운영 메모 |
|---|---|---|---|
| Nginx+certbot | 이미 nginx로 API·정적을 돌리는 조직 | Upgrade 명시, 동일 포트 http2 주의 | 갱신 훅·설정 검증을 팀이 관리 |
| Caddy 자동 HTTPS | TLS 의식을 최소화하려는 소규모 팀 | 대체로 단순, 커스텀 트랜스포트는 검증 | 헤더 기본값을 nginx 습관과 대조 |
| 클라우드 LB+Nginx | 헬스체크 있는 다중 AZ | LB 유휴 타임아웃을 WebSocket에 맞출 수 있음 | 이중 타임아웃 산술을 문서화 |
| Node 직접 TLS | mTLS 사설 메시 | Node가 업그레이드를 직접 처리, WAF 훅은 약함 | Node 크립토 패치 규율이 핵심 |
최소 조각: 루프백 업스트림, WebSocket 헤더, 긴 읽기
호스트명 교체 후 공개 경로로 curl -I …/health 확인. 아래는 주석 예시.
# --- Nginx (예시 server 블록) ---
# proxy_pass to http://127.0.0.1:18789;
# proxy_http_version 1.1;
# proxy_set_header Host $host;
# proxy_set_header X-Forwarded-Proto $scheme;
# proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# proxy_set_header Upgrade $http_upgrade;
# proxy_set_header Connection "upgrade";
# proxy_read_timeout 3600s;
# proxy_send_timeout 3600s;
# --- Caddy (예시) ---
# reverse_proxy 127.0.0.1:18789 {
# header_up X-Forwarded-Proto {scheme}
# header_up X-Forwarded-For {remote_host}
# }
# # WebSocket 통과; 장시간 소켓은 transport read_timeout 조정
타임아웃·버퍼·관측 기준선
대화형 WebSocket이나 어시스턴트 롱폴링이 지나는 경로에는 proxy_read_timeout과 proxy_send_timeout을 최소 3600초로 잡으세요. REST API용 짧은 기본값은 정상 세션을 끊습니다. HTTP 전용 호환 엔드포인트는 60~120초로 빠르게 실패시켜 붙은 업스트림을 드러낼 수 있습니다.
본문 크기 상한은 허용하는 Webhook·미디어 최대치와 맞춥니다. 강화 가이드가 아웃바운드 미디어를 수십 MB로 캡한다면 인바운드도 정렬해 공격자가 기각 전에 디스크를 채우지 못하게 합니다.
에지에서 TLS 프로토콜·암호를 주간 샘플링해 낡은 클라이언트를 잡고, 프로덕션 글처럼 라우트 패밀리별로 게이트웨이 로그를 걸러 보안 리뷰에 양층을 함께 제시합니다.
5분마다 합성 점검: 443 TCP, 전체 TLS 핸드셰이크, /health GET, 사전 합의 테스트 토큰으로 WebSocket 업그레이드 한 번. 어느 단계든 기준 지연에서 3 표준편차 이상 벗어나면 알림입니다.
용량: 업무 시간 활성 운영자당 최소 두 개의 동시 WebSocket을 예상하고, CI가 OpenAI 호환 엔드포인트를 두드릴 때의 버스트를 더합니다. 프록시 호스트의 worker_connections와 파일 디스크립터 ulimit으로 환산합니다.
롤백: 직전 nginx·Caddy 설정을 날짜 경로에 보관해 nginx -t 실패 시 알려진 좋은 상태로 되돌립니다.
감사용 한 장짜리 다이어그램에 DNS, 로드밸런서, 프록시, 루프백 OpenClaw, 아웃바운드 API 경로를 그려 신뢰 경계를 한눈에 보이게 합니다.
FAQ, 교차 링크, 호스팅 리모트 Mac이 스택을 단순화하는 경우
doctor는 녹색인데 브라우저만 403입니다. 어디를 보나요?
403을 낸 정확한 경로의 프록시 액세스 로그부터 보세요. nginx에 찍혔다면 OpenClaw 응답이 아닙니다. 애플리케이션 로그에만 403이면 allowedOrigins와 인증 헤더를 다시 봅니다.
OpenAI 호환 경로는 별도 server_name이 필요한가요?
필수는 아니지만 많은 팀이 /v1 호환 트래픽을 다른 가상 호스트로 빼 속도 제한·WAF를 대시보드와 분리합니다.
클라우드 FAQ 방화벽 절을 그대로 써도 되나요?
기준선으로 쓰고 프록시 포트 80·443, 헬스체크 소스 IP, 벤더가 공개한 IPv6 대역을 덧붙이세요.
요약: 프록시 TLS 종단, Upgrade 명시, allowedOrigins 정합, 층별 장애 분리.
한계: 인증서·프록시는 자체 운영. 관리형 리모트 Mac으로 인그레스 부담을 줄일 수 있습니다.
SFTPMAC 리모트 Mac으로 연결 관리·게이트웨이·SFTP를 한 흐름에 둘 수 있습니다.
게이트웨이와 파일 전달을 안정 인그레스 하나의 이야기로 묶고 싶다면 SFTPMAC 플랜을 살펴보세요.