# webclaw

> DureClaw의 브라우저 노드. Chrome MV3 확장으로 AI 에이전트에게 fetch·DOM·클릭·입력·다운로드 같은 '브라우저 손'을 빌려준다. 두뇌(브레인)는 마스터나 로컬 LLM이 맡고, webclaw 자신은 순수 JS로 손 역할만 한다.
> DureClaw's browser node. A Chrome MV3 extension that lends AI agents "browser hands" — fetch, DOM, click, fill, download. The brain (LLM) lives elsewhere (master or a local process); webclaw is pure JS hands.

설치: `git clone https://github.com/DureClaw/webclaw && chrome --load-extension=$(pwd)/webclaw` (Electron 임베딩은 `session.defaultSession.loadExtension()` 한 줄).

## 두 가지 실행 모드 / Two modes
- **bus 모드**: Phoenix 채널(`ws://<host>/socket`)에 `phx_join(work:<key>)`로 합류. 마스터가 `task.assign`을 보내면 `runTask`가 실행하고 `task.result`/`task.ack`로 응답. 두뇌는 마스터가 전담.
- **standalone 모드 (Wide Worker)**: `config.local.json`의 `standalone:true`, `bus:""`. 사람이 페이지 위 HUD 채팅에 입력 → `standaloneHandle(tabId,text,url)` → 로컬 `brainUrl/brain/exec`로 위임. 손(webclaw)+두뇌(로컬 브레인)가 한 머신에서 완결되는 단독 자율 브라우저 에이전트.

## 마커 명령어 / Marker commands (core.js runTask)
`[NAME]` 또는 `[NAME@<url일부>]`로 특정 탭 지정, 마커 없으면 브레인에 위임.
- `[FETCH] <url>` — 확장 fetch, host_permissions로 CORS 우회.
- `[DOWNLOAD] <url> [:: rel/path.ext]` — 세션 쿠키 유지 실제 다운로드. `[DOWNLOAD?] <id>` 상태 / `[CANCEL] <id|all>`.
- `[LINKS] <css?>` — `a[href]` 추출 → `[{text,href}]`. `[ATTR] <css> :: <attr>` — 속성값.
- `[DOM] <query>` — 대상 탭 DOM 읽기(빈 값=페이지 텍스트). `[TABS]` — 열린 탭 목록.
- `[CLICK] <sel>` / `[FILL]`·`[TYPE] <sel> = <val>` (줄바꿈이 ` = ` 분리보다 우선) / `[SUBMIT] <sel>`.
- `[JS] <code>` — 대상 페이지에서 실행, 결과 반환. `[OPEN] <url>` — 새 포그라운드 탭.
- `[HUD] on|off` — 시각 감독 오버레이. `[SAY] <text>` — HUD에 답변 렌더.

## 브레인 폴백 체인 / Brain fallback chain
로컬 브레인 서버(`app.mjs`)는 `WW_BACKENDS` 순서(기본 claude → codex → baryon)로 첫 성공을 채택. 프롬프트는 항상 stdin 전달.
- claude: `claude -p --output-format text`
- codex: `codex exec --skip-git-repo-check --ephemeral -s read-only --output-last-message <file> -`
- baryon: `POST <BARYON_API_URL>/v1/messages`
- API: `GET /health`, `POST /brain/exec {prompt}` → `{output,backend}`. 기본 포트 `4111`, `BRAIN_TOKEN` Bearer 인증.
- 주의: Claude Max 구독은 헤드리스(`claude -p`)에서 401 — 자동화는 codex 구독이나 baryon API 키 경유.

## 확장 로딩 / Extension loading
- Chrome: `chrome --user-data-dir=<profile> --load-extension=<ext> --disable-extensions-except=<ext> --no-first-run --no-default-browser-check`
- Electron(임베딩 권장): `session.defaultSession.loadExtension(WEBCLAW, {allowFileAccess:true})` — MV3가 WebContentsView 서브뷰에서 그대로 로드(Chromium 130 확인).
- manifest 권한: `offscreen, storage, scripting, tabs, tabGroups, sidePanel, downloads, <all_urls>`. `sidePanel`은 우측 고정(Chrome API 제약).

## 생태계 / Ecosystem
- [DureClaw](https://dureclaw.baryon.ai/) — 전체 협력 버스. 마스터가 두뇌, edgeclaw(OS·물리)·webclaw(브라우저)·deskclaw(데스크톱 GUI)가 손.
- [webclaw GitHub](https://github.com/DureClaw/webclaw)
- baryon-desktop(deskclaw) — Electron 셸의 WebContentsView 서브뷰에 webclaw를 그대로 로드해 진짜 임베드 브라우저 + 확장을 결합.

## 자주 묻는 질문 / FAQ
- **webclaw가 무엇인가?** Chrome MV3 확장 형태의 DureClaw 브라우저 노드. AI 에이전트에게 브라우저 손을 빌려준다.
- **bus와 standalone의 차이는?** bus는 마스터 지시를 받는 플릿의 일원, standalone(Wide Worker)은 로컬 브레인과 HUD 채팅으로 대화하는 단독 에이전트.
- **어떤 명령을 지원하나?** FETCH·DOWNLOAD·LINKS·ATTR·DOM·TABS·CLICK·FILL/TYPE·SUBMIT·JS·OPEN·HUD·SAY 13종.
- **브레인은 어디에?** claude→codex→baryon 폴백 체인의 로컬 서버(`/brain/exec`, 기본 4111 포트).

## 원칙 / Principles
손은 브라우저, 두뇌는 어디든 위임 가능 · 마커 없으면 자연어 그대로 브레인에 · 표준 출력은 stdin으로.
_Hands in the browser, brain delegated anywhere · no marker means plain-language delegation · prompts always via stdin._