2026년 OpenClaw Playwright skill-browser 헤드리스 Mac VPS 배포: Chromium 동일 계정 설치, 병렬 상한과 오류 대조 Runbook(의사결정표와 FAQ)

Mac VPS에서 OpenClaw가 IM 채널을 7×24 돌리는데 Agent에게 웹 페이지 열기, 폼 입력, 경쟁사 스냅샷 수집까지 맡기려면 「노트북에서 잠깐 Chrome을 여는」 운영으로는 감사 가능한 프로덕션 역량이 되지 않습니다. OpenClaw skill-browser는 Playwright 헤드리스 Chromium을 기반으로 브라우저 동작을 게이트웨이 도구면에 연결합니다. 본문은 SSH만 가능하고 데스크톱이 없는 Mac 클라우드 운영자와 플랫폼 책임자를 위해 전형 네 가지 통증을 분해하고, 헤드리스 Mac VPS vs 로컬 화면 Mac vs Docker browser 의사결정표, 사전 체크리스트, 병렬 파라미터 표, 7단계 Runbook, 세 가지 인용 가능한 판정, 오류 대조표, 업무 사례까지 한 Runbook으로 정리합니다. 게이트웨이 install, Docker 7×24, 버전 고정, ClawHub 감사 내부 링크로 연결해 Apple Silicon Mac 클라우드에서 재현 가능한 배포를 목표로 합니다.

헤드리스 Mac VPS에서 OpenClaw 게이트웨이가 skill-browser로 Playwright Chromium을 구동해 페이지 자동화를 수행하는 개념도

목차

1. 통증 분해: Chromium 누락, OOM, 모달 차단

skill-browser는 장애면을 브라우저 자식 프로세스까지 확장합니다. 게이트웨이가 online이어도 첫 navigate에서 실패하는 경우가 흔합니다. IM 채널은 정상인데 Agent가 「페이지를 열 수 없다」고만 응답할 때, 로그에는 tool timeout만 남고 Chromium stderr는 별도 파일에 흩어지는 패턴도 많습니다. 프로덕션에서 반복되는 전형 패턴을 네 가지로 정리합니다.

  1. Chromium 미동일 계정 설치: CLI와 launchd 사용자가 다르면 캐시가 갈라지고 로그에 실행 파일을 찾을 수 없다고 남습니다. SSH 세션에서만 npx puppeteer를 실행해도 상주 게이트웨이는 다른 사용자 HOME을 볼 수 있습니다.
  2. Exit 137: parallel contexts를 과도하게 올리면 Chromium이 OOM Kill되고 게이트웨이에는 tool timeout만 남습니다. 메모리 8GB 미만 노드에서 context 4 이상을 시도하면 재현하기 쉽습니다.
  3. HOME 분열: SSH에서는 스모크 성공, launchd에서는 실패. 설정 디렉터리 쓰기 불가 또는 profile 잠금이 남는 전형입니다. echo $HOME과 plist EnvironmentVariables를 반드시 대조하세요.
  4. 모달 차단: blockedByDialog 미설정 시 evaluate가 걸리고 빈 스냅샷이 반환됩니다. Cookie 동의나 SSO 대화상자가 원인인 경우가 많아 fail-fast와 dismiss 정책을 먼저 정해야 합니다.

2. 의사결정표: 헤드리스 Mac VPS vs 로컬 Mac vs Docker browser

selector 디버깅과 UI 확인은 로컬 화면 Mac이 적합합니다. 개발자가 노트북에서 headless=false로 눈으로 확인한 뒤, 동일 설정을 Mac VPS에 그대로 복사하면 display 오류로 실패하는 경우가 잦습니다. 7×24와 포트 18789 동일 호스트, JSONL toolCallId 추적이 필요하면 헤드리스 Mac 클라우드가 1순위입니다. Docker 내부 browser 운영은 7×24 Runbook을 참고하세요.

관점 헤드리스 Mac VPS 로컬 화면 Mac Docker 내부 browser
지연 게이트웨이 동일 호스트로 RTT 낮음, 프로덕션 적합 개발 편하지만 슬립 시 연결 끊김 네트워크·볼륨 권한 한 단계 추가
디스크 Chromium 캐시 약 300–500 MB 경로 통일 어려움 재빌드마다 재다운로드
권한 순수 headless, launchd 정렬 수동 모달 조작 가능 137과 봇 탐지에 취약
운영 게이트웨이 Runbook 참고 7×24 불가 장애 분석 체인 길음
시나리오 폼 입력, 스냅샷, IM 연동 selector 디버깅 단시간 배치

3. Mac VPS 사전 조건: Node 22, 18789, 동일 계정 HOME

skill-browser를 넣기 전에 게이트웨이 본체가 안정적인지 확인하세요. 반쯤 설치된 상태에서 browser skill만 추가하면 장애 분기가 더 어려워집니다. 특히 launchd로 상주하는 사용자와 대화형 SSH 사용자가 다르면, doctor는 통과해도 실제 navigate는 다른 HOME 아래 캐시를 찾습니다. 변경 전후로 openclaw gateway status --deep 출력을 보관해 두면 롤백 시 비교가 수월합니다.

openclaw doctor
openclaw gateway status
echo "USER=$USER HOME=$HOME"

4. skill-browser 파라미터 표: headless, 병렬, 타임아웃

skill-browser는 Playwright 헤드리스 Chromium을 기반으로 동작합니다. 아래 표는 리뷰용 골격입니다. 업그레이드 후 openclaw doctor로 재확인하세요. 프로덕션에서는 parallel contexts를 단계적으로 올리며 각 단계에서 RSS와 스냅샷 성공률을 기록하는 것을 권장합니다.

설정 키 권장 방향 흔한 오설정
headless 데스크톱 없는 환경은 true false로 display 없음
parallel contexts 초기 1–2, context당 약 400–600 MB 4 이상이면 OOM 137
timeout-ms navigate 3–6만 ms 너무 짧으면 실패, 길면 큐 점유
blockedByDialog 모달 dismiss 또는 fail-fast 미설정 시 evaluate hang
openclaw skills install skill-browser
npx puppeteer browsers install chromium

5. 7단계 Runbook: 계정 → 설치 → Chromium → 프로브 → 스모크 → launchd

아래 7단계를 변경 템플릿에 고정하고 각 단계에서 toolCallId 또는 doctor 출력을 남기세요. 롤백 시에도 같은 순서로 재검증할 수 있습니다. 스모크 URL은 내부 대시보드처럼 SSO가 없는 정적 페이지와, 실제 업무에서 쓰는 동적 페이지를 각각 하나씩 두면 blockedByDialog 정책을 조기에 검증할 수 있습니다. launchd 재기동 후에는 반드시 cold start 시간을 다시 측정하세요.

  1. 계정과 HOME 정렬: launchd plist UserName 확인. SSH는 동일 사용자로 로그인, echo $HOME이 plist와 일치.
  2. 버전 고정과 doctor: openclaw.json 백업 후 openclaw doctor. 업그레이드는 5월 버전 릴리스 트레인 Runbook 준수.
  3. skill-browser 설치: 감사 후 openclaw skills install skill-browser.
  4. Chromium 설치: 동일 계정으로 npx puppeteer browsers install chromium.
  5. 파라미터 기록: headless, parallel contexts, timeout-ms, blockedByDialog 설정.
  6. 프로브와 스모크: 18789 수신, 고정 URL 스냅샷, toolCallId 기록.
  7. launchd 검수: launchctl로 plist 로드, 재시작 후 스모크 재실행.
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist 2>/dev/null
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist
openclaw doctor
openclaw gateway status

6. 세 가지 판정: 콜드 스타트, RSS, 스냅샷 성공률

프로덕션 선언 전 아래 세 지표를 대시보드화하고 장애 시 임계값으로 분기하세요. 모두 게이트웨이 JSONL toolCallId와 대조합니다. 주간 릴리스 전에는 이 세 수치를 baseline으로 고정해 두면 회귀를 빠르게 잡을 수 있습니다.

7. 오류 대조표와 계층별 장애 분석

「browser 도구 실패」는 계층별로 나눕니다: Chromium 존재 → 동일 계정 HOME → headless/병렬 파라미터 → 모달과 timeout. 각 계층에서 JSONL toolCallId를 맞추고 감각적 재시작만 의존하지 마세요. Exit 137이 간헐적이면 메모리 그래프와 parallel contexts 변경 시각을 겹쳐 보세요. evaluate 타임아웃이 특정 도메인에서만 발생하면 timeout을 늘리기 전에 해당 사이트의 bot 탐지·지역 차단 여부를 먼저 확인하는 편이 낫습니다.

증상 근본 원인 복구
Chromium 없음 미설치 또는 사용자 불일치 동일 사용자 browser 재설치 + doctor
Exit 137 과도 병렬 / OOM parallel contexts 하향
blockedByDialog 모달 미처리 dismiss 또는 fail-fast
evaluate 타임아웃 timeout 과단 / 봇 탐지 timeout 조정 또는 URL 변경

8. 업무 사례: 폼 입력, 모니터링, IM 연동

고객 지원 페이지 자동 입력: Agent가 Telegram으로 티켓을 받고 skill-browser가 내부 폼을 열어 필드를 채운 뒤 스크린샷을 반송합니다. SSO 모달은 fail-fast로 두어 무한 대기를 막고, 실패 시 toolCallId와 함께 운영 채널로 알림을 보냅니다.

경쟁사 모니터링: cron으로 고정 selector 스냅샷을 JSONL에 기록하고, parallel은 1로 유지해 OOM을 방지합니다. selector 변경은 스냅샷 diff로 조기에 감지할 수 있습니다.

열람 후 회신: 사용자가 @bot으로 문서를 물으면 먼저 navigate한 뒤 요약합니다. 로그인 필요 페이지나 JavaScript로 렌더링되는 문서 포털처럼 단순 fetch로는 부족한 경우에 특히 유용합니다.

9. FAQ

질문: skill-browser는 Ollama나 다중 Provider와 공존할 수 있나요? 가능합니다. browser 자식 프로세스는 독립적이며 tools.profile에서 병렬 상한을 두고 RSS를 관찰하세요.

질문: v2026.5.x 업그레이드 후 재검증이 필요한가요? doctor, 동일 계정 Chromium 재설치, 최소 스냅샷 스모크가 필요합니다. 버전 릴리스 트레인 Runbook 참고.

질문: Mac 클라우드 vs Linux VPS/Docker 선택은? 7×24와 게이트웨이 동일 호스트면 Mac 클라우드. 단시간 배치는 Docker도 가능하나 OOM·권한 장애 분석이 길어집니다.

10. 결론

성공 기준은 skill-browser → 동일 계정 Chromium → 18789 스냅샷 재현의 사슬입니다. 노트북과 WSL2는 7×24에 부적합합니다. Linux VPS의 Docker browser는 /dev/shm과 headless 탐지로 장애 분석이 길어지기 쉽습니다. browser skill과 IM 채널을 병행 상주하려면 VPSMAC Apple Silicon Mac 클라우드에서 게이트웨이, Chromium 캐시, launchd를 한 Runbook으로 묶는 편이 안정적입니다. Docker는 단시간 배치용이며 프로덕션 헤드리스 Mac 스택을 대체하지 않습니다. Docker 7×24와 Skill 감사도 함께 읽으세요.