Browser Automation

CDP Chrome 자동화 — 스냅샷, 클릭, 내비게이션, 스크린샷, 탭. cli-jaw browser 명령어를 통해 ref 기반 요소 타겟팅으로 Chrome을 제어합니다.

빠른 참조

사전 요구 사항

• cli-jaw serve가 실행 중이어야 합니다 — 브라우저 스킬은 cli-jaw 서버를 통해 통신합니다.
• Google Chrome이 머신에 설치되어 있어야 합니다.
• playwright-core가 cli-jaw 프로젝트에 설치되어 있어야 합니다 (CDP 통신에 사용).
• 선택 사항: 좌표 기반 마우스 조작을 위해 brew install cliclick을 설치합니다.

핵심 워크플로우

모든 브라우저 자동화는 동일한 루프를 따릅니다: 스냅샷을 찍어 인터랙티브 요소를 확인하고, ref ID로 해당 요소에 액션을 수행한 뒤, 다시 스냅샷을 찍어 결과를 검증합니다.

내비게이션, 새로고침, 탭 전환 또는 페이지를 크게 변경하는 액션 이후에는 반드시 새로운 스냅샷을 찍으세요. ref ID는 가장 최근의 유효한 스냅샷에 속하며, 이후에는 무효화될 수 있습니다.

빠른 시작

# 자동화 세션 시작 (헤드리스, 창 표시 안 함)
cli-jaw browser start --agent

# 인터랙티브 브라우저 시작 (수동, 창 표시)
cli-jaw browser start

# URL로 이동
cli-jaw browser navigate "https://example.com"

# 인터랙티브 스냅샷 (ref ID 표시)
cli-jaw browser snapshot --interactive

# ref로 클릭
cli-jaw browser click e3

# 텍스트 입력 후 제출
cli-jaw browser type e5 "hello" --submit

# 스크린샷 촬영
cli-jaw browser screenshot

스냅샷 출력

snapshot --interactive 명령어는 페이지의 인터랙티브 요소 목록을 간결하게 반환하며, 각 요소에는 이후 명령어에서 사용할 짧은 ref ID가 부여됩니다.

e3과 같은 ref ID는 수명이 짧으며 최신 스냅샷에만 유효합니다. 페이지 변경 후에는 항상 스냅샷을 다시 찍으세요.

명령어 레퍼런스

지원 라벨

규칙 및 제약 사항

• ref ID는 일시적입니다. 최신 스냅샷에만 유효합니다. 내비게이션, 새로고침, 탭 전환 또는 페이지를 변경하는 액션 이후에는 항상 snapshot --interactive를 다시 실행하세요.
• 스냅샷에는 --interactive를 권장합니다 — 토큰 사용량을 줄일 수 있습니다. 전체 스냅샷은 비인터랙티브 노드를 포함하여 출력이 커질 수 있습니다.
• 자동화 세션에는 --agent를 사용하세요. 헤드리스로 시작하여 브라우저 창이 표시되지 않습니다.
• 일반 ps 출력에서 찾은 Chrome 프로세스를 절대 종료하지 마세요. jaw 소유 프로세스를 내구성 런타임 레코드를 통해 검증하는 cleanup-runtimes --close --force만 사용하세요.
• reset 전에 확인하세요. reset 명령어는 브라우저 프로필과 스크린샷을 삭제합니다. 사용자가 명시적으로 요청한 경우에만 사용하세요.
• evaluate는 진단 전용입니다. 상위 레벨 워크플로우에서 evaluate를 통해 임의의 사용자 제공 JavaScript를 전달하지 마세요.
• 비 DOM 요소 (Canvas, WebGL, 크로스 오리진 iframe, 커스텀 UI)의 경우 사용 가능한 ref가 없음을 확인한 후에만 vision-click 스킬로 대체하세요.

일반 워크플로우

웹 검색

cli-jaw browser start --agent
cli-jaw browser navigate "https://www.google.com"
cli-jaw browser snapshot --interactive
cli-jaw browser type e3 "search query" --submit
cli-jaw browser snapshot --interactive
cli-jaw browser click e7

폼 입력

cli-jaw browser snapshot --interactive
cli-jaw browser type e1 "John Doe"
cli-jaw browser type e2 "john@example.com"
cli-jaw browser click e3           # Submit button
cli-jaw browser snapshot           # 제출 확인

페이지 콘텐츠 읽기

cli-jaw browser navigate "https://news.ycombinator.com"
cli-jaw browser text               # 일반 텍스트 추출
cli-jaw browser text --format html # HTML 콘텐츠
cli-jaw browser snapshot --interactive

AI 웹 워크플로우

ChatGPT 또는 기타 web-ai 워크플로우의 경우 web-ai 스킬을 사용하세요. 브라우저 스킬은 기본 페이지 제어를 담당하며, web-ai는 구조화된 질문 렌더링, 활성 탭 안전성, 응답 기준선 처리를 담당합니다.

~해줘 예시

브라우저 스킬을 트리거하는 자연어 요청 예시입니다. 한국어와 영어 모두 사용 가능합니다.

헤드리스 모드

Chrome을 헤드리스로 실행하는 세 가지 방법:

# 자동화에 권장
cli-jaw browser start --agent

# 수동 모드에서 명시적 헤드리스
cli-jaw browser start --headless

# 환경 변수 사용
CHROME_HEADLESS=1 cli-jaw browser start

모든 에이전트 자동화에는 --agent를 사용하세요. 브라우저 창이 표시되지 않으며, 자동화 세션에서 기본값으로 사용됩니다.

환경 변수

기본 CDP 포트는 cli-jaw 서버 포트에서 파생됩니다. 명시적 오버라이드가 필요한 경우에만 cli-jaw browser start --port <port>를 사용하세요.

독립형 agbrowse 대안

단일 Chrome 인스턴스를 명시적으로 구동하려는 경우 (예: 로그인된 프로필을 유지하거나, cli-jaw serve와 두 번째 CDP 세션을 동시에 실행하지 않으려는 경우) 동일한 브라우저 명령어를 독립형 agbrowse CLI (npm install -g agbrowse)를 통해 사용할 수 있습니다. 플래그 체계는 동일하며, 바이너리 접두사만 다릅니다.

런타임 정리

# 런타임 상태 진단
cli-jaw browser doctor --json

# 드라이런: 정리 대상 확인
cli-jaw browser cleanup-runtimes

# jaw 소유 고아 런타임 실제 종료
cli-jaw browser cleanup-runtimes --close --force

cleanup-runtimes는 의도적으로 보수적입니다. jaw 소유 Chrome 실행에 의해 기록된 내구성 browser-runtime-owner.json 레코드에 대해서만 동작합니다. 프로세스 명령줄은 여전히 기록된 PID, CDP 포트 및 프로필과 일치해야 합니다. --type=을 포함하는 Chrome 헬퍼 프로세스는 거부됩니다. 일반 ps 출력을 Chrome 프로세스가 종료해도 안전하다는 근거로 사용하지 마세요.

복구 전략

문제가 발생하면, 다음 액션을 취하기 전에 멈추고 상태를 점검하세요.

문제 해결

계획된 런타임 델타

다음 명령어들은 30_browser 레퍼런스 설계의 패리티 대상으로 계획되어 있습니다. 이후 PRD에서 명시적으로 업그레이드되지 않는 한 현재 런타임에서는 사용할 수 없습니다.

계획된 관찰 및 진단

cli-jaw browser console --clear --reload --duration 3000
cli-jaw browser network --reload --duration 1000
cli-jaw browser wait 2000

계획된 액션

cli-jaw browser resize 0 0 --fullscreen
cli-jaw browser scroll down
cli-jaw browser scroll up --amount 1000

관련 스킬

참고 사항

• ref ID는 수명이 짧으며, 최신 스냅샷 범위에서만 유효한 것으로 처리해야 합니다.
• 내비게이션 또는 주요 페이지 변경 후에는 항상 snapshot --interactive를 다시 실행하세요.
• 토큰 절약을 위해 --interactive를 권장합니다.
• 스크린샷은 ~/.cli-jaw/screenshots/에 저장됩니다.
• 에이전트 자동화에는 start --agent를 기본으로 사용해야 합니다.
• Canvas, WebGL, 크로스 오리진 iframe, 커스텀 UI와 같은 비 DOM 요소는 명시적 대체로만 vision-click 스킬을 사용하세요.