2026 OpenClaw 프론트 실전:
원격 Mac에서 axe-core 접근성 JSON을 파싱·PR 가독 요약으로 회수
접근성 회귀는 스크린샷보다 violations가 담긴 JSON이 먼저입니다. 원격 Mac CI에서 axe-core를 동일 커맨드로 고정하고, OpenClaw가 규칙 ID·심각도·노드를 정규화한 뒤 PR 코멘트나 Webhook으로 돌려내면, 리뷰어는 로그인 콘솔 없이도 무엇이 깨졌는지 한 화면에서 봅니다.
01 axe 실행 방식과 JSON 출력
팀 표준은 하나로 고정하세요. @axe-core/cli로 URL 목록을 넘기거나, Playwright·Puppeteer 페이지에 injectAxe 후 axe.run() 결과를 그대로 axe-report.json으로 씁니다. Apple Silicon 원격 Mac에서는 로컬과 동일한 Node·브라우저 바이너리를 쓰므로, CI 캐시 키에 브라우저 리비전을 포함하면 재현 논쟁이 줄어듭니다.
원본 JSON에는 violations·incomplete·passes가 들어 있습니다. 게이트에는 보통 violations만 쓰고, 스크린 리더 관점 보조 정보는 nodes·html 요약만 PR 본문에 넣어 토큰과 PII 노출을 줄입니다. 배포 전 성능·링크와 묶은 순찰 루프는 Lighthouse·링크·접근성 순찰 HowTo와 같은 오케스트레이션을 참고하면 됩니다.
# 예: CLI로 단일 URL → stdout이 아닌 파일로
npx @axe-core/cli https://staging.example.com/ \
--save ./artifacts/axe-report.json --exit 0종료 코드 정책을 명시하세요. 위 예시는 수집만 하고 임계값 단계에서 실패시키는 패턴입니다. CI가 곧바로 빨간불을 켜야 하면 스크립트에서 violations 길이를 검사해 exit 1을 반환해도 됩니다.
02 OpenClaw 파싱 규칙 템플릿
에이전트 입력은 원본 axe JSON 한 파일로 제한하고, 아래 표처럼 내부 스키마로 변환합니다. URL·브랜치·커밋 SHA는 JSON 밖 메타데이터(환경 변수)로만 넘깁니다.
| 표준 필드 | axe 매핑 |
|---|---|
rule_id |
violations[].id |
impact |
violations[].impact (critical / serious / moderate / minor) |
wcag |
tags에서 WCAG 레벨 문자열 추출 |
selector_hint |
첫 nodes[].target를 짧게 이어붙인 문자열 |
help_url |
Deque 공개 문서 URL(로그인 불필요) |
동일한 “보고서 디렉터리만 쓰기” 패턴은 Source Map 스택 PR 요약 글과 맞추면, 게이트웨이 허용 경로를 한 번 설명하는 것으로 끝납니다. 출력은 예를 들어 .openclaw/reports/<sha>/a11y_pr_summary.md에만 기록합니다.
03 요약 필드와 임계값
PR 본문 상단에 한 줄 대시보드를 둡니다: 총 violations 수, impact별 건수, 신규 규칙 ID(기준선 diff), 스캔 대상 URL 수. 본문 본부는 상위 N건(예: 15)만 표로 올리고 나머지는 “아티팩트의 전체 JSON 참조” 한 줄로 막습니다.
임계값은 저장소에 YAML·JSON으로 버전 관리하세요. 예: critical > 0이면 실패, serious는 신규 항목만 실패, 알려진 레거시는 allowed_rule_ids에 SHA와 함께 명시합니다. 플래키한 동적 DOM은 셀렉터 대신 규칙 ID 집계로만 게이트를 걸면 안정적입니다.
- 이중 임계: CI 게이트(차단)와 PR 요약(가독)을 분리해 운영 알림만 켜는 팀도 둘 수 있습니다.
- 기준선: 메인 브랜치 최신 성공 런의 규칙 집합을 저장해 PR에서 집합 diff를 계산합니다.
04 Git 제공자 PR 코멘트 회송
URL은 리포지토리에 하드코딩하지 마세요. 토큰·엔드포인트·PR 번호는 CI 시크릿과 런타임 변수로만 주입합니다. 흐름은 다음과 같이 기술할 수 있습니다.
- 워크플로가 PR 이벤트에서 커밋 SHA·PR 번호·리포지토리 풀네임을 환경 변수로 보냅니다.
- axe JSON을 정규화한 마크다운을 같은 잡에서 생성하고, Git 호스트 REST의 “pull request 댓글 생성” API에 본문만 POST합니다. 호스트별 경로는 공식 문서의 리소스 형식을 따르고, 여기 글에는 로그인이 필요한 대시보드 딥링크를 넣지 않습니다.
- 사내 게이트웨이를 쓸 경우 클라이언트가 HMAC 서명과
Idempotency-Key(SHA+잡 ID)를 붙이고, 서버는 본문 해시로 중복을 무시합니다. - 토큰은 단일 저장소·최소 스코프(예: pull request 읽기/쓰기)·짧은 만료·봇 계정으로 분리합니다.
시각 회귀·번들 게이트와 같은 “요약 코멘트” 레일을 공유하려면 시각 회귀 diff PR 요약 HowTo의 Webhook·재시도 절차를 그대로 axe 파이프라인에 얹으면 됩니다.
05 오류 FAQ
Q. violations가 0인데 UI는 명백히 잘못됐습니다.
iframe·섀도 DOM·지연 로딩 콘텐츠는 기본 스캔에서 빠질 수 있습니다. 해당 프레임에 재진입하거나 네트워크 유휴 대기 후 두 번째 패스를 돌리세요.
Q. 429 / rate limit입니다.
코멘트 API를 연속 호출하지 말고 멱등 키로 합치고, 지수 백오프 최대 간격을 늘립니다. 야간 집중 스케줄은 분산하세요.
Q. 포크 PR에서 시크릿이 비어 있습니다.
호스트 정책상 포크는 시크릿이 막힐 수 있습니다. pull_request_target 대신 읽기 전용 워크플로와 승인된 러너 조합 등 팀 보안 가이드를 따르고, 요약은 아티팩트만 올린 뒤 메인 저장소 잡이 코멘트를 대행하는 패턴을 검토하세요.