トラブルシューティング

対処は発生箇所順です：ブラウザ操作、ログイン／CAPTCHA、インストール／実行時、検索／抽出、daemon、データです。ここで解決しない場合は-v付きでコマンドを実行し、omniscout daemon traceの出力を添えてGitHub issueに報告します。

ブラウザ操作

`@eN` refが見つかりません

前回のsnapshot以降にページが変わっています。再取得して新しいrefを使います：

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

navigate、reload、フォーム送信をまたいでrefを再利用しません。

snapshotに有効なrefがありません

ページがまだ読み込み中の可能性があります。内容を待ってから取得します：

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で止まり続けます

ヘッドフルウィンドウで解くか、サードパーティソルバーを使います：

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

まずomniscout browser captcha --detect-onlyでCAPTCHAなのかbot壁なのかを確認します。navigate --auto-captchaは読み込み直後に課題を解決します。

拡張機能が`backend_unavailable`と言います

chrome://extensionsを開きます — 拡張機能が読み込まれていることを確認します
拡張機能アイコンをクリックします — 切断されていれば再接続します
または--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をエクスポートし、すべてのコマンドで新しいポートを使います。

古いタブが溜まります

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

再起動後にログインが消えます

セッションはdaemon再起動をまたぎません — プロファイルは残ります。--profile <name>でログインし、以降の実行でも同じプロファイルを渡します（daemonとセッションをご覧ください）。

JSONとエージェント

画面にエラーが出て--json出力が空です：エラーは設計上stderrに出ます — stdoutではなく終了コードとstderrを確認します。
コマンドがハングする場合は-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/                   # Linux

FAQ

データはクラウドに送信されますか？ いいえ。外部送信はDuckDuckGo検索と明示的に取得したURLのみです。1回限りのモデルダウンロードはローカルにキャッシュします。

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