웹사이트 네트워크 트래픽을 API 스펙으로 바꾸려면, 코딩 에이전트가 OpenCode Browse로 실제 브라우저를 조작하게 하면 됩니다. 에이전트가 탭에서 network 캡처를 시작하고, 로그인된 상태로 사이트를 클릭해서 탐색하면, 에이전트가 캡처를 중단하면서 자격 증명은 삭제된 채 모든 요청을 수집합니다. 그런 다음 에이전트가 이 교환 내용을 바탕으로 OpenAPI 파일을 작성하고, Apidog CLI가 이를 임포트하여 테스트를 실행합니다.
이 가이드는 에이전트 프롬프트 하나로 이 흐름 전체를 다룹니다. Browse가 무엇을 캡처하는지, 무엇을 숨기는지, 그리고 작업을 마무리하는 apidog 명령어가 무엇인지 알아봅니다.
OpenCode Browse란 무엇인가?
OpenCode Browse는 코딩 에이전트가 여러분의 실제 브라우저를, 즉 열려 있는 탭, 로그인 세션, 확장 프로그램까지 그대로 사용할 수 있게 해주는 MCP 서버와 Chromium 확장 프로그램입니다. 에이전트는 백그라운드 탭을 열고, 페이지를 읽고, 클릭하고, 입력하고, 스크린샷을 찍고, 탭을 녹화하고, 네트워크 트래픽을 캡처할 수 있습니다. 사용자의 개입이 필요한 단계(로그인, 2FA 인증, 결제 등)에서는 에이전트가 탭을 사용자에게 넘기고 Continue를 클릭할 때까지 기다립니다.

| 항목 | 출처 내용 |
|---|---|
| 라이선스 | MIT (저장소의 LICENSE 파일) |
| 첫 공개 코드 | 저장소 생성일: 2026년 10월 27일 |
| 현재 릴리스 | v0.1.0, 2026년 11월 16일 배포 (단일 Rust 바이너리로 재작성) |
| 지원 브라우저 | Chrome, Edge, Brave, Arc, Helium, Vivaldi, Opera, Chromium |
| 지원 에이전트 | OpenCode, Claude Code, Codex, Cursor, Zed 등 약 30개 이상의 MCP 클라이언트 |
| 가격 | 제품 페이지에 명시되지 않음 |
제품 페이지에는 가격이나 출시일이 표시되어 있지 않으므로, 현재 시점에서 확인할 수 있는 비용 관련 유일한 신호는 MIT 라이선스입니다. DevTools 방식과 비교하고 싶다면, Claude와 함께 사용하는 Chrome DevTools MCP 가이드에서 대안을 다룹니다.
왜 실제 브라우저에서 트래픽을 캡처해야 할까?
대부분의 문서화되지 않은 API는 로그인 뒤에 숨어 있습니다. 헤드리스 브라우저는 쿠키 없이 시작하기 때문에 에이전트가 로그인 벽에 막히게 됩니다. Browse는 여러분이 이미 사용 중인 프로필 안에서 동작하므로, 에이전트는 사용자와 동일한 인증된 요청을 볼 수 있습니다. 이는 다음 세 가지 작업에 유용합니다:
- 스펙이 없던 내부 도구를 문서화하여, 새 팀원들이 난독화된 JavaScript를 읽지 않도록 합니다.
- 공개 API가 자체 프런트엔드보다 기능이 적은 SaaS 대시보드에 대한 통합을 구축합니다.
- 백엔드를 리팩토링하기 전에 웹 앱의 회귀 테스트를 작성합니다.
수동 방식은 DevTools에서 HAR을 내보내는 것입니다. API 리버스 엔지니어링 가이드를 참고하세요. 에이전트 방식은 이 스펙을 대신 작성해 줍니다.

웹사이트 네트워크 트래픽을 API 스펙으로 바꾸는 5단계
- Browse를 설치하고 확장 프로그램을 브라우저와 페어링합니다.
- 에이전트에게 Browse 탭에서 사이트를 열고 XHR과 Fetch로 필터링된
network캡처를 시작하도록 요청합니다. - 문서화하려는 기능들을 클릭해서 탐색한 뒤, 에이전트에게 캡처를 중단하라고 지시합니다.
- 에이전트가 교환 내용을 경로별로 그룹화하여
openapi.json을 작성하게 합니다. - Apidog CLI로 스펙을 임포트하고, 테스트 케이스를 만들어 실행합니다.
1단계: Browse 설치 및 에이전트 연결
macOS와 Linux에서는 한 줄 스크립트로 Browse를 설치합니다:
curl -fsSL https://opencode.ai/browse/install | bash
Windows에서는 PowerShell에서 irm https://opencode.ai/browse/install.ps1 | iex를 실행하세요. npm i -g @opencode/browse로 설치한 뒤 browse install을 실행하는 방법도 있습니다.
browse install은 바이너리를 설치하고, 감지된 에이전트들에 Browse MCP 서버를 추가하며, Chrome 웹 스토어 확장 프로그램을 페어링합니다. 대화형 선택기를 건너뛰려면:
browse install -a claude codex # Claude Code와 Codex만
browse install -y # 이 컴퓨터에서 발견된 모든 에이전트
설치 후 에이전트를 재시작하세요. browse status로 릴레이, 확장 프로그램, 페어링 상태가 정상인지 확인할 수 있습니다.
에이전트의 동작 방식을 바꾸는 세부 사항이 하나 있습니다. OpenCode는 일반 도구(navigate, snapshot, click, network 등)를 받습니다. Claude Code, Codex, Cursor 등 다른 클라이언트는 execute, status, tabs를 받으며, 여기서 execute는 모든 Browse 도구를 호출할 수 있는 JavaScript를 실행합니다. 어느 쪽이든 에이전트는 동일한 network 캡처에 접근합니다.
2단계: 필터링된 네트워크 캡처 시작
network 도구는 start, status, stop, cancel 중 하나의 action을 받으며, 탭당 하나의 캡처만 가능합니다. start 시 기록 범위를 좁힐 수 있습니다:
| 옵션 | 설명 | 기본값 |
|---|---|---|
urlFilter |
이 텍스트를 포함하는 URL만 캡처 | 없음 |
resourceTypes |
지정된 타입만 캡처, 예: ["XHR", "Fetch"] |
모든 타입 |
methods |
지정된 HTTP 메서드만 캡처 | 모든 메서드 |
bodies |
요청/응답 본문 캡처 | true |
maxDurationMs |
이 시간이 지나면 캡처를 종료하고 폐기 | 1,800,000 (30분) |
XHR과 Fetch로 필터링하고, /api/ 같은 urlFilter를 추가하여 분석 비콘을 제외하세요. 호출은 다음과 같습니다:
{
"action": "start",
"tab": "<tabId>",
"resourceTypes": ["XHR", "Fetch"],
"urlFilter": "/api/"
}
에이전트가 한 사이트에 머물게 하려면 allowedOrigins와 함께 탭을 여세요. Browse의 README는 이것이 탐색을 제한할 뿐 페이지가 스스로 보내는 요청까지 막지는 못한다고 분명히 밝히고 있습니다. 즉, 데이터 경계가 아니라 안전장치입니다.
3단계: 사이트 탐색 후 캡처 중단
이제 에이전트의 탭에서 사이트를 사용합니다. 목록을 열고, 필터를 적용하고, 상세 페이지를 보고, 테스트 레코드를 만들고 삭제해 보세요. 도중에 로그인이 필요하면 에이전트가 handoff를 호출하고, 사용자가 로그인을 마친 뒤 Continue를 클릭합니다.
작업이 끝나면 에이전트가 {"action": "stop"}을 보냅니다. 그러면 메서드, URL, 헤더, 상태, 본문을 포함한 모든 교환 내용이 반환됩니다. 다음 제한 사항을 알아두세요:
- 캡처당 최대 1,000개의 요청.
- JSON, 폼, multipart 본문은 텍스트로 반환되며, 각각 최대 1 MB, 캡처당 총 25 MB까지 가능.
- HTML, 스크립트, CSS, 이미지는 절대 가져오지 않고 MIME 타입과 크기만 기술함.
자격 증명은 항상 [redacted]로 대체됩니다: authorization 및 API-key 헤더, 모든 쿠키 값, 비밀로 추정되는 이름의 쿼리·JSON·폼 필드, 토큰처럼 보이는 경로 세그먼트가 대상입니다. README는 일반적인 필드 이름 아래 숨어 있는 비밀은 그대로 노출될 수 있다고 경고하므로, 공유하기 전에 스펙을 직접 확인하세요.
계획에 반영해야 할 변경 사항 하나: 버전 0.0.17(2026년 11월 14일)에서 HAR 내보내기가 제거되었고, 이제 캡처는 삭제된 트래픽을 직접 반환합니다. HAR 파일이 필요하다면 DevTools에서 내보내고 Apidog로 HAR 파일 임포트하기 가이드를 활용하세요.
4단계: 에이전트가 OpenAPI 스펙 작성하게 하기
원시 트래픽은 스펙이 아닙니다. /api/orders/1042, /api/orders/877, /api/orders/15로의 호출은 하나의 경로인 /api/orders/{orderId}와 하나의 응답 스키마로 정리되어야 합니다. 코딩 에이전트는 바로 이런 작업, 즉 패턴을 파악하고 실제 응답에서 타입을 추론하는 데 탁월합니다.

임포트가 깔끔하게 되도록 에이전트에게 몇 가지 규칙을 따르라고 요청하세요:
- 메서드와 라우트 패턴당 하나의 경로로 OpenAPI 3.x JSON을 작성할 것.
- URL의 숫자 ID, UUID, 슬러그는 경로 파라미터로 변환할 것.
- 본인이 본 응답 본문을 바탕으로
components/schemas아래에 스키마를 만들고, 모든 샘플에 존재하는 필드만 required로 표시할 것. - 사이트가 사용하는 인증 방식(bearer, cookie, API key)을
securitySchemes아래에 실제 값 없이 선언할 것. info.title은 안정적인 이름으로 설정할 것. Apidog가 임포트 시 모듈 이름으로 사용함.
5단계: Apidog CLI로 스펙 임포트 및 테스트
openapi.json이 만들어지면 나머지는 같은 에이전트에게 맡기면 됩니다. Apidog CLI는 스펙 임포트, 테스트 케이스 생성 및 실행을 위한 명령어를 제공하며, 모든 명령은 에이전트가 읽을 수 있는 구조화된 JSON을 출력합니다.
한 번만 설정하세요:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
그런 다음 전체 작업을 다루는 프롬프트 하나를 에이전트에게 전달하세요:
Open https://app.example.com in a Browse tab limited to app.example.com.
Start a network capture for XHR and Fetch requests whose URL contains /api/.
Hand the tab to me, wait while I use the orders pages, then stop the capture.
Write openapi.json (OpenAPI 3.1, info.title "Example Orders API") with path
parameters for IDs and schemas from the real responses. Create an AI branch in
Apidog project <projectId>, import the spec there, create a test case for
GET /api/orders/{orderId} that asserts status 200 and a numeric id, run it
against environment <envId> and summarize any failures.
에이전트는 아래 명령어들을 실행합니다. 모든 플래그는 Apidog CLI 2.2.12의 apidog <cmd> --help에서 확인한 것입니다:
apidog branch create --project <projectId> --type ai \
--name "ai/20261117-from-main-orders-capture" --from main
apidog import --project <projectId> --branch "ai/20261117-from-main-orders-capture" \
--format openapi --file ./openapi.json
apidog endpoint list --project <projectId> --branch "ai/20261117-from-main-orders-capture" \
--path-contains /api/orders
apidog test-case category --project <projectId> --branch "ai/20261117-from-main-orders-capture"
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --branch "ai/20261117-from-main-orders-capture" \
--file case.json
apidog run --test-case <caseId> --project <projectId> --branch "ai/20261117-from-main-orders-capture" \
-e <envId> -r cli,json
AI 브랜치로 임포트하면 검토 전까지는 캡처된 스펙이 메인 디자인에서 분리됩니다. 나중에 다시 캡처하여 재임포트할 때는 info.title을 그대로 유지하거나 --module-map "<info.title>=<moduleId>"를 전달하세요. 그래야 Apidog가 엔드포인트를 새로 복제하는 대신 기존 것을 제자리에서 업데이트합니다.
테스트가 통과되면 동일한 apidog run ... -r junit 명령을 CI에 바로 넣을 수 있습니다. Apidog CLI CI/CD 가이드에서 파이프라인 설정을 확인할 수 있고, Claude Code에서의 Apidog CLI 문서에서는 에이전트 측면을 더 자세히 다룹니다.
더 깔끔한 캡처 스펙을 위한 팁
- 한 번에 하나의 기능만 캡처하세요. "주문"에 집중한 5분 세션이 사방을 클릭하는 30분보다 더 정돈된 스펙을 만듭니다.
- 에러 경로도 유발하세요. 잘못된 폼을 제출하거나 삭제된 레코드를 열어 스펙에 200뿐 아니라 4xx 응답도 포함되게 하세요.
- 삭제(redaction)를 직접 확인하세요. 커밋하기 전에
openapi.json에서 긴 무작위 문자열을 검색해 보세요. - 사이트 약관을 존중하세요. 소유하거나, 통합이 허용되거나, 테스트 권한이 있는 앱만 캡처하세요.
FAQ
OpenCode Browse는 무료인가요? 저장소는 MIT 라이선스이며, 제품 페이지에는 가격이 표시되어 있지 않습니다. 2026년 11월 17일 기준으로 출처가 확인해 주는 정보가 이것이 전부이므로, 비용을 고려한 계획을 세우기 전에 페이지를 다시 확인하세요.
OpenCode Browse는 Claude Code와도 작동하나요, 아니면 OpenCode 전용인가요? Claude Code, Codex, Cursor, Zed 등 약 30개의 다른 MCP 클라이언트에서도 작동합니다. browse install -a claude로 Claude Code를 설정할 수 있습니다. OpenCode는 일반 도구를 받고, 다른 클라이언트는 동일한 도구들을 JavaScript에서 호출하는 execute 도구를 받습니다.
Browse는 HAR 파일을 내보낼 수 있나요? 더 이상 불가능합니다. 버전 0.0.17에서 HAR 내보내기가 제거되었고, network는 이제 삭제된 트래픽을 구조화된 데이터로 직접 반환합니다. HAR 파일이 필요하다면 Chrome DevTools에서 저장한 뒤 apidog import --format har로 임포트하세요.
내 세션 쿠키나 토큰이 스펙에 포함될 수 있나요? Browse는 authorization 및 API-key 헤더, 모든 쿠키 값, 비밀로 추정되는 이름의 필드, 토큰처럼 보이는 경로 세그먼트를 삭제합니다. 일반적인 필드 이름 아래 저장된 비밀은 여전히 노출될 수 있으므로, 공유 전에 파일을 검토하세요.
에이전트의 출력에는 어떤 Apidog 임포트 형식을 사용해야 하나요? 에이전트가 작성한 스펙에는 --format openapi를 사용하세요. Apidog CLI는 동일한 apidog import 명령으로 Postman, HAR, Insomnia, Swagger 2.0 등 20개 이상의 다른 형식도 지원합니다.
