OpenClaw는 Chrome DevTools Protocol(CDP)을 사용해 브라우저를 제어합니다. 이는 Chrome의 내장 개발자 도구를 구동하는 것과 동일한 저수준 통신 채널입니다. 2026년 3월 기준으로, GitHub 스타 68,000개 이상을 보유한 이 MIT 라이선스 플랫폼(버전 2026.2.6-3)은 세 가지 서로 다른 브라우저 제어 모드를 제공하며, 각각 다른 자동화 시나리오에 적합합니다. 로그인 세션 유지, 완전히 격리된 자동화 실행, 클라우드 파이프라인에 브라우저 제어 통합 등 어떤 것이 필요하든, 이러한 모드가 프로토콜 수준에서 어떻게 작동하는지 이해하면 이 도구를 더욱 효과적으로 활용할 수 있습니다.
핵심 요약
OpenClaw 브라우저 제어는 Chrome DevTools Protocol(CDP)을 기반으로 구축되어 있으며, HTTP 폴링이 아닌 지속적인 WebSocket 연결을 사용합니다. 세 가지 모드가 있습니다: Extension Relay(포트 18792)는 기존 Chrome 탭을 제어하고 로그인 상태를 유지하는 용도로, OpenClaw Managed(포트 18800~18899)는 안전한 자동화에 이상적인 격리된 Chromium 인스턴스용으로, Remote CDP는 클라우드 호스팅 브라우저 인프라 연결용으로 각각 사용됩니다. 스냅샷 시스템은 모든 인터랙티브 요소에 숫자 또는 역할 기반 참조(ref)를 할당합니다. 이러한 ref는 내비게이션 시 만료되므로 페이지 변경 후에는 반드시 다시 스냅샷을 찍어야 합니다. 2026년 기준으로 Playwright가 PDF 생성 및 AI 모드 스냅샷과 같은 고급 기능의 기반 엔진 역할을 합니다.
OpenClaw 브라우저 제어 작동 원리: CDP 기반
OpenClaw의 브라우저 제어 기능은 스크린샷이나 시각적 추론 위에 구축된 것이 아니라 프로토콜 수준에서 작동합니다. Chrome DevTools Protocol(CDP)은 실행 중인 Chrome(또는 모든 Chromium 기반) 브라우저에 직접 명령을 보낼 수 있는 양방향 WebSocket 연결을 제공합니다. 이는 요소를 검사하거나 네트워크 요청을 프로파일링할 때 Chrome의 자체 개발자 도구가 사용하는 것과 동일한 채널입니다.
여기서 아키텍처적 이점은 상당히 큽니다. 스크린샷을 찍고, 시각적으로 분석한 다음 마우스 클릭을 시뮬레이션하는 도구와 달리, OpenClaw는 브라우저의 렌더링 엔진과 실시간으로 통신합니다. browser click 12와 같은 명령을 발행하면, OpenClaw는 이를 적절한 CDP 작업으로 변환합니다. 즉, 인간 사용자가 DOM과 직접 상호작용한 것과 동일한 수준으로 브라우저가 명령을 받는다는 것입니다. 이 결정론적 접근 방식은 버튼이 약간 이동하거나 폰트 렌더링 차이로 인해 실패가 발생하는 시각적 자동화 도구의 불안정성을 제거합니다.
CDP는 Page, Network, DOM, Runtime, Input 등 여러 도메인에 걸쳐 약 300개의 명령을 노출합니다. 지속적인 WebSocket 연결은 실시간 이벤트 스트리밍을 가능하게 하므로, OpenClaw는 각 명령 후 변경 사항을 폴링하는 대신 네트워크 요청, 콘솔 로그, 내비게이션 이벤트를 비동기적으로 실시간 모니터링할 수 있습니다.
내부적으로 OpenClaw는 고급 기능을 위한 CDP 제어 엔진으로 Playwright를 사용합니다. Playwright는 aria-ref 시스템을 통한 요소 해석을 처리하고 브라우저 라이프사이클 이벤트를 관리합니다. Playwright 없이 기본 ARIA 기반 스냅샷을 사용하는 경우, OpenClaw는 더 가볍지만 복잡한 상호작용에는 덜 유능한 접근성 트리 접근 방식으로 폴백합니다. AI 모드 스냅샷, PDF 생성, 또는 요소 수준의 스크린샷이 필요한 경우 Playwright를 별도로 설치해야 합니다.
전체 통합을 이해하려면 컴포넌트 체인을 파악하면 도움이 됩니다. OpenClaw 게이트웨이(기본적으로 포트 18791)가 오케스트레이션 레이어 역할을 하며, HTTP 또는 CLI 인터페이스를 통해 에이전트 명령을 수신합니다. 컨트롤 서비스(게이트웨이 포트에서 오프셋)는 구성한 브라우저 모드에 대한 연결을 관리합니다. Extension Relay의 경우 Chrome 확장 프로그램이 포트 18792에 CDP 릴레이를 생성합니다. Managed 모드의 경우 OpenClaw가 자체 Chromium 인스턴스를 시작하고 관리합니다. 에이전트(GPT-4o, Claude, 또는 로컬 모델로 구동)는 게이트웨이에 명령을 보내며, 게이트웨이는 이를 브라우저에 대한 CDP 작업으로 변환합니다.
이를 기반으로 개발하는 개발자들에게 laozhang.ai는 Claude, GPT-4o 등의 모델에 대한 안정적인 접근을 제공하는 통합 API 게이트웨이로서, OpenClaw의 브라우저 자동화 워크플로의 AI 백본으로 활용할 수 있습니다. 문서는 docs.laozhang.ai에서 확인할 수 있습니다.
시작하기 전에, 브라우저 설정을 시도하기 전 OpenClaw 완전 설치 가이드에 따라 OpenClaw가 설치되어 있는지 확인하세요.
3가지 브라우저 제어 모드: 사용 사례에 맞는 모드 선택
OpenClaw의 세 가지 브라우저 제어 모드는 서로 교체 가능하지 않습니다. 각각이 특정 문제를 해결하기 위해 존재합니다. 잘못된 모드를 선택하면 불필요한 설정의 어려움, 보안 문제, 또는 자동화 실패로 이어집니다. 결정은 다섯 가지 질문으로 귀결됩니다: 기존 로그인된 세션에 접근해야 합니까? 개인 브라우저 데이터와 격리가 필요합니까? 브라우저가 로컬에서 실행되고 있습니까, 아니면 클라우드에서 실행되고 있습니까? 어느 수준의 설정 복잡성을 감수할 수 있습니까? 그리고 보안 격리가 얼마나 중요합니까?
Extension Relay 모드(포트 18792)는 작은 Chrome 확장 프로그램을 통해 OpenClaw를 기존 Chrome 브라우저에 연결합니다. 이 접근 방식은 에이전트에게 이미 인증된 탭을 포함한 모든 열린 탭에 완전한 접근 권한을 제공합니다. Gmail, Notion, 회사 인트라넷, 또는 로그인이 복잡하거나 SSO를 사용하는 사이트 내에서 작업을 자동화해야 하는 경우, Extension Relay가 올바른 선택입니다. 확장 프로그램은 OpenClaw의 컨트롤 서비스가 연결하는 로컬 CDP 릴레이를 생성하여 Chrome의 실제 실행 인스턴스에 명령을 전달합니다.
실제적인 의미로, Extension Relay는 Chrome 확장 프로그램을 설치하고 활성 탭과 연결해야 합니다. 에이전트는 탭을 나열하고, 특정 탭을 선택하여 쿠키와 인증된 상태를 포함한 제어를 인계받을 수 있습니다. 중요한 보안 주의사항으로, 자동화 작업에는 개인 브라우징 프로필이 아닌 전용 Chrome 프로필을 사용해야 합니다. 확장 프로그램은 설계상 해당 프로필의 모든 것에 접근할 수 있기 때문입니다.
OpenClaw Managed 모드(포트 1880018899)는 개인 브라우저와 분리된 전용의 격리된 Chromium 인스턴스를 시작하고 관리합니다. 공유 쿠키도, 공유 기록도, 개인 브라우징과 자동화 간의 교차 오염 위험도 없습니다. OpenClaw는 여러 관리 브라우저 프로필을 동시에 실행할 수 있으며, 각 프로필은 1880018899 범위 내의 다른 포트를 차지합니다. 이것은 웹 스크래핑, 테스팅, 배치 양식 처리를 포함한 대부분의 자동화 워크플로에 권장되는 모드입니다.
관리 브라우저는 서버 환경에 맞는 헤드리스 모드(비표시, UI 없음) 또는 디버깅용 헤드 모드(표시 창)로 실행할 수 있습니다. 위치 정보 스푸핑, 기기 에뮬레이션, 사용자 정의 HTTP 헤더, 오프라인 모드 시뮬레이션 등의 고급 기능은 구성 옵션을 통해 관리 모드에서 모두 사용 가능합니다. 이 구성에서 AI 모드 스냅샷을 사용하려면 Playwright를 설치해야 합니다.
Remote CDP 모드는 OpenClaw를 외부 Chromium 기반 브라우저(일반적으로 클라우드 환경에서 실행 중인)에 연결합니다. OpenClaw의 설정에서 엔드포인트 URL과 인증 토큰을 구성합니다. 이 모드는 브라우저 인프라가 별도로 관리되는 프로덕션 파이프라인을 위한 것입니다. 예를 들어, 로드 밸런서 뒤에서 실행되는 클라우드 브라우저 플릿 등입니다. Remote CDP 구성은 안전한 연결을 위한 HTTPS를 지원하며, 네트워크 지연에 따라 조정하는 타임아웃 설정(remoteCdpTimeoutMs와 remoteCdpHandshakeTimeoutMs)이 있습니다.
주요 결정 기준을 정리한 비교표는 다음과 같습니다:
| 기준 | Extension Relay | OpenClaw Managed | Remote CDP |
|---|---|---|---|
| 기존 세션 접근 | 가능 | 불가 | 설정에 따라 다름 |
| Chrome 확장 프로그램 필요 | 예 | 아니오 | 아니오 |
| 개인 데이터와 격리 | 아니오 | 예 | 예 |
| 로컬에서 작동 | 예 | 예 | 아니오 |
| 클라우드/프로덕션 사용 | 아니오 | 가능 | 예 |
| 설정 복잡성 | 중간 | 낮음 | 높음 |
| 기본 포트 | 18792 | 18800+ | 사용자 지정 |
Relay와 Managed 모두 사용 가능한 경우 선택 방법: 사이트가 새로운 세션(쿠키 없음)을 필요로 하는 경우 Managed를 선택합니다. 사이트에 프로그래밍 방식으로 재현하기 어려운 기존 인증된 세션이 있는 경우, 전용 프로필과 함께 Extension Relay를 사용합니다.
스냅샷 및 참조 시스템 작동 방법
스냅샷 및 참조 시스템은 OpenClaw가 AI 에이전트에게 취약한 CSS 선택자나 시각적 패턴 매칭 없이 브라우저 요소와 상호작용할 수 있게 하는 방법입니다. openclaw browser snapshot을 실행하면, OpenClaw는 전체 페이지를 스캔하고 모든 인터랙티브 요소(버튼, 입력 필드, 링크, 드롭다운 등)에 고유한 숫자 참조(ref)를 할당합니다. 에이전트는 이러한 ref를 사용하여 어떤 요소와 상호작용할지 지정합니다: browser click 12는 요소 12를 클릭하고, browser type e15 "hello"는 요소 15에 입력합니다.
두 가지 별개의 스냅샷 모드가 있으며, Playwright 설정에 따라 어느 것을 사용할지가 중요합니다. AI 모드 스냅샷은 숫자 ref(12, 34 등)를 생성합니다. 이는 내부적으로 Playwright의 aria-ref 해석을 사용하며, 시맨틱 접근성 정보를 안정적인 숫자 식별자에 매핑합니다. AI 모드 스냅샷은 Playwright가 설치된 경우의 기본값이며, Playwright가 요소 해석을 안정적으로 처리하기 때문에 복잡한 상호작용에 더 적합합니다.
역할 모드 스냅샷은 "e" 접두사가 붙은 ref(e12, e34 등)를 생성합니다. 이는 getByRole() 매칭 접근 방식을 통해 브라우저의 접근성 트리를 직접 사용합니다. 역할 스냅샷은 Playwright 없이 작동하므로 최소 설정을 위한 폴백 옵션입니다. 트레이드오프로, 역할 기반 매칭은 덜 정교하며 비정상적인 접근성 속성을 가진 요소에서 예기치 않게 동작할 수 있습니다.
스냅샷 시스템을 관리하는 가장 중요한 규칙은 ref 지속성입니다: ref는 현재 페이지 상태에 대해서만 유효합니다. 모든 내비게이션 이벤트(링크 클릭, browser navigate 호출, 또는 JavaScript 리다이렉트)는 기존의 모든 ref를 무효화합니다. 내비게이션 후, 새 페이지의 DOM 구조는 완전히 달라지며, 이전 ref 번호는 의미가 없어집니다. 마찬가지로, AJAX 호출이나 JavaScript 재렌더링을 통해 DOM을 상당히 업데이트하는 동적 페이지는 전체 내비게이션 없이 특정 ref를 무효화할 수 있습니다.
이 동작은 의도적인 것이며 버그가 아닙니다. ref 시스템은 정확성을 우선시합니다. 사라진 요소를 가리키는 오래된 ref는 조용히 실패하거나 잘못된 요소와 상호작용하게 됩니다. 운영상의 결과는 워크플로 규율입니다: 새 페이지에서 상호작용 시퀀스를 시작하기 전에 항상 새로운 스냅샷을 찍으세요.
신뢰할 수 있는 자동화를 위한 실용적인 패턴은 다음과 같습니다: URL로 이동하고, 스냅샷을 찍고, 스냅샷 출력에서 대상 요소 ref를 식별하고, 상호작용을 수행하고, 상호작용이 내비게이션이나 주요 DOM 변경을 유발했는지 확인하고, 그렇다면 계속하기 전에 다른 스냅샷을 찍습니다. 여러 페이지에 걸친 다단계 워크플로의 경우, 이 스냅샷→상호작용 사이클은 모든 페이지 전환에서 반복됩니다.
주목할 만한 미묘한 점은 스냅샷 출력에 각 요소에 대한 메타데이터가 포함된다는 것입니다: 역할(버튼, 링크, 텍스트박스), 접근 가능한 이름 또는 레이블, 그리고 ref입니다. AI 에이전트는 이 정보를 사용하여 예를 들어 "제출" 버튼이나 검색 입력 필드에 해당하는 요소를 추론합니다. 이 시맨틱 정보가 바로 OpenClaw의 자동화가 CSS 선택자 기반 접근 방식보다 더 강건한 이유입니다. 사이트가 재디자인될 때 버튼 레이블은 거의 변경되지 않지만, CSS 클래스 이름은 자주 변경됩니다.
실용적인 브라우저 자동화 워크플로
OpenClaw의 브라우저 제어는 스냅샷, 내비게이션, 상호작용 명령을 일관된 워크플로로 결합할 때 진정으로 유용해집니다. 세 가지 워크플로는 현재 상태에서 이 도구로 달성할 수 있는 범위를 보여줍니다.
워크플로 1: Extension Relay를 사용한 인증된 세션 자동화
이것은 Extension Relay 모드의 가장 일반적인 사용 사례입니다. 시나리오는 이미 로그인된 웹 애플리케이션 내에서 작업을 자동화하는 것입니다. 예를 들어, 비즈니스 인텔리전스 대시보드에서 보고서 내보내기, 반복적인 양식 작성, 또는 인증이 필요한 상태 페이지 모니터링 등입니다.
먼저, LLM 설정 프로세스를 통해 AI 제공업체를 구성합니다. 그런 다음, Extension Relay가 활성화되고 Chrome 확장 프로그램이 연결된 상태에서 브라우저에서 대상 사이트를 엽니다. 시퀀스는 다음과 같이 시작됩니다:
bashopenclaw browser tabs # 사용 가능한 탭 목록 표시 openclaw browser tab select 3 # 대상 탭으로 전환 openclaw browser snapshot # 인터랙티브 요소 스캔
스냅샷은 ref와 함께 요소 목록을 반환합니다. 에이전트는 이 출력을 파싱하고 상호작용해야 할 요소를 식별합니다. 여기서 워크플로는 다음과 같이 이어집니다: 내보내기 버튼(ref 8) 클릭, 모달이 나타나기를 기다리기, 다시 스냅샷을 찍어 모달의 요소 ref 가져오기, 날짜 범위 입력 필드 채우기, 확인 클릭. 주요 이점은 이 모든 것이 인증된 브라우저 세션 내에서 일어난다는 것입니다. 로그인 프로세스가 필요하지 않습니다.
워크플로 2: Managed 모드를 사용한 격리된 웹 스크래핑
공개 사이트에서의 데이터 추출에는 Managed 모드가 올바른 선택입니다. 격리로 인해 개인 쿠키나 브라우징 상태를 위험에 노출시키지 않으면서 더 높은 처리량을 위해 여러 프로필을 병렬로 실행할 수 있습니다.
bashopenclaw browser start --profile scraper-1 # 관리 브라우저 시작 openclaw browser navigate "https://target-site.com/data" openclaw browser wait # 페이지 로드 대기 openclaw browser snapshot
스냅샷에서 에이전트는 데이터 요소(테이블 행, 텍스트 블록, 따라갈 링크)를 식별합니다. 특정 ref에서 텍스트 콘텐츠를 추출하고, "다음" 버튼 ref를 클릭하여 페이지네이션을 따라가고, 모든 페이지가 처리될 때까지 프로세스를 반복합니다. AJAX로 로드된 콘텐츠가 있는 사이트의 경우, browser wait 명령(특정 텍스트가 나타날 때까지 기다릴 수 있음)은 에이전트가 요소가 존재하기 전에 상호작용하려고 시도하지 않도록 보장합니다.
OpenClaw는 웹 스크래핑의 실제적인 복잡성을 처리합니다: 세션 관리를 위한 쿠키 추출, 사이트가 만드는 API 호출을 이해하기 위한 네트워크 요청 인터셉트, 지연 로드된 콘텐츠를 트리거하기 위한 스크롤 이벤트 시뮬레이션 등입니다. 스냅샷 시스템은 에이전트가 미리 CSS 선택자를 알 필요 없이 접근성 구조에서 추론할 수 있게 합니다.
워크플로 3: 모니터링 및 알림 워크플로
특히 유용한 패턴은 주기적인 모니터링입니다. 페이지의 변경 사항을 확인하고 특정 것이 나타날 때 액션을 트리거합니다. AI 에이전트가 몇 분마다 대시보드를 확인하도록 구성합니다:
bashopenclaw browser navigate "https://status-page.com" openclaw browser snapshot # 조건이 충족되면: 구성된 채널을 통해 알림 전송
OpenClaw는 메시징 채널(Telegram, Slack, Discord 등)에 연결되므로, 모니터링 워크플로는 추가 통합 없이 에이전트의 통신 채널을 통해 직접 알림을 보낼 수 있습니다.
프로덕션 모니터링 워크플로에서는 토큰 소비에 주의하세요. 각 스냅샷은 AI 모델이 페이지 구조를 처리할 때 토큰을 소비합니다. 복잡한 페이지에서 빈번한 스냅샷을 실행할 때는 토큰 관리 모범 사례가 중요해집니다.
브라우저 릴레이 보안 모범 사례
브라우저 자동화에는 문제가 발생할 때까지 간과하기 쉬운 보안 고려사항이 있습니다. OpenClaw의 설계에는 여러 보안 기본값이 포함되어 있지만, 사용자가 의식적으로 구현해야 하는 중요한 관행이 있습니다.
OpenClaw의 브라우저 제어 서비스는 기본적으로 루프백 주소(127.0.0.1)에 바인딩됩니다. 이는 동일한 기기에서만 접근 가능하다는 것을 의미합니다. 이것은 의도적인 보안 기본값입니다. 포트 18792의 CDP 릴레이는 외부 네트워크에 절대 노출되어서는 안 됩니다. 2026년 1월, ZeroPath 보안 연구팀은 특정 네트워크 구성에서 루프백 바인딩이 우회될 수 있어 악의적인 웹사이트가 로컬 릴레이 서비스에 도달할 수 있는 OpenClaw의 브라우저 릴레이 서버의 취약점에 관한 결과를 발표했습니다. OpenClaw는 이후 버전에서 이를 해결하는 패치를 출시했지만, 이 사건은 네트워크 격리가 왜 중요한지를 다시 한번 강조합니다.
대부분의 사용자를 위한 실용적인 보안 구성에는 세 가지 레이어가 있습니다. 첫째, Extension Relay 자동화에는 전용 Chrome 프로필을 사용하고, 개인 브라우징에 사용하는 프로필에서 자동화 작업을 실행하지 마세요. 자동화 프로필에는 특정 작업에 필요한 쿠키와 자격 증명만 있어야 합니다. 프로필이 손상되거나 예기치 않게 동작하면, 피해 범위는 해당 프로필에 국한됩니다.
둘째, 게이트웨이 포트(18791)와 릴레이 포트(18792)를 방화벽 수준에서 외부 접근으로부터 차단하세요. 서버에서 OpenClaw를 실행하는 경우, OpenClaw 프로세스만 이 포트에 바인딩할 수 있도록 방화벽 규칙을 구성하세요. 명시적인 인증이 구성되지 않는 한 네트워크 주소 변환이나 포트 포워딩을 통해 노출하지 마세요.
셋째, Remote CDP 모드에서는 항상 HTTPS 연결을 사용하고 인증 토큰을 구성하세요. remoteCdpToken 설정은 클라우드 브라우저 엔드포인트에 대한 연결에 인증이 필요하도록 합니다. 특히 팀원들 간에 구성을 공유하는 경우 이러한 토큰을 주기적으로 교체하세요.
SSRF(서버 사이드 요청 위조) 보호를 위해, OpenClaw에는 관리 브라우저가 접근할 수 있는 URL을 제한하는 구성 가능한 SSRF 정책이 포함되어 있습니다. 브라우저가 내부 네트워크 리소스에 접근하도록 지시받을 수 있는 환경에서는 프라이빗 네트워크 차단 정책을 활성화하면 브라우저가 내부 서비스에 대한 프록시로 사용되는 것을 방지합니다.
자주 간과되는 위험 중 하나는 스냅샷을 통한 자격 증명 유출입니다. 에이전트가 민감한 양식 데이터가 포함된 페이지의 스냅샷을 처리하면, 해당 데이터가 AI 모델에 의해 처리되는 스냅샷 출력에 나타날 수 있습니다. 스냅샷하는 페이지에 주의를 기울이세요. 특정 통제 장치가 마련되지 않는 한, 전체 계정 번호, 주민등록번호 또는 유사한 민감한 데이터를 표시하는 페이지는 스냅샷하지 마세요.
브라우저 제어 트러블슈팅: 오류 메시지 및 수정 방법
OpenClaw의 브라우저 제어에서 가장 일반적인 좌절의 원인은 연결 실패이며, 거의 항상 "Can't reach the OpenClaw browser control service (timed out after 20000ms)"로 나타납니다. 이 오류에는 다른 수정이 필요한 여러 가지 원인이 있으며, 체계적으로 접근하는 것이 시행착오보다 빠릅니다.
가장 먼저 확인해야 할 것은 OpenClaw 게이트웨이가 실제로 실행되고 있는지입니다. 터미널을 열고 openclaw gateway status를 실행하세요. 게이트웨이가 실행되지 않고 있다면, openclaw gateway start 또는 macOS의 메뉴바 애플리케이션을 통해 시작하세요. 게이트웨이는 모든 브라우저 제어 명령이 작동하기 전에 실행되어야 합니다. 게이트웨이가 실행 중이지만 여전히 타임아웃 오류가 발생한다면, 컨트롤 포트(기본적으로 18791)가 다른 프로세스에 의해 점유되어 있는지 확인하세요: macOS/Linux에서는 lsof -i:18791, Windows에서는 netstat -ano | findstr 18791. 충돌하는 프로세스를 종료하고 게이트웨이를 다시 시작하세요.
특히 WSL2 내에서 OpenClaw를 실행하는 Windows 사용자의 경우, Windows 방화벽이 WSL2 가상 네트워크 인터페이스가 WSL2에서 실행 중인 게이트웨이에 도달하는 것을 차단하는 일반적인 문제가 있습니다. GitHub 이슈 #30196이 이를 정확히 문서화하고 있습니다. 수정 방법은 Windows 호스트에서 WSL2 IP로의 포트 프록시 규칙을 생성하는 것입니다: netsh interface portproxy add v4tov4 listenport=18791 listenaddress=0.0.0.0 connectport=18791 connectaddress=$(wsl hostname -I). 이는 Windows 호스트 포트에서 OpenClaw가 실행 중인 WSL2 인스턴스로의 연결을 전달합니다.
프록시 환경 변수는 미묘하고 혼란스러운 실패 모드를 만들어냅니다. HTTP_PROXY, HTTPS_PROXY, 또는 ALL_PROXY 환경 변수가 셸에 설정되어 있으면, OpenClaw에서 브라우저로의 CDP 연결 시도가 프록시를 통해 라우팅되어 타임아웃 또는 연결 거부 오류가 발생할 수 있습니다. GitHub 이슈 #31219가 이를 문서화하고 있습니다. 수정은 간단합니다: NO_PROXY 환경 변수에 localhost와 127.0.0.1(IPv6의 경우 ::1도)을 추가하세요. 셸 구성에 export NO_PROXY="localhost,127.0.0.1,::1"을 추가하세요.
"Tab not found" 오류와 오래된 ref를 사용한 후의 "ref not found"는 같은 근본 원인을 공유합니다: 내비게이션이 발생했고 ref가 새로고침되지 않은 것입니다. 모든 브라우저 내비게이션 명령 후, 페이지 변경을 일으키는 클릭 후, 또는 중요한 DOM 변경을 유발하는 액션 후에는 요소를 참조하기 전에 반드시 새로운 스냅샷을 찍으세요. 내비게이션 후 항상 스냅샷을 찍는 워크플로 규율이 이 오류 클래스를 완전히 제거합니다.
활성 탭에 확장 프로그램이 연결되지 않는 것처럼 보이는 Extension Relay 실패의 경우, 문제는 보통 해당 탭에 CDP 연결이 허용되지 않는다는 것입니다. 이는 확장 프로그램이 활성화되기 전에 탭이 열렸거나, 탭이 브라우저 내부 페이지(Chrome 설정이나 새 탭 페이지 등)인 경우에 발생합니다. 확장 프로그램 팝업을 확인하세요. 연결 상태가 표시됩니다. Chrome 도구 모음의 확장 프로그램 아이콘을 클릭하여 재연결을 트리거합니다. 확장 프로그램이 연결됨으로 표시되지만 명령이 여전히 실패한다면, browser tabs를 실행하여 사용 가능한 탭을 나열하고 browser tab select {id}로 대상 탭을 명시적으로 선택하세요.
Playwright 관련 실패, 특히 AI 모드 스냅샷이 Playwright를 찾을 수 없다는 오류로 실패하는 경우, Playwright와 해당 브라우저 바이너리를 설치하세요:
bashnpm install playwright npx playwright install chromium
Playwright 의존성을 피하려면 browser snapshot --role로 역할 모드 스냅샷으로 전환하세요. 역할 모드는 Playwright 없이 작동하지만 요소 해석의 정교함은 떨어집니다. 더 간단한 페이지와 간단한 상호작용 패턴에 대한 신뢰할 수 있는 폴백으로 생각하세요.
내장된 openclaw doctor 명령은 게이트웨이 연결성, 브라우저 가용성, Playwright 설치, 확장 프로그램 상태, 포트 바인딩 등 모든 컴포넌트를 확인하는 포괄적인 진단을 실행합니다. 트러블슈팅 시 이 명령을 먼저 실행하면 무엇이 작동하고 무엇이 작동하지 않는지에 대한 완전한 그림을 얻을 수 있어 상당한 디버깅 시간을 절약할 수 있습니다.
AI 모델이 스냅샷을 처리하지 못하게 하는 API 키 오류에 대해서는 API 키 트러블슈팅 가이드가 가장 일반적인 구성 문제를 다룹니다. 집중적인 브라우저 자동화 세션 중의 속도 제한 오류는 속도 제한 관리 가이드에서 다룹니다.
고급 구성: 포트, 프로필, 성능
OpenClaw의 기본 구성은 단일 브라우저 단일 사용자 설정에 적합하지만, 이 도구는 훨씬 더 정교한 배치를 지원합니다. 포트 아키텍처와 프로필 시스템을 이해하면 병렬 자동화, 복잡한 다단계 워크플로, 그리고 프로덕션 급 신뢰성이 실현됩니다.
포트 스키마는 고정된 오프셋 패턴을 따릅니다. 게이트웨이는 포트 18791에서 실행됩니다. 컨트롤 서비스는 게이트웨이 포트 + 9(기본 프로필의 경우 18800)에서 실행됩니다. 각 추가 관리 브라우저 프로필은 다음 포트를 차지합니다: 프로필 1은 18800, 프로필 2는 18801, 프로필 99는 18899까지. Extension Relay는 포트 18792를 차지합니다. 여러 개의 격리된 브라우저 세션을 동시에 실행해야 할 때(예: 다중 사용자 워크플로 테스트 또는 병렬 스크래핑 작업 실행), 여러 프로필을 시작합니다:
bashopenclaw browser start --profile job-1 # 18800 사용 openclaw browser start --profile job-2 # 18801 사용 openclaw browser start --profile job-3 # 18802 사용
각 프로필은 자체 쿠키, 스토리지, 브라우징 상태를 유지합니다. 할당하는 프로필 이름("job-1" 등)은 사람이 읽을 수 있는 레이블입니다. OpenClaw가 내부적으로 포트 매핑을 관리합니다.
헤드리스 대 헤드 작동에 대해, 헤드리스 모드는 디스플레이가 없는 서버 환경과 프로덕션 파이프라인에 적합한 선택입니다. 헤드 모드(표시된 브라우저 창)는 자동화가 펼쳐지는 것을 보고 시각적 문제를 파악할 수 있어 개발 중에 가치 있습니다. 모드 간 전환은 구성 플래그로 이루어집니다. 두 모드 모두 CDP 명령 인터페이스는 변하지 않습니다. 약간의 성능 차이가 있습니다: 헤드리스 모드는 브라우저가 시각적 컴포지션 레이어를 렌더링하지 않기 때문에 메모리와 CPU를 약간 덜 사용하지만, 그 차이는 자동화되는 페이지의 네트워크 및 JavaScript 실행 비용보다 작습니다.
사용자 정의 실행 파일 경로 구성으로 OpenClaw가 관리 모드에 사용하는 Chromium 기반 브라우저를 지정할 수 있습니다. 기본적으로 시스템 Chromium을 사용합니다. 자동화가 특정 브라우저 동작을 필요로 하는 경우, 특정 버전의 Chrome, Brave, 또는 Edge를 지정할 수 있습니다. 이는 브라우저 버전 간 사이트 호환성을 테스트할 때 유용합니다.
대량 자동화의 경우, 타임아웃 구성이 매우 중요합니다. 기본 remoteCdpTimeoutMs와 remoteCdpHandshakeTimeoutMs 값은 로컬 연결에 맞게 조정되어 있습니다. Remote CDP 엔드포인트에 네트워크 지연이 있는 경우(예: 다른 지역의 클라우드 브라우저 인스턴스), 이러한 타임아웃을 늘리면 느린 연결 설정으로 인한 잘못된 실패를 방지합니다. 마찬가지로 SSRF 정책 구성을 검토해야 합니다: 가장 엄격한 설정은 관리 브라우저가 프라이빗 네트워크 주소에 접근하는 것을 차단합니다. 이는 브라우저가 내부 네트워크 프록시로 사용되는 것을 방지하지만, 로컬 개발 서버에 합법적으로 접근해야 하는 자동화를 방해할 수 있습니다.
API 접근 비용을 고려하는 팀의 경우, 각 스냅샷 작업은 페이지 복잡성에 비례하여 토큰을 소비합니다. 인터랙티브 요소가 적은 단순한 페이지는 밀도 높은 엔터프라이즈 애플리케이션 페이지보다 훨씬 적은 토큰을 사용합니다. 역할 모드 스냅샷(Playwright 없음)을 사용하면 AI 모드 스냅샷보다 약간 더 작은 스냅샷 출력이 생성되므로, 고빈도 모니터링 워크플로의 토큰 소비를 줄일 수 있습니다.
요약: 실제로 활용하는 OpenClaw 브라우저 제어
OpenClaw의 브라우저 제어 시스템은 AI 기반 웹 자동화에 대한 일관된 접근 방식을 나타냅니다. CDP 기반은 시각적 자동화 도구가 도달할 수 없는 수준에서의 결정론적이고 신뢰할 수 있는 제어를 제공합니다. 세 가지 모드는 개인 인증된 워크플로부터 프로덕션 클라우드 배포까지 스펙트럼을 커버합니다. 스냅샷 및 참조 시스템은, ref 라이프사이클을 이해하면, AI 에이전트가 CSS 선택자나 XPath 표현식을 알지 않아도 웹 페이지에 대해 추론할 수 있는 깔끔한 추상화를 제공합니다.
워크플로를 구축할 때 염두에 두어야 할 실제적인 제약 사항: ref는 내비게이션 시 만료되므로 스냅샷 규율은 필수입니다. Extension Relay는 보안을 위해 전용 Chrome 프로필이 필요합니다. Playwright 의존성은 선택 사항이지만 가장 기능이 뛰어난 스냅샷 모드를 활성화합니다. 그리고 프록시 환경 변수는 프로덕션 환경에서 간과하기 쉬운 일반적인 조용한 실패 원인입니다.
2026년 초 기준으로 중요한 GitHub 활동 평균을 보이는 OpenClaw 에코시스템이 계속 발전함에 따라, 브라우저 제어는 텍스트를 처리하는 것뿐만 아니라 실제로 웹에서 행동할 수 있는 에이전트를 구축하기 위한 가장 강력한 기능 중 하나로 남아 있습니다.
이 가이드는 2026년 3월 기준 OpenClaw 버전 2026.2.6-3을 반영합니다. 최신 문서는 OpenClaw 공식 문서를 방문하세요.