브라우저 (OpenClaw 관리형)

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

초보자 관점:

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

# 제공되는 기능

• 기본적으로 주황색 강조 색상을 사용하는 openclaw라는 별도 브라우저 프로필.
• 결정적 탭 제어(목록/열기/포커스/닫기).
• 에이전트 작업(클릭/입력/드래그/선택), 스냅샷, 스크린샷, PDF.
• 브라우저 Plugin이 활성화되어 있을 때 에이전트에게 스냅샷, 안정적인 탭, 오래된 참조, 수동 차단 요소 복구 루프를 알려 주는 번들 browser-automation Skills.
• 선택적 다중 프로필 지원(openclaw, work, remote, ...).

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

# 빠른 시작

openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
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"가 표시되면 config에서 활성화하고(아래 참조) Gateway를 다시 시작하세요.

openclaw browser가 아예 없거나 에이전트가 브라우저 도구를 사용할 수 없다고 하면 누락된 브라우저 명령 또는 도구로 이동하세요.

# Plugin 제어

기본 browser 도구는 번들 Plugin입니다. 같은 browser 도구 이름을 등록하는 다른 Plugin으로 교체하려면 비활성화하세요.

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

기본값에는 plugins.entries.browser.enabled 및 browser.enabled=true가 모두 필요합니다. Plugin만 비활성화하면 openclaw browser CLI, browser.request Gateway 메서드, 에이전트 도구, 제어 서비스가 하나의 단위로 제거됩니다. browser.* config는 대체 항목을 위해 그대로 유지됩니다.

브라우저 config 변경 사항은 Plugin이 서비스를 다시 등록할 수 있도록 Gateway 재시작이 필요합니다.

# 에이전트 지침

도구 프로필 참고: tools.profile: "coding"에는 web_search와 web_fetch가 포함되지만 전체 browser 도구는 포함되지 않습니다. 에이전트 또는 생성된 하위 에이전트가 브라우저 자동화를 사용해야 한다면 프로필 단계에서 browser를 추가하세요.

{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

단일 에이전트에는 agents.list[].tools.alsoAllow: ["browser"]를 사용하세요. tools.subagents.tools.allow: ["browser"]만으로는 충분하지 않습니다. 하위 에이전트 정책은 프로필 필터링 이후에 적용되기 때문입니다.

브라우저 Plugin은 두 수준의 에이전트 지침을 제공합니다.

• browser 도구 설명에는 항상 적용되는 간결한 계약이 포함됩니다. 올바른 프로필을 선택하고, 참조를 같은 탭에 유지하며, 탭 대상을 지정할 때 tabId/레이블을 사용하고, 다단계 작업에는 브라우저 Skills를 로드합니다.
• 번들 browser-automation Skills에는 더 긴 작업 루프가 포함됩니다. 먼저 상태/탭을 확인하고, 작업 탭에 레이블을 지정하고, 작업 전 스냅샷을 찍고, UI 변경 후 다시 스냅샷을 찍고, 오래된 참조는 한 번 복구하며, 로그인/2FA/captcha 또는 카메라/마이크 차단 요소는 추측하지 말고 수동 조치로 보고합니다.

Plugin 번들 Skills는 Plugin이 활성화되면 에이전트의 사용 가능한 Skills에 나열됩니다. 전체 Skills 지침은 필요할 때 로드되므로 일반적인 턴에서는 전체 토큰 비용이 들지 않습니다.

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

업그레이드 후 openclaw browser를 알 수 없거나, browser.request가 없거나, 에이전트가 브라우저 도구를 사용할 수 없다고 보고한다면 일반적인 원인은 browser를 생략한 plugins.allow 목록이 있고 루트 browser config 블록이 없기 때문입니다. 다음을 추가하세요.

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

예를 들어 browser.enabled=true 또는 browser.profiles.<name> 같은 명시적 루트 browser 블록은 제한적인 plugins.allow 아래에서도 번들 브라우저 Plugin을 활성화하며, 이는 채널 config 동작과 일치합니다. plugins.entries.browser.enabled=true와 tools.alsoAllow: ["browser"]는 그 자체로 allowlist 멤버십을 대체하지 않습니다. plugins.allow를 완전히 제거해도 기본값이 복원됩니다.

# 프로필: openclaw vs user

• 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)
    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)
    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)
    actionTimeoutMs: 60000, // default browser act timeout (ms)
    tabCleanup: {
      enabled: true, // default: true
      idleMinutes: 120, // set 0 to disable idle cleanup
      maxTabsPerSession: 8, // set 0 to disable the per-session cap
      sweepMinutes: 5,
    },
    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",
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      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" },
    },
  },
}

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

시스템 기본 브라우저가 Chromium 기반(Chrome/Brave/Edge 등)이면 OpenClaw가 자동으로 사용합니다. 자동 감지를 재정의하려면 browser.executablePath를 설정하세요. 최상위 및 프로필별 executablePath 값은 OS 홈 디렉터리에 대해 ~를 허용합니다.

openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

또는 플랫폼별로 구성에서 설정하세요.

{
browser: {
executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
},
}

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

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

프로필별 executablePath는 OpenClaw가 실행하는 로컬 관리형 프로필에만 영향을 줍니다. existing-session 프로필은 대신 이미 실행 중인 브라우저에 연결하고, 원격 CDP 프로필은 cdpUrl 뒤의 브라우저를 사용합니다.

# 로컬 제어와 원격 제어

• 로컬 제어(기본값): Gateway가 loopback 제어 서비스를 시작하고 로컬 브라우저를 실행할 수 있습니다.
• 원격 제어(Node 호스트): 브라우저가 있는 머신에서 Node 호스트를 실행합니다. Gateway가 브라우저 작업을 그곳으로 프록시합니다.
• 원격 CDP: 원격 Chromium 기반 브라우저에 연결하려면 browser.profiles.<name>.cdpUrl(또는 browser.cdpUrl)을 설정합니다. 이 경우 OpenClaw는 로컬 브라우저를 실행하지 않습니다.
• loopback에서 외부 관리형 CDP 서비스(예: Docker에서 127.0.0.1로 게시된 Browserless)를 사용하는 경우 attachOnly: true도 설정하세요. attachOnly가 없는 loopback CDP는 로컬 OpenClaw 관리형 브라우저 프로필로 처리됩니다.
• headless는 OpenClaw가 실행하는 로컬 관리형 프로필에만 영향을 줍니다. 기존 세션 또는 원격 CDP 브라우저를 다시 시작하거나 변경하지 않습니다.
• executablePath도 같은 로컬 관리형 프로필 규칙을 따릅니다. 실행 중인 로컬 관리형 프로필에서 이를 변경하면 해당 프로필이 재시작/조정을 위해 표시되어 다음 실행에서 새 바이너리를 사용합니다.

중지 동작은 프로필 모드에 따라 다릅니다.

• 로컬 관리형 프로필: openclaw browser stop은 OpenClaw가 실행한 브라우저 프로세스를 중지합니다.
• 연결 전용 및 원격 CDP 프로필: openclaw browser stop은 활성 제어 세션을 닫고 Playwright/CDP 에뮬레이션 재정의(뷰포트, 색 구성표, 로캘, 시간대, 오프라인 모드 및 유사한 상태)를 해제합니다. OpenClaw가 브라우저 프로세스를 실행하지 않았더라도 그렇습니다.

원격 CDP URL에는 인증을 포함할 수 있습니다.

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

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

# Node 브라우저 프록시(무구성 기본값)

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

참고:

• Node 호스트는 프록시 명령을 통해 로컬 브라우저 제어 서버를 노출합니다.
• 프로필은 Node 자체의 browser.profiles 구성에서 가져옵니다(로컬과 동일).
• nodeHost.browserProxy.allowProfiles는 선택 사항입니다. 레거시/기본 동작을 원하면 비워 두세요. 프로필 생성/삭제 라우트를 포함해 구성된 모든 프로필이 프록시를 통해 계속 접근 가능합니다.
• nodeHost.browserProxy.allowProfiles를 설정하면 OpenClaw는 이를 최소 권한 경계로 처리합니다. 허용 목록에 있는 프로필만 대상으로 지정할 수 있고, 영구 프로필 생성/삭제 라우트는 프록시 표면에서 차단됩니다.
• 원하지 않으면 비활성화하세요.
  • Node에서: 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을 검색하도록 둘 수 있습니다.

# 같은 호스트의 Browserless Docker

Browserless가 Docker에서 자체 호스팅되고 OpenClaw가 호스트에서 실행되는 경우, Browserless를 외부 관리형 CDP 서비스로 처리하세요.

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

browser.profiles.browserless.cdpUrl의 주소는 OpenClaw 프로세스에서 도달 가능해야 합니다. Browserless도 일치하는 도달 가능한 엔드포인트를 광고해야 합니다. Browserless EXTERNAL을 ws://127.0.0.1:3000, ws://browserless:3000 또는 안정적인 비공개 Docker 네트워크 주소와 같이 동일한 public-to-OpenClaw WebSocket 기반으로 설정하세요. /json/version이 OpenClaw가 도달할 수 없는 주소를 가리키는 webSocketDebuggerUrl을 반환하면, CDP HTTP는 정상으로 보일 수 있지만 WebSocket 연결은 여전히 실패합니다.

loopback Browserless 프로필에는 attachOnly를 설정하지 않은 상태로 두지 마세요. attachOnly가 없으면 OpenClaw는 loopback 포트를 로컬 관리형 브라우저 프로필로 처리하고, 포트가 사용 중이지만 OpenClaw 소유가 아니라고 보고할 수 있습니다.

# 직접 WebSocket CDP 제공자

일부 호스팅 브라우저 서비스는 표준 HTTP 기반 CDP 검색(/json/version) 대신 직접 WebSocket 엔드포인트를 노출합니다. OpenClaw는 세 가지 CDP URL 형태를 허용하고 올바른 연결 전략을 자동으로 선택합니다.

• HTTP(S) 검색 - http://host[:port] 또는 https://host[:port]. OpenClaw는 WebSocket 디버거 URL을 검색하기 위해 /json/version을 호출한 다음 연결합니다. WebSocket 폴백은 없습니다.
• 직접 WebSocket 엔드포인트 - ws://host[:port]/devtools/<kind>/<id> 또는 /devtools/browser|page|worker|shared_worker|service_worker/<id> 경로가 있는 wss://.... OpenClaw는 WebSocket 핸드셰이크를 통해 직접 연결하고 /json/version을 완전히 건너뜁니다.
• 기본 WebSocket 루트 - /devtools/... 경로가 없는 ws://host[:port] 또는 wss://host[:port](예: Browserless, Browserbase). OpenClaw는 먼저 HTTP /json/version 검색을 시도합니다(스킴을 http/https로 정규화). 검색이 webSocketDebuggerUrl을 반환하면 이를 사용하고, 그렇지 않으면 OpenClaw는 기본 루트에서 직접 WebSocket 핸드셰이크로 폴백합니다. 광고된 WebSocket 엔드포인트가 CDP 핸드셰이크를 거부하지만 구성된 기본 루트가 이를 허용하면 OpenClaw는 그 루트로도 폴백합니다. 이를 통해 로컬 Chrome을 가리키는 기본 ws://도 여전히 연결할 수 있습니다. Chrome은 /json/version에서 가져온 특정 대상별 경로에서만 WebSocket 업그레이드를 허용하는 반면, 호스팅 제공자는 검색 엔드포인트가 Playwright CDP에 적합하지 않은 단기 URL을 광고할 때도 루트 WebSocket 엔드포인트를 계속 사용할 수 있기 때문입니다.

# 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 문서를 참고하세요.

# 보안

핵심 개념:

• 브라우저 제어는 loopback 전용입니다. 접근 흐름은 Gateway 인증 또는 노드 페어링을 통해 이루어집니다.
• 독립 실행형 loopback 브라우저 HTTP API는 공유 비밀 인증만 사용합니다: gateway 토큰 bearer 인증, x-openclaw-password, 또는 구성된 gateway 비밀번호를 사용하는 HTTP Basic 인증입니다.
• Tailscale Serve ID 헤더와 gateway.auth.mode: "trusted-proxy"는 이 독립 실행형 loopback 브라우저 API를 인증하지 않습니다.
• 브라우저 제어가 활성화되어 있고 공유 비밀 인증이 구성되어 있지 않으면, OpenClaw는 해당 시작에만 사용되는 런타임 전용 gateway 토큰을 생성합니다. 재시작 후에도 클라이언트에 안정적인 비밀이 필요하면 gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN, 또는 OPENCLAW_GATEWAY_PASSWORD를 명시적으로 구성하세요.
• gateway.auth.mode가 이미 password, none, 또는 trusted-proxy인 경우 OpenClaw는 해당 토큰을 자동 생성하지 않습니다.
• Gateway와 모든 노드 호스트를 사설 네트워크(Tailscale)에 유지하고, 공개 노출을 피하세요.
• 원격 CDP URL/토큰은 비밀로 취급하세요. env vars 또는 secrets manager를 선호하세요.

원격 CDP 팁:

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

# 프로필(다중 브라우저)

OpenClaw는 여러 이름 지정 프로필(라우팅 구성)을 지원합니다. 프로필은 다음일 수 있습니다:

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

기본값:

• openclaw 프로필이 없으면 자동 생성됩니다.
• user 프로필은 Chrome MCP existing-session 연결용으로 기본 제공됩니다.
• existing-session 프로필은 user 외에는 옵트인입니다. --driver existing-session으로 생성하세요.
• local CDP 포트는 기본적으로 18800-18899에서 할당됩니다.
• 프로필을 삭제하면 해당 로컬 데이터 디렉터리가 휴지통으로 이동합니다.

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

# Chrome DevTools MCP를 통한 기존 세션

OpenClaw는 공식 Chrome DevTools MCP 서버를 통해 실행 중인 Chromium 기반 브라우저 프로필에 연결할 수도 있습니다. 이렇게 하면 해당 브라우저 프로필에 이미 열려 있는 탭과 로그인 상태를 재사용합니다.

공식 배경 및 설정 참고 자료:

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

기본 제공 프로필:

• user

선택 사항: 다른 이름, 색상, 또는 브라우저 데이터 디렉터리를 원하면 직접 사용자 지정 existing-session 프로필을 생성하세요.

기본 동작:

• 기본 제공 user 프로필은 기본 local Google Chrome 프로필을 대상으로 하는 Chrome MCP 자동 연결을 사용합니다.

Brave, Edge, Chromium, 또는 기본값이 아닌 Chrome 프로필에는 userDataDir을 사용하세요. ~는 OS 홈 디렉터리로 확장됩니다:

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

그런 다음 일치하는 브라우저에서:

1. 원격 디버깅용 해당 브라우저의 검사 페이지를 엽니다.
2. 원격 디버깅을 활성화합니다.
3. 브라우저를 계속 실행한 상태로 두고 OpenClaw가 연결할 때 연결 프롬프트를 승인합니다.

일반적인 검사 페이지:

• 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+입니다
• 해당 브라우저의 검사 페이지에서 원격 디버깅이 활성화되어 있습니다
• 브라우저가 연결 동의 프롬프트를 표시했고 사용자가 승인했습니다
• openclaw doctor는 이전 확장 기반 브라우저 구성을 마이그레이션하고 기본 자동 연결 프로필에 대해 Chrome이 로컬에 설치되어 있는지 확인하지만, 사용자를 대신해 브라우저 측 원격 디버깅을 활성화할 수는 없습니다

Agent 사용:

• 사용자의 로그인된 브라우저 상태가 필요하면 profile="user"를 사용하세요.
• 사용자 지정 existing-session 프로필을 사용하는 경우 해당 명시적 프로필 이름을 전달하세요.
• 사용자가 컴퓨터 앞에서 연결 프롬프트를 승인할 수 있을 때만 이 모드를 선택하세요.
• Gateway 또는 노드 호스트는 npx chrome-devtools-mcp@latest --autoConnect를 생성할 수 있습니다

참고:

• 이 경로는 로그인된 브라우저 세션 안에서 동작할 수 있으므로 격리된 openclaw 프로필보다 위험도가 높습니다.
• OpenClaw는 이 드라이버에 대해 브라우저를 실행하지 않고 연결만 합니다.
• OpenClaw는 여기서 공식 Chrome DevTools MCP --autoConnect 흐름을 사용합니다. userDataDir이 설정되어 있으면 해당 사용자 데이터 디렉터리를 대상으로 하도록 그대로 전달됩니다.
• existing-session은 선택된 호스트 또는 연결된 브라우저 노드를 통해 연결할 수 있습니다. Chrome이 다른 곳에 있고 연결된 브라우저 노드가 없으면 대신 원격 CDP 또는 노드 호스트를 사용하세요.

# 사용자 지정 Chrome MCP 실행

기본 npx chrome-devtools-mcp@latest 흐름이 원하는 동작이 아닐 때(오프라인 호스트, 고정 버전, vendored binaries), 프로필별로 생성되는 Chrome DevTools MCP 서버를 재정의하세요:

existing-session 프로필에 cdpUrl이 설정되면 OpenClaw는 --autoConnect를 건너뛰고 엔드포인트를 Chrome MCP로 자동 전달합니다:

• http(s)://... → --browserUrl <url>(DevTools HTTP discovery 엔드포인트).
• ws(s)://... → --wsEndpoint <url>(직접 CDP WebSocket).

엔드포인트 플래그와 userDataDir은 함께 사용할 수 없습니다. cdpUrl이 설정되면 Chrome MCP가 프로필 디렉터리를 여는 대신 엔드포인트 뒤의 실행 중인 브라우저에 연결하므로, Chrome MCP 실행에서 userDataDir은 무시됩니다.

# 격리 보장

• 전용 사용자 데이터 디렉터리: 개인 브라우저 프로필을 절대 건드리지 않습니다.
• 전용 포트: 개발 워크플로와의 충돌을 방지하기 위해 9222를 피합니다.
• 결정적 탭 제어: tabs는 먼저 suggestedTargetId를 반환한 다음 t1 같은 안정적인 tabId 핸들, 선택적 레이블, 원시 targetId를 반환합니다. Agents는 suggestedTargetId를 재사용해야 합니다. 원시 ID는 디버깅 및 호환성을 위해 계속 사용할 수 있습니다.

# 브라우저 선택

로컬에서 실행할 때 OpenClaw는 사용 가능한 첫 번째 항목을 선택합니다:

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

browser.executablePath로 재정의할 수 있습니다.

플랫폼:

• macOS: /Applications 및 ~/Applications를 확인합니다.
• Linux: /usr/bin, /snap/bin, /opt/google, /opt/brave.com, /usr/lib/chromium, 및 /usr/lib/chromium-browser 아래의 일반적인 Chrome/Brave/Edge/Chromium 위치를 확인합니다.
• Windows: 일반적인 설치 위치를 확인합니다.

# 제어 API(선택 사항)

스크립팅 및 디버깅을 위해 Gateway는 작은 loopback 전용 HTTP 제어 API와 이에 맞는 openclaw browser CLI(snapshots, refs, wait power-ups, JSON output, debug workflows)를 제공합니다. 전체 참고 문서는 브라우저 제어 API를 참조하세요.

# 문제 해결

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

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

# CDP 시작 실패와 탐색 SSRF 차단

이 둘은 서로 다른 실패 유형이며 서로 다른 코드 경로를 가리킵니다.

• CDP 시작 또는 준비 상태 실패는 OpenClaw가 브라우저 제어 평면이 정상인지 확인할 수 없음을 의미합니다.
• 탐색 SSRF 차단은 브라우저 제어 평면은 정상이지만 페이지 탐색 대상이 정책에 의해 거부되었음을 의미합니다.

일반적인 예:

• CDP 시작 또는 준비 상태 실패:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
  • loopback 외부 CDP 서비스가 attachOnly: true 없이 구성되어 있을 때 Port <port> is in use for profile "<name>" but not by openclaw
• 탐색 SSRF 차단:
  • open, navigate, snapshot, 또는 탭 열기 흐름이 브라우저/네트워크 정책 오류로 실패하지만 start와 tabs는 계속 작동합니다

둘을 구분하려면 다음 최소 시퀀스를 사용하세요:

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

결과 해석 방법:

• start가 not reachable after start로 실패하면 먼저 CDP 준비 상태를 문제 해결하세요.
• start는 성공하지만 tabs가 실패하면 제어 평면이 여전히 비정상입니다. 이를 페이지 탐색 문제가 아니라 CDP 도달 가능성 문제로 취급하세요.
• start와 tabs는 성공하지만 open 또는 navigate가 실패하면 브라우저 제어 평면은 올라와 있고 실패는 탐색 정책 또는 대상 페이지에 있습니다.
• start, tabs, open이 모두 성공하면 기본 관리형 브라우저 제어 경로가 정상입니다.

중요한 동작 세부 사항:

• browser.ssrfPolicy를 구성하지 않아도 브라우저 구성은 기본적으로 fail-closed SSRF 정책 객체를 사용합니다.
• local loopback openclaw 관리형 프로필의 경우, CDP 상태 확인은 OpenClaw 자체 local 제어 평면에 대해 브라우저 SSRF 도달 가능성 강제를 의도적으로 건너뜁니다.
• 탐색 보호는 별개입니다. start 또는 tabs 결과가 성공했다고 해서 이후의 open 또는 navigate 대상이 허용된다는 뜻은 아닙니다.

보안 지침:

• 기본적으로 브라우저 SSRF 정책을 완화하지 마세요.
• 광범위한 사설 네트워크 접근보다 hostnameAllowlist 또는 allowedHostnames 같은 좁은 호스트 예외를 선호하세요.
• dangerouslyAllowPrivateNetwork: true는 사설 네트워크 브라우저 접근이 필요하고 검토된 의도적으로 신뢰된 환경에서만 사용하세요.

# Agent 도구 + 제어 작동 방식

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

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

매핑 방식:

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

이를 통해 에이전트를 결정론적으로 유지하고 깨지기 쉬운 선택자를 피할 수 있습니다.

# 관련 항목

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