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

브라우저 릴레이를 오래 쓰다 보면, 도구 문제처럼 보이지만 실제 원인은 대부분 운영 구조에 있다. 특히 “어떤 프로필로 붙는지”와 “포트를 어떻게 나눴는지”를 먼저 고정하지 않으면, 탭 ON을 눌러도 연결이 흔들린다. 이 문서는 실무에서 가장 덜 깨지는 기준선을 한 번에 정리한 운영 가이드다.

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

flowchart LR
A[문제 인지: 릴레이 연결 실패] --> B[원인 분해: 프로필/포트/계정]
B --> C{대응 선택}
C --> D[기본: openclaw profile]
C --> E[예외: chrome relay + 탭 ON attach]
D --> F[실행/검증]
E --> F

결론 먼저

브라우저 작업을 안정적으로 굴리려면, 기본 profile=openclaw + 예외 profile=chrome(탭 attach 필수) 구조로 고정하는 것이 가장 안전하다.

왜 자꾸 실패처럼 보이나

같은 “브라우저 연결”이라도 실제 동작 방식이 다르다.

• profile=chrome: 확장(Extension) 탭 attach가 필요하다. 탭 ON이 끊기면 바로 0 tabs 상태가 된다.
• profile=openclaw: OpenClaw가 관리하는 전용 브라우저라 attach 클릭 과정이 없다.

이 차이를 모르면, 터널은 정상인데도 “왜 안 붙지?”가 반복된다.

칠판 판서형 치트시트

1. 일반 업무 기본값은 profile=openclaw.
2. 기존 Chrome 세션이 꼭 필요할 때만 profile=chrome + 탭 attach ON.
3. 37/39 동시 운영은 로컬 포트를 반드시 분리(2879x / 3879x).
4. 실패 시 status → tabs → 포트점유(lsof) 3단계로 확인.

개념/원인/대응/실행 (MECE)

1) 개념: 프로필 2개를 다르게 쓴다

• openclaw 프로필: 자동화 안정성 우선
• chrome 프로필: 기존 탭/쿠키 재사용 우선

공식 참고: OpenClaw browser CLI/profile 동작은 openclaw browser 문서 기준으로 관리한다.
https://docs.openclaw.ai/cli/browser

2) 원인: 현장에서 가장 많이 터지는 4가지

1. chrome로 붙어 있는데 탭 ON attach를 안 함
2. options 페이지에서만 보고 “붙었다”고 오해함(실제 작업 탭 attach 누락)
3. 37/39를 같은 로컬 포트로 포워딩해서 충돌
4. alias와 함수를 같은 이름으로 중복 정의해서 셸 로딩 오류 발생

3) 대응: 운영 기준선

• 기본 운영: profile=openclaw 고정
• 예외 운영: profile=chrome (탭 attach 필수)
• 멀티머신: 포트 분리 + 스크립트 분리 + SSH Host 별칭 사용

참고 심화 문서(선택):
28. 듀얼 릴레이 운영 가이드

4) 실행: 빠른 점검 명령

# 현재 프로필 상태 확인
openclaw browser status --browser-profile openclaw
openclaw browser status --browser-profile chrome
 
# 탭 감지 확인
openclaw browser tabs --browser-profile openclaw
openclaw browser tabs --browser-profile chrome
 
# 포트 점유 확인(충돌 탐지)
lsof -nP -iTCP:18789 -sTCP:LISTEN
lsof -nP -iTCP:18792 -sTCP:LISTEN

한 번에 끝내는 기본 세팅 (이 문서만으로)

아래 순서대로 하면, 12번 문서만 보고도 실제 운영이 가능하다.

1) SSH Host 별칭 고정

~/.ssh/config에 머신별 별칭을 먼저 만든다.

Host relay37
  HostName <HOST_37_IP_OR_DNS>
  User <HOST_37_USER>
  IdentityFile ~/.ssh/<HOST_37_KEY>
  IdentitiesOnly yes
 
Host relay39
  HostName <HOST_39_IP_OR_DNS>
  User <HOST_39_USER>
  IdentityFile ~/.ssh/<HOST_39_KEY>
  IdentitiesOnly yes

검증:

chmod 600 ~/.ssh/config
ssh -G relay39 | egrep '^(hostname|user|identityfile) '
ssh -o BatchMode=yes relay39 'echo relay39-ok'

2) 포트 분리 릴레이 스크립트 생성

mkdir -p ~/.openclaw-relay
 
cat > ~/.openclaw-relay/rel37.sh <<'EOF'
#!/usr/bin/env bash
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
EOF
 
cat > ~/.openclaw-relay/rel39.sh <<'EOF'
#!/usr/bin/env bash
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
EOF
 
chmod +x ~/.openclaw-relay/rel37.sh ~/.openclaw-relay/rel39.sh

3) 셸 명령 고정(alias)

~/.zshrc에 추가:

unalias rel37 rel39 rel_ls rel37_off rel39_off 2>/dev/null
alias rel37="$HOME/.openclaw-relay/rel37.sh"
alias rel39="$HOME/.openclaw-relay/rel39.sh"
alias rel_ls='lsof -nP -iTCP:28789 -iTCP:28792 -iTCP:38789 -iTCP:38792 -sTCP:LISTEN'
alias rel37_off='ssh -S $HOME/.ssh/rel37.sock -O exit relay37 2>/dev/null || true'
alias rel39_off='ssh -S $HOME/.ssh/rel39.sock -O exit relay39 2>/dev/null || true'

적용:

exec zsh

4) 기본 운영(openclaw 프로필) 확인

rel39
rel_ls
curl -I http://127.0.0.1:38789/
 
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw tabs

여기까지 되면 기본 자동화는 바로 실행 가능하다.

5) 예외 운영(chrome 프로필) 확인

openclaw browser --browser-profile chrome status
openclaw browser --browser-profile chrome tabs

중요:

• chrome 프로필은 터미널 명령만으로 attach가 완료되지 않는다.
• 실제 브라우저 탭에서 OpenClaw Relay 확장 아이콘을 눌러 ON 해야 한다.

6) 3분 복구 루틴

문제가 생기면 아래만 순서대로 확인한다.

# 1) 터널/포트
rel_ls
curl -I http://127.0.0.1:38789/
 
# 2) SSH 별칭
ssh -G relay39 | egrep '^(hostname|user|identityfile) '
ssh -o BatchMode=yes relay39 'echo relay39-ok'
 
# 3) 브라우저 프로필 상태
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile chrome status
openclaw browser --browser-profile chrome tabs

운영 선택 가이드

지금 하려는 일	권장 프로필	실무 판단 기준
문서 작성, 사이트 점검, 일반 웹 자동화	openclaw	attach 클릭 없이 바로 재현 가능해서 장애율이 낮다
기존 Chrome 로그인 세션/확장 상태를 그대로 써야 함	chrome	이미 열어둔 탭·쿠키를 재사용할 수 있다 (탭 attach 필수)
37/39 원격 전환이 잦음	openclaw 우선 + 분리 포트	전환 중 실수(포트 충돌, attach 누락)를 줄일 수 있다

현장형 미니 사례

사례 A (성공)

운영팀이 기본 프로필을 openclaw로 고정하고, chrome은 “예외 작업”으로만 열었다. 일주일 내 tabs=0 문의가 눈에 띄게 줄었고, 작업 착수 시간이 짧아졌다.

사례 B (실패)

다른 팀은 rel37/rel39를 같은 로컬 포트(18789/18792)로 동시에 포워딩했다. 연결은 되는 듯 보였지만 세션이 번갈아 끊겼고, 포트를 2879x/3879x로 분리한 뒤에야 안정화됐다.

도입 우선순위 (누가/무엇/순서)

1. 운영 담당자: 팀 기본값을 openclaw로 공지하고, chrome은 예외 조건(attach 필요)로 문서화한다.
2. 자동화 담당자: rel37/rel39 포트를 분리하고 status → tabs → lsof 점검 명령을 런북에 고정한다.
3. 실사용자: chrome 사용 시 “탭에서 Relay 아이콘 ON”을 시작 체크리스트 1번으로 둔다.

적용 체크리스트

• 기본 브라우저 작업은 openclaw 프로필로 실행한다.
• chrome 프로필 사용 시 탭 attach가 필요하다는 것을 팀이 인지한다.
• 37/39 릴레이는 포트를 분리해 동시에 운영 가능하다.
• 셸에서 rel alias/function 중복이 없다.
• 장애 대응 순서(status → tabs → lsof)가 문서화돼 있다.

다음 읽기

• 18. 텔레그램 5분 복구
• 23. node run plaintext ws 보안 에러 해결
• 25. 크론 서브에이전트 분산운영
• 28. 듀얼 릴레이 운영 가이드

AI 생성 결과물을 포함한 문서입니다. 배포 전 네트워크 정책, SSH 계정, 포트 정책은 각 운영 환경에 맞게 최종 확인하세요.