서문
AI Agent는 종종 웹 페이지와 상호작용해야 합니다. 페이지 내용 크롤링, 폼 작성, 스크린샷 캡처, 복잡한 브라우저 자동화 작업 수행 등이 필요합니다. OpenClaw은 Chromium 커널 기반의 헤드리스 브라우저(Headless Browser) 통합 기능을 내장하고 있으며, Pi Agent SDK의 browser 도구를 통해 완전한 웹 페이지 상호작용 기능을 제공합니다.
이 글에서는 OpenClaw의 헤드리스 브라우저 기능을 설정하고 사용하는 방법과 Bridge URL의 작동 원리를 소개합니다.
Browser 도구 활성화
기본 설정
{
agents: {
"my-agent": {
tools: {
browser: {
enabled: true,
// 브라우저 엔진
engine: "chromium",
// 헤드리스 모드
headless: true,
// 브라우저 시작 매개변수
launchArgs: [
"--no-sandbox",
"--disable-gpu",
"--disable-dev-shm-usage"
],
// 기본 뷰포트 크기
viewport: {
width: 1280,
height: 720
},
// 페이지 로딩 타임아웃(밀리초)
timeout: 30000
}
}
}
}
}
Docker 환경 특별 설정
Docker에서 실행할 때는 Chromium 의존성이 설치되어 있어야 합니다:
FROM openclaw/gateway:latest
# Chromium 의존성 설치
RUN apt-get update && apt-get install -y \
chromium \
fonts-noto-cjk \
--no-install-recommends \
&& rm -rf /var/lib/apt/lists/*
또는 브라우저 지원이 포함된 사전 빌드 이미지를 사용합니다:
services:
openclaw:
image: openclaw/gateway:latest-browser
environment:
- OPENCLAW_BROWSER_ENABLED=true
Browser 도구 기능
AI Agent는 browser 도구를 통해 다음 작업을 수행할 수 있습니다:
1. 페이지 탐색 및 콘텐츠 추출
사용자: Hacker News 오늘의 인기 글을 확인해줘
AI 내부 실행:
→ browser.navigate("https://news.ycombinator.com")
→ browser.extract({ selector: ".titleline > a", fields: ["text", "href"] })
→ 추출 결과를 사용자에게 반환
2. 페이지 스크린샷
사용자: GitHub trending 페이지 스크린샷 찍어줘
AI 내부 실행:
→ browser.navigate("https://github.com/trending")
→ browser.screenshot({ fullPage: false })
→ 이미지 형태로 사용자에게 전송
3. 폼 상호작용
사용자: 그 웹사이트에서 "OpenClaw" 검색해줘
AI 내부 실행:
→ browser.navigate("https://example.com")
→ browser.fill({ selector: "#search-input", value: "OpenClaw" })
→ browser.click({ selector: "#search-button" })
→ browser.waitForNavigation()
→ browser.extract({ selector: ".results" })
4. JavaScript 실행
AI 내부 실행:
→ browser.evaluate("document.title")
→ browser.evaluate("document.querySelectorAll('a').length")
Bridge URL 메커니즘
Bridge URL은 OpenClaw의 고유한 기능으로, AI Agent가 브라우저 세션을 사용자에게 "브릿지"하여 사용자가 직접 브라우저에서 웹 페이지와 상호작용할 수 있게 합니다.
작동 원리
1. AI Agent가 헤드리스 브라우저에서 페이지 열기
2. OpenClaw이 Bridge URL 생성
3. 사용자가 Bridge URL을 클릭하여 자신의 브라우저에서 열기
4. 사용자에게 Agent 브라우저 세션의 실시간 미러 표시
5. 사용자가 페이지를 조작하면 Agent의 브라우저에 동기화
Bridge URL 설정
{
agents: {
"my-agent": {
tools: {
browser: {
bridge: {
enabled: true,
// Bridge 세션의 기본 URL
baseUrl: "https://openclaw.example.com/bridge",
// 세션 만료 시간(초)
sessionTTL: 600, // 10분
// 접근 인증
auth: {
required: true,
// 일회용 Token 인증
method: "token"
}
}
}
}
}
}
}
사용 시나리오
시나리오 1: 사용자 로그인이 필요한 웹사이트
사용자: 내 은행 계좌 잔액을 확인해줘
AI: 은행 웹사이트에 로그인이 필요합니다. 로그인 페이지를 열었으니
아래 링크를 클릭하여 로그인을 완료해 주세요:
🔗 https://openclaw.example.com/bridge/abc123
로그인 후 알려주시면 계속 진행하겠습니다.
사용자: [링크 클릭, 로그인 완료] 됐어
AI: [로그인 성공 감지]
→ browser.extract({ selector: ".balance" })
→ 계좌 잔액은 ₩12,345,670입니다
시나리오 2: 캡차 처리
캡차를 만나면 AI가 자체적으로 처리할 수 없으므로, Bridge URL을 통해 사용자가 직접 완료할 수 있습니다:
AI: 페이지에 캡차가 나타났습니다. 아래 링크를 클릭하여 인증을 완료해 주세요:
🔗 https://openclaw.example.com/bridge/def456
완료 후 계속 진행하겠습니다.
시나리오 3: 복잡한 상호작용 확인
민감한 작업을 수행하기 전에 사용자가 Bridge URL을 통해 확인하도록 합니다:
AI: 폼 내용을 작성했습니다. 아래 링크를 통해 확인하고 제출해 주세요:
🔗 https://openclaw.example.com/bridge/ghi789
고급 설정
프록시 설정
프록시를 통해 웹사이트에 접근해야 하는 경우:
{
tools: {
browser: {
proxy: {
server: "http://proxy.example.com:8080",
username: "user",
password: "pass",
// 프록시를 사용하지 않는 도메인
bypass: ["localhost", "*.internal.com"]
}
}
}
}
Cookie 및 세션 관리
{
tools: {
browser: {
// Cookie 영구 저장
persistCookies: true,
cookieDir: "./data/browser-cookies",
// 기본 Cookie
defaultCookies: [
{
name: "lang",
value: "ko-KR",
domain: ".example.com"
}
]
}
}
}
User-Agent 및 요청 헤더
{
tools: {
browser: {
userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
extraHeaders: {
"Accept-Language": "ko-KR,ko;q=0.9"
}
}
}
}
리소스 차단
성능 향상과 대역폭 절감을 위해 불필요한 리소스를 차단할 수 있습니다:
{
tools: {
browser: {
resourceBlocking: {
// 이미지 차단(순수 콘텐츠 추출 시)
blockImages: false,
// 폰트 차단
blockFonts: true,
// 광고 및 추적 스크립트 차단
blockPatterns: [
"*google-analytics*",
"*doubleclick*",
"*facebook.com/tr*"
]
}
}
}
}
보안 고려사항
샌드박스 격리
OpenClaw의 브라우저 도구는 샌드박스 환경에서 실행됩니다:
{
tools: {
browser: {
sandbox: {
// 네트워크 접근 화이트리스트
allowedDomains: [
"*.github.com",
"*.stackoverflow.com",
"news.ycombinator.com"
],
// 파일 다운로드 금지
blockDownloads: true,
// 로컬 파일 접근 금지
blockFileUrls: true,
// 최대 동시 열린 페이지 수
maxPages: 5,
// 단일 페이지 최대 실행 시간
maxPageTime: 60000
}
}
}
}
콘텐츠 필터링
{
tools: {
browser: {
contentFilter: {
// 민감한 정보 필터링(추출된 페이지에 비밀번호 필드 등이 포함된 경우)
redactPatterns: [
"password",
"credit.?card",
"ssn"
],
// 추출 콘텐츠의 최대 길이 제한
maxExtractLength: 10000
}
}
}
}
성능 최적화
브라우저 풀
고동시성 시나리오를 위해 OpenClaw은 브라우저 인스턴스 풀을 지원합니다:
{
tools: {
browser: {
pool: {
// 최소 브라우저 인스턴스 수
min: 2,
// 최대 브라우저 인스턴스 수
max: 10,
// 유휴 인스턴스의 최대 생존 시간
idleTimeout: 300000
}
}
}
}
페이지 캐시
{
tools: {
browser: {
pageCache: {
enabled: true,
// 캐시 만료 시간
ttl: 300, // 5분
// 최대 캐시 페이지 수
maxPages: 50
}
}
}
}
디버깅
# 비헤드리스 모드로 시작(로컬 디버깅용)
OPENCLAW_BROWSER_HEADLESS=false openclaw start
# 브라우저 도구 호출 로그 확인
openclaw logs --filter "browser"
# 스크린샷을 로컬에 저장
openclaw browser screenshot https://example.com --output ./screenshot.png
요약
OpenClaw의 헤드리스 브라우저 통합은 AI Agent에게 "웹 페이지를 보고 조작하는" 능력을 부여합니다. browser 도구를 통해 Agent는 웹 페이지 탐색, 콘텐츠 추출, 폼 작성, 스크린샷 캡처가 가능합니다. Bridge URL 메커니즘을 통해 사용자 참여가 필요한 작업(로그인, 캡차 등)을 원활하게 처리할 수 있습니다. 샌드박스 격리, 리소스 차단, 브라우저 풀 등 고급 설정과 결합하면 이 솔루션을 프로덕션 환경에서 안전하고 효율적으로 운영할 수 있습니다.