🦞 12. 브라우저 릴레이 연동 구조

브라우저 릴레이가 자꾸 흔들릴 때 많은 사람이 확장 아이콘이나 포트 포워딩만 의심한다. 그런데 실제로는 더 앞단에서 구조를 잘못 잡은 경우가 많다. 기본 작업을 어떤 프로필로 처리할지, 기존 로그인 브라우저가 꼭 필요한지, 문제가 브라우저인지 게이트웨이인지를 먼저 나누지 않으면 같은 증상이 계속 반복된다. 이 문서는 그 분기점을 한 번에 정리한 운영 가이드다.

안내: 본문은 생성형 AI를 활용해 초안을 작성하고, 공식 문서와 실제 운영 로그를 기준으로 사람이 검수해 보정했습니다.

flowchart LR
A[브라우저 작업 요청] --> B{기존 로그인/쿠키가 꼭 필요한가?}
B -->|아니오| C[profile=openclaw]
B -->|예| D{사용자 브라우저 제어인가?}
D -->|예| E[profile=user]
D -->|확장 attach 탭 필요| F[chrome-relay 경로]
C --> G[status → tabs → snapshot]
E --> G
F --> H[툴바 아이콘 ON 확인]
H --> G
G --> I{여전히 실패?}
I -->|예| J[gateway status / probe / SSH 포트 확인]
I -->|아니오| K[작업 진행]

결론 먼저

브라우저 작업을 안정적으로 굴리려면 기본값은 profile=openclaw, 기존 로그인 세션이 꼭 필요할 때만 profile=user, 확장 attach 탭 흐름이 필요한 예외 상황에서만 relay 경로로 나누는 것이 가장 덜 깨진다. 그리고 장애 진단은 status → tabs → snapshot으로 끝내지 말고, 필요할 때 openclaw gateway status --require-rpc와 openclaw gateway probe까지 이어서 봐야 한다.

공식 브라우저 문서는 openclaw를 전용 관리형 브라우저 프로필로, user를 기존 로그인 브라우저 제어 경로로 설명한다. 따라서 릴레이 문제를 줄이려면 “모든 브라우저 작업을 기존 Chrome으로 붙인다”가 아니라 “기본은 전용 프로필, 예외만 기존 세션”으로 설계를 바꾸는 편이 안전하다.

• 브라우저 CLI 참고: https://docs.openclaw.ai/cli/browser
• 게이트웨이 CLI 참고: https://docs.openclaw.ai/cli/gateway

30초 판단표

아래 세 줄만 제대로 구분해도 장애율이 많이 떨어진다.

지금 하려는 일	권장 경로	이유
문서 점검, 일반 자동화, 재현 가능한 테스트	profile=openclaw	attach 클릭 없이 바로 재현 가능하고, 세션 오염이 적다
내가 이미 로그인한 브라우저 상태를 그대로 써야 함	profile=user	기존 계정/쿠키/열린 탭을 그대로 활용할 수 있다
확장 툴바 아이콘을 눌러 특정 탭을 attach해야 함	relay 경로	탭 단위 attach가 핵심이라, 브라우저 상태보다 attach 성공 여부가 더 중요하다

실무에서는 첫 줄을 기본값으로 두고, 두 번째와 세 번째를 예외 처리로 두는 편이 가장 단순하다.

왜 자꾸 실패처럼 보이나

겉보기 증상은 비슷하지만 원인은 크게 네 갈래다.

1. 프로필 선택이 잘못된 경우
   기본 자동화인데도 기존 로그인 브라우저부터 붙으려 하면, 쿠키·확장·열린 탭 상태에 따라 재현성이 급격히 떨어진다.
2. 탭 attach가 빠진 경우
   relay 경로는 브라우저가 열려 있어도 실제 작업 탭에 attach가 안 되면 tabs=0처럼 보일 수 있다.
3. 게이트웨이 쪽 문제가 섞인 경우
   브라우저가 죽은 줄 알았는데 실제로는 Gateway RPC가 불안정하거나 원격 포워딩이 꼬인 사례가 많다.
4. 탐지와 조작 단계를 섞는 경우
   status와 tabs는 되는데 snapshot이나 navigate가 실패하면, 브라우저 전체보다는 권한·정책·접근 제한 문제일 가능성이 더 높다.

공식 브라우저 문서도 비슷한 흐름을 권한다. status와 tabs가 통과했는데 snapshot 또는 navigate가 실패하면, 브라우저 제어면 전체보다 개별 페이지 접근 정책이나 SSRF 제한 쪽을 먼저 의심하라고 안내한다.

가장 덜 깨지는 운영 기준선

1) 기본값은 openclaw

일반적인 웹 자동화, 문서 점검, 테스트 재현은 openclaw 프로필이 가장 안정적이다. OpenClaw가 관리하는 전용 브라우저라서, “어제 누가 어떤 탭을 열어뒀는지” 같은 외부 변수가 적다.

실행 예시는 아래처럼 아주 짧게 끝난다.

openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw snapshot

검증 포인트는 간단하다.

• status가 살아 있는가
• tabs에 실제 탭이 잡히는가
• snapshot이 페이지 내용을 읽어 오는가

이 셋이 모두 통과하면, 브라우저 제어면은 대체로 건강하다고 봐도 된다.

2) 기존 로그인 브라우저가 꼭 필요할 때만 user

Gmail, 내부 SaaS, 기존 로그인 세션처럼 “이미 로그인해 둔 브라우저 상태”가 중요한 작업은 user 경로가 맞다. 다만 이 경로는 편한 대신, 사용자의 실제 브라우저 상태 영향을 직접 받는다. 확장 충돌, 탭 정리, 세션 만료 같은 변수가 곧바로 결과에 반영된다.

그래서 운영 기준은 단순해야 한다.

1. 기본 자동화는 openclaw
2. 기존 로그인 상태가 필요한 요청만 user
3. 한 번 실패했다고 곧바로 릴레이 전체를 의심하지 말고, 먼저 현재 브라우저 세션이 실제로 살아 있는지 확인

이 분리를 해 두면 같은 “브라우저 작업”이라도 장애 원인을 훨씬 빨리 좁힐 수 있다.

3) relay 경로는 확장 attach가 필요한 예외 흐름

브라우저 릴레이를 “모든 사용자 브라우저 제어의 기본값”으로 놓으면 헷갈린다. relay 경로는 보통 브라우저 툴바 아이콘을 눌러 특정 탭을 attach하는 흐름이 핵심이다. 즉, 브라우저가 열렸는지보다 작업 탭에서 attach가 성공했는지가 더 중요하다.

실패할 때는 아래 순서로 보는 편이 좋다.

1. 옵션 페이지가 아니라 실제 작업 탭에서 relay 아이콘이 ON인지 확인
2. tabs에서 attach된 탭이 보이는지 확인
3. 그래도 안 되면 브라우저보다 게이트웨이/포트 포워딩 쪽을 확인

이 경로는 “기존 브라우저를 그대로 쓰겠다”는 요구가 아니라, “특정 탭 attach가 꼭 필요한가”라는 질문으로 판단해야 덜 꼬인다.

진단 순서는 status → tabs → snapshot → gateway

문제가 생겼을 때 많은 사람이 tabs=0만 보고 원인을 단정한다. 하지만 실무에서는 브라우저와 게이트웨이를 분리해서 보는 습관이 더 중요하다.

1단계. 브라우저 상태 확인

openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw snapshot

여기서 status와 tabs는 되는데 snapshot만 실패하면, 브라우저 프로세스 자체보다는 대상 페이지 정책이나 접근 제한 쪽을 먼저 본다.

2단계. Gateway RPC 확인

openclaw gateway status --require-rpc
openclaw gateway probe

이 두 명령은 “프로세스가 떠 있냐”보다 한 단계 더 나아가, 실제 Gateway RPC가 응답 가능한지를 확인하는 데 유용하다. 공식 문서도 --require-rpc를 스크립트/자동화에서 권장한다. 단순히 서비스가 떠 있는 것만으로는 브라우저 툴이 정상이라고 단정할 수 없기 때문이다.

3단계. 원격 접속이면 SSH 포워딩 확인

lsof -nP -iTCP:18789 -sTCP:LISTEN
lsof -nP -iTCP:18792 -sTCP:LISTEN
ssh -G relay39 | egrep '^(hostname|user|identityfile) '
ssh -o BatchMode=yes relay39 'echo relay39-ok'

여기서 막히면 브라우저 명령을 더 쌓아도 해결되지 않는다. 이 단계는 특히 멀티 머신에서 중요하다.

한 번에 끝내는 기본 세팅

A. 단일 머신 기본 운영

한 대의 머신에서만 브라우저를 쓴다면, 아래처럼 단순하게 두는 편이 좋다.

1. 기본 프로필은 openclaw
2. 기존 로그인 브라우저가 필요할 때만 user
3. 확장 attach가 필요한 예외에서만 relay
4. 문제가 생기면 browser status 다음에 바로 gateway status --require-rpc

이 구조는 문서화도 쉽고, 팀 내 설명 비용도 낮다.

B. 원격 머신 2대 이상 운영

두 대 이상의 원격 머신을 오갈 때는 포트를 분리하지 않으면 금방 꼬인다. 예를 들어 37번 머신과 39번 머신을 동시에 쓴다면 로컬 포트를 겹치지 않게 잡아야 한다.

# 예시: 37번은 28789/28792, 39번은 38789/38792
ssh -fN -M -S "$HOME/.ssh/rel37.sock" \
  -o ExitOnForwardFailure=yes \
  -L 28789:127.0.0.1:18789 \
  -L 28792:127.0.0.1:18792 \
  relay37
 
ssh -fN -M -S "$HOME/.ssh/rel39.sock" \
  -o ExitOnForwardFailure=yes \
  -L 38789:127.0.0.1:18789 \
  -L 38792:127.0.0.1:18792 \
  relay39

공식 게이트웨이 문서도 여러 게이트웨이가 동시에 보일 수는 있지만, 대부분의 운영에서는 한 머신에 한 게이트웨이를 기준으로 보고 진단하라고 설명한다. 그래서 포트를 분리하지 않으면 “어느 머신에 붙은 상태인지”부터 헷갈리기 쉽다.

미니 사례로 이해하기

사례 A. 잘 된 경우

운영팀이 기본값을 openclaw로 고정하고, Gmail처럼 로그인 상태가 필요한 경우에만 user를 열었다. 그 결과 브라우저 장애 문의가 “전체 브라우저가 안 된다”가 아니라 “이 작업만 user 쪽 세션이 만료됐다”처럼 훨씬 구체적으로 바뀌었다. 문제를 좁히는 시간이 크게 줄었다.

사례 B. 자주 꼬이는 경우

다른 팀은 모든 브라우저 작업을 기존 로그인 브라우저에서만 처리했다. 처음에는 편했지만, 누군가 탭을 닫거나 확장을 꺼 두면 자동화가 재현되지 않았다. 결국 테스트는 openclaw, 실제 세션 의존 작업만 user로 나눈 뒤에야 실패 패턴이 정리됐다.

사례 C. 브라우저 문제처럼 보였지만 사실은 Gateway 문제였던 경우

tabs가 들쭉날쭉하고 snapshot이 간헐적으로 실패해 브라우저를 재설치하려 했지만, 실제 원인은 원격 포트 포워딩 충돌이었다. openclaw gateway status --require-rpc와 gateway probe를 먼저 봤다면 훨씬 빨리 원인을 찾을 수 있었던 사례다.

팀에 바로 적용할 운영 순서

1. 운영 담당자는 팀 기본값을 openclaw로 문서화한다.
2. 실사용자는 기존 로그인 상태가 꼭 필요한 작업만 user로 요청한다.
3. 고급 사용자는 특정 탭 attach가 필요한 예외 상황에서만 relay 경로를 쓴다.
4. 장애 대응 담당자는 status → tabs → snapshot → gateway status --require-rpc → gateway probe 순서를 런북으로 고정한다.
5. 멀티 머신 운영자는 머신별 로컬 포트를 분리하고, SSH 별칭과 종료 명령까지 함께 관리한다.

이 다섯 줄만 팀 기준선으로 잡아도 “브라우저가 안 된다”는 막연한 장애 보고가 많이 줄어든다.

적용 체크리스트

• 일반 자동화 기본값을 openclaw로 두었다.
• 기존 로그인 세션이 필요한 작업만 user로 분리했다.
• relay 경로는 탭 attach가 필요한 예외 흐름으로만 사용한다.
• 브라우저 진단 뒤에 openclaw gateway status --require-rpc를 확인한다.
• 원격 머신이 둘 이상이면 로컬 포트를 분리했다.
• 팀 런북에 status → tabs → snapshot → gateway probe 순서를 적어 두었다.

다음 읽기

• 32. OpenClaw browser에서 Access denied가 뜰 때 해결
• 33. gateway status는 정상인데 browser가 안 될 때 해결
• 11. Gmail 연결
• 28. 듀얼 릴레이 운영 가이드
• systemd 충돌 해결

AI 생성 결과물을 포함한 문서입니다. 배포 전 브라우저 프로필 정책, SSH 포워딩, Gateway 인증 방식은 각 운영 환경에 맞게 최종 확인하세요.