AI / 자동화 2026년 5월 6일

2026-05-06 OpenClaw 듀얼 게이트웨이：포트、OPENCLAW_STATE_DIR、nginx 업스트림 롤아웃（임대 Apple Silicon 클라우드 Mac、HK / JP / KR / SG / US）

MacXCode Engineering Team 2026년 5월 6일 약 24분 읽기

동일한 임대 Mac mini M4에서 두 세트의 OpenClaw 게이트웨이를 돌리려는 팀이 많습니다. 프로덕션 옆의 카나리, 고객 webhook과 분리된 스테이징 모델 허용 목록 등이 대표적입니다. 설정을 잘못하면——포트 충돌, 공유 ~/.openclaw, 요청 도중에 바뀌는 nginx 가중치——모델 장애처럼 보이는 502 폭풍이 생기지만 실제로는 배관 문제뿐입니다. 이 2026-05-06 가이드는 충돌하지 않는 루프백 리슨 포트, 분리된 OPENCLAW_STATE_DIR 트리, slow_start가 들어간 nginx upstream, 헬스 프로브를 순서대로 정리해 홍콩·도쿄·서울·싱가포르·미국에서 SSH에 의존하지 않고 트래픽을 드레인할 수 있게 합니다. 에이전트가 겹치는 저장소를 읽을 때는 nginx 및 webhook 진입, 헬스 프로브, launchd 환경 변수 우선순위, 파일 도구 규율과 연계하세요.

듀얼 게이트웨이가 복잡도를 감당할 만한 경우

예산이 허용되면 두 번째 Mac을 우선하세요——witness 노드 추가는 요금을 참고합니다. 한 대로 고정되어야 한다면 다음 경우에도 듀얼 구성이 도움이 됩니다.

  • 규제 트래픽과 실험 트래픽의 모델 허용 목록이 다를 때
  • 스테이징과 프로덕션의 webhook 서명 비밀 로테이션 주기가 다를 때
  • CPU 핀닝은 없지만 카나리와 프로덕션 세션 사이에 영향 범위 방화벽이 필요할 때
수치: 첫 48시간 동안 카나리 가중치를 요청의 5–12%로 유지하고, 오류 예산이 녹색일 때만 10% 단계로 올립니다.

토폴로지: 나란히 active/active vs primary/standby

나란히 active/active는 클라이언트를 무작위로 보낼 수 있거나 nginx 가중치를 완전히 제어할 때 적합합니다. primary/standby는 결정론적 디버깅이 필요한 팀에 맞습니다——무거운 쓰기 도구는 공유 git 미러에 대해 한 게이트웨이만 소유합니다. 선택은 launchctl 레이블을 적어 둔 README와 같은 문서에 기록하세요.

패턴 장점 단점
Active / active 처리량; 실제 동시성에서 soak 멱등 webhook과 중복 제거된 부작용 필요
Primary / standby 로그 단순; 롤백 용이 스탠바이가 합성 프로브를 돌리지 않으면 CPU 유휴

포트, 바인드 주소, launchd 레이블

lsof 한 번으로 빈 포트를 추측하지 마세요——plist와 nginx에 고정합니다. 예시(시맨틱 버전에 맞게 조정):

export OPENCLAW_GATEWAY_PORT_PRIMARY=18789 export OPENCLAW_GATEWAY_PORT_CANARY=18890

둘 다 127.0.0.1에 바인딩하고 0.0.0.0:443은 nginx에 맡깁니다. 카나리만 ::1에 묶고 upstream이 IPv4 전용이면 유령 같은 연결 리셋을 쫓게 됩니다. 주소 체계는 아웃바운드 DNS/TLS 복원력 가이드에 맞추세요.

상태 디렉터리: ~/.openclaw 공유가 금지인 이유

각 게이트웨이는 전용 경로를 가리키는 자체 OPENCLAW_STATE_DIR가 필요합니다(예: /var/lib/openclaw-prod vs /var/lib/openclaw-canary). 홈을 공유하면 세션 파일 경합과 API 키 회전 시 오염된 캐시가 생깁니다. launchd가 두 작업 모두에 같은 UID를 쓰더라도 디렉터리는 반드시 분리하고 sqlite나 세션 루트를 공유하지 마세요.

백업: nginx 가중치를 바꾸기 전에 두 상태 트리를 스냅샷하세요——롤백은 rsync와 launchctl kickstart이며 재설치 이야기가 아닙니다.

nginx upstream: 가중치, slow_start, max_fails

동작 중인 server 블록을 리버스 프록시 가이드에서 복사한 뒤 upstream 정의를 복제합니다.

upstream openclaw_primary { server 127.0.0.1:18789 max_fails=3 fail_timeout=20s; } upstream openclaw_canary { server 127.0.0.1:18890 max_fails=1 fail_timeout=10s slow_start=30s; }

위험 허용도에 맞춰 split_clients 또는 가중 proxy_pass를 사용합니다. proxy_read_timeout은 허용하는 최장 모델 왕복에 맞춥니다——게이트웨이를 나눈다고 LLM 지연이 줄지 않습니다.

nginx reload 시 worker_connections와 keepalive 풀은 워커별입니다. upstream을 두 배로 늘리고 한도를 올리지 않으면 webhook 버스트 재전송에서 처리량이 막힐 수 있습니다. 가능하면 stub_status를 수집하고, 아니면 access 로그에서 upstream 응답 시간을 분석하세요. reload 직후 p95가 35% 이상 뛰면 OpenClaw 설정보다 워커 기아를 의심합니다. TLS 부하가 크면 staging과 프로덕션 cipher 스위트를 맞추세요. OpenClaw 상태 스냅샷 옆에 롤백용 nginx tarball을 명시적으로 문서화하세요——Node 트리만 백업하고 nginx를 잊으면 map $http_x_forwarded_proto 두 줄 오타로 파서가 fail closed 되며 두 게이트웨이가 동시에 멈출 수 있습니다.

헬스 프로브: 트래픽 이동 전에 둘 다 녹색으로

준비 프로브와 동일한 curl 매트릭스를 두 로컬 포트에 실행하고, reload 후에는 nginx 경로로도 실행합니다. HTTP 상태, upstream 연결 시간, TLS 핸드셰이크 시간을 분리해 로깅하면 nginx 퇴보와 OpenClaw 퇴보를 구분할 수 있습니다.

8단계 롤아웃 체크리스트

  1. 스냅샷 plist, nginx, 두 상태 디렉터리
  2. 설치 두 번째 게이트웨이(바이너리 또는 npm 핀이 프로덕션과 동일)
  3. 각 트리에서 openclaw doctor 독립 검증
  4. nginx에서 카나리 가중치 0(준비될 때까지 블랙홀)
  5. 스테이징에서 합성 webhook 리플레이 스모크
  6. 카나리 슬라이스로 가중치 상향(5–12%)
  7. 48시간 오류 예산 관찰
  8. 문서화된 가중 단계로 승격 또는 롤백

타임아웃, webhook 재시도, 이중 전달

듀얼 게이트웨이는 업스트림이 공격적으로 재시도할 때 이중 전달 위험을 키웁니다. 핸들러가 멱등 키를 존중하고 올바른 상태 디렉터리 아래에 중복 제거 마커를 저장해야 합니다. proxy_read_timeout은 공급자 TCP 유휴 제한에 맞추세요——재시도 표는 webhook 전달 및 서명을 참고합니다.

SLO 신호 임계값 조치
localhost upstream 연결 p95 > 120 ms 가중치 이동 중단; launchd 스로틀링 조사
5xx 비율 15분 동안 > 0.5% 카나리 가중치를 0으로 드레인
큐 적체 대기 작업 > 200 두 번째 Mac 추가 또는 동시성 감소——세 번째 게이트웨이는 쌓지 않음

SLO 표: “건강한 듀얼 게이트웨이”의 의미

듀얼 게이트웨이를 미니 서비스 메시처럼 다루고 홉마다 측정합니다. 프로덕션은 녹색인데 카나리만 SLO 위반이면 nginx를 건드리기 전에 카나리 설정을 고칩니다.

내부 대시보드에는 게이트웨이당 네 개의 선: 프로세스 RSS, CPU%, nginx 로그의 진행 중 HTTP 수, 실패한 upstream 연결 수. 같은 트래픽 가중치에서 카나리 RSS가 프로덕션보다 18% 이상 벌어지면 플러그인 메모리 누수나 Node semver 불일치가 흔합니다——롤아웃을 멈추고 각 OPENCLAW_STATE_DIR에서 npm ls --depth=0를 비교하세요. 이 비교를 건너뛴 팀은 주말을 “LLM 품질 퇴보”로 보내지만 실제로는 카나리에서 skill 번들이 두 번 로드된 경우가 많습니다.

분기마다 nginx 완전 실패를 리허설하세요——의도적으로 nginx를 중지하고 launchd가 두 게이트웨이를 루프백에서 유지하는지, 인시던트 봇이 적절한 사람에게 알리는지 확인합니다.

FAQ: TLS, DNS, 비밀

질문 실무 답변 (2026-05-06)
게이트웨이마다 TLS 인증서가 필요한가요? 보통 아니요——nginx에서 한 번 종료하고 게이트웨이는 루프백만 사용합니다.
같은 API 키를 둘 다 써도 되나요? 피하세요——영향 범위를 줄이려 독립 로테이션; 패턴은 업그레이드·롤백을 참고합니다.

맥 미니 M4 베어메탈이 듀얼 게이트웨이 혼란을 줄이는 이유

듀얼 게이트웨이는 CPU, 디스크, launchd 장부를 동시에 압박합니다. MacXCode 노드에서 1–2TB NVMe가 있는 임대 Mac mini M4는 nginx→OpenClaw 루프백 지연을 예측 가능하게 해 주고, 야간 xcodebuild 이웃 레인에서 코어를 빼앗지 않고 두 개의 Node 그래프를 돌릴 만큼 통합 메모리를 제공합니다. 이미 바쁜 호스트에 세 번째 게이트웨이를 올리기보다 전용 두 번째 노드가 필요할 때는 지역별 요금으로 설득하고, 새 TLS 신뢰 앵커에 대한 브레이크글래스는 도움말과 VNC를 참고하세요.

세 번째 게이트웨이보다 두 번째 빌더를 먼저 추가하세요

HK / JP / KR / SG / US · SSH / 선택적 VNC