AI 에이전트와 함께 OmniScout 사용하기

Claude Code, Cursor, Codex, Kimi가 OmniScout를 구동하기 위한 바로 쓰는 프롬프트와 스킬 파일.

OmniScout는 AI 에이전트가 구동하도록 만들어졌습니다. 모든 명령어는 JSON을 말하고, 요소 ref는 안정적이며, 전체 동작 히스토리를 조회할 수 있습니다. 설정 방법은 다음과 같습니다.

1. 설치

pip install omniscout
omniscout install --skill

--skill 플래그는 에이전트의 스킬 디렉터리에 지침을 복사합니다:

에이전트	위치
Claude Code	`~/.claude/skills/scout/SKILL.md`
Cursor	`~/.cursor/skills-cursor/scout/SKILL.md`
Codex CLI	`~/.codex/skills/scout/SKILL.md`
Gemini CLI / Antigravity	`~/.gemini/config/skills/scout/SKILL.md`

다음 세션부터 에이전트가 자동으로 인식합니다. 다른 에이전트(Pi, OpenCode, Windsurf, Cline, Copilot Agent Mode, 셸 사용이 가능한 모든 어시스턴트)는 번들된 SKILL.md를 시스템 프롬프트에 붙여넣으세요.

2. Daemon 시작

omniscout daemon start

3. everywhere JSON 사용

루프 시작 시 OMNISCOUT_JSON=1을 설정하세요(또는 호출마다 --json 전달). stdout은 구조화된 페이로드가 되고 로그는 stderr로 갑니다:

export OMNISCOUT_JSON=1
omniscout search "robotics simulators"
omniscout browser snapshot | jq '.refs[] | select(.role == "button")'

형태는 Pydantic 규약(models.py)입니다 — 파서가 믿고 쓸 수 있는 안정적인 필드입니다. 모든 응답은 다음 호출에 필요한 맥락(ref, url, id)을 충분히 담고 있습니다.

4. 프롬프트 입력

질문 리서치

Use OmniScout to research "state of open-source browser agents in 2026" and summarize the top 5 passages with their source URLs.

이동 및 클릭

Open https://news.ycombinator.com using OmniScout, snapshot interactive elements, click the top story, and screenshot the result to /tmp/hn-top.png.

한 번 로그인하고 재사용

Run `omniscout browser login https://github.com --profile work`, pause for me to authenticate, then screenshot my notifications page with that profile.

지식 그래프 구축

Build a knowledge graph for "Cursor" with OmniScout. Run `omniscout graph "Cursor" --json --data`, show the tree, and cite sources.

양식 작성

Use OmniScout to open https://duckduckgo.com, fill the search box with "local-first AI agents", press Enter, wait for results, and list the top 5 results.

네트워크 트래픽 캡처

Open the Vercel pricing page with OmniScout, capture network traffic while scrolling, then list requests matching stripe|payment|checkout.

에이전트 루프

안정적인 루프는 다음과 같습니다:

daemon start (멱등 — 매 세션 실행해도 안전).
export OMNISCOUT_JSON=1.
동작: navigate → snapshot --refs-only → click/fill → 다시 snapshot.
관찰: screenshot, get text, network tail, console tail.
정리: browser close --all.

병렬 작업은 --session <name>으로 격리해 탭과 ref가 충돌하지 않도록 하세요.

에이전트 실행 디버깅

omniscout daemon trace — 최근 10k 동작의 JSONL 히스토리 조회 (에이전트가 실제로 무엇을 했나요?).
omniscout daemon replay / omniscout replay … — 기록된 흐름을 다시 실행해 실패 재현.
omniscout daemon watch — 에이전트가 동작하는 동안 live 이벤트 스트림 따라가기.
omniscout context — 현재 워크플로 연속성 상태 보기, 새로 시작하려면 omniscout reset.

에러 종류

다음을 예상하고 처리하세요:

실패	신호	해결법
오래된 `@eN` ref	"ref not found"	다시 snapshot하고 새 ref 사용
페이지 미로드	빈 스크린샷 / 텍스트 누락	먼저 `browser wait text/networkidle`
로그인 만료	로그인 페이지로 리디렉션	`browser login --profile …` 다시 실행
CAPTCHA	챌린지 감지	headful로 직접 해결 또는 `--solver 2captcha`
Daemon 다운	Connection refused	`daemon start` (또는 `--port` 확인)
결과 없음	빈 히트	쿼리를 좁히거나 다른 `--source` 시도

전체 목록: 문제 해결.

에이전트 팁

구조화된 출력을 위해 시작할 때 OMNISCOUT_JSON=1을 설정하세요.
omniscout browser snapshot --refs-only로 요소를 찾은 뒤 @eN ref로 클릭하세요.
매 navigate 뒤에 다시 snapshot하세요 — ref가 무효화됩니다.
고정 sleep보다 wait text/networkidle을 우선하세요.
반복 흐름은 매번 새로 만드는 대신 record/macro run으로 기록하세요.
끝나면 omniscout browser close --all로 세션을 닫으세요.

AI 에이전트와 함께 OmniScout 사용하기

On this page