OpenClaw 관리형 브라우저 설정: 1분 만에 격리 환경 구축

브라우저 (openclaw 관리형)

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

초보자를 위한 설명:

에이전트 전용 브라우저라고 생각하시면 돼요.
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

만약 “Browser disabled”라는 메시지가 나오면, 아래 내용을 참고해 설정에서 활성화한 뒤 Gateway를 재시작해 주세요.

openclaw browser 명령어 자체가 없거나 에이전트가 브라우저 툴을 사용할 수 없다고 한다면, 브라우저 명령어 또는 툴이 없는 경우 섹션으로 이동하세요.

플러그인 제어

기본 browser 툴은 이제 기본적으로 활성화되어 제공되는 번들 플러그인이에요. 즉, OpenClaw의 나머지 플러그인 시스템을 제거하지 않고도 이 툴만 비활성화하거나 교체할 수 있어요.

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

동일한 browser 툴 이름을 제공하는 다른 플러그인을 설치하기 전에는 번들 플러그인을 비활성화해야 합니다. 기본 브라우저 환경을 사용하려면 다음 두 가지 조건이 모두 충족되어야 해요.

plugins.entries.browser.enabled가 비활성화되지 않음
browser.enabled=true

플러그인만 끄면 번들 브라우저 CLI(openclaw browser), Gateway 메서드(browser.request), 에이전트 툴, 그리고 기본 브라우저 제어 서비스가 모두 함께 사라집니다. 하지만 browser.* 설정은 그대로 유지되므로 교체용 플러그인에서 재사용할 수 있어요.

번들 브라우저 플러그인은 이제 브라우저 런타임 구현도 직접 담당합니다. Core는 공유 Plugin SDK 헬퍼와 이전 내부 임포트 경로에 대한 호환성용 re-exports만 유지해요. 실제로 브라우저 플러그인 패키지를 제거하거나 교체하면, Core에 런타임이 남지 않고 브라우저 기능 세트가 완전히 제거됩니다.

브라우저 설정을 변경한 후에는 Gateway를 재시작해야 해요. 그래야 번들 플러그인이 새로운 설정으로 브라우저 서비스를 다시 등록할 수 있습니다.

브라우저 명령어 또는 툴이 없는 경우

업그레이드 후 갑자기 openclaw browser가 알 수 없는 명령어가 되거나, 에이전트가 브라우저 툴이 누락되었다고 보고한다면, 가장 흔한 원인은 plugins.allow 리스트에 browser가 포함되지 않았기 때문이에요.

잘못된 설정 예시:

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

플러그인 허용 리스트에 browser를 추가하여 해결할 수 있습니다.

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

중요 참고 사항:

plugins.allow가 설정되어 있을 때는 browser.enabled=true 설정만으로는 부족합니다.
plugins.entries.browser.enabled=true 역시 plugins.allow가 설정된 상태에서는 충분하지 않아요.
tools.alsoAllow: ["browser"]는 번들 브라우저 플러그인을 로드하지 않습니다. 이는 플러그인이 이미 로드된 후에 툴 정책만 조정할 뿐이에요.
제한적인 플러그인 허용 리스트가 필요하지 않다면, plugins.allow 설정을 제거하여 기본 번들 브라우저 동작을 복구할 수도 있습니다.

전형적인 증상:

openclaw browser 명령어나 browser.request 메서드가 누락됩니다.
에이전트가 브라우저 툴을 사용할 수 없거나 누락되었다고 보고합니다.

프로필: `openclaw` vs `user`

OpenClaw에는 두 가지 주요 프로필이 있어요.

openclaw: 별도의 확장이 필요 없는 관리형 격리 브라우저예요.
user: 여러분이 실제로 로그인해서 사용 중인 Chrome 세션에 연결하기 위한 내장 Chrome MCP 프로필이에요.

에이전트의 브라우저 도구 호출 시 가이드라인이에요:

기본적으로는 격리된 openclaw 브라우저를 사용하세요.
이미 로그인된 세션이 중요하고, 사용자가 직접 컴퓨터 앞에서 연결 승인 팝업을 클릭할 수 있는 상황이라면 profile="user"를 사용하는 게 좋아요.
특정 브라우저 모드를 강제로 지정하고 싶을 때는 profile 옵션을 명시적으로 사용하면 돼요.

관리형 모드를 기본으로 쓰고 싶다면 browser.defaultProfile: "openclaw"로 설정해 두세요.

설정

브라우저 설정은 ~/.openclaw/openclaw.json 파일에서 관리해요.

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (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)에서 파생된 포트의 loopback에 바인딩돼요.
Gateway 포트(gateway.port 또는 OPENCLAW_GATEWAY_PORT)를 변경하면, 브라우저 포트도 같은 “패밀리”를 유지하기 위해 자동으로 함께 이동해요.
cdpUrl을 설정하지 않으면 기본적으로 관리형 로컬 CDP 포트를 사용해요.
remoteCdpTimeoutMs는 원격(loopback이 아닌) CDP 연결 확인 시 적용돼요.
remoteCdpHandshakeTimeoutMs는 원격 CDP WebSocket 핸드셰이크 확인 시 적용돼요.
브라우저 탐색이나 탭 열기는 탐색 전 SSRF 가드로 보호되며, 탐색 후 최종 http(s) URL에서도 다시 한번 확인해요.
엄격한 SSRF 모드에서는 원격 CDP 엔드포인트 탐색이나 프로브(cdpUrl, /json/version 조회 포함)도 체크 대상이 돼요.
browser.ssrfPolicy.dangerouslyAllowPrivateNetwork는 기본적으로 비활성화되어 있어요. 신뢰할 수 있는 프라이빗 네트워크 브라우저 접근이 필요할 때만 true로 설정하세요.
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 기반 브라우저) 사용하기

시스템 기본 브라우저가 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가 loopback 제어 서비스를 시작하고 로컬 브라우저를 실행할 수 있어요.
원격 제어 (node host): 브라우저가 설치된 머신에서 node host를 실행하면, Gateway가 브라우저 동작을 해당 머신으로 프록시해 줘요.
원격 CDP: 원격 Chromium 기반 브라우저에 연결하려면 browser.profiles.<name>.cdpUrl(또는 browser.cdpUrl)을 설정하세요. 이 경우 OpenClaw는 로컬 브라우저를 실행하지 않아요.

중지 동작은 프로필 모드에 따라 달라요:

로컬 관리형 프로필: openclaw browser stop 명령어가 OpenClaw가 실행했던 브라우저 프로세스를 종료해요.
attach-only 및 원격 CDP 프로필: OpenClaw가 브라우저 프로세스를 직접 실행하지 않았더라도, openclaw browser stop을 실행하면 활성화된 제어 세션을 닫고 Playwright/CDP 에뮬레이션 오버라이드(viewport, color scheme, locale, timezone, offline mode 등)를 해제해요.

원격 CDP URL에는 인증 정보를 포함할 수 있어요:

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

OpenClaw는 /json/* 엔드포인트를 호출하거나 CDP WebSocket에 연결할 때 이 인증 정보를 그대로 유지해요. 토큰을 설정 파일에 직접 기록하기보다는 환경 변수나 시크릿 관리 도구를 사용하는 것을 추천해요.

Node 브라우저 프록시 (설정 불필요 기본값)

브라우저가 설치된 머신에서 node host를 실행하면, OpenClaw는 별도의 브라우저 설정 없이도 브라우저 도구 호출을 해당 노드로 자동 라우팅해 줘요. 이건 원격 Gateway의 기본 경로이기도 해요.

참고 사항:

Node host는 proxy command를 통해 로컬 브라우저 제어 서버를 노출해요.
Profile은 노드 자체의 browser.profiles 설정에서 가져와요 (로컬과 동일해요).
nodeHost.browserProxy.allowProfiles는 선택 사항이에요. 비워두면 기존 기본 동작대로 작동해요. 즉, 프로필 생성/삭제 경로를 포함해 설정된 모든 프로필에 프록시를 통해 접근할 수 있어요.
nodeHost.browserProxy.allowProfiles를 설정하면 OpenClaw는 이를 최소 권한 경계로 취급해요. 허용 목록(allowlist)에 있는 프로필만 대상으로 지정할 수 있고, 프록시 상에서 영구적인 프로필 생성/삭제 경로는 차단돼요.
기능을 끄고 싶다면 이렇게 하세요:
- 노드에서: nodeHost.browserProxy.enabled=false
- Gateway에서: gateway.nodes.browser.mode="off"

Browserless (호스팅된 원격 CDP)

Browserless는 HTTPS와 WebSocket을 통해 CDP 연결 URL을 노출하는 호스팅된 Chromium 서비스예요. OpenClaw는 두 형식 모두 사용할 수 있지만, 원격 브라우저 프로필의 경우 Browserless 연결 문서에 있는 직접 WebSocket URL을 사용하는 게 가장 간단해요.

예시:

{
  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 제공업체

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

HTTP(S) 엔드포인트 — OpenClaw가 /json/version을 호출해 WebSocket 디버거 URL을 찾은 다음 연결해요.
WebSocket 엔드포인트 (ws:// / wss://) — OpenClaw가 /json/version 단계를 건너뛰고 직접 연결해요. Browserless, Browserbase 또는 WebSocket URL을 제공하는 다른 업체를 사용할 때 이 방식을 쓰세요.

Browserbase

Browserbase는 CAPTCHA 해결, 스텔스 모드, 주거용 Proxy가 내장된 헤드리스 브라우저 실행용 클라우드 플랫폼이에요.

{
  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 문서를 참고해 주세요.

보안

핵심 개념:

브라우저 제어는 루프백(loopback) 전용이에요. 액세스는 Gateway의 인증이나 노드 페어링을 통해 흐르게 돼요.
독립형 루프백 브라우저 HTTP API는 공유 비밀(shared-secret) 인증만 사용해요: Gateway 토큰 Bearer 인증, x-openclaw-password, 또는 설정된 Gateway 비밀번호를 사용한 HTTP 기본 인증이 해당돼요.
Tailscale Serve ID 헤더와 gateway.auth.mode: "trusted-proxy"는 이 독립형 루프백 브라우저 API를 인증하지 않아요.
브라우저 제어가 활성화되어 있고 공유 비밀 인증이 설정되지 않은 경우, OpenClaw는 시작 시 gateway.auth.token을 자동으로 생성하고 설정에 저장해요.
gateway.auth.mode가 이미 password, none, 또는 trusted-proxy인 경우에는 토큰을 자동 생성하지 않아요.
Gateway와 모든 Node host는 프라이빗 네트워크(Tailscale)에 유지하고, 공용 노출은 피하세요.
원격 CDP URL/토큰은 비밀 정보로 취급하세요. 환경 변수나 비밀 관리자(secrets manager)를 사용하는 게 좋아요.

원격 CDP 팁:

가능한 경우 암호화된 엔드포인트(HTTPS 또는 WSS)와 수명이 짧은 토큰을 사용하세요.
설정 파일에 수명이 긴 토큰을 직접 포함하지 마세요.

프로필 (멀티 브라우저)

OpenClaw는 여러 개의 이름을 가진 프로필(라우팅 설정)을 지원해요. 프로필은 다음과 같은 유형으로 나뉩니다.

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

기본 설정은 다음과 같아요.

openclaw 프로필이 없으면 자동으로 생성돼요.
user 프로필은 Chrome MCP의 기존 세션 연결을 위해 내장되어 있어요.
기존 세션 프로필은 user 외에는 선택 사항이에요. --driver existing-session을 사용해 생성할 수 있어요.
로컬 CDP 포트는 기본적으로 18800–18899 사이에서 할당돼요.
프로필을 삭제하면 해당 로컬 데이터 디렉토리는 휴지통으로 이동해요.

모든 제어 엔드포인트는 ?profile=<name> 쿼리를 사용할 수 있고, CLI에서는 --browser-profile 옵션을 사용해요.

Chrome DevTools MCP를 통한 기존 세션 연결

OpenClaw는 공식 Chrome DevTools MCP 서버를 통해 실행 중인 Chromium 기반 브라우저 프로필에 연결할 수 있어요. 이 방식을 사용하면 브라우저 프로필에 이미 열려 있는 탭과 로그인 상태를 그대로 재사용할 수 있어 편리해요.

공식 배경 지식과 설정 참고 자료는 아래 링크를 확인해 보세요.

내장 프로필:

user

선택 사항: 다른 이름, 색상 또는 브라우저 데이터 디렉토리를 사용하고 싶다면 커스텀 기존 세션 프로필을 직접 만들 수도 있어요.

기본 동작:

내장된 user 프로필은 Chrome MCP 자동 연결을 사용하며, 기본 로컬 Google Chrome 프로필을 대상으로 해요.

Brave, Edge, Chromium 또는 기본값이 아닌 Chrome 프로필을 사용하려면 userDataDir을 설정하세요.

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

그 다음, 해당 브라우저에서 아래 단계를 수행하세요.

원격 디버깅을 위해 해당 브라우저의 inspect 페이지를 엽니다.
원격 디버깅(remote debugging)을 활성화합니다.
브라우저를 계속 실행해 두고, OpenClaw가 연결될 때 나타나는 연결 승인 프롬프트를 수락합니다.

주요 브라우저별 inspect 페이지 주소예요.

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

연결 상태를 확인하기 위한 스모크 테스트(smoke test) 명령어예요.

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이 선택된 활성 탭의 참조(refs)를 반환함

연결이 되지 않을 때 체크리스트예요.

대상 Chromium 기반 브라우저 버전이 144 이상인지 확인하세요.
브라우저의 inspect 페이지에서 원격 디버깅이 활성화되어 있는지 확인하세요.
브라우저에 표시된 연결 동의 프롬프트를 승인했는지 확인하세요.
openclaw doctor는 이전 확장 프로그램 기반의 브라우저 설정을 마이그레이션하고, 기본 자동 연결 프로필을 위해 Chrome이 로컬에 설치되어 있는지 확인해 줘요. 하지만 브라우저 측의 원격 디버깅을 대신 활성화해 줄 수는 없어요.

에이전트 사용 팁:

사용자의 로그인된 브라우저 상태가 필요할 때는 profile="user"를 사용하세요.
커스텀 기존 세션 프로필을 사용한다면 해당 프로필 이름을 명시적으로 전달하세요.
사용자가 컴퓨터 앞에 있어 연결 승인 프롬프트를 직접 누를 수 있을 때만 이 모드를 선택하세요.
Gateway 또는 Node 호스트는 npx chrome-devtools-mcp@latest --autoConnect를 실행할 수 있어요.

참고 사항:

이 경로는 격리된 openclaw 프로필보다 위험도가 높아요. 사용자가 로그인한 브라우저 세션 내부에서 동작할 수 있기 때문이죠.
OpenClaw는 이 드라이버를 위해 브라우저를 직접 실행하지 않아요. 오직 기존 세션에 연결만 합니다.
OpenClaw는 공식 Chrome DevTools MCP의 --autoConnect 흐름을 사용해요. userDataDir이 설정되면 OpenClaw는 해당 Chromium 사용자 데이터 디렉토리를 타겟팅하도록 값을 전달해요.
기존 세션의 스크린샷 기능은 페이지 캡처와 스냅샷의 --ref 엘리먼트 캡처를 지원하지만, CSS --element 선택자는 지원하지 않아요.
기존 세션 페이지 스크린샷은 Playwright 없이 Chrome MCP를 통해 작동해요. 참조 기반 엘리먼트 스크린샷(--ref)도 작동하지만, --full-page는 --ref나 --element와 함께 사용할 수 없어요.
기존 세션 액션은 관리형 브라우저(managed browser) 경로보다 여전히 제한적이에요.
- click, type, hover, scrollIntoView, drag, select는 CSS 선택자 대신 스냅샷 참조(refs)가 필요해요.
- click은 왼쪽 버튼만 가능해요. (버튼 오버라이드나 수정 키 미지원)
- type은 slowly=true를 지원하지 않아요. 대신 fill이나 press를 사용하세요.
- press는 delayMs를 지원하지 않아요.
- hover, scrollIntoView, drag, select, fill, evaluate는 호출당 타임아웃 오버라이드를 지원하지 않아요.
- select는 현재 단일 값만 지원해요.
기존 세션의 wait --url은 다른 브라우저 드라이버와 마찬가지로 일치, 부분 일치, glob 패턴을 지원해요. wait --load networkidle은 아직 지원되지 않아요.
기존 세션 업로드 훅은 ref 또는 inputRef가 필요하며, 한 번에 하나의 파일만 지원해요. CSS element 타겟팅은 지원하지 않아요.
기존 세션 대화상자(dialog) 훅은 타임아웃 오버라이드를 지원하지 않아요.
일괄 액션(batch actions), PDF 내보내기, 다운로드 가로채기, responsebody 등 일부 기능은 여전히 관리형 브라우저 경로가 필요해요.
기존 세션은 호스트 로컬 방식이에요. Chrome이 다른 머신이나 다른 네트워크 네임스페이스에 있다면 원격 CDP나 Node 호스트를 사용하세요.

격리 보장

전용 사용자 데이터 디렉토리: 여러분의 개인 브라우저 프로필은 절대 건드리지 않아요.
전용 포트: 개발 워크플로우와의 충돌을 피하기 위해 9222 포트를 사용하지 않아요.
결정론적 탭 제어: “마지막 탭”이 아닌 targetId를 통해 정확하게 탭을 타겟팅해요.

브라우저 선택

로컬에서 실행할 때 OpenClaw는 사용 가능한 브라우저를 다음 순서대로 선택해요.

Chrome
Brave
Edge
Chromium
Chrome Canary

browser.executablePath를 설정해 이 설정을 바꿀 수 있어요.

플랫폼별 확인 경로:

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

AI Setup Assistant

Control 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> 파라미터를 받을 수 있어요.

공유 비밀(shared-secret) Gateway 인증이 설정된 경우, 브라우저 HTTP 경로에도 인증이 필요해요:

Authorization: Bearer <gateway token>
x-openclaw-password: <gateway password> 또는 해당 패스워드를 사용한 HTTP Basic 인증

참고 사항:

이 독립형 루프백 브라우저 API는 trusted-proxy나 Tailscale Serve의 ID 헤더를 사용하지 않아요.
gateway.auth.mode가 none 또는 trusted-proxy인 경우에도, 이 루프백 브라우저 경로는 해당 인증 모드를 상속받지 않으니 루프백 전용으로 유지하세요.

`/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): existing-session 프로필에서 해당 액션이 지원되지 않아요.

기타 런타임 실패는 code 필드 없이 { "error": "<message>" }만 반환할 수 있어요.

Playwright 요구 사항

일부 기능(navigate, act, AI snapshot, role snapshot, element screenshots, PDF)은 Playwright가 필요해요. Playwright가 설치되어 있지 않으면 해당 엔드포인트는 명확한 501 에러를 반환해요.

Playwright 없이도 작동하는 기능:

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

여전히 Playwright가 필요한 기능:

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

요소 스크린샷은 --full-page 옵션을 거부하며, 이 경우 경로는 fullPage is not supported for element screenshots를 반환해요.

만약 Playwright is not available in this gateway build라는 메시지가 보인다면, 전체 Playwright 패키지(playwright-core 아님)를 설치하고 Gateway를 재시작하거나, 브라우저 지원이 포함된 OpenClaw를 다시 설치하세요.

Docker에서 Playwright 설치하기

Gateway를 Docker에서 실행 중이라면 npx playwright 사용은 피하세요(npm override 충돌이 발생할 수 있어요). 대신 번들로 제공되는 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 문서를 참고하세요.

작동 원리 (내부 구조)

상위 수준의 흐름은 다음과 같아요:

작은 control server가 HTTP 요청을 받아요.
CDP를 통해 Chromium 기반 브라우저(Chrome/Brave/Edge/Chromium)에 연결해요.
고급 액션(click, type, snapshot, 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

검사(Inspection):

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

수명 주기(Lifecycle) 참고 사항:

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

액션(Actions):

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

상태(State):

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 호출이에요. 파일 선택창이나 대화 상자를 트리거하는 클릭/누르기 동작을 수행하기 전에 먼저 실행해야 합니다.
Trace 및 다운로드 출력 경로는 OpenClaw 임시 루트로 제한돼요:
- traces: /tmp/openclaw (fallback: ${os.tmpdir()}/openclaw)
- downloads: /tmp/openclaw/downloads (fallback: ${os.tmpdir()}/openclaw/downloads)
업로드 경로는 OpenClaw 임시 업로드 루트로 제한돼요:
- uploads: /tmp/openclaw/uploads (fallback: ${os.tmpdir()}/openclaw/uploads)
upload는 --input-ref 또는 --element를 통해 파일 입력을 직접 설정할 수도 있어요.
snapshot:
- --format ai (Playwright가 설치된 경우 기본값): 숫자 ref(aria-ref="<n>"이 포함된 AI 스냅샷을 반환해요.
- --format aria: 접근성 트리를 반환해요 (ref가 없으며 검사용으로만 사용됩니다).
- --efficient (또는 --mode efficient): 효율적인 역할(role) 스냅샷 프리셋이에요 (interactive + compact + depth + 낮은 maxChars).
- 설정 기본값 (도구/CLI 전용): 호출자가 모드를 전달하지 않을 때 효율적인 스냅샷을 사용하려면 browser.snapshotDefaults.mode: "efficient"를 설정하세요 (Gateway 설정 참조).
- 역할 스냅샷 옵션(--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 selector는 액션에서 의도적으로 지원하지 않습니다.

스냅샷과 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와 같은 역할 ref): openclaw browser snapshot --interactive (또는 --compact, --depth, --selector, --frame)
- 출력: [ref=e12] (및 선택적으로 [nth=1])를 포함하는 역할 기반 리스트/트리.
- 액션: openclaw browser click e12, openclaw browser highlight e12.
- 내부적으로 ref는 getByRole(...) (중복 시 nth() 추가)을 통해 해결됩니다.
- --labels를 추가하면 e12 레이블이 오버레이된 뷰포트 스크린샷을 포함할 수 있어요.

Ref 동작 방식:

Ref는 페이지 이동(navigation) 시 유지되지 않아요. 동작이 실패하면 snapshot을 다시 실행하고 새로운 ref를 사용하세요.
--frame 옵션으로 역할 스냅샷을 찍은 경우, 다음 역할 스냅샷을 찍기 전까지 역할 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

디버그 워크플로우

액션이 실패하는 상황(예: “not visible”, “strict mode violation”, “covered”)이 발생하면 다음 단계를 따라보세요:

openclaw browser snapshot --interactive 실행
click <ref> / type <ref> 사용 (대화형 모드에서는 role ref를 사용하는 것을 추천해요)
여전히 실패한다면: openclaw browser highlight <ref> 명령어로 Playwright가 어떤 요소를 타겟팅하고 있는지 확인해 보세요.
페이지가 이상하게 동작한다면:
- openclaw browser errors --clear
- openclaw browser requests --filter api --clear
심층 디버깅이 필요할 때는 trace를 기록하세요:
- 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 snapshot에는 refs와 함께 작은 stats 블록(lines/chars/refs/interactive)이 포함되어 있어요. 덕분에 외부 툴에서 페이로드의 크기나 밀도를 쉽게 계산하고 판단할 수 있죠.

상태 및 환경 설정

사이트가 특정 상황처럼 동작하도록 만드는 “make the site behave like X” 워크플로우에서 유용하게 쓸 수 있는 설정들이에요.

Cookies: cookies, cookies set, cookies clear
Storage: storage local|session get|set|clear
Offline: set offline on|off
Headers: set headers --headers-json '{"X-Debug":"1"}' (기존에 사용하던 set headers --json '{"X-Debug":"1"}' 방식도 계속 지원해요)
HTTP basic auth: set credentials user pass (또는 --clear)
Geolocation: set geo <lat> <lon> --origin "https://example.com" (또는 --clear)
Media: set media dark|light|no-preference|none
Timezone / locale: set timezone ..., set locale ...
Device / viewport:
- set device "iPhone 14" (Playwright의 device presets를 사용해요)
- set viewport 1280 720

보안 및 개인정보 보호

openclaw 브라우저 프로필에는 로그인된 세션 정보가 포함될 수 있으니, 항상 민감한 데이터로 취급해야 해요.

browser act kind=evaluate / openclaw browser evaluate 명령과 wait --fn은 페이지 컨텍스트 내에서 임의의 JavaScript를 실행합니다. Prompt injection 공격으로 인해 실행 흐름이 조작될 수 있으니, 이 기능이 꼭 필요한 상황이 아니라면 browser.evaluateEnabled=false 설정을 통해 비활성화하는 것을 추천해요.

로그인이나 안티봇 관련 주의 사항(X/Twitter 등)은 Browser login + X/Twitter posting 문서를 참고해 보세요.

Gateway/node 호스트는 외부로 노출되지 않도록 loopback이나 tailnet 전용으로 설정해 비공개 상태를 유지해야 해요. 원격 CDP 엔드포인트는 매우 강력한 제어 권한을 가지므로, 반드시 터널링을 이용해 안전하게 보호하는 것이 중요합니다.

다음은 프라이빗/내부 목적지로의 접근을 기본적으로 차단하는 Strict-mode 설정 예시예요.

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

문제 해결

Linux 환경에서 발생하는 이슈(특히 snap Chromium 관련)는 Browser troubleshooting 문서에서 해결 방법을 찾아보세요.

WSL2 Gateway와 Windows Chrome을 함께 사용하는 분할 호스트 설정에 문제가 있다면 WSL2 + Windows + remote Chrome CDP troubleshooting 문서를 확인하면 도움이 될 거예요.

에이전트 도구와 제어 방식

에이전트는 브라우저 자동화를 위해 하나의 도구를 사용해요:

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

각 기능은 다음과 같이 매핑돼요:

browser snapshot은 안정적인 UI tree(AI 또는 ARIA)를 반환해요.
browser act는 snapshot의 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"로 고정하지 않는 한 도구가 해당 노드로 자동 라우팅될 수 있어요.

이 방식을 통해 에이전트는 결정론적으로 동작하며, 쉽게 깨지는 selector를 사용하지 않아도 돼요.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.

OpenClaw 관리형 브라우저 설정: 1분 만에 격리 환경 구축

브라우저 (openclaw 관리형)

제공되는 기능

빠른 시작

플러그인 제어

브라우저 명령어 또는 툴이 없는 경우

프로필: openclaw vs user

설정

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

로컬 vs 원격 제어

Node 브라우저 프록시 (설정 불필요 기본값)

Browserless (호스팅된 원격 CDP)

직접 WebSocket CDP 제공업체

Browserbase

보안

프로필 (멀티 브라우저)

Chrome DevTools MCP를 통한 기존 세션 연결

격리 보장

브라우저 선택

Control API (선택 사항)

/act 에러 규약

Playwright 요구 사항

Docker에서 Playwright 설치하기

작동 원리 (내부 구조)

CLI 빠른 참조

스냅샷과 ref

Wait 기능 강화하기

디버그 워크플로우

JSON 출력

상태 및 환경 설정

보안 및 개인정보 보호

문제 해결

에이전트 도구와 제어 방식

관련 문서

아직 막혀 있나요?

프로필: `openclaw` vs `user`

`/act` 에러 규약