개요
브라우저 도구(Browser Tool)는 OpenClaw에 내장된 핵심 도구 중 하나로, AI 에이전트에게 웹페이지를 직접 조작하는 능력을 부여합니다. 이 도구를 통해 에이전트는 웹페이지 탐색, 콘텐츠 추출, 폼 작성, 버튼 클릭, 스크린샷 캡처는 물론 복잡한 다단계 웹 상호작용 프로세스까지 수행할 수 있습니다.
도구 아키텍처
OpenClaw의 브라우저 도구는 샌드박스 브라우저 브릿지 메커니즘을 통해 실제 브라우저 인스턴스와 통신합니다. Pi SDK가 직접 임베드되어 있으므로, 브라우저 도구는 7단계 도구 파이프라인 중 "OpenClaw 내장 도구" 단계에서 주입되는 구성원으로서 추가 설치 없이 사용할 수 있습니다.
브라우저 도구의 통신 체인은 다음과 같습니다: AI 에이전트 → 도구 호출 → 샌드박스 브라우저 브릿지 → 브라우저 인스턴스 (WebSocket 프로토콜). 이 아키텍처는 브라우저 작업이 제어된 환경에서 실행되도록 보장합니다.
활성화 및 설정
기본 설정
tools:
browser:
enabled: true
headless: true
bridgeUrl: "ws://localhost:9222"
defaultTimeout: 15000
viewport:
width: 1280
height: 720
고급 옵션
tools:
browser:
userAgent: "OpenClaw-Browser/1.0"
acceptLanguage: "zh-CN,zh;q=0.9,en;q=0.8"
ignoreHTTPSErrors: false
extraHTTPHeaders:
X-Custom-Header: "openclaw"
proxy:
server: "http://proxy.example.com:8080"
핵심 작업
페이지 탐색
브라우저 도구는 표준 페이지 탐색 작업을 지원합니다. AI 에이전트는 도구에 지정된 URL을 열도록 지시하고, 페이지 로드가 완료될 때까지 기다린 후 후속 작업을 수행할 수 있습니다. 탐색 작업은 타임아웃 시간과 대기 조건(예: 특정 요소가 나타날 때까지 대기)을 설정할 수 있습니다.
요소 상호작용
도구는 풍부한 요소 상호작용 기능을 제공합니다:
- 클릭: 선택자로 요소를 찾아 클릭
- 입력: 입력 필드에 텍스트 입력
- 선택: 드롭다운 메뉴 옵션 조작
- 호버: 요소 위에 마우스를 올려놓기
- 스크롤: 페이지 또는 컨테이너 내 스크롤
요소 위치 지정은 CSS 선택자와 텍스트 내용 매칭 두 가지 방식을 지원합니다. AI 에이전트는 보통 먼저 콘텐츠 추출 기능으로 페이지 구조를 파악한 후 적합한 위치 지정 전략을 선택합니다.
콘텐츠 추출
브라우저 도구는 페이지에서 다양한 유형의 콘텐츠를 추출할 수 있습니다:
- 텍스트 콘텐츠: 페이지의 순수 텍스트 콘텐츠를 추출하고, 숨겨진 요소와 보이지 않는 텍스트를 자동 처리
- 구조화된 데이터: 테이블, 목록 등 구조화된 정보 추출
- 링크 정보: 페이지의 모든 링크와 해당 텍스트 가져오기
- 메타데이터: 페이지 제목, 설명, Open Graph 태그 등 읽기
스크린샷 기능
스크린샷은 브라우저 도구의 중요한 기능 중 하나입니다. 전체 페이지 스크린샷과 지정 영역 스크린샷을 지원하며, 출력 형식은 PNG 또는 JPEG를 선택할 수 있습니다. 스크린샷 결과는 대화에서 사용자에게 직접 표시하거나 파일 시스템에 저장하여 후속 사용할 수 있습니다.
tools:
browser:
screenshot:
format: png
quality: 80
fullPage: false
maxWidth: 1920
maxHeight: 1080
다중 탭 관리
브라우저 도구는 여러 탭의 동시 관리를 지원합니다. AI 에이전트는 서로 다른 탭 사이를 전환하면서 교차 페이지 정보 비교 및 데이터 통합을 수행할 수 있습니다. 리소스 남용을 방지하기 위해 샌드박스는 최대 탭 수를 제한합니다 (기본값 3).
Cookie 및 상태 관리
Cookie 작업
도구는 Cookie의 읽기 및 설정 기능을 제공합니다. 이는 로그인 상태가 필요한 작업 시나리오에서 매우 중요합니다. 관리자는 인증 Cookie를 미리 설정하여 AI 에이전트가 필요할 때 자동으로 사용하도록 할 수 있습니다.
세션 영속화
브라우저의 상태(Cookie 및 로컬 스토리지 포함)는 세션 간에 영속화될 수 있습니다. 이는 AI 에이전트가 한 번의 대화에서 완료한 로그인 작업이 후속 대화에서도 유효하여 반복 인증이 필요 없음을 의미합니다.
다른 도구와의 협업
브라우저 도구는 단독으로 사용되는 경우가 드물며, 보통 다른 도구와 함께 복잡한 작업을 완료합니다:
- web 도구와 협업: browser는 상호작용 작업을, web 도구는 API 호출을 담당
- canvas 도구와 협업: 웹페이지에서 추출한 데이터를 canvas 도구로 시각화
- messaging 도구와 협업: 브라우저 스크린샷이나 추출된 정보를 메시지 도구로 전송
보안 주의사항
- 도메인 화이트리스트: 항상
allowedDomains를 설정하여 AI 에이전트가 접근해서는 안 되는 웹사이트에 방문하는 것을 방지하세요 - 자격 증명 보호: 대화에서 비밀번호를 평문으로 전달하지 말고, 미리 설정된 인증 방식을 사용하세요
- 다운로드 제한: 샌드박스는 기본적으로 파일 다운로드를 차단하며, 필요 시 허용되는 파일 유형을 신중하게 설정하세요
- JavaScript 실행: 브라우저 도구는 페이지에 스크립트를 주입하는 것을 지원하며, 이는 강력하지만 신중하게 사용해야 하는 기능입니다
문제 해결
- 페이지 로드 타임아웃: 네트워크 연결과
defaultTimeout설정을 확인하세요 - 요소를 찾을 수 없음: 선택자가 올바른지, 페이지가 완전히 로드되었는지 확인하세요
- 브릿지 연결 실패: 브라우저 인스턴스 상태와
bridgeUrl설정을 확인하세요 - 스크린샷 빈 화면: 뷰포트 크기 설정과 페이지 렌더링 상태를 확인하세요
정리
브라우저 도구는 OpenClaw의 AI 에이전트에게 진정한 웹 상호작용 능력을 부여합니다. 적절한 설정과 보안 제약을 통해 간단한 정보 조회부터 복잡한 다단계 웹 작업까지 다양한 과제를 안전하고 효율적으로 수행할 수 있습니다.