문제 해결

해결법은 문제가 생기는 순서대로 정리했습니다: 브라우저 상호작용, 로그인/CAPTCHA, 설치/런타임, 검색/추출, daemon, 데이터. 여기서 해결이 안 되면 -v를 붙여 실행하고 omniscout daemon trace 출력을 첨부해 GitHub 이슈에 올려주세요.

브라우저 상호작용

`@eN` ref를 찾을 수 없음

마지막 snapshot 이후 페이지가 바뀌었습니다. 다시 snapshot하고 새 ref를 사용하세요:

omniscout browser snapshot --refs-only
omniscout browser click '@e7'

navigate, reload, 폼 제출을 넘나들며 ref를 재사용하지 마세요.

Snapshot에 쓸 만한 ref가 없음

페이지가 아직 로딩 중일 수 있습니다. snapshot 전에 콘텐츠를 기다리세요:

omniscout browser wait networkidle
omniscout browser wait text "expected heading"
omniscout browser snapshot --refs-only

접근성 트리가 없는 canvas/WebGL 페이지는 screenshot + --coord 클릭 또는 observe/act로 폴백하세요.

클릭이 먹히지 않음

먼저 요소가 동작 가능한지 확인하고 키보드 대안을 시도하세요:

omniscout browser is '@e3' visible
omniscout browser is '@e3' enabled
omniscout browser hover '@e3'
omniscout browser key Enter

스크린샷이 비어 있음

# Wait for loading
omniscout browser screenshot https://example.com --delay 3 --out /tmp/page.png

# Full page
omniscout browser screenshot https://example.com --full-page --out /tmp/full.png

wait networkidle 후에도 비어 있으면 daemon이 탭을 잃은 경우가 많습니다 — browser close --all 후 다시 이동하세요.

로그인 및 CAPTCHA

로그인이 끝나지 않음

다른 셸에서 --done 신호를 사용하세요:

# Terminal A:
omniscout browser login https://app.example.com --profile work

# Terminal B (after you log in):
omniscout browser login --done

사이트가 이상하게 리디렉션되면 --success-pattern "dashboard|/app"을 전달해 5분짜리 --timeout-ms를 다 기다리지 않고 URL 매치로 로그인을 해결하세요.

CAPTCHA가 계속 막음

headful 창에서 직접 해결하거나 타사 솔버를 사용하세요:

export TWOCAPTCHA_API_KEY=...
omniscout browser captcha --solver 2captcha

omniscout browser captcha --detect-only로 bot-wall이 아니라 실제 CAPTCHA인지 먼저 확인하세요. navigate --auto-captcha는 로드 직후 챌린지를 해결합니다.

Extension에 `backend_unavailable` 표시

chrome://extensions를 여세요 — extension이 로드되었는지 확인
extension 아이콘 클릭 — 끊겼으면 다시 연결
또는 --backend extension을 빼고 Patchright 사용

설치 및 런타임

Python 버전 오류

python --version  # needs 3.11+
pip install omniscout

Chrome을 찾을 수 없음

omniscout settings browsers          # see what's installed
omniscout settings set browser edge  # or brave, vivaldi, etc.

사용자 지정 경로는 config.toml에 browser = "custom"와 browser_executable을 쓰세요(설정 참고).

첫 검색이 느림

일회성 임베딩 모델 다운로드 때문입니다. 미리 로드하세요: omniscout warmup. OMNISCOUT_EMBED_LOCAL_ONLY=0이 아니면 이후에는 오프라인입니다.

검색 및 추출

검색 결과가 없음

omniscout search "more specific query"
omniscout search "query" --source ddg
omniscout search "query" --no-rerank   # check if the reranker is hiding hits

추출 결과가 이상함

--format text를 시도해 보세요(깨진 마크업 제거) 또는 --no-cache(오래된 캐시).
JS 위주 페이지는 브라우저를 쓰세요: extract 대신 navigate → extract-visible.
사이트 전체 가져오기는 --include/--exclude 필터의 사이트 내보내기 모드를 쓰세요(추출 참고).

Daemon, 프로필, 세션

Daemon이 시작되지 않음

omniscout daemon stop
omniscout daemon start
lsof -i :7720                       # check if port is in use
omniscout daemon start --port 7721   # use different port

다른 도구가 7720 포트를 쓰고 있으면 OMNISCOUT_DAEMON_PORT=7721을 export해 모든 명령어가 새 포트를 쓰도록 하세요.

오래된 탭이 쌓임

omniscout session list
omniscout session kill <id>
omniscout browser close --all

재시작 후 로그인 소실

세션은 daemon 재시작 후 유지되지 않습니다 — 프로필은 유지됩니다. --profile <name>으로 로그인하고 이후 실행에도 같은 프로필을 전달하세요(Daemon 및 세션 참고).

JSON 및 에이전트

화면에 에러가 있는데 --json 출력이 비어 있음: 에러는 설계상 stderr로 갑니다 — stdout이 아니라 종료 코드와 stderr를 확인하세요.
명령어가 멈추면 -v를 붙여 verbose daemon/HTTP 로깅을 보세요.

최종 수단

pip install --upgrade omniscout
omniscout daemon restart
rm -rf ~/Library/Application\ Support/omniscout/   # macOS — wipes profiles, cache, memory
rm -rf ~/.local/share/omniscout/                   # Linux

FAQ

내 데이터가 클라우드로 전송되나요? 아니요. 유일한 외부 트래픽은 DuckDuckGo 검색과 직접 가져오기로 지정한 URL뿐입니다. 일회성 모델 다운로드는 로컬에 캐시됩니다.

Chrome 없이 OmniScout를 사용할 수 있나요? Chromium 계열 브라우저가 필요합니다. Chrome/Chromium을 설치하거나 omniscout install --browser custom --browser-executable <path>로 사용자 지정 경로를 설정하세요.

업데이트는 어떻게 하나요?

pip install --upgrade omniscout

모든 데이터를 지우려면 어떻게 하나요?

rm -rf ~/Library/Application\ Support/omniscout/   # macOS
rm -rf ~/.local/share/omniscout/                   # Linux

도움은 어디서 받나요?

문제 해결

On this page