브라우저 제어 API

설정, 구성, 문제 해결은 Browser를 참고하세요. 이 페이지는 로컬 제어 HTTP API, openclaw browser CLI, 그리고 스크립팅 패턴(스냅샷, ref, 대기, 디버그 흐름)에 대한 참조입니다.

제어 API(선택 사항)

로컬 통합 전용으로, Gateway는 작은 loopback 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
권한: POST /permissions/grant
디버깅: 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>을 허용합니다. POST /start?headless=true는 저장된 브라우저 구성을 변경하지 않고 로컬 관리형 프로필에 대해 일회성 headless 실행을 요청합니다. attach-only, 원격 CDP, 기존 세션 프로필은 OpenClaw가 해당 브라우저 프로세스를 실행하지 않으므로 이 override를 거부합니다. 공유 비밀 Gateway 인증이 구성된 경우, 브라우저 HTTP 라우트에도 인증이 필요합니다.

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

참고:

이 독립 실행형 loopback 브라우저 API는 trusted-proxy 또는 Tailscale Serve identity 헤더를 사용하지 않습니다.
gateway.auth.mode가 none 또는 trusted-proxy인 경우, 이러한 loopback 브라우저 라우트는 해당 identity-bearing 모드를 상속하지 않습니다. loopback 전용으로 유지하세요.

`/act` 오류 계약

POST /act는 라우트 수준 검증 및 정책 실패에 구조화된 오류 응답을 사용합니다.

{ "error": "<message>", "code": "ACT_*" }

현재 code 값:

ACT_KIND_REQUIRED(HTTP 400): kind가 없거나 인식되지 않습니다.
ACT_INVALID_REQUEST(HTTP 400): 동작 페이로드의 정규화 또는 검증에 실패했습니다.
ACT_SELECTOR_UNSUPPORTED(HTTP 400): selector가 지원되지 않는 동작 종류와 함께 사용되었습니다.
ACT_EVALUATE_DISABLED(HTTP 403): evaluate(또는 wait --fn)가 구성에서 비활성화되어 있습니다.
ACT_TARGET_ID_MISMATCH(HTTP 403): 최상위 또는 배치된 targetId가 요청 대상과 충돌합니다.
ACT_EXISTING_SESSION_UNSUPPORTED(HTTP 501): 기존 세션 프로필에서는 동작이 지원되지 않습니다.

다른 런타임 실패는 여전히 code 필드 없이 { "error": "<message>" }를 반환할 수 있습니다.

Playwright 요구 사항

일부 기능(탐색/동작/AI 스냅샷/role 스냅샷, 요소 스크린샷, PDF)에는 Playwright가 필요합니다. Playwright가 설치되어 있지 않으면 해당 엔드포인트는 명확한 501 오류를 반환합니다. Playwright 없이도 계속 작동하는 기능:

ARIA 스냅샷
탭별 CDP WebSocket을 사용할 수 있을 때 role 스타일 접근성 스냅샷(--interactive, --compact, --depth, --efficient). 이는 검사 및 ref 발견을 위한 fallback이며, Playwright는 여전히 기본 동작 엔진입니다.
탭별 CDP WebSocket을 사용할 수 있을 때 관리형 openclaw 브라우저의 페이지 스크린샷
existing-session / Chrome MCP 프로필의 페이지 스크린샷
스냅샷 출력에서 가져온 existing-session ref 기반 스크린샷(--ref)

여전히 Playwright가 필요한 기능:

navigate
act
Playwright의 네이티브 AI 스냅샷 형식에 의존하는 AI 스냅샷
CSS selector 요소 스크린샷(--element)
전체 브라우저 PDF 내보내기

요소 스크린샷은 --full-page도 거부합니다. 라우트는 fullPage is not supported for element screenshots를 반환합니다. Playwright is not available in this gateway build가 표시되면 패키징된 Gateway에 핵심 브라우저 런타임 의존성이 없습니다. OpenClaw를 다시 설치하거나 업데이트한 다음 Gateway를 다시 시작하세요. Docker의 경우 아래와 같이 Chromium 브라우저 바이너리도 설치하세요.

Docker Playwright 설치

Gateway가 Docker에서 실행되는 경우 npx playwright(npm override 충돌)를 피하세요. 커스텀 이미지에서는 Chromium을 이미지에 포함하세요.

OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh

기존 이미지의 경우 대신 번들된 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 또는 bind mount를 통해 유지되는지 확인하세요. OpenClaw는 Linux에서 유지된 Chromium을 자동 감지합니다. Docker를 참고하세요.

작동 방식(내부)

작은 loopback 제어 서버가 HTTP 요청을 수락하고 CDP를 통해 Chromium 기반 브라우저에 연결합니다. 고급 동작(클릭/입력/스냅샷/PDF)은 CDP 위의 Playwright를 통해 수행됩니다. Playwright가 없으면 Playwright가 필요 없는 작업만 사용할 수 있습니다. 에이전트는 로컬/원격 브라우저와 프로필이 내부에서 자유롭게 바뀌더라도 하나의 안정적인 인터페이스를 봅니다.

CLI 빠른 참조

모든 명령은 특정 프로필을 대상으로 지정하는 --browser-profile <name>과 기계가 읽을 수 있는 출력을 위한 --json을 허용합니다.

Basics: status, tabs, open/focus/close

openclaw browser status
openclaw browser start
openclaw browser start --headless # one-shot local managed headless launch
openclaw browser stop            # also clears emulation on attach-only/remote CDP
openclaw browser tabs
openclaw browser tab             # shortcut for current 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

Inspection: screenshot, snapshot, console, errors, requests

openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12        # or --ref e12
openclaw browser screenshot --labels
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 --urls
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

Actions: navigate, click, type, drag, wait, evaluate

openclaw browser navigate https://example.com
openclaw browser resize 1280 720
openclaw browser click 12 --double           # or e12 for role refs
openclaw browser click-coords 120 340        # viewport coordinates
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

State: cookies, storage, offline, headers, geo, device

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            # --clear to remove
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
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 호출입니다. chooser/dialog를 트리거하는 클릭/키 입력 전에 실행하세요.
click/type 등에는 snapshot의 ref(숫자 12, role ref e12, 또는 실행 가능한 ARIA ref ax12)가 필요합니다. CSS selector는 동작에서 의도적으로 지원되지 않습니다. 보이는 뷰포트 위치가 유일하게 신뢰할 수 있는 대상일 때는 click-coords를 사용하세요.
다운로드, trace, upload 경로는 OpenClaw 임시 루트로 제한됩니다: /tmp/openclaw{,/downloads,/uploads}(fallback: ${os.tmpdir()}/openclaw/...).
upload는 --input-ref 또는 --element를 통해 파일 입력을 직접 설정할 수도 있습니다.

OpenClaw가 대체 탭을 증명할 수 있으면, 예를 들어 동일한 URL이거나 폼 제출 후 단일 이전 탭이 단일 새 탭이 되는 경우, 안정적인 탭 ID와 라벨은 Chromium 원시 대상 교체 후에도 유지됩니다. 원시 대상 ID는 여전히 변동될 수 있습니다. 스크립트에서는 tabs의 suggestedTargetId를 선호하세요. 스냅샷 플래그 한눈에 보기:

--format ai(Playwright 사용 시 기본값): 숫자 ref(aria-ref="<n>")가 있는 AI 스냅샷.
--format aria: axN ref가 있는 접근성 트리. Playwright를 사용할 수 있으면 OpenClaw는 후속 동작에서 사용할 수 있도록 백엔드 DOM ID가 있는 ref를 라이브 페이지에 바인딩합니다. 그렇지 않으면 출력을 검사 전용으로 취급하세요.
--efficient(또는 --mode efficient): compact role 스냅샷 preset. 이를 기본값으로 만들려면 browser.snapshotDefaults.mode: "efficient"를 설정하세요(Gateway 구성 참고).
--interactive, --compact, --depth, --selector는 ref=e12 ref가 있는 role 스냅샷을 강제합니다. --frame "<iframe>"은 role 스냅샷 범위를 iframe으로 제한합니다.
--labels는 ref 라벨이 overlay된 뷰포트 전용 스크린샷을 추가합니다(MEDIA:<path> 출력).
--urls는 발견된 링크 대상을 AI 스냅샷에 추가합니다.

스냅샷과 ref

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

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() 추가)를 통해 해석됩니다.
- overlay된 e12 라벨이 있는 뷰포트 스크린샷을 포함하려면 --labels를 추가하세요.
- 링크 텍스트가 모호하고 에이전트에 구체적인 탐색 대상이 필요할 때 --urls를 추가하세요.
ARIA 스냅샷(ax12 같은 ARIA 참조): openclaw browser snapshot --format aria
- 출력: 구조화된 노드로 된 접근성 트리.
- 작업: 스냅샷 경로가 Playwright와 Chrome 백엔드 DOM ID를 통해 참조를 바인딩할 수 있을 때 openclaw browser click ax12가 작동합니다.
Playwright를 사용할 수 없어도 ARIA 스냅샷은 검사에 여전히 유용할 수 있지만, 참조는 작업에 사용할 수 없을 수 있습니다. 작업 참조가 필요하면 --format ai 또는 --interactive로 다시 스냅샷을 찍으세요.
raw-CDP 폴백 경로에 대한 Docker 증명: pnpm test:docker:browser-cdp-snapshot은 CDP로 Chromium을 시작하고, browser doctor --deep을 실행하며, 역할 스냅샷에 링크 URL, 커서로 승격된 클릭 가능 항목, iframe 메타데이터가 포함되는지 검증합니다.

참조 동작:

참조는 탐색 사이에서 안정적이지 않습니다. 무언가 실패하면 snapshot을 다시 실행하고 새 참조를 사용하세요.
/act는 교체 탭을 증명할 수 있을 때 작업으로 트리거된 교체 이후의 현재 raw targetId를 반환합니다. 후속 명령에는 안정적인 탭 ID/레이블을 계속 사용하세요.
역할 스냅샷을 --frame으로 찍은 경우, 다음 역할 스냅샷까지 역할 참조는 해당 iframe으로 범위가 지정됩니다.
알 수 없거나 오래된 axN 참조는 Playwright의 aria-ref 셀렉터로 넘어가지 않고 빠르게 실패합니다. 이런 일이 발생하면 같은 탭에서 새 스냅샷을 실행하세요.

대기 기능 강화

시간/텍스트 외에도 더 많은 조건을 기다릴 수 있습니다.

URL 대기(Playwright에서 glob 지원):
- 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”):

openclaw browser snapshot --interactive
click <ref> / type <ref> 사용(대화형 모드에서는 역할 참조를 선호)
여전히 실패하면: Playwright가 무엇을 대상으로 삼는지 확인하려면 openclaw browser highlight <ref>
페이지가 이상하게 동작하면:
- openclaw browser errors --clear
- openclaw browser requests --filter api --clear
심층 디버깅: 트레이스 기록:
- 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 기본 인증: 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 게시를 참조하세요.
Gateway/노드 호스트는 비공개로 유지하세요(local loopback 또는 tailnet 전용).
원격 CDP 엔드포인트는 강력하므로, 터널링하고 보호하세요.

엄격 모드 예시(기본적으로 비공개/내부 대상을 차단):

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optional exact allow
    },
  },
}

Documentation Index

​제어 API(선택 사항)

​/act 오류 계약

​Playwright 요구 사항

​Docker Playwright 설치

​작동 방식(내부)

​CLI 빠른 참조

​스냅샷과 ref

​대기 기능 강화

​디버그 워크플로

​JSON 출력

​상태와 환경 조정 항목

​보안과 개인정보 보호

​관련