Browser (openclaw 관리)

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

초보자 관점:

  • 별도의 에이전트 전용 브라우저로 생각하십시오.
  • 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" 오류가 발생하면 설정에서 활성화하고(아래 참조) Gateway를 다시 시작하십시오.

프로필: openclaw vs chrome

  • openclaw: 관리되는 격리된 브라우저(확장 프로그램 불필요).
  • chrome: 시스템 브라우저에 대한 확장 프로그램 릴레이(탭에 OpenClaw 확장 프로그램 연결 필요).

기본적으로 관리 모드를 사용하려면 browser.defaultProfile: "openclaw"를 설정하십시오.

구성

브라우저 설정은 ~/.openclaw/openclaw.json에 있습니다.

{
  browser: {
    enabled: true,                    // 기본값: true
    // 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" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" }
    }
  }
}

참고:

  • 브라우저 제어 서비스는 gateway.port에서 파생된 포트의 루프백에 바인딩됩니다(기본값: 18791, 게이트웨이 + 2). 릴레이는 다음 포트(18792)를 사용합니다.
  • Gateway 포트를 오버라이드하면(gateway.port 또는 OPENCLAW_GATEWAY_PORT), 파생된 브라우저 포트도 동일한 "계열"을 유지하도록 이동합니다.
  • cdpUrl은 설정하지 않으면 릴레이 포트로 기본 설정됩니다.
  • remoteCdpTimeoutMs는 원격(비루프백) CDP 연결 가능성 확인에 적용됩니다.
  • remoteCdpHandshakeTimeoutMs는 원격 CDP WebSocket 연결 가능성 확인에 적용됩니다.
  • attachOnly: true는 "로컬 브라우저를 시작하지 않음. 이미 실행 중인 경우에만 연결"을 의미합니다.
  • color + 프로필별 color는 브라우저 UI를 색칠하여 활성 프로필을 확인할 수 있습니다.
  • 기본 프로필은 chrome(확장 프로그램 릴레이)입니다. 관리 브라우저를 사용하려면 defaultProfile: "openclaw"를 사용하십시오.
  • 자동 감지 순서: Chromium 기반인 경우 시스템 기본 브라우저, 그렇지 않으면 Chrome → Brave → Edge → Chromium → Chrome Canary.
  • 로컬 openclaw 프로필은 cdpPort/cdpUrl을 자동 할당합니다. 원격 CDP에 대해서만 설정하십시오.

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

  • 로컬 제어(기본값): Gateway가 루프백 제어 서비스를 시작하고 로컬 브라우저를 실행할 수 있습니다.
  • 원격 제어(노드 호스트): 브라우저가 있는 머신에서 노드 호스트를 실행합니다. Gateway는 브라우저 액션을 프록시합니다.
  • 원격 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 계정과 일치하는 지역 엔드포인트를 선택하십시오(문서 참조).

보안

주요 개념:

  • 브라우저 제어는 루프백 전용입니다. 액세스는 Gateway의 인증 또는 노드 페어링을 통해 흐릅니다.
  • Gateway 및 모든 노드 호스트를 개인 네트워크(Tailscale)에 유지하십시오. 공개 노출을 피하십시오.
  • 원격 CDP URL/토큰을 시크릿으로 처리하십시오. 환경 변수 또는 시크릿 관리자를 선호하십시오.

원격 CDP 팁:

  • 가능한 경우 HTTPS 엔드포인트 및 단기 토큰을 선호하십시오.
  • 구성 파일에 장기 토큰을 직접 포함하지 마십시오.

프로필(다중 브라우저)

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

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

기본값:

  • openclaw 프로필은 누락된 경우 자동 생성됩니다.
  • chrome 프로필은 Chrome 확장 프로그램 릴레이용으로 내장되어 있습니다(기본적으로 http://127.0.0.1:18792 가리킴).
  • 로컬 CDP 포트는 기본적으로 18800–18899에서 할당됩니다.
  • 프로필을 삭제하면 로컬 데이터 디렉토리가 휴지통으로 이동합니다.

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

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

OpenClaw는 로컬 CDP 릴레이 + Chrome 확장 프로그램을 통해 기존 Chrome 탭을 구동할 수도 있습니다(별도의 "openclaw" Chrome 인스턴스 없음).

전체 가이드: Chrome extension

플로우:

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

Gateway가 다른 곳에서 실행되는 경우 Gateway가 브라우저 액션을 프록시할 수 있도록 브라우저 머신에서 노드 호스트를 실행하십시오.

샌드박스 세션

에이전트 세션이 샌드박스되어 있으면 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
  • 에이전트 도구: profile="chrome"과 함께 browser

선택 사항: 다른 이름이나 릴레이 포트를 원하는 경우 자체 프로필을 만드십시오:

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

참고:

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

격리 보장

  • 전용 사용자 데이터 디렉토리: 개인 브라우저 프로필을 절대 건드리지 않습니다.
  • 전용 포트: 개발 워크플로와의 충돌을 피하기 위해 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(선택 사항)

로컬 통합만을 위해 Gateway는 작은 루프백 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>을 허용합니다.

Playwright 요구 사항

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

Playwright is not available in this gateway build 오류가 표시되면 전체 Playwright 패키지(playwright-core가 아님)를 설치하고 게이트웨이를 다시 시작하거나 브라우저 지원과 함께 OpenClaw를 다시 설치하십시오.

작동 방식(내부)

높은 수준의 플로우:

  • 작은 제어 서버가 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 /tmp/report.pdf
  • openclaw browser waitfordownload /tmp/report.pdf
  • openclaw browser upload /tmp/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 --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는 아밍 호출입니다. 선택기/대화상자를 트리거하는 클릭/프레스 전에 실행하십시오.
  • upload는 --input-ref 또는 --element를 통해 파일 입력을 직접 설정할 수도 있습니다.
  • snapshot:
    • --format ai(Playwright가 설치된 경우 기본값): 숫자 ref가 있는 AI 스냅샷을 반환합니다(aria-ref="<n>").
    • --format aria: 접근성 트리를 반환합니다(ref 없음, 검사 전용).
    • --efficient(또는 --mode efficient): 컴팩트 role 스냅샷 프리셋(interactive + compact + depth + 낮은 maxChars).
    • 구성 기본값(도구/CLI만): 호출자가 모드를 전달하지 않을 때 효율적인 스냅샷을 사용하려면 browser.snapshotDefaults.mode: "efficient"를 설정하십시오(Gateway 구성 참조).
    • 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

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

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

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

  • Role 스냅샷(role ref e12 등): 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 동작:

  • Ref는 탐색 간에 안정적이지 않습니다. 무언가 실패하면 snapshot을 다시 실행하고 새로운 ref를 사용하십시오.
  • role 스냅샷이 --frame과 함께 촬영된 경우 role ref는 다음 role 스냅샷까지 해당 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> 사용(interactive 모드에서는 role 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의 role 스냅샷에는 refs와 작은 stats 블록(lines/chars/refs/interactive)이 포함되어 도구가 페이로드 크기와 밀도를 추론할 수 있습니다.

상태 및 환경 노브

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

  • 쿠키: cookies, cookies set, cookies clear
  • 스토리지: storage local|session get|set|clear
  • 오프라인: set offline on|off
  • 헤더: set headers --json '{"X-Debug":"1"}'(또는 --clear)
  • 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 등)은 Browser login + X/Twitter posting을 참조하십시오.
  • Gateway/노드 호스트를 비공개로 유지하십시오(루프백 또는 테일넷 전용).
  • 원격 CDP 엔드포인트는 강력합니다. 터널을 통해 보호하십시오.

문제 해결

Linux 관련 문제(특히 snap Chromium)는 Browser troubleshooting을 참조하십시오.

에이전트 도구 + 제어 작동 방식

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

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

매핑 방식:

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

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

← 문서로 돌아가기