Browser Relay · SSH 터널 · Gateway 포트 · 6단계 수용 Runbook
VPS 또는 클라우드 Mac에서 OpenClaw Gateway를 실행하면서, 공식 Browser Relay 확장 프로그램이 있는 로컬 Chrome으로 웹 자동화를 하고 싶습니다. 헤드리스 Chromium 컨테이너가 아니라 실제 브라우저를 쓰는 시나리오입니다. 흔한 실패는 확장 프로그램이 연결됨으로 표시되는데 CDP가 no tab is connected를 반환하거나, SSH 터널 이후 401 및 포트 프로브 불일치가 발생하는 경우입니다. 본문은 원격 제어 평면과 로컬 실제 브라우저를 감사 가능하게 분리하려는 팀을 위해 헤드리스 Docker 대비 의사결정 매트릭스, 18792 헬스 체크와 터널 파라미터 증상 대조표, 6단계 Runbook을 제공합니다. 헤드리스 브라우저 Skill 체크리스트 및 Compose 네트워크 Runbook과 함께 읽으시기 바랍니다.
2026년 기본 구성에서 Gateway는 127.0.0.1:18789를, 개발 노트북의 Browser Relay는 127.0.0.1:18792를 리스닝하는 경우가 많습니다. Gateway를 원격 VPS로 옮기면 제어 평면과 브라우저 평면이 서로 다른 네트워크 네임스페이스로 분리됩니다. Agent는 여전히 localhost를 가리키지만 브라우저는 노트북에 있습니다. 커뮤니티 보고(원격 Gateway + SSH 터널)에서는 로컬 runtime 맵만 검증하는 relay 인증으로 터널 경유 401, 잘못된 포트의 EADDRINUSE 프로브, 확장 ON이지만 탭 미 Attach 문제가 집중됩니다. 채널 응답을 완전한 수용 조건으로 보면 모델 타임아웃 튜닝에 수 시간을 낭비하게 됩니다.
확장 프로그램 녹색을 E2E 통과로 오인: ON은 relay 프로세스가 리스닝 중임을 의미할 뿐입니다. 대상 사이트에서 탭을 열고 Attach하지 않으면 CDP는 no tab을 보고합니다.
터널 방향 역전: 원격 Gateway가 로컬 18792에 도달해야 할 때는 원격 포워딩 -R을 사용합니다. -L로 원격 18789만 노트북에 매핑하면 브라우저 평면은 수정되지 않습니다.
토큰과 포트 표 드리프트: relay token, 터널 매핑, 확장 옵션은 동일 세트여야 합니다. 하나만 변경하면 401이나 빈 포트가 발생합니다.
헤드리스 Docker와 혼동: 컨테이너에는 shm_size가 필요합니다. 로컬 Relay에는 터널과 Attach가 필요합니다. 헤드리스 체크리스트를 참조하세요.
편의를 위해 Gateway를 0.0.0.0에 바인딩: 제어 평면 노출이 확대됩니다. loopback + 터널 또는 사설망을 유지하고 네트워킹 문서를 따르세요.
다섯 항목을 변경 티켓의 터널 필수 조건과 금지 패턴으로 문서화하세요. 다음 절에서는 헤드리스 컨테이너와 로컬 Relay 사이의 서명 가능한 매트릭스를 제시한 뒤 복사 가능한 수용 단계로 진행합니다.
개인 취향이 아니라 브라우저 실행 위치, 사용자 세션 보유 주체, 컴플라이언스 경계에 따라 선택하세요. 표에서 하나를 고른 뒤 동일 변경 창에서 두 스택을 동시에 튜닝하지 마세요.
| 패턴 | 적합 시나리오 | 주요 비용과 리스크 |
|---|---|---|
| Docker 헤드리스 Chromium | 노트북 SSO 불필요한 무인 VPS 배치 | shm/메모리 피크 높음. 핑거프린트가 실제 프로필과 다를 수 있음 |
| 로컬 Chrome + Relay | 노트북 Cookie/SSO, 대화형 디버깅 필요 | SSH 터널과 확장 Attach 필요. 원격 Gateway는 브라우저를 공인망에 노출하면 안 됨 |
| 전용 24/7 클라우드 Mac + Relay | 동일 리전 팀 공유 용량 | 운영 비용은 높지만 SLA와 터널 템플릿을 방어 가능 |
Relay 안정성은 18792 소유 주체, 터널이 어떤 localhost를 매핑하는지, 토큰이 동일 세트인지에 달려 있습니다. 다른 튜닝은 부차적입니다.
2026년 공식 가이드는 제어 평면에 openclaw onboard --install-daemon, openclaw gateway status, openclaw doctor를 권장합니다. 브라우저 Skill에는 relay health와 탭 Attach를 Gateway 녹색과 동등한 릴리스 게이트로 추가하세요.
이 순서는 Gateway 설치 문제 해결 체크리스트의 연장입니다. 제어 평면을 증명한 뒤 브라우저 평면으로 진행합니다. 각 단계 출력을 티켓에 붙여 넣으세요.
Gateway 수용: VPS에서 openclaw gateway status를 실행하고 18789(또는 문서화된 포트) loopback 바인딩을 확인합니다. 도달성은 프록시 또는 SSH만 허용합니다.
로컬 Relay 시작: Chrome 확장 프로그램을 설치하고 노트북에서 curl -sS http://127.0.0.1:18792/health를 실행합니다.
탭 Attach: 대상 사이트를 열고 확장으로 Attach합니다. Attach 없이는 no tab is connected가 예상됩니다.
터널 생성: 노트북에서 예: ssh -N -R 18793:127.0.0.1:18792 user@vps를 실행하고 Gateway relay URL을 VPS의 127.0.0.1:18793로 지정합니다.
토큰 정렬: Gateway relay/gateway token을 확장 또는 환경 변수 주입과 일치시킵니다. 터널 경유 401에서는 gateway token 헤더를 확인합니다.
엔드투엔드 Skill: 최소 브라우저 Skill을 실행하고 openclaw logs --follow를 tail합니다. 실패 시 증상표에서 한 변수씩 조정합니다.
curl -sS http://127.0.0.1:18792/health openclaw gateway status ssh -N -R 18793:127.0.0.1:18792 user@your-vps.example curl -sS http://127.0.0.1:18793/health
팁: 컨테이너 내 헤드리스 브라우저로 전환할 경우 헤드리스 Skill 체크리스트를 사용하고 본 Runbook에 shm 조정을 겹치지 마세요.
증상부터 색인합니다. 실험마다 한 변수만 변경하고 curl과 로그 조각을 보관하세요.
| 증상 | 먼저 확인 | 일반적 원인과 조치 |
|---|---|---|
| 확장 ON, Skill이 no tab connected | 대상 URL에서 탭 열고 Attach 했는지 | 운영 게이트. Runbook에 명시 |
| 터널 후 curl mapped-port /health 실패 | ssh -R 생존, 원격 리스너 | 터널 종료 또는 포트 점유. ss -lntp 사용 |
| Relay 401 / unauthorized | 토큰 헤더와 설정 | 원격 터널이 gateway token 미사용. 설정 정렬 |
| EADDRINUSE인데 브라우저 불가 | 프로브 포트 vs 실제 Relay 포트 | 포트 표 통일. 커뮤니티 터널 사례 참조 |
| Gateway CLI 타임아웃 | 18789 도달성, SSH -L | Relay를 의심하기 전 네트워킹 문서를 읽으세요 |
주의: API 키, 리버스 프록시 인증서, 터널 포트를 한 번에 교체하지 마세요. 삼중 변경은 이분 탐색이 불가능합니다.
로컬 Relay는 대화형 디버깅과 노트북 사용자 신원에 적합합니다. 24/7 무인 실행이 필요하거나 개인 노트북 터널을 유지할 수 없을 때 토폴로지를 이전하세요.
| 신호 | 권장 조치 | 비고 |
|---|---|---|
| 다수 사용자가 한 개발자 노트북 터널에 의존 | 헤드리스 Docker 또는 전용 클라우드 Mac으로 이전 | 버스 팩터 제거 |
| 절전으로 터널이 주간 단위로 끊김 | 리전 고정 24/7 노드 + 표준화 ssh/systemd | 터널 uptime을 SLO에 포함 |
| 공인망 브라우저 도달이 요구사항 | 금지. 헤드리스 또는 준수 원격 데스크톱 | Relay는 loopback 신뢰를 가정 |
애드혹 VPS + 수동 SSH는 초기에 유연하지만, 프로덕션 OpenClaw에는 서명 가능한 용량과 티켓화된 변경이 필요합니다. Gateway와 브라우저 워크로드를 예측 가능한 24/7 클라우드 Mac 풋프린트에 두고 고정 Runbook으로 관리하는 것이 반복적인 포트 수정보다 효율적입니다. 전용·리전 안정 Mac 용량이 필요한 팀에는 제어 평면과 Relay 또는 헤드리스 프로필을 동거시키기 위한 VpsMesh Mac Mini 클라우드 대여가 일반적으로 더 적합합니다. 가격은 가격 페이지, 안내는 고객 센터를 참조하세요.
디버깅용으로 -L 18789:127.0.0.1:18789로 원격 Gateway 제어 평면을 노트북으로 가져옵니다. -R로 VPS가 로컬 18792에 도달하고 Gateway relay URL과 일치시킵니다. 제어 평면 타임아웃은 Compose 네트워킹 문서를 참조하세요.
먼저 대상 사이트에서 탭을 열고 Attach하세요. Attach 후에도 실패하면 터널 health와 토큰을 확인하고 설치 문제 해결 체크리스트의 로그 순서를 따르세요.
권장하지 않습니다. loopback + SSH/사설망을 유지하거나 헤드리스 Docker Skill 또는 전용 노드로 전환하세요.