OpenClaw · Unlighthouse · 프론트 CI 2026

2026 원격 Mac: Unlighthouse JSON·데드링크 임계·Lighthouse PR 요약 재현

2026.05.20 프론트 CI·출하 게이트 10분

대상은 프리뷰마다 사이트 전역 링크·성능을 한 티켓으로 닫는 프론트 플랫폼 팀입니다. 리눅스 러너의 단일 URL Lighthouse만으로는 데드 링크·4xx 누수를 놓치기 쉽습니다. 본문은 임계 대조표·재현 HowTo·OpenClaw PR/Webhook을 묶었습니다. 프리뷰 Lighthouse·Playwright HTML·홈.

전역 스캔 · 링크 게이트 · 성능 회귀

00 통증: 홈만 녹색 ≠ 출하 승인

깊은 404

마케팅 랜딩만 측정하면 블로그·문서 하위의 404가 머지 후에야 드러납니다.

JSON 미파싱

Unlighthouse 산출물을 아티팩트만 올리면 리뷰어가 diff 없이 숫자를 읽지 못합니다.

엔진 분리

Chromium 점수만 통과해도 Safari에서 LCP·폰트 스왑이 깨지면 제품 승인이 지연됩니다.

01 Unlighthouse vs 단일 Lighthouse CLI 선형

Unlighthouse는 크롤로 다수 URL에 Lighthouse를 붙이고, 단일 CLI는 골든 URL 회귀에 씁니다. 링크·4xx는 전역 스캔, LCP·CLS는 URL 3~5개만 엄격 임계하세요.

기준 Unlighthouse Lighthouse CLI
범위 전역·깊은 링크·데드링크 탐지. 지정 URL·카테고리 단일 실행.
산출물 reports/*.json·라우트 목록. .lhr.json 한 파일.
CI 시간 샤드·maxRoutes로 상한. 워밍 2회 후 40초 내외.
차단 brokenLinks·4xx 비율. LCP·CLS·성능 점수.

02 원격 Mac에 Node 24+와 OpenClaw 게이트웨이 설치

임대 Mac에서 Node 24+·동일 Chromium을 고정합니다. OpenClaw 게이트웨이는 Webhook·PR 토큰만 담고 측정은 에이전트가 합니다.

  1. 런타임: nvm install 24 && nvm use 24 — engines.node와 일치.
  2. 게이트웨이: 읽기 전용 OPENCLAW_TOKEN·HMAC 시크릿을 키체인에 저장(토큰 E2E).
  3. 상관 id: GIT_SHA·OPENCLAW_RUN_ID·PREVIEW_URL export.
  4. 디렉터리: mkdir -p .openclaw/reports — 아티팩트 경로 고정.
  5. 스캔 실행: 아래 CLI 예시로 JSON 생성.
  6. 집계: OpenClaw openclaw report merge로 Markdown 템플릿 채움.
export PREVIEW_URL="https://preview.example.com"
npx unlighthouse --site "$PREVIEW_URL" \
  --output-dir ".openclaw/reports/${OPENCLAW_RUN_ID}" \
  --build-static false --max-routes 120

03 Unlighthouse CI 출력 JSON 필드 설명

아래 키만 읽어도 PR 표를 채울 수 있습니다. README에 ms·비율 단위를 고정하세요.

  • routes[] — path·status·score.performance.
  • routes[].lighthouse.audits — LCP·CLS·TBT numericValue.
  • brokenLinks[] — from·to·status(404/410).
  • summary.failedRoutes — 임계 미달 URL 수.
  • meta.generatedAt·meta.site — PR 마커와 멱등 키.
{
  "meta": { "site": "https://preview.example.com", "generatedAt": "2026-05-20T08:00:00Z" },
  "summary": { "failedRoutes": 2, "totalRoutes": 118 },
  "brokenLinks": [{ "from": "/docs", "to": "/old-page", "status": 404 }]
}

05 성능 회귀(LCP·CLS) 임계 표

상위 실패 라우트와 CLI 골든 URL을 교차합니다. Lighthouse 알림·빌드 요약과 숫자를 맞춥니다.

지표 프리뷰 상한 메인 대비 회귀
LCP (ms) ≤ 2800 main +250ms 초과 시 실패
CLS ≤ 0.08 +0.02 초과 시 실패
성능 점수 ≥ 0.88 보조 — LCP·CLS 우선
TBT (ms) ≤ 350 광고·서드파티 슬롯만 완화

06 OpenClaw 집계 보고서·PR 코멘트·Webhook 회송

게이트웨이가 JSON·LHR를 Markdown으로 합치고 마커 openclaw-ul:${GIT_SHA}로 코멘트를 upsert합니다. Webhook은 Deployments와 동일 HMAC을 씁니다.

  1. 링크 표(상위 5 broken) + LCP·CLS worst 3 URL.
  2. verdict: pass | link_fail | perf_fail.
  3. NDJSON phase=unlighthouse_merge append.
  4. Checks 어노테이션에 동일 본문(선택).
  5. 실패 시 노드 로그 링크만 노출(시크릿 제외).

07 Safari·WebKit 연동 주의

측정은 Chromium 기준입니다. 동일 OPENCLAW_RUN_ID로 Safari 매트릭스 스모크를 이어 붙이고, 쿠키는 ITP 가이드를 보세요.

  • 프리뷰 로그인 쿠키는 WebKit 프로젝트에만 주입.
  • LCP 스크린샷 diff는 Chromium과 분리 저장.
  • prefers-reduced-motion 게이트는 출하 전 필수.

08 자주 묻는 질문(FAQ)

Unlighthouse 0 exit인데 PR이 막히나요?

팀 스크립트가 brokenLinks를 별도 exit 2로 매핑했는지 확인하세요.

스캔이 30분 넘깁니다

--max-routes·사이트맵 화이트리스트·샤드(경로 prefix)로 상한을 둡니다.

JSON 파싱 ENOENT

OPENCLAW_RUN_ID 디렉터리와 CI 아티팩트 업로드 경로가 같은지 맞춥니다.

09 인용 가능한 임계·파라미터

스캔

M4 임대 노드 max-routes 120·워커 2 — PR 피드백 25분 SLA.

링크

프리뷰 brokenLinks ≤ 3·프로덕션 0.

성능

LCP 2800ms·CLS 0.08·main 대비 LCP +250ms 회귀 차단.

전역 스캔·PR 요약에는 Chromium 고정 원격 Mac이 필요합니다. 요금·프론트 빌드 노드, SSH·VNC, 블로그, 홈에서 임대를 시작하세요.

원격 Mac · Unlighthouse · OpenClaw

프론트 CI용 원격 Mac 빌드 노드를 고르세요

프리뷰 Lighthouse·Playwright HTML 후 원격 Mac 프론트 빌드 노드를 선택하세요.

홈 · 블로그

프론트 CI 노드 임대