---
제목: "BrowserCode 완전 정리 — 개념부터 실전 사용법까지"
부제: "도구를 늘리지 말고 코드를 쓰게 하라"
대상: https://github.com/browser-use/browsercode
참고: https://discuss.pytorch.kr/t/browsercode-api-chrome/11714
라이선스: MIT
작성일: 2026-08-26
문서_목적: BrowserCode의 설계 사상과 동작 구조를 이해하고, 설치부터 실전 활용·보안 설정까지 한 문서로 끝내기 위한 실무 가이드
---

# BrowserCode 완전 정리

> ⚠️ **이름 주의**: 이 문서의 대상은 `browser-use/browsercode`입니다.
> `leaningtech/browsercode`(브라우저에서 AI CLI를 돌리는 IDE)는 **완전히 다른 프로젝트**입니다.

---

## 1. 한 줄 요약

**브라우저 조작을 "정해진 동작 API" 문제에서 "코드 작성" 문제로 바꾼 터미널 에이전트.**

에이전트에게 자바스크립트를 실행할 통로 하나만 주고, 페이지를 보면서 필요한 코드를 그 자리에서 짜게 합니다.

---

## 2. 왜 만들었나

### 기존 브라우저 에이전트의 벽

대부분의 웹 AI 에이전트는 이런 도구 목록을 받습니다.

```
click(element)
type(element, text)
scroll(direction)
read(element)
```

예상한 모양의 페이지에서는 잘 돕니다. 문제는 목록 밖의 상황입니다.

- 무한 스크롤 목록에서 **항목을 전부** 모아야 할 때
- **Shadow DOM** 안쪽 요소를 다뤄야 할 때
- 사이트마다 구조가 달라 **새 사이트마다 같은 벽**에 부딪힐 때

대응은 늘 하나였습니다 — 도구 목록을 늘린다.

### BrowserCode의 답

목록을 늘리는 대신 **없앴습니다.** 개발사 Browser Use의 근거는 이 한 문장입니다.

> "Browser ability and code-writing ability are deeply connected."
> (브라우저를 다루는 능력과 코드를 쓰는 능력은 깊이 연결되어 있다)

사람이 웹에서 뭔가 자동화할 때 하는 행동을 떠올려 보세요. F12를 눌러 DevTools 콘솔을 열고, `document.querySelectorAll(...)`을 쳐보고, 결과를 보고 고치고, 다시 칩니다. BrowserCode는 **그 행동을 그대로 에이전트에게 시킵니다.**

---

## 3. 핵심 구조: `browser_execute` 하나

BrowserCode가 OpenCode(코딩 에이전트)에 더한 것은 **원시 기능(Primitive) 딱 하나**입니다.

```
browser_execute(code)
  -> runs JavaScript in-process
  -> talks to Chrome through the DevTools Protocol
  -> keeps the browser session alive across calls
  -> returns logs, values, and screenshots to the agent
```

풀어쓰면:

| 동작 | 의미 | 왜 중요한가 |
|---|---|---|
| **프로세스 내 JS 실행** | 에이전트가 넘긴 자바스크립트를 그대로 실행 | 도구 목록의 표현력 한계를 JS 표현력으로 대체 |
| **CDP 직결** | Playwright 같은 래퍼 없이 Chrome DevTools Protocol로 직접 명령 | 중간 계층의 실패 지점·속도 손실 제거 |
| **세션 유지** | 호출 사이에 브라우저를 살려둠 | 한 페이지를 열어둔 채 여러 번 나눠 탐색 가능 |
| **로그+값+스크린샷 반환** | 실행 결과를 3종으로 돌려줌 | 에이전트가 실패를 **눈으로** 보고 수정 |

### 성공한 코드는 버려지지 않는다

한 번 통한 스크립트는 여기에 파일로 남습니다.

```
.bcode/agent-workspace/
```

같은 사이트를 반복해서 다룰수록 유리해지는 구조입니다. **쓸수록 빨라집니다.**

### 방법론 요약: "One Primitive, Runtime Code"

```
1. 축소  →  도구 N개를 browser_execute 1개로
2. 직결  →  CDP로 Chrome에 직접 명령
3. 유지  →  세션을 살려둔 채 대화형 탐색
4. 관측  →  로그·값·스크린샷으로 결과 확인
5. 영속  →  성공한 코드를 파일로 굳혀 재사용
```

핵심 루프: **탐색 → 관측 → 수정 → 재실행 → 성공 시 파일화**

---

## 4. 아키텍처

```
┌─────────────────────────────────────┐
│  BrowserCode (bcode)                │
│  ├── OpenCode 포크 (코딩 에이전트 본체)  │
│  └── Browser Harness TypeScript 이식본 │
│         └── browser_execute()        │
└──────────────┬──────────────────────┘
               │ CDP
               ▼
        실제 Chrome 브라우저
```

- **OpenCode**: 터미널 기반 오픈소스 코딩 에이전트 (`anomalyco/opencode`)
- **Browser Harness**: 같은 개발사의 Chrome 제어 계층. BrowserCode는 이걸 TypeScript로 이식해 저장소 안에 포함

> 프로젝트는 **"BrowserCode is not built by the OpenCode team and is not affiliated with OpenCode in any way"** 라고 명시합니다. 포크일 뿐 OpenCode 팀과 무관합니다.

기여할 때도 목적지가 갈립니다.
- 브라우저 자동화 관련 → `browser-use/browser-harness`
- 코딩 에이전트 본체 관련 → `anomalyco/opencode`

---

# 실전 사용법

## 5. 설치

### 5-1. 원라인 설치 (권장)

bash를 지원하는 터미널에서:

```bash
curl -fsSL https://bcode.sh/install | bash
```

> 💡 **저장소 이름은 `browsercode`, 실행 명령은 `bcode`** 입니다. 헷갈리기 쉬우니 기억해 두세요.

### 5-2. 소스에서 직접 실행

[Bun](https://bun.com)이 필요합니다.

```bash
git clone https://github.com/browser-use/browsercode.git
cd browsercode
bun install
bun run --cwd packages/opencode dev
```

### 5-3. ⚠️ 첫 실행 전에 반드시 — 텔레메트리 끄기

BrowserCode는 **익명 사용 추적을 기본으로 전송합니다.** 끄려면:

```bash
export DO_NOT_TRACK=1
```

`~/.zshrc` 또는 `~/.bashrc`에 넣어두면 매번 안 해도 됩니다.

```bash
echo 'export DO_NOT_TRACK=1' >> ~/.zshrc && source ~/.zshrc
```

---

## 6. 모델 연결

### 방법 A — TUI 안에서

```bash
bcode
```

실행 후 프롬프트에 입력:

```
/connect
```

### 방법 B — 환경 변수

공급자 API 키를 환경 변수로 두면 자동 인식됩니다.

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
# 또는 OPENAI_API_KEY, 기타 공급자 키
```

BrowserCode는 **API 키로 닿을 수 있는 모든 모델 + OpenCode가 지원하는 모든 공급자**를 씁니다.

### 어떤 모델을 쓸까 — 공식 추천 3종

개발사 자체 벤치마크(BU Bench) 기준 추천입니다.

| 목적 | 모델 | BU Bench | 특징 |
|---|---|---|---|
| **최고 성능** | `claude-opus-4-8` | 89.5% | 시간당 25.8작업 / $1당 1.1작업 |
| **공개 가중치 최고** | `kimi-k3` | 86.0% | 시간당 6.3작업 / $1당 1.3작업 |
| **가성비 최고** | `gpt-5.6-luna` (xhigh) | 82.0% | 시간당 25.6작업 / **$1당 26.6작업** |

### 💰 실무 팁 1 — 모델보다 추론 강도부터

같은 `gpt-5.6-luna`인데 설정만 다릅니다.

```
xhigh 추론 강도  →  82.0%
기본값          →  72.4%
                   ─────────
차이              9.6 포인트
```

**모델을 바꾸지 않고 추론 강도만 올려도 모델 간 차이만큼 결과가 달라집니다.** 성능이 안 나오면 모델 교체 전에 Reasoning Effort부터 확인하세요.

### 💰 실무 팁 2 — 비용 차이가 24배

`gpt-5.6-luna`(xhigh)는 $1당 처리 작업 수가 `opus`의 **약 24배**입니다. 성능은 7.5포인트 낮습니다. 대량 반복 작업이면 계산해 볼 값어치가 있습니다.

> ⚠️ 위 수치는 전부 **개발사 Browser Use의 자체 벤치마크**입니다. 비교 대상 목록과 각 대상 점수는 공개되지 않았습니다.

---

## 7. 실행

### 대화형 (TUI)

```bash
bcode
```

### 비대화형 — 지시 한 줄만

```bash
bcode run "On Google flights return all flight details from New York to SF tomorrow"
```

한국어 지시도 됩니다.

```bash
bcode run "쿠팡에서 무선 이어폰 상위 20개 상품명과 가격을 CSV로 정리해줘"
```

---

## 8. 브라우저 연결 — 3가지 방법

여기가 BrowserCode의 특이한 점입니다. **브라우저 연결 방식을 설정 파일이 아니라 지시문으로 정합니다.** 에이전트가 알아서 연결합니다.

### ① 지금 열려 있는 내 탭 이어받기

```
Connect to my current tab on amazon.com and find deals for 64GB DDR5 RAM, return URLs
```

→ 에이전트가 **내 실제 브라우저**를 넘겨받습니다. 로그인 상태가 그대로 유지됩니다.

### ② 에이전트 전용 프로필 새로 만들기

```
Make a new browser profile and QA test http://localhost:3000, fix bugs and open a PR
```

→ 에이전트가 자기 브라우저 프로필 안에서만 작업합니다. **가장 안전한 기본값.**

### ③ 원격(클라우드) 브라우저 열기

```
Open a remote browser and extract every item sold on mcdonalds.com in SF
```

→ Browser Use Cloud 브라우저를 제어하고, 지켜볼 수 있는 링크를 줍니다.

---

## 9. Browser Use Cloud (선택)

### 무엇을 주나

| 항목 | 내용 |
|---|---|
| 브라우저 개수 | 무제한 무료 |
| 동시 세션 | **3개 제한** |
| 부가 기능 | 스텔스 접속, 캡차 처리, 프록시 |

### 연결

```bash
export BROWSER_USE_API_KEY="your-key"
```

> 프로젝트는 **에이전트가 스스로 가입까지 할 수 있다**고 적어 두었습니다. 그냥 시켜보세요.

### API로 직접 실행

터미널 없이 HTTP 요청 한 번으로도 같은 에이전트를 돌립니다.

```bash
curl -X POST https://api.browser-use.com/api/v4/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Your task"}'
```

---

## 10. ⚠️ 보안 — 도입 전 반드시 읽을 것

이 프로젝트의 **설계 자체가 "에이전트가 임의의 자바스크립트를 실행한다"** 입니다. 이건 버그가 아니라 기능입니다. 그래서 위험도 기능에 딸려옵니다.

### 위협 모델

```
악성 페이지에 숨은 지시문
        ↓
에이전트가 그걸 읽고 코드 생성
        ↓
로그인된 내 세션에서 실행
        ↓
쿠키·토큰·계정 접근
```

**프롬프트 인젝션이 곧 세션 탈취가 될 수 있는 구조**이며, 프로젝트는 이에 대한 샌드박싱 대책을 제시하지 않습니다.

### 안전 수칙

- **①번(내 탭 이어받기)은 마지막 수단으로** — 은행·이메일·업무 계정이 로그인된 브라우저는 절대 연결하지 말 것
- **기본은 ②번(신규 프로필)** — 필요한 계정만 그 프로필에 따로 로그인
- **신뢰할 수 없는 사이트는 ③번(원격 브라우저)** — 내 머신과 격리
- **`DO_NOT_TRACK=1` 먼저 설정**
- **폐쇄망이면 로컬 경로만** — 원격 브라우저는 Browser Use Cloud 계정에 묶입니다. 외부 트래픽이 막힌 환경에서는 쓸 수 없습니다

### 첫 테스트 권장 조합

```bash
export DO_NOT_TRACK=1
bcode run "Make a new browser profile and open example.com, return the page title"
```

신규 프로필 + 무해한 사이트로 감을 잡은 뒤 범위를 넓히세요.

---

## 11. Playwright를 대체하나?

**아니오. 층위가 다릅니다.**

BrowserCode는 **에이전트**, Playwright는 **라이브러리**입니다. 실제로 Playwright와 같은 층에 있는 건 그 안에 들어간 Browser Harness입니다.

| 영역 | 선택 | 이유 |
|---|---|---|
| CI 회귀 테스트 | **Playwright** | LLM이 매번 다른 코드를 써서 재현성이 깨짐 |
| 크로스 브라우저(Firefox/Safari) | **Playwright** | BrowserCode는 CDP 전용 = Chrome 전용 |
| 구조 안정된 사이트 스크래핑 | **Playwright** | 더 싸고 빠름 |
| **구조가 자주 바뀌는 사이트** | **BrowserCode** | 런타임 적응 |
| **셀렉터를 미리 모르는 일회성 작업** | **BrowserCode** | 탐색하며 알아냄 |
| **탐색적 QA (버그 찾기)** | **BrowserCode** | 예상 못 한 경로를 스스로 시도 |

### 재현성 문제 — 왜 CI에 못 쓰나

개발사 자체 데이터입니다. **같은 모델·같은 하네스로 5회 반복** 실행했을 때:

```
106개 과제 중 약 89개 통과 (매번)
  └ 항상 통과:   64개
  └ 항상 실패:    2개
  └ 무작위:      40개  ← 문제
```

통과 개수는 비슷한데 **통과하는 과제 조합이 매번 달랐습니다.** 이 특성으로 회귀 테스트를 돌리면 실패가 코드 버그인지 에이전트 변덕인지 구분할 수 없습니다.

### 현실적인 조합

```
BrowserCode로 탐색  →  동작하는 JS 확보
        ↓
Playwright 스크립트로 고정  →  CI에 투입
```

**BrowserCode는 Playwright를 대체하는 게 아니라 Playwright의 입력을 만들어줍니다.**

---

## 12. 언제 쓰면 좋은가 — 체크리스트

다음 중 **하나라도** 해당하면 시도해 볼 값어치가 있습니다.

- 자동화 대상 사이트의 DOM 구조가 자주 바뀐다
- 무한 스크롤 / Shadow DOM / 교차 출처 iframe 때문에 기존 도구가 막혔다
- 같은 사이트를 **반복해서** 다룬다 (스크립트 축적 효과)
- 셀렉터를 미리 알 수 없어 매번 사람이 F12를 열어야 한다
- 로컬 개발 서버를 탐색적으로 QA하고 싶다

다음에 해당하면 **쓰지 마세요.**

- CI 파이프라인에 넣을 회귀 테스트가 필요하다
- Firefox·Safari 검증이 필요하다
- 대상 사이트 구조가 안정적이고 이미 잘 도는 스크립트가 있다
- 외부 네트워크가 차단된 환경에서 원격 브라우저가 필요하다

---

## 13. 명령어 치트시트

```bash
# 설치
curl -fsSL https://bcode.sh/install | bash

# 텔레메트리 끄기 (첫 실행 전)
export DO_NOT_TRACK=1

# 대화형 실행
bcode

# 비대화형 실행
bcode run "지시문"

# TUI 안에서 모델 연결
/connect

# 클라우드 연결
export BROWSER_USE_API_KEY="..."

# 클라우드 API 직접 호출
curl -X POST https://api.browser-use.com/api/v4/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Your task"}'

# 소스에서 실행
git clone https://github.com/browser-use/browsercode.git
cd browsercode && bun install
bun run --cwd packages/opencode dev
```

**주요 경로**

| 경로 | 용도 |
|---|---|
| `.bcode/agent-workspace/` | 재사용 가능한 브라우저 스크립트 저장소 |

---

## 14. 참고 링크

| 대상 | URL |
|---|---|
| BrowserCode 저장소 | https://github.com/browser-use/browsercode |
| Browser Use 홈 | https://browser-use.com |
| Browser Use Cloud | https://cloud.browser-use.com |
| Browser Harness | https://github.com/browser-use/browser-harness |
| OpenCode | https://github.com/anomalyco/opencode |
| Chrome DevTools Protocol | https://chromedevtools.github.io/devtools-protocol/ |
| 한국어 소개 글 (PyTorchKR) | https://discuss.pytorch.kr/t/browsercode-api-chrome/11714 |

**라이선스**: MIT (개인·상업적 사용 자유). LICENSE 파일 저작권 표기는 포크 출처를 따라 `Copyright (c) 2025 opencode`로 남아 있습니다.

---

## 15. 도구를 안 써도 남는 것

BrowserCode를 도입하지 않더라도, 이 설계 패턴은 다른 에이전트에 그대로 이식할 값어치가 있습니다.

> **원시 기능 하나 + 런타임 코드 생성 + 결과물 영속화**

"도구 목록을 늘려 모든 경우를 커버한다"는 접근이 막힐 때, "표현력 있는 원시 기능 하나를 주고 나머지를 모델에게 맡긴다"는 반대 방향이 있다는 것 — 이게 이 프로젝트가 남기는 진짜 교훈입니다.

**도구는 관망, 패턴은 차용.**