Claude Code로 Chrome 브라우저 자동화 켜기: 오늘 만들 설치·검증 체크리스트

"Claude Code가 브라우저를 직접 열어서 웹 화면을 눌러보고 테스트하게 만들고 싶은데, 어디서부터 손대야 하지?" 이 글은 그 질문에 답합니다. 결론부터 말하면, Chrome 연동(웹 자동화·테스트를 위해 Claude가 크롬을 다루는 기능)을 켜기 전에 설치·버전·인증 상태를 확인하는 작은 체크리스트 파일을 먼저 만드는 게 가장 안전합니다. 이 글이 오늘 남기는 산출물이 바로 그 체크리스트입니다.

왜 기능부터 켜지 말아야 할까

zebbern/claude-code-guide는 Claude Code의 설치, 명령어, MCP, 자동화, 문제 해결을 한곳에 모은 커뮤니티 가이드입니다(원문: https://github.com/zebbern/claude-code-guide). 이 가이드는 "웹 자동화와 테스트를 위해 Chrome 브라우저 연동을 켜라(Enable Chrome browser integration for web automation and testing)"고 안내하면서, 동시에 문제 해결 항목에서 "Anthropic API 키가 CLI에서 접근 가능한지 확인하라(Verify your Anthropic API key is available to the CLI)"고 짚습니다.

즉 브라우저 연동이 안 될 때 가장 흔한 막힘은 기능 자체가 아니라 그 아래의 기본기 — 설치가 제대로 됐는지, 인증이 CLI까지 닿는지 — 라는 뜻입니다. 그래서 기능 버튼을 먼저 누르기보다, 토대를 점검하는 순서가 함정을 줄입니다.

오늘 만들 산출물: setup-check.sh

아래는 직접 손에 남기는 검증 스크립트입니다. 프로젝트 폴더에 setup-check.sh로 저장하세요.

#!/usr/bin/env bash
# Claude Code Chrome 연동 전 사전 점검
echo "== 1. Node 설치 확인 =="
node --version || echo "Node 없음"

echo "== 2. npm 확인 =="
npm --version || echo "npm 없음"

echo "== 3. claude 패키지 최신 버전 확인 =="
npm view claude version

echo "== 4. API 키가 CLI에 보이는지 =="
if [ -n "$ANTHROPIC_API_KEY" ]; then
  echo "ANTHROPIC_API_KEY 설정됨"
else
  echo "ANTHROPIC_API_KEY 비어 있음 → 인증부터 해결"
fi

실행은 이렇게 합니다.

chmod +x setup-check.sh
./setup-check.sh

각 항목이 통과해야 하는 기준

점검 항목	통과 기준	막히면
Node 버전	숫자 버전이 출력됨 (예: 확인 환경에서 v25.6.1)	가이드의 Native Installer 사용
npm	버전 출력됨 (예: 11.9.0)	Node 재설치
claude 패키지	버전 문자열 출력됨 (예: 0.1.2)	네트워크/레지스트리 확인
API 키	"설정됨"으로 표시	"API 키가 CLI에 접근 가능한지 확인" 단계로

괄호 안 값은 macOS 한 대에서 확인한 예시일 뿐이며, 버전은 환경마다 다르니 숫자가 비어 있지 않은지만 보면 됩니다. 4번 항목에서 "비어 있음"이 나오면, 가이드가 말한 그 인증 문제에 정확히 걸린 상태입니다. 여기서 멈추고 인증부터 푸는 게 브라우저 연동으로 넘어가는 지름길입니다.

안 만들어도 되는 경우

이미 Claude Code로 다른 작업을 매끄럽게 쓰고 있고 claude 명령이 인증 오류 없이 도는 사람은 4번만 눈으로 확인하고 넘어가도 됩니다. 반대로 설치를 막 끝냈거나, 회사 PC처럼 환경 변수가 어떻게 설정됐는지 모르는 경우에는 이 스크립트가 "어디서 끊겼는지"를 한 줄로 보여줍니다.

네이티브 설치가 막힐 때

가이드는 Node.js 없이 쓰는 Native Installer(네이티브 설치 프로그램)를 가장 먼저 권합니다. macOS·Linux·WSL은 터미널 설치 스크립트, Windows는 CMD나 PowerShell 명령으로 받습니다. 1번에서 Node가 없다고 나와도 네이티브 설치 경로가 따로 있으니, "Node부터 깔아야 하나" 하고 멈출 필요는 없습니다. 정확한 설치 명령은 위 원문의 Quick Start에서 직접 확인하세요.

다음에 확인할 한 가지

체크리스트 4개가 모두 통과했다면, 그때 비로소 Chrome 연동을 켜고 간단한 웹 페이지 하나를 열어보게 시켜 보세요. 만약 그 단계에서 막힌다면, 새 기능을 의심하기 전에 이 스크립트의 4번(API 키가 CLI에 보이는가)을 다시 돌려 보는 것 — 그 한 줄이 가장 먼저 확인할 판단 기준입니다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 빌드
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독