Устранение неполадок
Типичные проблемы и способы их решения.
Исправления упорядочены по месту возникновения: взаимодействие с браузером, вход/CAPTCHA, установка/рантайм, поиск/извлечение, daemon и данные. Если ничего не помогло, запускайте команды с -v и прикладывайте вывод omniscout daemon trace к вашему GitHub issue.
Взаимодействие с браузером
@eN ref не найден
Страница изменилась с момента последнего snapshot. Сделайте снимок заново и используйте новый ref:
omniscout browser snapshot --refs-only
omniscout browser click '@e7'Никогда не переиспользуйте refs между navigate, reload или отправками форм.
Snapshot не показывает полезных refs
Страница может ещё грузиться. Дождитесь контента перед snapshot:
omniscout browser wait networkidle
omniscout browser wait text "expected heading"
omniscout browser snapshot --refs-onlyДля canvas/WebGL-страниц без accessibility-дерева откатитесь на screenshot + клики --coord или observe/act.
Клик ничего не сделал
Сначала проверьте, что элемент actionable, затем попробуйте клавиатурные альтернативы:
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 и navigate заново.
Вход и 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", чтобы вход завершался по совпадению URL вместо ожидания полных 5 минут --timeout-ms.
CAPTCHA блокирует навсегда
Решите её в видимом окне или используйте сторонний решатель:
export TWOCAPTCHA_API_KEY=...
omniscout browser captcha --solver 2captchaНачните с omniscout browser captcha --detect-only, чтобы убедиться, что это действительно CAPTCHA, а не bot-wall. navigate --auto-captcha решает проверки сразу после загрузки.
Расширение сообщает backend_unavailable
- Откройте
chrome://extensions— убедитесь, что расширение загружено - Нажмите на значок расширения — переподключитесь, если отключено
- Или уберите
--backend extension, чтобы использовать Patchright
Установка и рантайм
Ошибка версии Python
python --version # needs 3.11+
pip install omniscoutChrome не найден
omniscout settings browsers # see what's installed
omniscout settings set browser edge # or brave, vivaldi, etc.Для своего пути: browser = "custom" плюс browser_executable в config.toml (см. Конфигурация).
Первый поиск медленный
Это одноразовая загрузка embedding-модели. Предзагрузите её: 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-тяжёлых страниц используйте браузер:
navigate→extract-visibleвместоextract. - Для pulls целого сайта используйте режим экспорта сайта с фильтрами
--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, чтобы каждая команда использовала новый порт.
Копятся протухшие вкладки
omniscout session list
omniscout session kill <id>
omniscout browser close --allПотеря входов после рестарта
Сессии не переживают рестарты daemon — профили переживают. Входите с --profile <name> и передавайте тот же профиль в later runs (см. Daemon и сессии).
JSON и агенты
- Пустой вывод
--jsonс ошибками на экране: ошибки идут вstderrпо дизайну — проверяйте код выхода иstderr, а неstdout. - Добавьте
-vдля подробного логирования 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/ # LinuxFAQ
Мои данные отправляются в облако? Нет. Единственный исходящий трафик — поиски DuckDuckGo и URL, которые вы явно загружаете. Одноразовая загрузка модели кэшируется локально.
Могу ли я использовать OmniScout без Chrome?
Нужен браузер семейства 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Где получить помощь?