Chrome 확장 프로그램 (브라우저 릴레이)

OpenClaw Chrome 확장 프로그램을 사용하면 에이전트가 별도의 openclaw 관리 Chrome 프로필을 시작하는 대신 기존 Chrome 탭(일반 Chrome 창)을 제어할 수 있습니다.

연결/분리는 단일 Chrome 툴바 버튼을 통해 이루어집니다.

개념

세 가지 부분으로 구성됩니다:

브라우저 제어 서비스(Gateway 또는 노드): 에이전트/도구가 호출하는 API(Gateway를 통해)
로컬 릴레이 서버(루프백 CDP): 제어 서버와 확장 프로그램 간의 브리지(기본값: http://127.0.0.1:18792)
Chrome MV3 확장 프로그램: chrome.debugger를 사용하여 활성 탭에 연결하고 CDP 메시지를 릴레이로 파이프

그런 다음 OpenClaw는 일반 browser 도구 인터페이스를 통해 연결된 탭을 제어합니다(올바른 프로필 선택).

설치/로드(언팩)

안정적인 로컬 경로에 확장 프로그램을 설치합니다:

openclaw browser extension install

설치된 확장 프로그램 디렉토리 경로를 출력합니다:

openclaw browser extension path

Chrome → chrome://extensions

"개발자 모드" 활성화
"압축 해제된 확장 프로그램 로드" → 위에서 출력된 디렉토리 선택

확장 프로그램을 고정합니다.

업데이트(빌드 단계 없음)

확장 프로그램은 정적 파일로 OpenClaw 릴리스(npm 패키지) 내부에 제공됩니다. 별도의 "빌드" 단계가 없습니다.

OpenClaw 업그레이드 후:

openclaw browser extension install을 다시 실행하여 OpenClaw 상태 디렉토리 아래의 설치된 파일을 새로 고칩니다.
Chrome → chrome://extensions → 확장 프로그램에서 "다시 로드" 클릭.

사용(추가 구성 불필요)

OpenClaw는 기본 포트의 확장 프로그램 릴레이를 타겟으로 하는 chrome이라는 내장 브라우저 프로필과 함께 제공됩니다.

사용:

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"

연결/분리(툴바 버튼)

OpenClaw가 제어하도록 하려는 탭을 엽니다.
확장 프로그램 아이콘을 클릭합니다.
- 연결되면 배지에 ON이 표시됩니다.
분리하려면 다시 클릭합니다.

어떤 탭을 제어하나요?

"보고 있는 탭"을 자동으로 제어하지 않습니다.
툴바 버튼을 클릭하여 명시적으로 연결한 탭만 제어합니다.
전환하려면: 다른 탭을 열고 거기서 확장 프로그램 아이콘을 클릭합니다.

배지 + 일반적인 오류

ON: 연결됨. OpenClaw가 해당 탭을 제어할 수 있습니다.
…: 로컬 릴레이에 연결 중.
!: 릴레이에 연결할 수 없음(가장 일반적: 이 머신에서 브라우저 릴레이 서버가 실행되지 않음).

!가 표시되는 경우:

Gateway가 로컬로 실행 중인지 확인하거나(기본 설정), Gateway가 다른 곳에서 실행되는 경우 이 머신에서 노드 호스트를 실행하십시오.
확장 프로그램 옵션 페이지를 엽니다. 릴레이에 연결할 수 있는지 표시됩니다.

원격 Gateway(노드 호스트 사용)

로컬 Gateway(Chrome과 동일한 머신) — 일반적으로 추가 단계 불필요

Gateway가 Chrome과 동일한 머신에서 실행되는 경우 루프백에서 브라우저 제어 서비스를 시작하고 릴레이 서버를 자동 시작합니다. 확장 프로그램은 로컬 릴레이와 통신하고 CLI/도구 호출은 Gateway로 이동합니다.

원격 Gateway(Gateway가 다른 곳에서 실행) — 노드 호스트 실행

Gateway가 다른 머신에서 실행되는 경우 Chrome이 실행되는 머신에서 노드 호스트를 시작하십시오. Gateway는 브라우저 액션을 해당 노드로 프록시하고 확장 프로그램 + 릴레이는 브라우저 머신에 로컬로 유지됩니다.

여러 노드가 연결되어 있는 경우 gateway.nodes.browser.node로 하나를 고정하거나 gateway.nodes.browser.mode를 설정하십시오.

샌드박싱(도구 컨테이너)

에이전트 세션이 샌드박스되어 있는 경우(agents.defaults.sandbox.mode != "off"), browser 도구가 제한될 수 있습니다:

기본적으로 샌드박스 세션은 종종 호스트 Chrome이 아닌 샌드박스 브라우저(target="sandbox")를 타겟으로 합니다.
Chrome 확장 프로그램 릴레이 테이크오버에는 호스트 브라우저 제어 서버 제어가 필요합니다.

옵션:

가장 쉬운 방법: 비샌드박스 세션/에이전트에서 확장 프로그램을 사용하십시오.
또는 샌드박스 세션에 대해 호스트 브라우저 제어를 허용하십시오:

{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true
        }
      }
    }
  }
}

그런 다음 도구 정책에 의해 거부되지 않았는지 확인하고 필요한 경우 target="host"와 함께 browser를 호출하십시오.

디버깅: openclaw sandbox explain

원격 액세스 팁

Gateway와 노드 호스트를 동일한 테일넷에 유지하십시오. 릴레이 포트를 LAN 또는 공용 인터넷에 노출하지 마십시오.
의도적으로 노드를 페어링하십시오. 원격 제어를 원하지 않는 경우 브라우저 프록시 라우팅을 비활성화하십시오(gateway.nodes.browser.mode="off").

"확장 프로그램 경로" 작동 방식

openclaw browser extension path는 확장 프로그램 파일이 포함된 설치된 온디스크 디렉토리를 출력합니다.

CLI는 의도적으로 node_modules 경로를 출력하지 않습니다. 항상 먼저 openclaw browser extension install을 실행하여 OpenClaw 상태 디렉토리 아래의 안정적인 위치에 확장 프로그램을 복사하십시오.

해당 설치 디렉토리를 이동하거나 삭제하면 유효한 경로에서 다시 로드할 때까지 Chrome이 확장 프로그램을 손상된 것으로 표시합니다.

보안 영향(읽어보기)

이것은 강력하지만 위험합니다. 모델에게 "브라우저에 손을 주는" 것처럼 취급하십시오.

확장 프로그램은 Chrome의 디버거 API(chrome.debugger)를 사용합니다. 연결되면 모델은 다음을 수행할 수 있습니다:
- 해당 탭에서 클릭/타이핑/탐색
- 페이지 콘텐츠 읽기
- 탭의 로그인 세션이 액세스할 수 있는 모든 항목에 액세스
전용 openclaw 관리 프로필처럼 격리되지 않습니다.
- 일상적으로 사용하는 프로필/탭에 연결하면 해당 계정 상태에 대한 액세스 권한을 부여하는 것입니다.

권장 사항:

확장 프로그램 릴레이 사용을 위해 개인 브라우징과 별도의 전용 Chrome 프로필을 선호하십시오.
Gateway 및 모든 노드 호스트를 테일넷 전용으로 유지하십시오. Gateway 인증 + 노드 페어링에 의존하십시오.
LAN(0.0.0.0)을 통해 릴레이 포트를 노출하지 말고 Funnel(공개)을 피하십시오.