브라우저(OpenClaw 관리)

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

제공되는 기능

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

​

Plugin 제어

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

​

에이전트 가이드

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

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

​

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

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

​

프로필: openclaw와 user

• openclaw: 관리되는 격리 브라우저(확장 프로그램 필요 없음).
• user: 실제 로그인된 Chrome 세션을 위한 기본 제공 Chrome MCP 연결 프로필.

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

​

설정

{
  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 기반 브라우저 사용

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",
  },
}

​

로컬 제어와 원격 제어

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

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

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

​

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

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

​

같은 호스트의 Browserless Docker

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

​

직접 WebSocket CDP 제공자

• HTTP(S) 발견 - http://host[:port] 또는 https://host[:port]. OpenClaw는 /json/version을 호출해 WebSocket 디버거 URL을 발견한 다음 연결합니다. 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

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

• 가입하고 개요 대시보드에서 API Key를 복사하세요.
• <BROWSERBASE_API_KEY>를 실제 Browserbase API 키로 바꾸세요.
• Browserbase는 WebSocket 연결 시 브라우저 세션을 자동 생성하므로 수동 세션 생성 단계가 필요하지 않습니다.
• 무료 티어는 동시 세션 1개와 월 브라우저 1시간을 허용합니다. 유료 플랜 한도는 가격을 참조하세요.
• 전체 API 참조, SDK 가이드, 통합 예시는 Browserbase 문서를 참조하세요.

​

보안

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

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

​

프로필(다중 브라우저)

• 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에서 할당됩니다.
• 프로필을 삭제하면 해당 로컬 데이터 디렉터리가 휴지통으로 이동합니다.

​

Chrome DevTools MCP를 통한 기존 세션

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

• user

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

{
  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

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이 로컬에 설치되어 있는지 확인하지만, 브라우저 측 원격 디버깅을 대신 활성화할 수는 없습니다

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

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

​

사용자 지정 Chrome MCP 실행

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

​

격리 보장

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

​

브라우저 선택

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

• macOS: /Applications와 ~/Applications를 확인합니다.
• Linux: /usr/bin, /snap/bin, /opt/google, /opt/brave.com, /usr/lib/chromium, /usr/lib/chromium-browser 아래의 일반적인 Chrome/Brave/Edge/Chromium 위치와 PLAYWRIGHT_BROWSERS_PATH 또는 ~/.cache/ms-playwright 아래의 Playwright 관리 Chromium을 확인합니다.
• Windows: 일반적인 설치 위치를 확인합니다.

​

제어 API(선택 사항)

​

문제 해결

​

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 차단:
  • start와 tabs는 여전히 작동하지만, open, navigate, 스냅샷 또는 탭 열기 흐름이 브라우저/네트워크 정책 오류로 실패합니다

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 정책 객체를 사용합니다.
• 로컬 loopback openclaw 관리형 프로필의 경우, CDP 상태 확인은 OpenClaw 자체 로컬 제어 플레인에 대해 의도적으로 브라우저 SSRF 도달성 적용을 건너뜁니다.
• 탐색 보호는 별개입니다. 성공적인 start 또는 tabs 결과가 이후 open 또는 navigate 대상이 허용된다는 의미는 아닙니다.

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

​

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

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

• browser snapshot은 안정적인 UI 트리(AI 또는 ARIA)를 반환합니다.
• browser act는 스냅샷 ref ID를 사용해 클릭/입력/드래그/선택을 수행합니다.
• browser screenshot은 픽셀을 캡처합니다(전체 페이지, 요소 또는 레이블이 지정된 ref).
• 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"를 고정하지 않는 한 도구가 해당 노드로 자동 라우팅할 수 있습니다.

​

관련 항목

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