Chrome Relay로 코딩 에이전트가 로그인된 Chrome을 제어하도록 설정하기

Chrome Relay란 무엇인가요?

Chrome Relay를 사용하면 지원되는 코딩 에이전트가 명령줄에서 평소 사용하는 Google Chrome 프로필에 접근할 수 있습니다. 에이전트는 이미 로그인한 사이트에 접근하면서 비활성 백그라운드 탭에서 작업하므로, 자동화가 현재 창의 포커스를 빼앗지 않습니다.

이 프로젝트는 Claude Code, Codex, Cursor, Paseo와 함께 작동합니다. agent-browser를 통해 각 도구의 브라우저 명령을 Chrome에 연결합니다. 명령은 일반적으로 약 0.15초 안에 완료되며 Chrome에 원격 디버깅 포트가 필요하지 않습니다.

Chrome Relay는 선택 사항입니다. 확장 프로그램을 자동으로 설치하지 않으며, 소유자가 설정을 완료한 Mac에서만 실행됩니다.

Chrome Relay 작동 방식

agent-browser CLI → 로컬 릴레이 → Chrome Relay 확장 프로그램 → 에이전트 탭

시스템은 세 가지 주요 구성 요소로 이루어집니다.

• Chrome 확장 프로그램: 에이전트가 사용할 각 Chrome 프로필에 별도로 로드하는 압축 해제된 Manifest V3 확장 프로그램입니다. 비활성 상태로 접힌 Agents 탭 그룹에 에이전트 탭을 열고, chrome.debugger를 통해 DevTools 명령을 전송합니다.
• 로컬 릴레이: 127.0.0.1:9333에서 수신 대기하는 LaunchAgent입니다. 각 에이전트에 별도의 DevTools 엔드포인트를 제공하고, 에이전트가 직접 연 탭으로만 접근을 제한합니다.
• 명령줄 도구: chrome-relay 명령이 설정, 연결 URL, ID, 업데이트, 진단, 로그 및 감사 기록을 처리합니다.

릴레이는 Chrome을 표시하거나 포커스를 맞출 수 있는 명령을 억제합니다. 에이전트가 작업하는 동안 Chrome에 Chrome Relay started debugging this browser라는 메시지가 계속 표시될 수 있습니다.

요구 사항

설치하기 전에 다음 항목을 준비하세요.

• macOS
• Google Chrome
• Node.js 20 이상
• 전역으로 설치된 agent-browser

npm으로 agent-browser를 설치합니다.

npm i -g agent-browser

Chrome Relay 설치

1. 프로젝트 복제 및 구성

git clone https://github.com/aindeev/agent-chrome-relay
cd agent-chrome-relay
bin/chrome-relay setup

설정 명령은 로컬 비밀 키를 생성하고, 백그라운드 서비스를 구성하며, ID를 기록하고, chrome-relay를 PATH에 추가하고, Claude Code용 Chrome Relay 스킬을 연결합니다.

2. Chrome에 확장 프로그램 로드

에이전트가 사용할 각 Chrome 프로필에서 다음 단계를 반복합니다.

1. chrome://extensions를 엽니다.
2. 개발자 모드를 활성화합니다.
3. 압축 해제된 확장 프로그램을 로드를 선택합니다.
4. 저장소의 extension 폴더를 선택합니다.

각 Chrome 프로필은 자체 확장 프로그램 사본을 로드하므로, 명시적으로 선택한 프로필만 노출할 수 있습니다.

3. 설치 확인

chrome-relay doctor

에이전트에게 브라우징을 요청하기 전에 진단 출력으로 릴레이와 확장 프로그램이 올바르게 구성되었는지 확인합니다.

코딩 에이전트에 Chrome Relay 알리기

Claude Code

설정 과정에서 skill/SKILL.md가 ~/.claude/skills/chrome-relay에 연결됩니다. 이렇게 하면 모든 저장소에서 스킬을 사용할 수 있습니다. 명시적인 지침이 필요한 경우에만 저장소 수준의 CLAUDE.md에 해당 스킬을 가리키는 한 줄을 추가하면 됩니다.

Codex, Cursor 및 기타 지원되는 에이전트

에이전트의 전역 지침에서 동일한 스킬 파일을 가리키도록 설정합니다. 예를 들어 ~/.codex/AGENTS.md에 다음과 같은 지침을 추가합니다.

로그인이 필요한 브라우저 단계에서는 /path/to/agent-chrome-relay/skill/SKILL.md를 따르세요.

예시 경로를 복제한 저장소의 절대 경로로 바꾸세요.

첫 번째 브라우저 자동화 실행

먼저 Chrome Relay에 인증된 연결 URL을 요청한 다음 해당 URL을 agent-browser에 전달합니다.

agent-browser --cdp "$(chrome-relay url you@company.com)" open https://app.example.com/
agent-browser snapshot -i
agent-browser click @e5
agent-browser close

you@company.com을 관련 설정 ID로 바꾸고, 예시 사이트를 자동화하려는 페이지로 바꾸세요.

1. chrome-relay url은 이 Mac의 비밀 키가 포함된 연결 URL을 출력합니다.
2. agent-browser open은 에이전트가 소유한 비활성 탭을 만들고 요청한 페이지를 엽니다.
3. snapshot -i는 링크, 버튼, 입력란과 같은 대화형 컨트롤을 나열합니다. 각 항목에는 @e5와 같은 참조가 부여됩니다.
4. click @e5는 백그라운드 탭에서 실제 입력 에뮬레이션을 사용해 참조된 요소를 활성화합니다.
5. close는 브라우저 세션을 종료합니다.

로그인 동작 이해

에이전트는 사용자의 인증 정보를 입력하지 않습니다. 사이트가 Google을 거쳐 리디렉션되고 올바른 계정이 이미 로그인되어 있다면, 확장 프로그램이 해당 계정을 선택하고 Continue 또는 Allow를 클릭할 수 있습니다. 이 과정은 페이지 스크립팅을 사용하므로 1Password가 페이지에 프레임을 삽입한 경우에도 작동할 수 있습니다.

흐름이 비밀번호, 패스키, 2단계 인증 또는 로그아웃된 계정 화면에 도달하면 자동화가 중지됩니다. 에이전트에는 SIGN-IN NEEDED 메시지가 전달되며, 사용자의 창에서 직접 로그인 절차를 완료하도록 요청해야 합니다.

프로필 및 사이트 ID 관리

ID 구성은 ~/.chrome-relay/identities.json에 저장됩니다. 다음 명령으로 확인하거나 관리할 수 있습니다.

chrome-relay identities

구성에는 설정 중 발견된 Chrome 프로필, 선택적으로 직접 구성한 sites.rules, 그리고 로그인 홉이 성공한 후 기록된 sites.learned 항목이 포함됩니다. 기본적으로 사이트는 선택한 Chrome 프로필에 속한 계정을 사용합니다.

보안 모델

모든 에이전트 연결은 두 가지 검사를 통과해야 합니다.

1. 로컬 시크릿: 설정 과정에서 파일 모드 600인 토큰이 ~/.chrome-relay/token에 생성됩니다. 토큰은 chrome-relay url이 출력하는 URL에 포함됩니다.
2. 허용된 에이전트 애플리케이션: 연결 프로세스는 Claude Code, Codex, Cursor 또는 Paseo와 연결되어 있어야 합니다. 릴레이는 프로세스와 이러한 애플리케이션이 자식 프로세스에 설정하는 식별 정보를 검사합니다.

브라우저 Origin 헤더가 포함된 연결은 시크릿이 있더라도 거부됩니다. 확장 프로그램도 Chrome에서 파생된 확장 프로그램 ID, chrome-extension:// 오리진, 그리고 연결 프로세스가 Chrome이어야 한다는 조건을 사용해 검사합니다.

이러한 제어 기능은 관련 없는 로컬 도구, 웹 페이지 및 우발적인 연결을 차단합니다. 하지만 사용자 권한으로 이미 실행 중인 악성 코드에 대한 보안 경계는 아닙니다. 그런 소프트웨어는 시크릿을 읽고 프로세스 식별 정보를 모방할 수 있기 때문입니다.

감사 추적 검토

Chrome Relay는 ~/.chrome-relay/audit/YYYY-MM-DD.jsonl 아래의 일별 JSON Lines 파일에 에이전트 활동을 기록합니다. 다음 명령으로 기록을 확인할 수 있습니다.

chrome-relay audit

감사 추적에는 연결 세부 정보, 작업 폴더, 세션 식별자, 방문한 페이지, 클릭 위치, 특수 키, 에이전트 스크립트, 스크린샷, 업로드, 팝업, 로그인 클릭 및 차단된 페이지가 포함됩니다. 개인정보 보호를 위해 입력한 텍스트는 문자 수로만 표시되며 URL 쿼리 문자열은 제거됩니다.

고급 동작 및 팁

팝업 및 새 탭

target=_blank를 사용하는 링크와 팝업은 동일한 에이전트가 소유한 숨겨진 탭으로 열립니다. 팝업 인증 흐름은 여전히 오프너에 메시지를 보내고 스스로 닫힐 수 있습니다. 릴레이는 페이지의 주장을 신뢰하지 않고 확인된 메시지 오리진과 targetOrigin을 적용합니다.

1Password 페이지

페이지에 다른 확장 프로그램의 프레임이 포함되어 있으면 Chrome이 확장 프로그램 디버거를 분리할 수 있습니다. 예를 들어 로그인 양식에 1Password 메뉴가 포함된 경우가 이에 해당합니다. Chrome Relay는 에이전트 명령을 계속 실행하기 전에 잠시 기다렸다가 다시 연결합니다.

자동 정리

에이전트 탭은 30분 동안 활동이 없으면 닫힙니다. 릴레이가 다시 시작되면 확장 프로그램도 이전에 열었던 탭을 닫습니다. 정리는 탭 ID를 기준으로 수행되므로 사용자가 직접 만든 탭 그룹은 수정하지 않습니다.

백그라운드 입력

에이전트 탭에서는 포커스 에뮬레이션이 계속 활성화되어 있습니다. 따라서 현재 Chrome 탭을 그대로 둔 채 비활성 탭에 클릭과 입력을 전달할 수 있습니다.

Chrome Relay 업데이트, 진단 및 제거

저장소 변경 사항을 가져온 후 릴레이를 다시 시작하고 구성된 모든 프로필에서 확장 프로그램을 다시 로드합니다.

git pull
chrome-relay update

다음 명령으로 릴레이 로그를 확인할 수 있습니다.

chrome-relay logs

로그 파일은 ~/.chrome-relay/relay.log에 저장됩니다. 로컬 서비스와 명령줄 설정을 제거하려면 다음을 실행합니다.

chrome-relay uninstall

그런 다음 각 Chrome 프로필에서 압축 해제된 확장 프로그램을 수동으로 제거합니다.

개발 및 테스트

릴레이 종속 항목을 설치하고 테스트 모음을 실행하려면 다음을 실행합니다.

cd relay && npm install && npm test

테스트는 시크릿, 허용된 애플리케이션, Chrome 전용 확장 프로그램 연결 및 감사 동작을 포함한 연결 권한 부여를 다룹니다. extension/ 아래의 파일을 편집한 후에는 다음 명령으로 확장 프로그램을 다시 로드합니다.

chrome-relay update

사용자 지정 환경에서는 CHROME_RELAY_HOME으로 데이터 디렉터리를 재정의하고 CHROME_RELAY_PORT로 릴레이 포트를 재정의할 수 있습니다.

결론

Chrome Relay는 원격 디버깅 포트를 요구하거나 현재 사용 중인 창을 대신 제어하지 않고, 지원되는 코딩 에이전트에 기존 Chrome 세션에 대한 제어된 액세스를 제공합니다. 로컬 릴레이와 압축 해제된 확장 프로그램을 구성하면 agent-browser로 인증된 브라우저 작업을 자동화하고, 프로필 또는 사이트별로 ID를 선택하며, 개인정보를 고려한 상세 감사 기록을 확인하고, 방치된 세션을 자동으로 정리할 수 있습니다.

소스 코드, 업데이트 및 이슈 제보는 Chrome Relay GitHub 저장소를 방문하세요. 이 프로젝트는 MIT 라이선스로 제공됩니다.