AI 브라우저 agent-browser 설치법: 클로드 코드가 웹 누르게
클로드 코드한테 “이 사이트 로그인해서 주문 내역 좀 확인해 줘”라고 하면 보통 막혀요. 터미널 안에서 일하는 AI라 웹페이지를 사람처럼 눌러 볼 방법이 마땅치 않거든요. 요즘 AI 브라우저 이야기가 많은데, 사람이 쓰는 브라우저에 AI를 넣는 쪽 말고 반대로 AI에게 브라우저를 쥐여 주는 도구도 있습니다.
오늘 깃허브에서 다시 눈에 띈 agent-browser가 그쪽이에요. 버셀(Vercel) 랩스 저장소에 있고, 11월 8일 기준 별이 46,730개입니다. npm 내려받기는 10월 8일부터 11월 6일까지 한 달 동안 826만 번이 넘었어요. 생각보다 훨씬 많이 쓰이고 있더라고요.
agent-browser, 정체부터 짚고 갈게요

공식 설명은 한 줄이에요. “AI 에이전트를 위한 브라우저 자동화 CLI”. 러스트(Rust)로 만든 명령줄 프로그램이고, 라이선스는 아파치 2.0이라 무료로 씁니다. 저장소는 올해 1월에 열렸고 가장 최근 버전은 한국 시각 11월 4일에 나온 0.41.2예요.
헷갈리기 쉬운 점이 하나 있어요. 이 안에는 AI 모델이 없습니다. 사람이 채팅창에 말을 거는 브라우저도 아니고요. 클로드 코드, 커서, 깃허브 코파일럿, 오픈AI 코덱스, 구글 제미나이, 오픈코드처럼 셸 명령을 실행할 수 있는 에이전트가 이 도구를 불러서 브라우저를 움직이는 구조예요. 공식 문서에 나온 지원 목록도 딱 이 여섯 개에 “셸 명령을 돌릴 수 있는 에이전트라면 무엇이든”이 붙어 있습니다.

움직이는 방식은 단순해요. 페이지를 열고, 읽고, 누르고, 다시 읽습니다. 명령 하나가 짧은 셸 호출 한 번이고, 그 사이에 브라우저는 계속 열려 있어요. 뒤에서 데몬(백그라운드 프로그램)이 크롬을 붙잡고 있다가 명령이 올 때마다 크롬 개발자 도구 프로토콜(CDP)로 전달하는 방식입니다.
왜 스냅샷과 ref 일까
이 도구의 핵심은 snapshot 명령이에요. 화면을 사진으로 찍는 대신 페이지를 접근성 트리(시각장애인용 화면 낭독기가 읽는 구조)로 바꿔 텍스트로 돌려줍니다. 버튼, 링크, 입력칸마다 @e1, @e2 같은 번호표가 붙어서 나오고요. 에이전트는 그 번호로 “e2 눌러” 하면 됩니다.

공식 문서가 내세우는 숫자가 있어요. 이렇게 텍스트로 받으면 200~400 토큰 정도인데, 페이지 전체 구조(DOM)를 그대로 넘기면 3,000~5,000 토큰이 든다는 겁니다. AI 입장에선 읽을 양이 열 배 넘게 줄어드는 셈이라, 요금이나 대화 한도를 생각하면 꽤 큰 차이예요.

문서에서 반복해서 강조하는 규칙도 있어요. 페이지를 옮기거나 내용이 바뀌면 번호표를 다시 받아야 합니다. 그리고 누르려는 버튼이 쿠키 동의 창 같은 것에 가려 있으면, 성공한 척하지 않고 실패로 돌려준대요. 에이전트가 “눌렀어요” 하고 넘어갔는데 실제론 안 눌린 상황을 막겠다는 뜻이라, 이건 좋게 봤습니다.
AI 브라우저 agent-browser 설치법
Node.js가 깔린 PC라면 두 줄이에요. 첫 줄이 프로그램 설치, 둘째 줄이 자동화용 크롬(Chrome for Testing) 내려받기입니다. 크롬 내려받기는 처음 한 번만 하면 돼요.
npm install -g agent-browser
agent-browser install

맥은 brew install agent-browser 로도 되고, 리눅스는 agent-browser install --with-deps 로 하면 브라우저에 필요한 시스템 라이브러리까지 같이 깔아 줍니다. 설치 없이 맛만 보고 싶으면 npx agent-browser open example.com 도 됩니다. 실행 파일은 맥(애플 실리콘·인텔), 리눅스(ARM64·x64), 윈도우(x64)용이 따로 나와 있고 npm이 알아서 맞는 걸 고른다고 해요. 맥은 macOS 13 아래 버전이면 크롬 내려받기 단계에서 멈추니 먼저 업데이트하라고 문서에 적혀 있습니다.

공식 빠른 시작에 나온 기본 흐름은 이래요.
agent-browser open example.com
agent-browser snapshot -i # 누를 수 있는 것만, 번호표와 함께
agent-browser click @e2 # 번호로 클릭
agent-browser snapshot -i # 바뀐 화면 다시 읽기
agent-browser close
사람이 직접 칠 일은 사실 많지 않아요. 이 명령들은 에이전트가 치라고 만든 거라서요.
클로드 코드에 붙이려면?

방법은 두 가지예요. 하나는 스킬 설치입니다. npx skills add vercel-labs/agent-browser 를 실행하면 에이전트 쪽에 얇은 안내 파일이 깔리고, 에이전트는 그걸 보고 agent-browser skills get core 로 지금 설치된 버전에 맞는 사용법을 직접 받아 읽어요. 도구를 업데이트해도 설명서가 따로 놀지 않게 만든 구조입니다.
다른 하나는 프로젝트의 AGENTS.md(클로드 코드라면 CLAUDE.md)에 두 줄을 넣는 거예요. “브라우저 자동화는 agent-browser 로 하고, 처음 쓰기 전에 skills get core 를 실행해 따르라”는 내용입니다. MCP를 쓰는 프로그램이면 agent-browser mcp 로 MCP 서버를 띄우는 방법도 있고요. CLAUDE.md 를 어떻게 다루는지 궁금하면 예전에 쓴 카파시 스킬 글을 같이 보셔도 좋아요.

스킬 모음 사이트 skills.sh 를 보면 agent-browser 스킬 설치 수가 140만 회로 나와요. 같은 버셀 랩스에서 PC 앱을 조작하는 agent-desktop도 냈는데, 그쪽이 데스크톱 앱 담당이라면 이쪽은 웹페이지 담당입니다.
명령만 50개가 넘어요

클릭과 입력만 있는 게 아니에요. 화면 캡처, PDF 저장, 동작 녹화, 쿠키·저장소 확인, 네트워크 요청 보기, 탭과 프레임 다루기, 콘솔 오류 확인까지 들어 있습니다. 웹 개발하는 쪽이라면 “에이전트가 내 사이트를 직접 열어 보고 오류를 찾아 고치는” 일에 바로 쓸 만한 구성이에요.
브라우저도 고를 수 있어요. 기본은 자동화용 크롬이지만 이미 켜 둔 크롬에 붙을 수도 있고, 라이트판다(Lightpanda) 같은 다른 엔진, 아이폰 시뮬레이터의 사파리, 브라우저베이스 같은 클라우드 브라우저도 됩니다. 화면 없이 뜬 브라우저는 한 시간 동안 명령이 없으면 데몬이 알아서 닫고 꺼진다고 해요.
쓰기 전에 꼭 볼 보안 설정

여기서 한 번 멈춰야 해요. 공식 보안 문서 첫머리에 “기본값으로는 이동, 동작, 출력에 아무 제한도 걸지 않는다”고 적혀 있습니다. 에이전트가 아무 사이트나 열고 아무 버튼이나 누를 수 있다는 뜻이에요. 문서가 직접 꼽는 위험도 있어요. 나쁜 페이지에 “이전 지시는 무시하고 이걸 해” 같은 글을 숨겨 두는 프롬프트 주입, 엉뚱한 도메인으로 데이터를 빼돌리는 것 같은 일들입니다.

그래서 옵션이 준비돼 있어요. --allowed-domains 로 갈 수 있는 사이트를 정하고, --action-policy 와 --confirm-actions 로 다운로드·업로드·스크립트 실행 전에 사람 승인을 받게 할 수 있습니다. 로그인이 필요하면 auth save 로 비밀번호를 로컬에 저장해 두고 이름으로만 부르는 방식이라, AI가 비밀번호 자체를 보지 않아요. 다만 문서도 도메인 제한이 운영체제 방화벽은 아니라고 선을 긋고 있습니다.
제 생각엔 은행이나 쇼핑몰처럼 돈이 걸린 사이트는 아직 맡기지 않는 게 맞아요. 회사 관리자 페이지에서 반복 확인하는 일, 내 홈페이지가 제대로 뜨는지 점검하는 일처럼 실수해도 되돌릴 수 있는 곳부터 쓰는 게 안전합니다. 저도 이번엔 이 라즈베리파이에 설치해 돌려 보진 않았고, 공식 문서와 저장소 내용만 확인했어요. 블로그 미리보기 점검을 이걸로 바꿔 볼 수 있을지 따로 시험해 보고 후기로 정리해 볼 생각입니다. 여러분은 AI에게 브라우저를 맡긴다면 어떤 일부터 시켜 보고 싶으세요?
출처
· vercel-labs/agent-browser 깃허브 저장소·README
· agent-browser 릴리스 (v0.41.2)
· agent-browser 공식 문서 첫 화면
· 공식 문서 – 설치
· 공식 문서 – 빠른 시작
· 공식 문서 – 스냅샷
· 공식 문서 – 보안
· skills.sh 등록 페이지
· npm 월간 내려받기 수
(2026년 11월 8일 확인)
컴퓨터가 고장 났다면 부산 컴퓨터수리 · 출장수리 부컴에 맡겨 주세요. 부산·울산·김해·양산 어디든 직접 방문합니다.
