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

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

연결/해제는 Chrome 도구 모음 버튼 한 번으로 이루어집니다.

OpenClaw 확장 프로그램 릴레이 대신 Chrome의 공식 DevTools MCP 연결 흐름을 사용하려면 existing-session 브라우저 프로필을 사용하세요. 브라우저를 참조하세요. Chrome 자체 설정 문서는 Chrome for Developers: Use Chrome DevTools MCP with your browser session 및 Chrome DevTools MCP README를 참조하세요.

개념

세 가지 구성 요소가 있습니다:

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

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

설치 / 로드 (언팩)

  1. 확장 프로그램을 안정적인 로컬 경로에 설치:
openclaw browser extension install
  1. 설치된 확장 프로그램 디렉터리 경로 출력:
openclaw browser extension path
  1. Chrome → chrome://extensions
  • “개발자 모드” 활성화
  • “압축해제된 확장 프로그램을 로드합니다” → 위에서 출력된 디렉터리 선택
  1. 확장 프로그램 고정.

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

확장 프로그램은 OpenClaw 릴리스(npm 패키지) 내에 정적 파일로 포함됩니다. 별도의 “빌드” 단계는 없습니다.

OpenClaw 업그레이드 후:

  • openclaw browser extension install을 다시 실행하여 OpenClaw 상태 디렉터리의 설치 파일을 갱신합니다.
  • Chrome → chrome://extensions → 확장 프로그램에서 “새로고침” 클릭.

사용 방법 (게이트웨이 토큰 1회 설정)

OpenClaw에는 기본 포트의 확장 프로그램 릴레이를 대상으로 하는 chrome이라는 기본 제공 브라우저 프로필이 있습니다.

처음 연결 전에 확장 프로그램 옵션을 열고 설정합니다:

  • Port (기본값 18792)
  • Gateway token (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN과 일치해야 함)

사용 방법:

  • CLI: openclaw browser --browser-profile chrome tabs
  • 에이전트 도구: browser에 profile="chrome"

다른 이름이나 다른 릴레이 포트를 원하면 자체 프로필을 생성합니다:

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

커스텀 게이트웨이 포트

커스텀 게이트웨이 포트를 사용하는 경우, 확장 프로그램 릴레이 포트가 자동으로 파생됩니다:

확장 프로그램 릴레이 포트 = 게이트웨이 포트 + 3

예시: gateway.port: 19001이면:

  • 확장 프로그램 릴레이 포트: 19004 (게이트웨이 + 3)

확장 프로그램 옵션 페이지에서 파생된 릴레이 포트를 사용하도록 구성하세요.

연결 / 해제 (도구 모음 버튼)

  • OpenClaw가 제어할 탭을 엽니다.
  • 확장 프로그램 아이콘을 클릭합니다.
    • 연결 시 배지에 ON 표시.
  • 다시 클릭하면 해제됩니다.

어떤 탭을 제어하나요?

  • “보고 있는 탭”을 자동으로 제어하지 않습니다.
  • 도구 모음 버튼을 클릭하여 명시적으로 연결한 탭만 제어합니다.
  • 전환하려면: 다른 탭을 열고 확장 프로그램 아이콘을 클릭하세요.

배지 + 일반적인 오류

  • ON: 연결됨. OpenClaw가 해당 탭을 제어할 수 있습니다.
  • …: 로컬 릴레이에 연결 중.
  • !: 릴레이에 접근 불가/인증 실패 (가장 흔한 원인: 릴레이 서버가 실행되지 않거나, 게이트웨이 토큰이 누락/잘못됨).

!가 표시되면:

  • 게이트웨이가 로컬에서 실행 중인지 확인하세요 (기본 설정). 게이트웨이가 다른 곳에서 실행되면 이 머신에서 노드 호스트를 실행하세요.
  • 확장 프로그램 옵션 페이지를 열어보세요. 릴레이 접근성 + 게이트웨이 토큰 인증을 검증합니다.

원격 게이트웨이 (노드 호스트 사용)

로컬 게이트웨이 (Chrome과 같은 머신) — 보통 추가 단계 불필요

게이트웨이가 Chrome과 같은 머신에서 실행되면, 루프백에서 브라우저 제어 서비스를 시작하고 릴레이 서버를 자동 시작합니다. 확장 프로그램은 로컬 릴레이와 통신하고, CLI/도구 호출은 게이트웨이로 전달됩니다.

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

게이트웨이가 다른 머신에서 실행되면, Chrome이 실행되는 머신에서 노드 호스트를 시작하세요. 게이트웨이가 해당 노드로 브라우저 액션을 프록시합니다. 확장 프로그램 + 릴레이는 브라우저 머신에 로컬로 유지됩니다.

여러 노드가 연결된 경우, gateway.nodes.browser.node로 하나를 고정하거나 gateway.nodes.browser.mode를 설정하세요.

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

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

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

옵션:

  • 가장 쉬운 방법: 비샌드박스 세션/에이전트에서 확장 프로그램 사용.
  • 또는 샌드박스 세션에서 호스트 브라우저 제어 허용:
{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true,
        },
      },
    },
  },
}

그런 다음 도구가 도구 정책에 의해 거부되지 않는지 확인하고, (필요하면) browser를 target="host"로 호출하세요.

디버깅: openclaw sandbox explain

원격 접근 팁

  • 게이트웨이와 노드 호스트를 같은 tailnet에 유지하고, 릴레이 포트를 LAN이나 공개 인터넷에 노출하지 마세요.
  • 의도적으로 노드를 페어링하고, 원격 제어가 필요하지 않으면 브라우저 프록시 라우팅을 비활성화하세요 (gateway.nodes.browser.mode="off").
  • 실제 크로스 네임스페이스 필요가 없는 한 릴레이를 루프백에 유지하세요. WSL2나 유사한 분할 호스트 설정의 경우, browser.relayBindHost를 0.0.0.0과 같은 명시적 바인드 주소로 설정하되, 게이트웨이 인증, 노드 페어링, 사설 네트워크로 접근을 제한하세요.

”extension path” 동작 원리

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

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

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

보안 관련 사항 (반드시 읽으세요)

이것은 강력하면서도 위험합니다. 모델에게 “브라우저에 대한 조작 권한”을 주는 것으로 생각하세요.

  • 확장 프로그램은 Chrome의 디버거 API(chrome.debugger)를 사용합니다. 연결되면 모델이:
    • 해당 탭에서 클릭/입력/내비게이션 가능
    • 페이지 내용 읽기 가능
    • 탭의 로그인 세션이 접근할 수 있는 모든 것에 접근 가능
  • 전용 openclaw 관리형 프로필처럼 격리되지 않습니다.
    • 일상적으로 사용하는 프로필/탭에 연결하면, 해당 계정 상태에 대한 접근을 허용하는 것입니다.

권장 사항:

  • 확장 프로그램 릴레이 사용 시 개인 브라우징과 별개인 전용 Chrome 프로필을 사용하세요.
  • 게이트웨이 및 모든 노드 호스트를 tailnet 전용으로 유지하고, 게이트웨이 인증 + 노드 페어링에 의존하세요.
  • LAN(0.0.0.0)이나 Funnel(공개)을 통한 릴레이 포트 노출을 피하세요.
  • 릴레이는 비확장 프로그램 출처를 차단하며, /cdp와 /extension 모두에 대해 게이트웨이 토큰 인증을 요구합니다.

관련 문서:

arrow_back
이전
Browser Login
다음
Browser Linux Troubleshooting
arrow_forward