Claude Code agent-browser 설치 방법과 초기 설정 가이드
Claude Code에서 웹사이트를 직접 열고, 버튼을 클릭하고, 입력 양식을 작성하거나 웹 애플리케이션을 테스트하고 싶다면 agent-browser를 활용해 보세요. agent-browser는 Vercel Labs에서 개발한 브라우저 자동화 도구로, Claude Code가 명령어를 통해 실제 브라우저를 제어할 수 있도록 도와줍니다.
설치는 크게 두 단계입니다. 먼저 agent-browser CLI를 설치하고 Chrome을 준비한 다음, Claude Code에서 사용할 Skill을 추가하면 됩니다.
📌 핵심 요약
도구: Vercel Labs의 agent-browser
CLI 설치:
npm install -g agent-browser브라우저 설치:
agent-browser installClaude Code Skill 설치:
npx skills add vercel-labs/agent-browser주요 기능: 웹 탐색, 클릭, 입력, 화면 캡처, 데이터 추출 및 웹 테스트
🔍 agent-browser란 무엇인가요?
agent-browser는 AI 에이전트가 브라우저를 자동으로 조작하도록 지원하는 CLI(Command Line Interface) 도구입니다.
일반적인 AI 코딩 도구가 코드를 작성하는 데 집중한다면, agent-browser는 실제 웹페이지를 열고 화면에 표시된 요소를 확인한 뒤 사용자의 행동처럼 클릭하거나 입력할 수 있도록 지원합니다.
예를 들어 다음과 같은 작업이 가능합니다.
웹사이트에 접속하고 페이지 내용 확인하기
로그인 및 입력 양식 작성하기
버튼 클릭과 페이지 이동하기
웹사이트 화면 캡처하기
웹 애플리케이션 기능 테스트하기
특히 Claude Code와 함께 사용하면 개발한 웹사이트를 직접 실행하고 동작을 확인하는 작업에 유용합니다.
⚙️ agent-browser 설치 방법
먼저 Node.js와 npm이 설치되어 있는지 확인합니다. Windows PowerShell 또는 터미널에서 다음 명령어를 실행하세요.
node -v
npm -v
버전이 정상적으로 표시되면 다음 단계로 진행합니다.
1. agent-browser CLI 설치
다음 명령어를 실행합니다.
npm install -g agent-browser
전역 설치 방식이므로 여러 프로젝트에서 동일한 명령어를 사용할 수 있습니다.
2. Chrome 브라우저 설치
CLI 설치가 끝났다면 브라우저 실행에 필요한 Chrome을 준비합니다.
agent-browser install
이 명령어는 Chrome for Testing을 다운로드합니다. 기존 Chrome 설치 여부와 별개로 자동화에 필요한 브라우저 환경을 준비하는 과정입니다.
3. Claude Code Skill 설치
이제 Claude Code가 agent-browser의 사용 방법을 이해하도록 Skill을 설치합니다.
npx skills add vercel-labs/agent-browser
설치하면 Claude Code 프로젝트의 .claude/skills/agent-browser/ 경로에 Skill이 추가됩니다.
이 Skill은 상세한 명령어를 모두 고정해서 저장하는 방식이 아니라, 실행 중인 agent-browser에서 최신 사용 지침을 불러오도록 안내하는 구조입니다.
🚀 설치 후 정상 작동 확인하기
설치가 끝났다면 다음 명령어로 CLI가 정상적으로 준비되었는지 확인합니다.
agent-browser --help
이후 실제 웹사이트에 접속해 보세요.
agent-browser open https://example.com
페이지가 열리면 화면에 있는 요소를 확인합니다.
agent-browser snapshot -i
이 명령어는 클릭하거나 입력할 수 있는 요소를 참조 번호와 함께 보여줍니다.
예를 들어 @e1이라는 참조 번호가 표시되었다면 해당 요소를 다음과 같이 클릭할 수 있습니다.
agent-browser click @e1
입력란에 값을 넣을 때는 다음 명령어를 사용합니다.
agent-browser fill @e2 "Hello World"
페이지가 변경되면 다시 snapshot -i를 실행해 현재 화면을 확인하는 것이 좋습니다.
💡 Claude Code에서 활용하는 방법
Claude Code를 실행한 다음 자연어로 작업을 요청하면 됩니다.
예를 들어 다음과 같이 요청할 수 있습니다.
"agent-browser를 사용해서 현재 개발 중인 웹사이트에 접속하고, 주요 메뉴를 확인한 다음 각 페이지가 정상적으로 열리는지 테스트해 줘."
Claude Code는 Skill의 지침을 참고해 브라우저를 열고, 화면을 확인하고, 필요한 동작을 수행할 수 있습니다.
프로젝트의 CLAUDE.md에 브라우저 자동화 작업에는 agent-browser를 사용하도록 안내를 추가하면 일관된 활용에도 도움이 됩니다.
⚠️ 설치 및 사용 시 주의할 점
agent-browser CLI 설치와 Claude Code Skill 설치는 별개의 과정입니다. Skill만 설치하면 브라우저 실행 프로그램까지 자동으로 준비되는 것은 아니므로 두 단계를 구분해서 진행하세요.
또한 로그인 상태의 웹사이트나 개인정보가 포함된 페이지를 자동화할 때는 접근 권한과 실행 명령을 확인해야 합니다. 결제, 게시물 작성, 데이터 삭제처럼 실제 결과가 발생하는 작업은 실행 전에 내용을 검토하는 것이 안전합니다.
웹사이트 개발과 테스트를 자주 한다면 지금 터미널에서 agent-browser --help를 실행해 설치 상태부터 확인해 보세요. 이후 Claude Code에 간단한 페이지 접속 및 메뉴 테스트를 요청하면 실제 활용 방법을 익히기 좋습니다.