브라우저 (OpenClaw 관리형)

OpenClaw는 에이전트가 제어하는 전용 Chrome/Brave/Edge/Chromium 프로필을 실행할 수 있습니다. 이 프로필은 개인 브라우저와 격리되어 있으며, 게이트웨이 내부의 작은 로컬 제어 서비스(루프백 전용)를 통해 관리됩니다.

초보자 안내:

  • 별도의 에이전트 전용 브라우저라고 생각하면 됩니다.
  • openclaw 프로필은 개인 브라우저 프로필에 영향을 주지 않습니다.
  • 에이전트가 안전한 경로에서 탭을 열고, 페이지를 읽고, 클릭하고, 입력할 수 있습니다.
  • 기본 chrome 프로필은 확장 프로그램 릴레이를 통해 시스템 기본 Chromium 브라우저를 사용합니다. 격리된 관리형 브라우저를 사용하려면 openclaw으로 전환하세요.

제공되는 기능

  • openclaw이라는 별도 브라우저 프로필 (기본적으로 주황색 악센트).
  • 결정적 탭 제어 (목록/열기/포커스/닫기).
  • 에이전트 액션 (클릭/입력/드래그/선택), 스냅샷, 스크린샷, PDF.
  • 선택적 다중 프로필 지원 (openclaw, work, remote, …).

이 브라우저는 일상용 브라우저가 아닙니다. 에이전트 자동화 및 검증을 위한 안전하고 격리된 환경입니다.

빠른 시작

openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

“Browser disabled”이 표시되면 설정에서 활성화하고(아래 참조) 게이트웨이를 재시작하세요.

프로필: openclaw vs chrome

  • openclaw: 관리형, 격리 브라우저 (확장 프로그램 불필요).
  • chrome: 시스템 브라우저로의 확장 프로그램 릴레이 (OpenClaw 확장 프로그램이 탭에 연결되어야 함).
  • existing-session: 실행 중인 Chrome 프로필에 대한 공식 Chrome MCP 연결 흐름.

관리형 모드를 기본으로 원하면 browser.defaultProfile: "openclaw"을 설정하세요.

설정

브라우저 설정은 ~/.openclaw/openclaw.json에 위치합니다.

{
  browser: {
    enabled: true, // 기본값: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // 기본 신뢰 네트워크 모드
      // allowPrivateNetwork: true, // 레거시 별칭
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // 레거시 단일 프로필 오버라이드
    remoteCdpTimeoutMs: 1500, // 원격 CDP HTTP 타임아웃 (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // 원격 CDP WebSocket 핸드셰이크 타임아웃 (ms)
    defaultProfile: "chrome",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      chromeLive: {
        cdpPort: 18802,
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

참고:

  • 브라우저 제어 서비스는 gateway.port에서 파생된 포트의 루프백에 바인딩됩니다 (기본값: 18791, 게이트웨이 + 2). 릴레이는 다음 포트(18792)를 사용합니다.
  • 게이트웨이 포트(gateway.port 또는 OPENCLAW_GATEWAY_PORT)를 오버라이드하면, 파생된 브라우저 포트도 같은 “패밀리”에 맞춰 이동합니다.
  • cdpUrl은 설정되지 않은 경우 릴레이 포트를 기본값으로 합니다.
  • remoteCdpTimeoutMs는 원격(비루프백) CDP 접근성 검사에 적용됩니다.
  • remoteCdpHandshakeTimeoutMs는 원격 CDP WebSocket 접근성 검사에 적용됩니다.
  • 브라우저 내비게이션/탭 열기는 내비게이션 전에 SSRF 검사를 수행하며, 내비게이션 후 최종 http(s) URL에 대해 최선 노력으로 재검사합니다.
  • browser.ssrfPolicy.dangerouslyAllowPrivateNetwork의 기본값은 true(신뢰 네트워크 모델)입니다. 엄격한 공개 전용 브라우징을 위해 false로 설정하세요.
  • browser.ssrfPolicy.allowPrivateNetwork는 호환성을 위한 레거시 별칭으로 계속 지원됩니다.
  • attachOnly: true는 “로컬 브라우저를 실행하지 않고, 이미 실행 중인 경우에만 연결”을 의미합니다.
  • color + 프로필별 color는 어떤 프로필이 활성화되어 있는지 확인할 수 있도록 브라우저 UI에 색조를 입힙니다.
  • 기본 프로필은 openclaw(OpenClaw 관리형 독립 브라우저)입니다. Chrome 확장 프로그램 릴레이를 선택하려면 defaultProfile: "chrome"을 사용하세요.
  • 자동 감지 순서: Chromium 기반인 경우 시스템 기본 브라우저. 그렇지 않으면 Chrome → Brave → Edge → Chromium → Chrome Canary.
  • 로컬 openclaw 프로필은 cdpPort/cdpUrl을 자동 할당합니다 — 원격 CDP에만 직접 설정하세요.
  • driver: "existing-session"은 원시 CDP 대신 Chrome DevTools MCP를 사용합니다. 이 드라이버에는 cdpUrl을 설정하지 마세요.

Brave (또는 다른 Chromium 기반 브라우저) 사용

시스템 기본 브라우저가 Chromium 기반(Chrome/Brave/Edge 등)이면 OpenClaw가 자동으로 사용합니다. 자동 감지를 오버라이드하려면 browser.executablePath를 설정하세요:

CLI 예시:

openclaw config set browser.executablePath "/usr/bin/google-chrome"
// macOS
{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
  }
}

// Windows
{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
  }
}

// Linux
{
  browser: {
    executablePath: "/usr/bin/brave-browser"
  }
}

로컬 vs 원격 제어

  • 로컬 제어 (기본값): 게이트웨이가 루프백 제어 서비스를 시작하고 로컬 브라우저를 실행할 수 있습니다.
  • 원격 제어 (노드 호스트): 브라우저가 있는 머신에서 노드 호스트를 실행하면 게이트웨이가 브라우저 액션을 프록시합니다.
  • 원격 CDP: browser.profiles.<name>.cdpUrl (또는 browser.cdpUrl)을 설정하여 원격 Chromium 기반 브라우저에 연결합니다. 이 경우 OpenClaw는 로컬 브라우저를 실행하지 않습니다.

원격 CDP URL에는 인증 정보를 포함할 수 있습니다:

  • 쿼리 토큰 (예: https://provider.example?token=<token>)
  • HTTP Basic 인증 (예: https://user:[email protected])

OpenClaw는 /json/* 엔드포인트 호출 시와 CDP WebSocket 연결 시 인증 정보를 보존합니다. 토큰을 설정 파일에 커밋하는 대신 환경 변수나 시크릿 관리자를 사용하는 것이 좋습니다.

노드 브라우저 프록시 (무설정 기본값)

브라우저가 있는 머신에서 노드 호스트를 실행하면, OpenClaw가 추가 브라우저 설정 없이 해당 노드로 브라우저 도구 호출을 자동 라우팅할 수 있습니다. 원격 게이트웨이의 기본 경로입니다.

참고:

  • 노드 호스트는 프록시 명령을 통해 로컬 브라우저 제어 서버를 노출합니다.
  • 프로필은 노드의 자체 browser.profiles 설정에서 가져옵니다 (로컬과 동일).
  • 원하지 않으면 비활성화:
    • 노드에서: nodeHost.browserProxy.enabled=false
    • 게이트웨이에서: gateway.nodes.browser.mode="off"

Browserless (호스팅 원격 CDP)

Browserless는 HTTPS를 통해 CDP 엔드포인트를 노출하는 호스팅 Chromium 서비스입니다. OpenClaw 브라우저 프로필을 Browserless 리전 엔드포인트로 지정하고 API 키로 인증할 수 있습니다.

예시:

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

참고:

  • <BROWSERLESS_API_KEY>를 실제 Browserless 토큰으로 교체하세요.
  • Browserless 계정에 맞는 리전 엔드포인트를 선택하세요 (공식 문서 참조).

직접 WebSocket CDP 프로바이더

일부 호스팅 브라우저 서비스는 표준 HTTP 기반 CDP 검색(/json/version) 대신 직접 WebSocket 엔드포인트를 노출합니다. OpenClaw는 두 가지 모두 지원합니다:

  • HTTP(S) 엔드포인트 (예: Browserless) — OpenClaw가 /json/version을 호출하여 WebSocket 디버거 URL을 검색한 후 연결.
  • WebSocket 엔드포인트 (ws:// / wss://) — OpenClaw가 /json/version을 건너뛰고 직접 연결. Browserbase 등 WebSocket URL을 제공하는 서비스에 사용.

Browserbase

Browserbase는 내장 CAPTCHA 해결, 스텔스 모드, 주거용 프록시를 갖춘 헤드리스 브라우저 실행을 위한 클라우드 플랫폼입니다.

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

참고:

  • 가입하고 Overview 대시보드에서 API Key를 복사하세요.
  • <BROWSERBASE_API_KEY>를 실제 Browserbase API 키로 교체하세요.
  • Browserbase는 WebSocket 연결 시 브라우저 세션을 자동 생성하므로 수동 세션 생성 단계가 필요하지 않습니다.
  • 무료 티어는 동시 세션 1개와 월 브라우저 시간 1시간을 허용합니다. 유료 플랜 제한은 가격을 참조하세요.
  • 전체 API 참조, SDK 가이드, 통합 예시는 Browserbase 문서를 참조하세요.

보안

핵심 사항:

  • 브라우저 제어는 루프백 전용이며, 게이트웨이의 인증 또는 노드 페어링을 통해 접근합니다.
  • 브라우저 제어가 활성화되어 있고 인증이 구성되지 않은 경우, OpenClaw는 시작 시 gateway.auth.token을 자동 생성하고 설정에 유지합니다.
  • 게이트웨이 및 모든 노드 호스트를 사설 네트워크(Tailscale)에 유지하고, 공개 노출을 피하세요.
  • 원격 CDP URL/토큰을 시크릿으로 취급하고, 환경 변수 또는 시크릿 관리자를 사용하세요.

원격 CDP 팁:

  • 가능하면 암호화된 엔드포인트(HTTPS 또는 WSS)와 단기 토큰을 사용하세요.
  • 설정 파일에 장기 토큰을 직접 포함하는 것을 피하세요.

프로필 (다중 브라우저)

OpenClaw는 여러 명명된 프로필(라우팅 설정)을 지원합니다. 프로필은 다음과 같을 수 있습니다:

  • openclaw 관리형: 자체 사용자 데이터 디렉터리 + CDP 포트가 있는 전용 Chromium 기반 브라우저 인스턴스
  • 원격: 명시적 CDP URL (다른 곳에서 실행되는 Chromium 기반 브라우저)
  • 확장 프로그램 릴레이: 로컬 릴레이 + Chrome 확장 프로그램을 통한 기존 Chrome 탭
  • 기존 세션: Chrome DevTools MCP 자동 연결을 통한 기존 Chrome 프로필

기본값:

  • openclaw 프로필은 누락 시 자동 생성됩니다.
  • chrome 프로필은 Chrome 확장 프로그램 릴레이를 위한 기본 제공 프로필입니다 (기본적으로 http://127.0.0.1:18792를 가리킴).
  • 기존 세션 프로필은 옵트인 방식으로, --driver existing-session으로 생성합니다.
  • 로컬 CDP 포트는 기본적으로 18800–18899에서 할당됩니다.
  • 프로필 삭제 시 로컬 데이터 디렉터리가 휴지통으로 이동합니다.

모든 제어 엔드포인트는 ?profile=<name>을 허용하며, CLI는 --browser-profile을 사용합니다.

Chrome 확장 프로그램 릴레이 (기존 Chrome 사용)

OpenClaw는 별도의 “openclaw” Chrome 인스턴스 없이 로컬 CDP 릴레이 + Chrome 확장 프로그램을 통해 기존 Chrome 탭을 제어할 수도 있습니다.

전체 가이드: Chrome 확장 프로그램

흐름:

  • 게이트웨이가 로컬에서 실행되거나(동일 머신) 노드 호스트가 브라우저 머신에서 실행.
  • 로컬 릴레이 서버가 루프백 cdpUrl에서 수신 대기 (기본값: http://127.0.0.1:18792).
  • OpenClaw Browser Relay 확장 프로그램 아이콘을 탭에서 클릭하여 연결(자동 연결 아님).
  • 에이전트가 올바른 프로필을 선택하여 일반 browser 도구를 통해 해당 탭을 제어.

게이트웨이가 다른 곳에서 실행되는 경우, 브라우저 머신에서 노드 호스트를 실행하면 게이트웨이가 브라우저 액션을 프록시할 수 있습니다.

샌드박스 세션

에이전트 세션이 샌드박스된 경우, browser 도구가 기본적으로 target="sandbox" (샌드박스 브라우저)를 사용할 수 있습니다. Chrome 확장 프로그램 릴레이 인수인계에는 호스트 브라우저 제어가 필요하므로:

  • 세션을 비샌드박스로 실행하거나,
  • agents.defaults.sandbox.browser.allowHostControl: true를 설정하고 도구 호출 시 target="host"를 사용하세요.

설정

  1. 확장 프로그램 로드 (개발/언팩):
openclaw browser extension install
  • Chrome → chrome://extensions → “개발자 모드” 활성화
  • “압축해제된 확장 프로그램을 로드합니다” → openclaw browser extension path에서 출력된 디렉터리 선택
  • 확장 프로그램을 고정한 다음, 제어할 탭에서 클릭 (배지가 ON 표시).
  1. 사용:
  • CLI: openclaw browser --browser-profile chrome tabs
  • 에이전트 도구: browser에 profile="chrome"

선택 사항: 다른 이름이나 릴레이 포트를 원하면 자체 프로필을 생성하세요:

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

참고:

  • 이 모드는 대부분의 작업에 Playwright-on-CDP를 사용합니다 (스크린샷/스냅샷/액션).
  • 확장 프로그램 아이콘을 다시 클릭하여 연결 해제.

Chrome 기존 세션(MCP 연결)

OpenClaw는 공식 Chrome DevTools MCP 서버를 통해 실행 중인 Chrome 프로필에 연결할 수도 있습니다. 이미 해당 Chrome 프로필에서 열린 탭과 로그인 상태를 재사용합니다.

공식 배경 및 설정 참조:

프로필 생성:

openclaw browser create-profile \
  --name chrome-live \
  --driver existing-session \
  --color "#00AA00"

그런 다음 Chrome에서:

  1. chrome://inspect/#remote-debugging 열기
  2. 원격 디버깅 활성화
  3. Chrome을 계속 실행하고 OpenClaw가 연결할 때 연결 프롬프트 승인

라이브 연결 스모크 테스트:

openclaw browser --browser-profile chrome-live start
openclaw browser --browser-profile chrome-live status
openclaw browser --browser-profile chrome-live tabs
openclaw browser --browser-profile chrome-live snapshot --format ai

성공 시:

  • status에 driver: existing-session 표시
  • status에 running: true 표시
  • tabs에 이미 열린 Chrome 탭 목록 표시
  • snapshot이 선택된 라이브 탭의 ref를 반환

연결이 동작하지 않을 때 확인할 사항:

  • Chrome 버전이 144+인지
  • chrome://inspect/#remote-debugging에서 원격 디버깅이 활성화되어 있는지
  • Chrome에서 연결 동의 프롬프트를 표시하고 승인했는지
  • 게이트웨이 또는 노드 호스트가 npx chrome-devtools-mcp@latest --autoConnect를 실행할 수 있는지

참고:

  • 이 경로는 로그인된 브라우저 세션 내에서 작동할 수 있으므로 격리된 openclaw 프로필보다 위험이 높습니다.
  • OpenClaw는 이 드라이버에서 Chrome을 실행하지 않으며, 기존 세션에만 연결합니다.
  • OpenClaw는 레거시 기본 프로필 원격 디버깅 포트 워크플로가 아닌 공식 Chrome DevTools MCP --autoConnect 흐름을 사용합니다.
  • 기존 세션 스크린샷은 페이지 캡처와 스냅샷에서의 --ref 요소 캡처를 지원하지만, CSS --element 선택자는 지원하지 않습니다.
  • 기존 세션 wait --url은 다른 브라우저 드라이버처럼 정확, 부분 문자열, 글롭 패턴을 지원합니다. wait --load networkidle은 아직 지원되지 않습니다.
  • PDF 내보내기 및 다운로드 인터셉션과 같은 일부 기능은 여전히 확장 프로그램 릴레이 또는 관리형 브라우저 경로가 필요합니다.
  • 기본적으로 릴레이를 루프백 전용으로 유지하세요. 릴레이가 다른 네트워크 네임스페이스에서 접근 가능해야 하는 경우(예: WSL2의 게이트웨이, Windows의 Chrome), browser.relayBindHost를 0.0.0.0과 같은 명시적 바인드 주소로 설정하되, 주변 네트워크를 비공개로 유지하고 인증을 적용하세요.

WSL2 / 크로스 네임스페이스 예시:

{
  browser: {
    enabled: true,
    relayBindHost: "0.0.0.0",
    defaultProfile: "chrome",
  },
}

격리 보장

  • 전용 사용자 데이터 디렉터리: 개인 브라우저 프로필을 절대 건드리지 않습니다.
  • 전용 포트: 개발 워크플로와의 충돌을 피하기 위해 9222를 사용하지 않습니다.
  • 결정적 탭 제어: “마지막 탭”이 아닌 targetId로 탭을 대상으로 합니다.

브라우저 선택

로컬에서 실행할 때 OpenClaw는 사용 가능한 첫 번째 브라우저를 선택합니다:

  1. Chrome
  2. Brave
  3. Edge
  4. Chromium
  5. Chrome Canary

browser.executablePath로 오버라이드할 수 있습니다.

플랫폼:

  • macOS: /Applications 및 ~/Applications를 확인.
  • Linux: google-chrome, brave, microsoft-edge, chromium 등을 검색.
  • Windows: 일반적인 설치 위치를 확인.

제어 API (선택)

로컬 통합 전용으로, 게이트웨이는 작은 루프백 HTTP API를 노출합니다:

  • 상태/시작/중지: GET /, POST /start, POST /stop
  • 탭: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
  • 스냅샷/스크린샷: GET /snapshot, POST /screenshot
  • 액션: POST /navigate, POST /act
  • 후크: POST /hooks/file-chooser, POST /hooks/dialog
  • 다운로드: POST /download, POST /wait/download
  • 디버깅: GET /console, POST /pdf
  • 디버깅: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
  • 네트워크: POST /response/body
  • 상태: GET /cookies, POST /cookies/set, POST /cookies/clear
  • 상태: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
  • 설정: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

모든 엔드포인트는 ?profile=<name>을 허용합니다.

게이트웨이 인증이 구성된 경우, 브라우저 HTTP 라우트에도 인증이 필요합니다:

  • Authorization: Bearer <gateway token>
  • x-openclaw-password: <gateway password> 또는 해당 비밀번호로 HTTP Basic 인증

Playwright 요구 사항

일부 기능(navigate/act/AI 스냅샷/역할 스냅샷, 요소 스크린샷, PDF)에는 Playwright가 필요합니다. Playwright가 설치되지 않으면 해당 엔드포인트는 명확한 501 오류를 반환합니다. ARIA 스냅샷과 기본 스크린샷은 openclaw 관리형 Chrome에서 여전히 동작합니다. Chrome 확장 프로그램 릴레이 드라이버의 경우 ARIA 스냅샷과 스크린샷에 Playwright가 필요합니다.

Playwright is not available in this gateway build가 표시되면, 전체 Playwright 패키지(playwright-core가 아닌)를 설치하고 게이트웨이를 재시작하거나, 브라우저 지원이 포함된 OpenClaw를 재설치하세요.

Docker Playwright 설치

게이트웨이가 Docker에서 실행되는 경우, npx playwright를 사용하지 마세요 (npm 오버라이드 충돌). 번들된 CLI를 대신 사용하세요:

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

브라우저 다운로드를 유지하려면 PLAYWRIGHT_BROWSERS_PATH를 설정하고(예: /home/node/.cache/ms-playwright), /home/node이 OPENCLAW_HOME_VOLUME 또는 바인드 마운트를 통해 유지되는지 확인하세요. Docker를 참조하세요.

내부 동작 원리

상위 수준 흐름:

  • 작은 제어 서버가 HTTP 요청을 수락합니다.
  • CDP를 통해 Chromium 기반 브라우저(Chrome/Brave/Edge/Chromium)에 연결합니다.
  • 고급 액션(클릭/입력/스냅샷/PDF)에는 CDP 위에 Playwright를 사용합니다.
  • Playwright가 없으면 비 Playwright 작업만 사용 가능합니다.

이 설계는 로컬/원격 브라우저와 프로필을 교체하면서도 에이전트가 안정적이고 결정적인 인터페이스를 유지하게 합니다.

CLI 빠른 참조

모든 명령은 --browser-profile <name>으로 특정 프로필을 대상으로 할 수 있습니다. 모든 명령은 --json으로 기계 판독 가능한 출력을 지원합니다 (안정적 페이로드).

기본:

  • openclaw browser status
  • openclaw browser start
  • openclaw browser stop
  • openclaw browser tabs
  • openclaw browser tab
  • openclaw browser tab new
  • openclaw browser tab select 2
  • openclaw browser tab close 2
  • openclaw browser open https://example.com
  • openclaw browser focus abcd1234
  • openclaw browser close abcd1234

검사:

  • openclaw browser screenshot
  • openclaw browser screenshot --full-page
  • openclaw browser screenshot --ref 12
  • openclaw browser screenshot --ref e12
  • openclaw browser snapshot
  • openclaw browser snapshot --format aria --limit 200
  • openclaw browser snapshot --interactive --compact --depth 6
  • openclaw browser snapshot --efficient
  • openclaw browser snapshot --labels
  • openclaw browser snapshot --selector "#main" --interactive
  • openclaw browser snapshot --frame "iframe#main" --interactive
  • openclaw browser console --level error
  • openclaw browser errors --clear
  • openclaw browser requests --filter api --clear
  • openclaw browser pdf
  • openclaw browser responsebody "**/api" --max-chars 5000

액션:

  • openclaw browser navigate https://example.com
  • openclaw browser resize 1280 720
  • openclaw browser click 12 --double
  • openclaw browser click e12 --double
  • openclaw browser type 23 "hello" --submit
  • openclaw browser press Enter
  • openclaw browser hover 44
  • openclaw browser scrollintoview e12
  • openclaw browser drag 10 11
  • openclaw browser select 9 OptionA OptionB
  • openclaw browser download e12 report.pdf
  • openclaw browser waitfordownload report.pdf
  • openclaw browser upload /tmp/openclaw/uploads/file.pdf
  • openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
  • openclaw browser dialog --accept
  • openclaw browser wait --text "Done"
  • openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
  • openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
  • openclaw browser highlight e12
  • openclaw browser trace start
  • openclaw browser trace stop

상태:

  • openclaw browser cookies
  • openclaw browser cookies set session abc123 --url "https://example.com"
  • openclaw browser cookies clear
  • openclaw browser storage local get
  • openclaw browser storage local set theme dark
  • openclaw browser storage session clear
  • openclaw browser set offline on
  • openclaw browser set headers --headers-json '{"X-Debug":"1"}'
  • openclaw browser set credentials user pass
  • openclaw browser set credentials --clear
  • openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
  • openclaw browser set geo --clear
  • openclaw browser set media dark
  • openclaw browser set timezone America/New_York
  • openclaw browser set locale en-US
  • openclaw browser set device "iPhone 14"

참고:

  • upload과 dialog은 준비 호출입니다. 선택기/대화 상자를 트리거하는 클릭/키 누르기 전에 실행하세요.
  • 다운로드 및 트레이스 출력 경로는 OpenClaw 임시 루트로 제한됩니다:
    • 트레이스: /tmp/openclaw (폴백: ${os.tmpdir()}/openclaw)
    • 다운로드: /tmp/openclaw/downloads (폴백: ${os.tmpdir()}/openclaw/downloads)
  • 업로드 경로는 OpenClaw 임시 업로드 루트로 제한됩니다:
    • 업로드: /tmp/openclaw/uploads (폴백: ${os.tmpdir()}/openclaw/uploads)
  • upload은 --input-ref 또는 --element를 통해 파일 입력을 직접 설정할 수도 있습니다.
  • snapshot:
    • --format ai (Playwright 설치 시 기본값): 숫자 ref가 포함된 AI 스냅샷을 반환 (aria-ref="<n>").
    • --format aria: 접근성 트리를 반환 (ref 없음, 검사 전용).
    • --efficient (또는 --mode efficient): 간결한 역할 스냅샷 프리셋 (interactive + compact + depth + 낮은 maxChars).
    • 설정 기본값 (도구/CLI 전용): 호출자가 모드를 전달하지 않을 때 효율적 스냅샷을 사용하려면 browser.snapshotDefaults.mode: "efficient"를 설정 (게이트웨이 설정 참조).
    • 역할 스냅샷 옵션(--interactive, --compact, --depth, --selector)은 ref=e12 형태의 ref가 있는 역할 기반 스냅샷을 강제합니다.
    • --frame "<iframe selector>"는 역할 스냅샷을 iframe으로 범위 제한합니다 (e12 같은 역할 ref와 함께 사용).
    • --interactive는 대화형 요소의 편평하고 선택하기 쉬운 목록을 출력합니다 (액션 구동에 최적).
    • --labels는 오버레이된 ref 레이블이 있는 뷰포트 전용 스크린샷을 추가합니다 (MEDIA:<path> 출력).
  • click/type/등은 snapshot에서 얻은 ref가 필요합니다 (숫자 12 또는 역할 ref e12). CSS 선택자는 액션에서 의도적으로 지원되지 않습니다.

스냅샷과 ref

OpenClaw는 두 가지 “스냅샷” 스타일을 지원합니다:

  • AI 스냅샷 (숫자 ref): openclaw browser snapshot (기본값, --format ai)

    • 출력: 숫자 ref가 포함된 텍스트 스냅샷.
    • 액션: openclaw browser click 12, openclaw browser type 23 "hello".
    • 내부적으로 Playwright의 aria-ref를 통해 ref가 해석됩니다.

  • 역할 스냅샷 (e12 같은 역할 ref): openclaw browser snapshot --interactive (또는 --compact, --depth, --selector, --frame)

    • 출력: [ref=e12] (및 선택적 [nth=1])가 포함된 역할 기반 목록/트리.
    • 액션: openclaw browser click e12, openclaw browser highlight e12.
    • 내부적으로 getByRole(...) (중복 시 nth() 추가)를 통해 ref가 해석됩니다.
    • --labels를 추가하면 오버레이된 e12 레이블이 있는 뷰포트 스크린샷이 포함됩니다.

ref 동작:

  • ref는 내비게이션 간에 안정적이지 않습니다. 실패 시 snapshot을 다시 실행하고 새 ref를 사용하세요.
  • 역할 스냅샷이 --frame으로 촬영된 경우, 다음 역할 스냅샷까지 역할 ref가 해당 iframe으로 범위 제한됩니다.

Wait 고급 기능

시간/텍스트 이상의 것을 기다릴 수 있습니다:

  • URL 대기 (Playwright에서 글롭 지원):
    • openclaw browser wait --url "**/dash"
  • 로드 상태 대기:
    • openclaw browser wait --load networkidle
  • JS 조건식 대기:
    • openclaw browser wait --fn "window.ready===true"
  • 선택자가 표시될 때까지 대기:
    • openclaw browser wait "#main"

조합 사용 가능:

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

디버그 워크플로

액션 실패 시(예: “not visible”, “strict mode violation”, “covered”):

  1. openclaw browser snapshot --interactive
  2. click <ref> / type <ref> 사용 (대화형 모드에서는 역할 ref 선호)
  3. 여전히 실패하면: openclaw browser highlight <ref>로 Playwright가 대상으로 삼는 것을 확인
  4. 페이지가 이상하게 동작하면:
    • openclaw browser errors --clear
    • openclaw browser requests --filter api --clear
  5. 심층 디버깅: 트레이스 기록:
    • openclaw browser trace start
    • 문제 재현
    • openclaw browser trace stop (TRACE:<path> 출력)

JSON 출력

--json은 스크립팅 및 구조화된 도구용입니다.

예시:

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

JSON의 역할 스냅샷에는 refs와 작은 stats 블록(lines/chars/refs/interactive)이 포함되어 도구가 페이로드 크기와 밀도를 분석할 수 있습니다.

상태 및 환경 조정

“사이트를 X처럼 동작하게 만들기” 워크플로에 유용합니다:

  • 쿠키: cookies, cookies set, cookies clear
  • 저장소: storage local|session get|set|clear
  • 오프라인: set offline on|off
  • 헤더: set headers --headers-json '{"X-Debug":"1"}' (레거시 set headers --json '{"X-Debug":"1"}'도 계속 지원)
  • HTTP basic 인증: set credentials user pass (또는 --clear)
  • 지리적 위치: set geo <lat> <lon> --origin "https://example.com" (또는 --clear)
  • 미디어: set media dark|light|no-preference|none
  • 시간대 / 로케일: set timezone ..., set locale ...
  • 장치 / 뷰포트:
    • set device "iPhone 14" (Playwright 장치 프리셋)
    • set viewport 1280 720

보안 및 개인정보

  • openclaw 브라우저 프로필에는 로그인된 세션이 포함될 수 있으므로 민감하게 취급하세요.
  • browser act kind=evaluate / openclaw browser evaluate 및 wait --fn은 페이지 컨텍스트에서 임의의 JavaScript를 실행합니다. 프롬프트 인젝션이 이를 조종할 수 있습니다. 필요하지 않으면 browser.evaluateEnabled=false로 비활성화하세요.
  • 로그인 및 봇 방지 관련 사항(X/Twitter 등)은 브라우저 로그인 + X/Twitter 포스팅을 참조하세요.
  • 게이트웨이/노드 호스트를 비공개로 유지하세요 (루프백 또는 tailnet 전용).
  • 원격 CDP 엔드포인트는 강력합니다. 터널링하고 보호하세요.

엄격 모드 예시 (기본적으로 사설/내부 대상 차단):

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // 선택적 정확한 허용
    },
  },
}

문제 해결

Linux 관련 문제(특히 snap Chromium)는 브라우저 문제 해결을 참조하세요.

WSL2 게이트웨이 + Windows Chrome 분할 호스트 설정은 WSL2 + Windows + 원격 Chrome CDP 문제 해결을 참조하세요.

에이전트 도구 + 제어 방식

에이전트는 브라우저 자동화를 위한 하나의 도구를 갖습니다:

  • browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

매핑:

  • browser snapshot은 안정적 UI 트리(AI 또는 ARIA)를 반환합니다.
  • browser act는 스냅샷 ref ID를 사용하여 클릭/입력/드래그/선택합니다.
  • browser screenshot은 픽셀을 캡처합니다 (전체 페이지 또는 요소).
  • browser가 허용하는 옵션:
    • profile: 명명된 브라우저 프로필 선택 (openclaw, chrome 또는 원격 CDP).
    • target (sandbox | host | node): 브라우저 위치 선택.
    • 샌드박스 세션에서 target: "host"는 agents.defaults.sandbox.browser.allowHostControl=true가 필요합니다.
    • target이 생략되면: 샌드박스 세션은 sandbox가 기본값, 비샌드박스 세션은 host가 기본값.
    • 브라우저 지원 노드가 연결된 경우, target="host" 또는 target="node"를 고정하지 않으면 도구가 자동으로 라우팅할 수 있습니다.

이를 통해 에이전트를 결정적으로 유지하고 불안정한 선택자를 피합니다.

arrow_back
이전
Web
다음
Browser Login
arrow_forward