openclaw-browser-setup

OpenClaw ブラウザーのセットアップ

概要

最短で確実な手順で OpenClaw ブラウザーを動作させ、設定の確認だけで終わらせず、実際のページ操作で動作を検証します。

修正の根拠となる公式の記述が必要な場合は、references/official-docs.md をお読みください。

対象を選択する

変更を加える前に、ユーザーがローカルゲートウェイとリモートゲートウェイのどちらを指しているかを判断します。

次を実行します。

openclaw gateway status --json
openclaw config get gateway.mode
openclaw config get gateway.remote.url

ユーザーがローカル環境と VPS の両方を利用しており、対象が不明確な場合は、--url を明示的に指定します。

最短手順

まず、ドキュメントに記載されているローカル環境の手順を試します。

openclaw browser profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

open が成功し、続けて snapshot または screenshot が成功したら、ブラウザー制御が動作している証拠とみなします。status は更新が遅れたり、古い状態に見えたりすることがあります。

最初にペアリングと認証を修正する

ブラウザーコマンドが pairing required または PAIRING_REQUIRED で失敗する場合は、ブラウザーの内部動作を調査する前に、デバイスの承認を修正します。

次を実行します。

openclaw devices list
openclaw devices approve <requestId>

接続がより広いスコープで再試行された場合、または認証の詳細が変更された場合は、承認前にデバイスを再度一覧表示してください。保留中の requestId が変わっている可能性があります。

共有トークン認証が関係する場合は、推測せずに設定済みのトークンを確認します。

openclaw config get gateway.auth.token

ブラウザーコマンドの不足またはプラグイン状態を修正する

openclaw browser が見つからない場合、またはエージェントがブラウザーツールを利用できないと報告する場合は、ブラウザープロファイルに手を加える前に、プラグインの読み込みを確認します。

次を確認します。

openclaw config get plugins.allow
openclaw config get plugins.entries.browser.enabled
openclaw config get browser.enabled

plugins.allow が設定されている場合は、browser が含まれていることを確認します。ブラウザープラグインまたはブラウザー設定を変更した場合は、ゲートウェイを再起動します。

openclaw gateway restart

適切なプロファイルを選択する

次を使用します。

• 分離された管理対象ブラウザーには openclaw を使用します。
• ログイン状態が重要で、ユーザーがアタッチの確認を承認できる状態にある場合は、既存のサインイン済み Chrome セッションに user を使用します。

サーバー、コンテナー、またはヘッドレス Linux ホストでは、デフォルトで user を使用しないでください。

Linux のヘッドレス環境と CDP の起動失敗に対処する

openclaw browser start が失敗した場合は、設定を変更する前にログを確認します。

openclaw logs --limit 120 --plain
openclaw browser status

デスクトップセッションのない Linux サーバーでよくある修正方法：

openclaw config set browser.headless true
openclaw gateway restart
openclaw browser --browser-profile openclaw start

設定済みのブラウザーバイナリが誤っているか、見つからない場合は、インストール済みのものを確認します。

which google-chrome-stable
google-chrome-stable --version
which chromium-browser

ログに snap Chromium または CDP の起動失敗に関する記述がある場合は、公式の executablePath、attachOnly、手動 CDP のガイダンスについて、references/official-docs.md をお読みください。

実際の操作で検証する

起動に成功したら、必ず実際の一連の操作を実行します。

openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
openclaw browser --browser-profile openclaw screenshot
openclaw browser --browser-profile openclaw tabs

open が成功しても tabs の表示がおかしい場合は、実際のページ操作を続けてください。snapshot または screenshot から有用なページ状態が返されれば、ブラウザーの動作経路は正常です。

順序立てて問題を切り分ける

最初の試行に失敗した場合は、次の順序で対応します。

1. 対象のゲートウェイを確認します。
2. openclaw devices list と approve を使って pairing required を解消します。
3. ブラウザープラグインが読み込まれていることを確認します。
4. 管理対象の openclaw プロファイルで再試行します。
5. GUI のない Linux ホストでは、ヘッドレスモードに切り替えます。
6. ブラウザーバイナリのパス、または snap／attach-only のケースを確認します。
7. その後に限り、user またはリモート CDP プロファイルを試します。