Claude Code로 하는 브라우저 자동화: 실전 2026 가이드

이 도구 분야는 변화가 빨라서, 실행하기 전에 agent-browser skills get core --full 와 npx …@latest 로 최신 명령을 확인하세요.

Claude Code로 하는 브라우저 자동화란?

Claude Code로 하는 브라우저 자동화란, 모든 것을 손으로 일일이 클릭하는 대신 CLI, MCP 서버, 또는 확장 프로그램을 통해 Claude Code 에이전트가 실제 브라우저를 조작하도록(이동, 클릭, 폼 입력, DOM과 콘솔 읽기, 스크린샷 촬영, 데이터 추출) 맡기는 것을 뜻해요. 간단히 말하면 AI가 브라우저를 조작하는 것이에요. 원하는 바를 평이한 영어로 설명하면, Claude Code가 그것을 웹 동작으로 바꿔서 대신 실행해 줘요.

개발자에게 이게 왜 필요할까요? 실제 상황 몇 가지를 들어볼게요. 로그인 플로우의 E2E 테스트 실행, 폼을 입력하고 제출해 유효성 검사 확인, 컴포넌트를 만든 직후 UI 검증, 또는 데이터 테이블을 스크래핑해 교차 확인하기 같은 것들이에요. 예전에는 Playwright나 Puppeteer 스크립트를 손으로 작성했지만, 이제는 Claude Code가 그 동작들을 스스로 만들어 실행하고, 결과(콘솔 로그, DOM 구조)를 읽은 다음 뭔가 망가지면 스스로 고칠 수 있어요.

이 도구가 처음이라면, 먼저 Claude Code가 무엇인지 부터 시작해 에이전트와 권한 개념에 익숙해지는 게 좋아요. 브라우저 자동화는 당신을 대신해 행동할 권한을 AI에게 주는 것과 곧바로 이어지기 때문이에요.

Claude Code가 브라우저를 조작하는 4가지 방법(알맞은 도구 고르기)

가장 헷갈리는 점은, 방법이 네 가지인데 각 도구의 문서가 이들을 나란히 비교해 주지 않는다는 거예요. 처음부터 제대로 고를 수 있도록 간단한 안내도를 드릴게요. 넷 중 셋은 MCP(Model Context Protocol) 에 의존해요. 이는 Claude Code가 외부 도구에 연결할 때 쓰는 표준 프로토콜이에요.

방법 4는 별도 섹션을 둘 만큼 깊이가 있어요. 바로 아래를 보세요.

대부분의 개발자에게 agent-browser 는 합리적인 기본 선택이에요. 가볍고 토큰 효율이 좋으며, Playwright 스택 전체를 끌어들이지 않고도 오래 동작해요. 이어지는 세 섹션에서 설치와 사용법을 자세히 다뤄요. Playwright MCP는 claude mcp add playwright npx @playwright/mcp@latest 로 빠르게 추가할 수 있고, Chrome DevTools MCP는 claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest 로 추가할 수 있어요(microsoft/playwright-mcp 와 ChromeDevTools/chrome-devtools-mcp 의 README 기준, 2026년 8월 확인).

Claude Code를 위한 agent-browser 설치

설정은 빠르게 끝나요. agent-browser 는 vercel-labs의 오픈소스 CLI이고, 아래 단계는 2026년 8월 9일에 실제로 확인한 것이에요.

# 1. Install the CLI globally
npm install -g agent-browser

# 2. Download the Chromium that agent-browser drives
agent-browser install
# On Linux, if system libraries are missing:
agent-browser install --with-deps

# 3. Confirm the install worked
agent-browser --version

# 4. Load the core workflow set for Claude Code
agent-browser skills get core
# For the full command reference:
agent-browser skills get core --full

4단계는 워크플로 설명을 불러와, Claude Code가 알맞은 맥락에서 agent-browser 를 호출할 수 있게 해요. 마지막으로, 권한 설정에 허용 도구 Bash(agent-browser:*) 를 선언해서 Claude Code가 명령을 실행할 수 있게 하세요. 그러지 않으면 실행할 때마다 직접 승인해야 해요. 나중에 agent-browser upgrade 로 업데이트하세요.

단계별로 보는 Claude Code 브라우저 자동화

아래 네 단계가 핵심 작업 루프예요. 중심 아이디어는 스냅샷을 찍어 각 요소의 @eN 참조를 얻은 다음, 그 참조를 통해 동작하는 것이에요 — 길고 잘 깨지는 CSS 선택자를 작성하는 대신에요.

1단계 - 페이지를 열고 스냅샷 찍기

agent-browser open https://example.com
agent-browser snapshot -i

snapshot -i 는 각 상호작용 요소에 @e1, @e2 같은 짧은 참조를 붙인 접근성 트리를 반환해요. 각 스냅샷이 약 280자에 불과하므로(Playwright MCP의 8K 이상 대비) Claude Code가 빠르게 읽고 토큰도 거의 쓰지 않아요 — 바로 이 점이 에이전트가 맥락을 넘치게 하지 않으면서 여러 단계를 연달아 이어갈 수 있는 이유예요.

2단계 - 클릭, 폼 입력, 이동

# Fill the email field (ref taken from the snapshot)
agent-browser fill @e3 "[email protected]"
# Click the login button
agent-browser click @e7

항상 가장 최근 스냅샷의 참조로 동작하세요. 솔직한 주의사항 하나: @eN 참조는 현재 렌더링에 묶여 있어요. 페이지 상태가 바뀌면(탭 전환, 모달 열기, 새로고침) 스냅샷을 새로 찍으세요. 예전 참조가 이제 엉뚱한 요소를 가리킬 수 있으니까요.

3단계 - 스크린샷과 데이터 추출(스크래핑)

# Save an image of the current state for a visual check
agent-browser screenshot result.png
# Take a snapshot to extract DOM structure and text
agent-browser snapshot -i

스냅샷에서 Claude Code는 콘텐츠(예: 상품 목록이나 가격표)를 읽고 요약해, 터미널에서 바로 JSON이나 Markdown 표로 만들 수 있어요.

4단계 - 셀프 체크 루프(만들고, 검증하고, 디버깅하기)

여기가 가장 값진 부분이자, 다른 가이드들이 한 문장으로만 언급하는 부분이에요. 흐름은 이래요. 당신이 터미널에서 만들고, Claude Code가 브라우저를 열어 결과를 검증하고, 콘솔과 DOM을 읽고, 뭔가 잘못됐으면 스스로 고쳐 다시 실행해요. 구체적으로는:

1. Claude Code가 코드를 수정하고 개발 서버를 시작해요.
2. agent-browser open http://localhost:3000 로 방금 만든 UI를 열어요.
3. agent-browser snapshot -i 로 기대한 요소가 나타났는지 확인하고, 콘솔을 읽어 런타임 오류를 잡아요.
4. 뭔가 어긋나면 Claude Code가 코드를 수정하고 페이지를 새로고침한 뒤, UI가 올바를 때까지 반복해요.

이 루프가 바로 “AI가 코드를 작성한다”를 “AI가 실제 브라우저에서 자기 코드를 검증한다”로 바꾸는 거예요.

실전 예시: 데모 사이트에 로그인하고 UI 검증하기

데모 작업은 이래요. 데모 사이트에 로그인한 뒤, 대시보드에 올바른 사용자 이름이 표시되는지 확인해요. 이것을 실제 E2E 테스트로 키울 수 있는 템플릿으로 사용하세요.

# Plain-English request you send to Claude Code:
# "Open the demo login page, sign in with the test account,
# then check that the dashboard shows the right name."

agent-browser open https://practice.expandtesting.com/login
agent-browser snapshot -i # get refs for the input fields + button
agent-browser fill @e2 "practice"
agent-browser fill @e3 "SuperSecretPassword!"
agent-browser click @e4 # the Login button
agent-browser snapshot -i # confirm you reached the secure page

경험에 대한 솔직한 한마디: fill과 click 단계는 단순한 폼에서는 대체로 매끄럽게 동작해요. 발목을 잡기 쉬운 건 페이지가 바뀐 뒤 참조가 오래되는 것이에요 — Login을 클릭하면 보안 페이지는 새로운 DOM이라서, 검증하기 전에 snapshot -i 를 다시 실행해야 해요. 로그인 페이지의 참조를 재사용하지 마세요. captcha나 2단계 인증이 있는 사이트에서는 agent-browser 만으로는 부족해요. 그럴 때 실제 로그인된 세션이 필요해요(아래 chrome-profile 섹션 참고).

클라우드와 CI/CD에서 실행하기(로컬 브라우저 불필요)

CI 파이프라인 안이나 Chrome이 없는 머신에서 실행할 때는, 로컬에 Chromium을 설치하는 대신 agent-browser를 클라우드 브라우저로 향하게 해요:

# Browserbase: set the environment variables, then add the provider with -p
export BROWSERBASE_API_KEY=...
export BROWSERBASE_PROJECT_ID=...
agent-browser -p browserbase open https://example.com

Browserbase 외에도 agent-browser는 일회성 환경을 위해 AWS Bedrock AgentCore와 Vercel Sandbox도 지원해요. 실행 중인 세션(세션, 로그)을 관찰하기 위해 agent-browser는 포트 4848 에 관측 대시보드를 제공해요. 이는 개발 머신에서 손으로만 돌리는 대신, 브라우저 테스트를 자동화 파이프라인으로 옮기기 위한 토대예요.

agent-browser 대 chrome-profile: 실제 Chrome이 필요한 건 언제?

핵심 판단은 이거예요. 그 작업이 실제 로그인된 세션과 쿠키를 필요로 하나요, 아닌가요?

요컨대, 기본은 agent-browser 를 쓰고, 실제 로그인된 세션을 정말로 빌려야 할 때만 chrome-profile 로 바꾸세요 — 실제 계정 위에서 동작하기 때문에 위험이 더 커요.

Chrome에서 바로 실시간 디버깅: --chrome, /chrome

이건 위 표의 4번째 방법으로, 별도 섹션을 둘 만큼 깊이가 있어요. agent-browser, Playwright MCP, Chrome DevTools MCP 는 모두 일회용의 CDP 제어 브라우저를 조작하지만, 그와 달리 네이티브 Chrome 통합은 “Claude in Chrome” 확장 프로그램을 통해 당신의 실제 Chrome 안에서 동작하고, (헤드리스가 아니라) 눈에 보이는 탭을 열며, 당신의 실제 로그인된 세션을 사용해요. 이는 별도 제품이 아니라, CLI나 VS Code를 확장 프로그램에 연결하는 Claude Code의 네이티브 기능이에요.

claude --chrome 로 실행하세요. 처음에는 사이트 권한이 어떻게 작동하는지 설명하는 일회성 대화상자가 떠요 — Enter로 계속하세요. 매 세션마다 플래그를 넘기는 수고를 덜려면 /chrome 를 실행하고 “Enabled by default(기본으로 활성화)”를 선택하세요 — 절충점은 브라우저 도구가 계속 로드된 채 있어 매 세션마다 추가 컨텍스트 비용이 든다는 것이니, 자주 쓰는 경우에만 켜세요. /chrome 는 연결 상태 확인, 사이트 권한 관리, 확장 프로그램 재연결, 그리고 둘 이상이 연결됐을 때 사용할 브라우저 선택에도 써요(브라우저 선택에는 Claude Code v2.1.154 이상이 필요해요).

평이한 영어 프롬프트 예시(문서 자체의 예시를 그대로 옮긴 것):

Go to code.claude.com/docs, click on the search box,
type "hooks", and tell me what results appear

문서에는 8개의 기능 그룹이 나열돼 있는데, 개발자에게 가장 관련 있는 셋은 다음과 같아요:

• 실시간 디버깅 - 콘솔 오류와 DOM 상태를 직접 읽고, 그 원인이 된 코드를 곧바로 고쳐요. 이것이 코딩 워크플로에서 가장 유용한 기능이며, 이번 개정 전의 글에서는 완전히 빠져 있었어요.
• 디자인 검증 - Figma 목업으로 UI를 만든 뒤, 브라우저에서 열어 일치하는지 확인해요.
• 인증된 웹 앱 - Gmail, Google Docs, Notion, 또는 이미 로그인된 사내 앱에서 API 커넥터를 설정할 필요 없이 작업해요.
• 이 밖에도 포함돼요: 웹 앱 테스트(폼 유효성 검사, 시각적 회귀), 구조화된 데이터 추출, 반복 작업 자동화, 파일 업로드(10MB 한도, node_modules 내부처럼 하드 링크가 여러 개인 파일은 거부, v2.1.211 이상 필요), 그리고 세션을 공유 가능한 GIF로 녹화하기.

플랜 모드 안전성: 플랜 모드에서 읽기 전용 호출(read_page, get_page_text, find, 콘솔/네트워크 읽기, 스크린샷 촬영)은 확인 없이 실행되지만, 상태를 바꾸는 호출(클릭, 입력, 이동, 탭/창 관리, GIF 녹화)은 여전히 승인을 요구해요.

실제 예시: “망가진 로그인 폼 디버깅하기” - localhost:3000 을 열고, Claude Code에게 잘못된 데이터로 폼을 제출하게 하고, 콘솔에 뜨는 내용을 읽고, 그 원인이 된 코드의 수정안을 제안하게 해요. 여기서는 특별한 CLI 문법이 필요 없어요 — 위 두 프롬프트와 같은 방식의 평이한 영어 요청이면 돼요.

지름길 - AgentKit에는 ak-agent-browser 스킬이 들어 있어요

각 도구를 직접 세우고 설정하기 번거롭다면, 지름길이 있어요. AgentKit 번들(Engineer Kit)에는 관련된 두 스킬이 함께 묶여 있어요: ak-agent-browser(내부에서 agent-browser CLI를 감싸요)와 ak-chrome-profile 이에요 — 평이한 영어 요청을 입력하면 실행되고, 플래그를 외울 필요가 없어요.

이름에 대한 참고: 여기서 “AgentKit”은 ak CLI를 쓰는 agentkit.best의 Claude Code용 키트를 가리키며, OpenAI의 “AgentKit” 제품이 아니에요. 그리고 agent-browser 는 이 스킬 밑에 있는 오픈소스 CLI(vercel-labs)예요.

이건 편리한 지름길일 뿐 필수는 아니에요. 위 섹션에서 보여드린 그대로, agent-browser 를 무료로 그대로 쓸 수도 있어요.

흔한 오류와 해결 방법

AI에게 브라우저를 맡길 때 안전 지키기

브라우저 제어를 AI에게 넘기면 실제 공격 표면이 열려요: 프롬프트 인젝션 - 웹 페이지의 악의적 콘텐츠가 당신이 의도하지 않은 일을 에이전트가 하도록 속이는 거예요. Anthropic이 Claude for Chrome을 발표할 때 밝힌 바에 따르면, 방어를 추가한 뒤 프롬프트 인젝션 공격 성공률이 23.6%에서 11.2%로 떨어졌고, 브라우저 특유의 한 부류의 공격에 대해서는 자체 챌린지 세트에서 35.7%에서 0%로 떨어졌어요(claude.com/blog/claude-for-chrome, 2025년 8월).

안전하게 자동화하기 위한 실용 원칙:

• 권한은 전역이 아니라 사이트별로 부여하세요.
• 위험도가 높은 동작 전에는 확인을 필수로 하세요: 게시, 이메일 전송, 데이터 공유, 결제.
• 민감한 데이터나 중요한 계정이 있는 페이지에서 에이전트가 독자적으로 행동하지 않게 하세요.
• 로그인이 필요 없는 작업에는 일회용 브라우저(agent-browser)를 우선하고, 실제 세션(chrome-profile)은 꼭 필요할 때만 쓰세요.

네이티브 Chrome 통합에서는 위의 “동작별로 권한 부여” 원칙이 단순한 일반론이 아니에요 — 플랜 모드가 바로 그 메커니즘을 강제해요. 읽기 전용 호출은 자유롭게 실행되고, 상태를 바꾸는 호출은 항상 확인을 요구해요(자세한 내용은 위의 --chrome//chrome 섹션 참고).

자주 묻는 질문(FAQ)

agent-browser와 Playwright MCP 중 뭐가 더 좋아요?

필요한 바에 따라 달라요. agent-browser 는 간결한 스냅샷(약 280자, Playwright MCP의 8K 이상 대비) 덕분에 가볍고 토큰 효율이 좋아서, 길고 자율적인 실행에 잘 맞아요. Playwright MCP는 이미 Playwright 생태계를 알고 있고 많은 도구(네트워크, 스토리지, PDF)를 바로 쓰고 싶다면 강력해요. 대부분의 개발자에게는 agent-browser 가 무난한 기본 선택이에요.

Playwright를 알아야 하나요?

아니요. agent-browser 는 Playwright나 Puppeteer 위에 만들어지지 않았어요. 평이한 영어로 요청하고 스냅샷의 @eN 참조를 통해 동작하므로, Playwright 스크립트를 손으로 작성할 필요가 없어요.

헤드리스 / CI에서 실행할 수 있나요?

네. CI나 로컬 브라우저가 없는 머신에서는 agent-browser를 Browserbase(agent-browser -p browserbase open …), AWS Bedrock AgentCore, 또는 Vercel Sandbox 같은 클라우드 브라우저로 향하게 하세요.

이미 로그인된 페이지를 자동화할 수 있나요?

네, 다만 실제 로그인된 세션과 쿠키를 빌리려면 chrome-profile 를 써야 해요. agent-browser 는 기본적으로 일회용 브라우저를 실행하는데, 실제 계정이 필요 없을 때는 이게 올바른 선택이에요.

AI에게 브라우저를 맡겨도 안전한가요?

프롬프트 인젝션 위험이 있지만 관리할 수 있어요: 권한은 사이트별로 부여하고, 위험한 동작 전에는 확인하고, 민감한 페이지는 피하세요. 공급업체들도 공격 성공률을 크게 낮추는 방어를 추가했어요(안전 섹션 참고).

AgentKit에 이 스킬이 포함되나요?

네. AgentKit 번들(Engineer Kit)에는 ak-agent-browser 와 ak-chrome-profile 스킬이 들어 있어, 수동 설정을 건너뛸 수 있어요. 이는 선택적 지름길이지, agent-browser를 쓰기 위한 필수 요건이 아니에요.

--chrome 는 비교표의 “Claude for Chrome”과 어떻게 다른가요?

같은 확장 프로그램이에요. --chrome 는 CLI에서 통합을 켜는 플래그(또는 /chrome 를 실행해 기본으로 활성화)이고, 표의 “Claude for Chrome”은 확장 프로그램을 가리킬 때 이 같은 기능을 부르는 또 다른 이름일 뿐이에요.

Chrome 통합이 Bedrock이나 Vertex를 통해 동작하나요?

아니요. 직접 가입한 Anthropic 계정(/login 으로 로그인)이 필요하며, Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 같은 서드파티 제공업체를 통해서는 이용할 수 없어요. 회사가 이들 중 하나를 통해서만 Claude를 이용한다면, Chrome 기능에는 별도의 claude.ai 계정이 필요해요.

결론과 다음 단계

기본은 agent-browser 로 하세요: 가볍고 토큰 효율이 좋으며, 테스트, 폼 입력, 스크래핑에서 자율적으로 잘 동작해요. 실제 로그인된 세션이 필요할 때만 chrome-profile 로 바꾸고, 성능을 측정해야 할 때는 Chrome DevTools MCP를 고려하고, 코딩 중 실시간 디버깅/검증만 필요하고 헤드리스나 CI가 필요 없다면 --chrome 가 가장 빠른 지름길이에요 — 확장 프로그램 외에는 설치할 게 없어요. 그 아래에 있는 프로토콜 계층을 이해하려면 MCP가 무엇인지 를 이어서 읽어 보세요. Claude Code용으로 나만의 도구를 만들려면 Claude Code용 MCP 서버 만드는 법 을 참고하세요.