Chrome extension을 이용한 브라우저 제어 (browser relay)

에이전트에게 브라우저 작업을 시킬 때마다 로그인이 안 된 깨끗한 새 창이 떠서 당황하신 적 있으시죠? 평소 사용하던 환경 그대로, 이미 로그인된 탭에서 에이전트가 바로 작업을 이어가면 정말 편할 텐데 말이죠.

OpenClaw Chrome extension을 사용하면 별도의 프로필을 실행할 필요 없이, 여러분이 지금 보고 있는 Chrome 탭을 에이전트가 직접 제어할 수 있습니다. 툴바 버튼 클릭 한 번으로 에이전트에게 브라우저 주도권을 넘겨주는 방법을 알아볼게요.

필요한 것

5분 안에 설정을 마치고 바로 시작해 보세요.

확장 프로그램 설치: 터미널에서 아래 명령어를 실행하여 확장 프로그램 파일을 로컬 경로에 설치합니다.
Terminal window
```
openclaw browser extension install
```
설치 경로 확인: 설치된 디렉토리 경로를 출력합니다.
Terminal window
```
openclaw browser extension path
```
Chrome에 로드:
- Chrome에서 chrome://extensions 페이지로 이동합니다.
- 우측 상단의 개발자 모드를 켭니다.
- 압축해제된 확장 프로그램을 로드 버튼을 누르고, 위에서 확인한 경로의 폴더를 선택합니다.
고정 및 실행: 확장 프로그램을 툴바에 고정하세요. 제어하고 싶은 탭에서 확장 프로그램 아이콘을 클릭하면 ON 표시와 함께 에이전트가 해당 탭을 제어할 수 있게 됩니다.

OpenClaw에는 기본적으로 이 확장 프로그램을 사용하도록 설정된 chrome이라는 브라우저 프로필이 포함되어 있습니다.

CLI에서 사용:

openclaw browser --browser-profile chrome tabs

만약 포트를 변경하거나 별도의 이름을 쓰고 싶다면 직접 프로필을 만들 수도 있습니다.

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

OpenClaw를 업데이트한 후에는 확장 프로그램 파일도 함께 갱신해야 합니다. 별도의 빌드 과정은 필요 없습니다.

에이전트는 여러분이 보고 있는 모든 탭을 마음대로 제어하지 않습니다.

Gateway가 Chrome과 같은 컴퓨터에서 실행 중이라면 추가 설정이 필요 없습니다. Gateway가 브라우저 제어 서비스와 relay 서버를 자동으로 시작합니다.

Gateway가 다른 서버에 있다면, Chrome이 실행 중인 로컬 머신에서 node host를 실행해야 합니다.

에이전트 세션에 샌드박스가 적용된 경우(agents.defaults.sandbox.mode != "off"), 기본적으로 호스트의 브라우저 제어가 제한될 수 있습니다.

가장 쉬운 방법은 샌드박스가 없는 세션에서 확장 프로그램을 사용하는 것이지만, 꼭 필요하다면 아래와 같이 설정을 변경하여 호스트 브라우저 제어를 허용할 수 있습니다.

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

이후 browser 툴을 호출할 때 target="host"를 지정했는지 확인하세요. 자세한 디버깅은 openclaw sandbox explain 명령어로 가능합니다.

이 기능은 에이전트에게 여러분의 브라우저를 직접 조작할 수 있는 권한을 주는 것이므로 주의가 필요합니다.

확장 프로그램은 Chrome의 chrome.debugger API를 사용합니다. 연결된 상태에서 모델은 해당 탭의 클릭, 타이핑, 페이지 내용 읽기뿐만 아니라 로그인된 세션의 모든 권한을 가집니다.
OpenClaw가 관리하는 독립된 프로필과 달리, 여러분의 개인 계정이 로그인된 탭에 직접 접근하게 됩니다.
보안을 위해 개인적인 용도의 브라우저 프로필보다는 확장 프로그램 전용 Chrome 프로필을 별도로 만들어 사용하는 것을 추천합니다.
Gateway와 node host는 가급적 Tailscale 같은 전용 네트워크 안에서만 운영하세요.

확장 프로그램 아이콘의 배지 상태를 통해 문제를 파악할 수 있습니다.

! 표시가 뜬다면 Gateway가 로컬에서 실행 중인지 확인해 보세요. 확장 프로그램의 옵션(Options) 페이지에서도 relay 연결 상태를 확인할 수 있습니다.

도움이 필요하신가요? AI Setup Assistant에게 물어보세요!

OpenClaw Expert

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.