​

브라우저(openclaw 관리형)

• 이를 에이전트 전용 별도 브라우저라고 생각하면 됩니다.
• openclaw 프로필은 개인 브라우저 프로필을 건드리지 않습니다.
• 에이전트는 안전한 범위 안에서 탭 열기, 페이지 읽기, 클릭, 입력을 할 수 있습니다.
• 내장 user 프로필은 Chrome MCP를 통해 실제 로그인된 Chrome 세션에 연결합니다.

​

제공 기능

• 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

​

plugin 제어

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

• plugins.entries.browser.enabled가 비활성화되어 있지 않을 것
• browser.enabled=true

​

브라우저 명령 또는 도구 누락

{
  plugins: {
    allow: ["telegram"],
  },
}

{
  plugins: {
    allow: ["telegram", "browser"],
  },
}

• plugins.allow가 설정된 경우 browser.enabled=true만으로는 충분하지 않습니다.
• plugins.allow가 설정된 경우 plugins.entries.browser.enabled=true만으로도 충분하지 않습니다.
• tools.alsoAllow: ["browser"]는 번들 브라우저 plugin을 로드하지 않습니다. plugin이 이미 로드된 후에만 도구 정책을 조정합니다.
• 제한적인 plugin allowlist가 필요 없다면 plugins.allow를 제거하는 것만으로도 기본 번들 브라우저 동작이 복원됩니다.

• openclaw browser가 알 수 없는 명령입니다.
• browser.request가 없습니다.
• 에이전트가 브라우저 도구를 사용할 수 없거나 없다고 보고합니다.

​

프로필: openclaw vs user

• openclaw: 관리형, 격리된 브라우저(확장 프로그램 필요 없음).
• user: 실제 로그인된 Chrome 세션에 연결되는 내장 Chrome MCP attach 프로필.

• 기본값: 격리된 openclaw 브라우저를 사용합니다.
• 기존 로그인 세션이 중요하고 사용자가 컴퓨터 앞에서 attach 프롬프트를 클릭/승인할 수 있다면 profile="user"를 선호하세요.
• 특정 브라우저 모드가 필요할 때는 profile이 명시적 재정의입니다.

​

구성

{
  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: "openclaw",
    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" },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

• 브라우저 제어 서비스는 gateway.port에서 파생된 포트의 루프백에 바인딩됩니다 (기본값: 18791, 즉 gateway + 2).
• Gateway 포트(gateway.port 또는 OPENCLAW_GATEWAY_PORT)를 재정의하면 파생 브라우저 포트도 같은 “패밀리” 안에 있도록 함께 이동합니다.
• cdpUrl이 설정되지 않으면 기본적으로 관리형 로컬 CDP 포트를 사용합니다.
• remoteCdpTimeoutMs는 원격(비루프백) CDP 도달 가능성 검사에 적용됩니다.
• remoteCdpHandshakeTimeoutMs는 원격 CDP WebSocket 도달 가능성 검사에 적용됩니다.
• 브라우저 탐색/탭 열기는 탐색 전에 SSRF 보호가 적용되며, 탐색 후 최종 http(s) URL에 대해서도 최선의 노력으로 다시 검사합니다.
• 엄격한 SSRF 모드에서는 원격 CDP 엔드포인트 탐색/프로브(cdpUrl, /json/version 조회 포함)도 검사됩니다.
• browser.ssrfPolicy.dangerouslyAllowPrivateNetwork의 기본값은 true(신뢰 네트워크 모델)입니다. 엄격한 공용 전용 브라우징이 필요하면 false로 설정하세요.
• browser.ssrfPolicy.allowPrivateNetwork는 호환성을 위한 레거시 별칭으로 계속 지원됩니다.
• attachOnly: true는 “로컬 브라우저를 절대 실행하지 않고, 이미 실행 중일 때만 연결한다”는 의미입니다.
• color 및 프로필별 color는 브라우저 UI에 색을 입혀 어느 프로필이 활성 상태인지 볼 수 있게 합니다.
• 기본 프로필은 openclaw입니다(OpenClaw 관리형 독립 브라우저). 로그인된 사용자 브라우저를 사용하려면 defaultProfile: "user"를 사용하세요.
• 자동 감지 순서: 시스템 기본 브라우저가 Chromium 기반이면 그것을 사용하고, 아니면 Chrome → Brave → Edge → Chromium → Chrome Canary 순입니다.
• 로컬 openclaw 프로필은 cdpPort/cdpUrl이 자동 할당되므로, 원격 CDP가 아닌 경우에는 이를 설정하지 마세요.
• driver: "existing-session"은 raw CDP 대신 Chrome DevTools MCP를 사용합니다. 이 드라이버에는 cdpUrl을 설정하지 마세요.
• 기존 세션 프로필이 Brave 또는 Edge 같은 비기본 Chromium 사용자 프로필에 연결되어야 한다면 browser.profiles.<name>.userDataDir을 설정하세요.

​

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

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 원격 제어

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

• 로컬 관리형 프로필: openclaw browser stop은 OpenClaw가 시작한 브라우저 프로세스를 중지합니다
• attach-only 및 원격 CDP 프로필: openclaw browser stop은 OpenClaw가 브라우저 프로세스를 시작하지 않았더라도 활성 제어 세션을 닫고 Playwright/CDP 에뮬레이션 재정의(뷰포트, 색 구성표, 로캘, 시간대, 오프라인 모드 등)를 해제합니다

• 쿼리 토큰(예: https://provider.example?token=<token>)
• HTTP Basic auth(예: https://user:pass@provider.example)

​

Node 브라우저 프록시(기본 제로 구성)

• node host는 로컬 브라우저 제어 서버를 프록시 명령으로 노출합니다.
• 프로필은 노드 자체의 browser.profiles config(로컬과 동일)에서 가져옵니다.
• nodeHost.browserProxy.allowProfiles는 선택 사항입니다. 비워 두면 레거시/기본 동작이 적용되어, 프로필 생성/삭제 라우트를 포함해 구성된 모든 프로필이 프록시를 통해 접근 가능합니다.
• nodeHost.browserProxy.allowProfiles를 설정하면, OpenClaw는 이를 최소 권한 경계로 취급합니다. allowlist에 있는 프로필만 대상으로 지정할 수 있으며, 영구 프로필 생성/삭제 라우트는 프록시 표면에서 차단됩니다.
• 원하지 않으면 비활성화하세요:
  • 노드에서: nodeHost.browserProxy.enabled=false
  • 게이트웨이에서: gateway.nodes.browser.mode="off"

​

Browserless(호스팅 원격 CDP)

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

• <BROWSERLESS_API_KEY>를 실제 Browserless 토큰으로 바꾸세요.
• Browserless 계정에 맞는 리전 엔드포인트를 선택하세요(자세한 내용은 해당 문서 참조).
• Browserless가 HTTPS 기본 URL을 제공하는 경우, 직접 CDP 연결을 위해 이를 wss://로 변환하거나 HTTPS URL을 그대로 두고 OpenClaw가 /json/version을 탐색하도록 할 수 있습니다.

​

직접 WebSocket CDP provider

• HTTP(S) 엔드포인트 — OpenClaw가 /json/version을 호출해 WebSocket 디버거 URL을 탐색한 후 연결합니다.
• WebSocket 엔드포인트 (ws:// / wss://) — OpenClaw가 직접 연결하며 /json/version은 건너뜁니다. 이는 Browserless, Browserbase 또는 WebSocket URL을 직접 제공하는 모든 provider에 사용하세요.

​

Browserbase

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

• 회원 가입 후 Overview dashboard에서 API Key를 복사하세요.
• <BROWSERBASE_API_KEY>를 실제 Browserbase API 키로 바꾸세요.
• Browserbase는 WebSocket 연결 시 브라우저 세션을 자동 생성하므로 수동 세션 생성 단계가 필요하지 않습니다.
• 무료 등급은 동시 세션 1개와 월 1 브라우저 시간을 허용합니다. 유료 요금제 한도는 pricing을 참조하세요.
• 전체 API 참조, SDK 가이드, 통합 예시는 Browserbase docs를 참조하세요.

​

보안

• 브라우저 제어는 루프백 전용이며, 액세스는 Gateway 인증 또는 node pairing을 통해 흐릅니다.
• 독립형 루프백 브라우저 HTTP API는 공유 비밀 인증만 사용합니다: gateway 토큰 bearer auth, x-openclaw-password, 또는 구성된 gateway 비밀번호를 사용한 HTTP Basic auth.
• Tailscale Serve identity 헤더와 gateway.auth.mode: "trusted-proxy"는 이 독립형 루프백 브라우저 API를 인증하지 않습니다.
• 브라우저 제어가 활성화되어 있고 공유 비밀 인증이 구성되지 않은 경우, OpenClaw는 시작 시 gateway.auth.token을 자동 생성하고 config에 저장합니다.
• gateway.auth.mode가 이미 password, none, 또는 trusted-proxy인 경우에는 해당 토큰을 자동 생성하지 않습니다.
• Gateway와 모든 node host는 비공개 네트워크(Tailscale)에 유지하고, 공용 노출은 피하세요.
• 원격 CDP URL/토큰은 시크릿으로 취급하고, env var 또는 시크릿 매니저를 선호하세요.

• 가능하면 암호화된 엔드포인트(HTTPS 또는 WSS)와 짧은 수명의 토큰을 선호하세요.
• 오래 유지되는 토큰을 config 파일에 직접 포함하지 마세요.

​

프로필(멀티 브라우저)

• openclaw-managed: 자체 사용자 데이터 디렉터리와 CDP 포트를 가진 전용 Chromium 기반 브라우저 인스턴스
• remote: 명시적 CDP URL(다른 곳에서 실행 중인 Chromium 기반 브라우저)
• existing session: Chrome DevTools MCP 자동 연결을 통한 기존 Chrome 프로필

• openclaw 프로필은 없으면 자동 생성됩니다.
• user 프로필은 Chrome MCP existing-session attach용 내장 프로필입니다.
• existing-session 프로필은 user 외에는 opt-in이며, --driver existing-session으로 생성하세요.
• 로컬 CDP 포트는 기본적으로 18800–18899 범위에서 할당됩니다.
• 프로필을 삭제하면 해당 로컬 데이터 디렉터리는 휴지통으로 이동합니다.

​

Chrome DevTools MCP를 통한 existing-session

• Chrome for Developers: Use Chrome DevTools MCP with your browser session
• Chrome DevTools MCP README

• user

• 내장 user 프로필은 Chrome MCP 자동 연결을 사용하며, 기본 로컬 Google Chrome 프로필을 대상으로 합니다.

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

1. 원격 디버깅용 inspect 페이지를 엽니다.
2. 원격 디버깅을 활성화합니다.
3. 브라우저를 계속 실행한 채 OpenClaw가 연결할 때 나타나는 연결 승인 프롬프트를 수락합니다.

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

• status에 driver: existing-session이 표시됨
• status에 transport: chrome-mcp가 표시됨
• status에 running: true가 표시됨
• tabs에 이미 열려 있는 브라우저 탭이 나열됨
• snapshot이 선택된 라이브 탭의 ref를 반환함

• 대상 Chromium 기반 브라우저 버전이 144+인지
• 해당 브라우저 inspect 페이지에서 원격 디버깅이 활성화되어 있는지
• 브라우저에 연결 승인 프롬프트가 표시되었고 이를 수락했는지
• openclaw doctor는 이전 확장 기반 브라우저 config를 마이그레이션하고 기본 자동 연결 프로필용으로 Chrome이 로컬에 설치되어 있는지 확인하지만, 브라우저 측 원격 디버깅까지 대신 활성화해 주지는 않습니다

• 사용자의 로그인된 브라우저 상태가 필요할 때는 profile="user"를 사용하세요.
• custom existing-session 프로필을 사용한다면 명시적으로 해당 프로필 이름을 전달하세요.
• 사용자가 컴퓨터 앞에 있어 attach 프롬프트를 승인할 수 있을 때만 이 모드를 선택하세요.
• Gateway 또는 node host는 npx chrome-devtools-mcp@latest --autoConnect를 실행할 수 있습니다

• 이 경로는 로그인된 브라우저 세션 내부에서 동작할 수 있으므로 격리된 openclaw 프로필보다 위험도가 높습니다.
• 이 드라이버에서는 OpenClaw가 브라우저를 실행하지 않으며, 기존 세션에만 연결합니다.
• OpenClaw는 여기서 공식 Chrome DevTools MCP --autoConnect 흐름을 사용합니다. userDataDir이 설정되어 있으면 해당 명시적 Chromium 사용자 데이터 디렉터리를 대상으로 하도록 이를 전달합니다.
• existing-session 스크린샷은 페이지 캡처와 스냅샷의 --ref 요소 캡처는 지원하지만 CSS --element 선택자는 지원하지 않습니다.
• existing-session 페이지 스크린샷은 Chrome MCP를 통해 Playwright 없이도 작동합니다. ref 기반 요소 스크린샷(--ref)도 작동하지만, --full-page는 --ref 또는 --element와 함께 사용할 수 없습니다.
• existing-session 작업은 관리형 브라우저 경로보다 여전히 더 제한적입니다:
  • click, type, hover, scrollIntoView, drag, select는 CSS 선택자 대신 스냅샷 ref가 필요합니다
  • click은 왼쪽 버튼만 지원합니다(버튼 재정의나 modifier 없음)
  • type은 slowly=true를 지원하지 않으며, fill 또는 press를 사용해야 합니다
  • press는 delayMs를 지원하지 않습니다
  • hover, scrollIntoView, drag, select, fill, evaluate는 호출별 타임아웃 재정의를 지원하지 않습니다
  • select는 현재 단일 값만 지원합니다
• existing-session wait --url은 다른 브라우저 드라이버처럼 정확 일치, 부분 문자열, glob 패턴을 지원합니다. wait --load networkidle은 아직 지원하지 않습니다.
• existing-session 업로드 훅은 ref 또는 inputRef가 필요하고, 한 번에 한 파일만 지원하며, CSS element 대상 지정은 지원하지 않습니다.
• existing-session 대화상자 훅은 타임아웃 재정의를 지원하지 않습니다.
• 일부 기능은 여전히 관리형 브라우저 경로가 필요합니다. 예를 들면 배치 작업, PDF 내보내기, 다운로드 가로채기, responsebody 등이 있습니다.
• existing-session은 호스트 로컬 전용입니다. Chrome이 다른 머신이나 다른 네트워크 네임스페이스에 있다면 remote CDP 또는 node host를 대신 사용하세요.

​

격리 보장

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

​

브라우저 선택

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

• macOS: /Applications와 ~/Applications를 확인합니다.
• Linux: google-chrome, brave, microsoft-edge, chromium 등을 찾습니다.
• Windows: 일반적인 설치 위치를 확인합니다.

​

제어 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

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password> 또는 해당 비밀번호를 사용하는 HTTP Basic auth

• 이 독립형 루프백 브라우저 API는 trusted-proxy 또는 Tailscale Serve identity 헤더를 사용하지 않습니다.
• gateway.auth.mode가 none 또는 trusted-proxy인 경우에도 이 루프백 브라우저 라우트는 그런 identity 기반 모드를 상속하지 않으므로 반드시 루프백 전용으로 유지하세요.

​

Playwright 필요 사항

• ARIA 스냅샷
• 탭별 CDP WebSocket을 사용할 수 있는 경우 관리형 openclaw 브라우저의 페이지 스크린샷
• existing-session / Chrome MCP 프로필의 페이지 스크린샷
• 스냅샷 출력에서 existing-session ref 기반 스크린샷(--ref)

• navigate
• act
• AI 스냅샷 / role 스냅샷
• CSS 선택자 요소 스크린샷(--element)
• 전체 브라우저 PDF 내보내기

​

Docker Playwright 설치

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

​

작동 방식(내부)

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

​

CLI 빠른 참조

• 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

• attach-only 및 원격 CDP 프로필에서는 테스트 후에도 openclaw browser stop이 올바른 정리 명령입니다. 기본 브라우저를 종료하는 대신 활성 제어 세션을 닫고 임시 에뮬레이션 재정의를 해제합니다.
• 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는 arming 호출입니다. 파일 선택기/대화상자를 트리거하는 클릭/press 전에 먼저 실행하세요.
• 다운로드 및 trace 출력 경로는 OpenClaw 임시 루트로 제한됩니다:
  • traces: /tmp/openclaw (폴백: ${os.tmpdir()}/openclaw)
  • downloads: /tmp/openclaw/downloads (폴백: ${os.tmpdir()}/openclaw/downloads)
• 업로드 경로도 OpenClaw 임시 업로드 루트로 제한됩니다:
  • uploads: /tmp/openclaw/uploads (폴백: ${os.tmpdir()}/openclaw/uploads)
• upload는 --input-ref 또는 --element를 통해 파일 입력을 직접 설정할 수도 있습니다.
• snapshot:
  • --format ai(기본값, Playwright 설치 시): 숫자 ref(aria-ref="<n>")가 있는 AI 스냅샷을 반환합니다.
  • --format aria: 접근성 트리를 반환합니다(ref 없음, 검사 전용).
  • --efficient(또는 --mode efficient): compact role 스냅샷 프리셋(interactive + compact + depth + 낮은 maxChars)입니다.
  • config 기본값(도구/CLI 전용): 호출자가 모드를 전달하지 않을 때 efficient 스냅샷을 사용하려면 browser.snapshotDefaults.mode: "efficient"를 설정하세요(Gateway configuration 참조).
  • role 스냅샷 옵션(--interactive, --compact, --depth, --selector)은 ref=e12 같은 ref가 있는 role 기반 스냅샷을 강제합니다.
  • --frame "<iframe selector>"는 role 스냅샷을 해당 iframe으로 범위 제한합니다(e12 같은 role ref와 함께 사용).
  • --interactive는 상호작용 가능한 요소를 평면적이고 선택하기 쉽게 출력합니다(작업 구동에 가장 적합).
  • --labels는 ref 레이블이 오버레이된 뷰포트 전용 스크린샷을 추가합니다(MEDIA:<path> 출력).
• click/type 등은 snapshot에서 얻은 ref(숫자 12 또는 role ref e12)가 필요합니다. 작업에는 의도적으로 CSS 선택자를 지원하지 않습니다.

​

스냅샷과 ref

• AI 스냅샷(숫자 ref): openclaw browser snapshot(기본값, --format ai)
  • 출력: 숫자 ref가 포함된 텍스트 스냅샷.
  • 작업: openclaw browser click 12, openclaw browser type 23 "hello".
  • 내부적으로 이 ref는 Playwright의 aria-ref를 통해 확인됩니다.
• Role 스냅샷(e12 같은 role ref): openclaw browser snapshot --interactive(--compact, --depth, --selector, --frame도 가능)
  • 출력: [ref=e12](선택적으로 [nth=1])가 있는 role 기반 목록/트리.
  • 작업: openclaw browser click e12, openclaw browser highlight e12.
  • 내부적으로 이 ref는 getByRole(...)(중복일 경우 nth() 포함)로 확인됩니다.
  • --labels를 추가하면 e12 레이블이 오버레이된 뷰포트 스크린샷이 포함됩니다.

• ref는 탐색 간에 안정적이지 않습니다. 실패하면 snapshot을 다시 실행해 새 ref를 사용하세요.
• role 스냅샷을 --frame으로 찍었다면, 다음 role 스냅샷 전까지 role ref는 해당 iframe 범위로 제한됩니다.

​

wait 기능 강화

• URL 대기(Playwright glob 지원):
  • openclaw browser wait --url "**/dash"
• 로드 상태 대기:
  • openclaw browser wait --load networkidle
• JS predicate 대기:
  • 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

​

디버그 워크플로

1. openclaw browser snapshot --interactive
2. click <ref> / type <ref> 사용(interactive 모드에서는 role ref 권장)
3. 여전히 실패하면: openclaw browser highlight <ref>로 Playwright가 무엇을 대상으로 삼는지 확인
4. 페이지 동작이 이상하면:
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. 심층 디버깅이 필요하면 trace를 기록:
   • openclaw browser trace start
   • 문제 재현
   • openclaw browser trace stop(TRACE:<path> 출력)

​

JSON 출력

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

​

상태 및 환경 옵션

• 쿠키: 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 auth: 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 등)은 Browser login + X/Twitter posting을 참조하세요.
• Gateway/node host는 비공개 상태(루프백 또는 tailnet 전용)로 유지하세요.
• 원격 CDP 엔드포인트는 강력하므로 터널링하고 보호해야 합니다.

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

​

문제 해결

​

에이전트 도구 + 제어 방식

• 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 또는 remote CDP).
  • target (sandbox | host | node): 브라우저가 존재하는 위치 선택.
  • 샌드박스 세션에서 target: "host"는 agents.defaults.sandbox.browser.allowHostControl=true가 필요합니다.
  • target이 생략되면: 샌드박스 세션은 기본적으로 sandbox, 비샌드박스 세션은 기본적으로 host.
  • 브라우저 기능이 있는 노드가 연결되어 있으면 target="host" 또는 target="node"로 고정하지 않는 한 도구가 자동 라우팅될 수 있습니다.

​

관련 항목

• 도구 개요 — 사용 가능한 모든 에이전트 도구
• 샌드박싱 — 샌드박스 환경에서의 브라우저 제어
• 보안 — 브라우저 제어 위험 및 강화 방법