> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # ブラウザ制御 API セットアップ、設定、トラブルシューティングについては、[Browser](/ja-JP/tools/browser) を参照してください。 このページは、ローカル制御 HTTP API、`openclaw browser` CLI、スクリプトパターン（スナップショット、ref、待機、デバッグフロー）のリファレンスです。 ## 制御 API（任意） ローカル統合専用に、Gateway は小さなループバック HTTP API を公開します。 このスタンドアロンサーバーはオプトインです。HTTP エンドポイントを利用可能にするには、gateway サービス環境で環境変数 `OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1` を設定し、 gateway を再起動します。この変数がない場合でも、ブラウザー制御ランタイムは CLI と agent tools 経由で動作しますが、ループバック制御ポートでは何も待ち受けません。 * ステータス/開始/停止: `GET /`, `GET /doctor`, `POST /start`, `POST /stop`, `POST /reset-profile` * プロファイル: `GET /profiles`, `POST /profiles/create`, `DELETE /profiles/:name` * タブ: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`, `POST /tabs/action` * スナップショット/スクリーンショット: `GET /snapshot`, `POST /screenshot` * アクション: `POST /navigate`, `POST /act` * フック: `POST /hooks/file-chooser`, `POST /hooks/dialog` * ダウンロード: `POST /download`, `POST /wait/download` * 権限: `POST /permissions/grant` * デバッグ: `GET /console`, `POST /pdf` * デバッグ: `GET /errors`, `GET /requests`, `GET /dialogs`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight` * ネットワーク: `POST /response/body` * 状態: `GET /cookies`, `POST /cookies/set`, `POST /cookies/clear` * 状態: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear` * 設定: `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device` `POST /tabs/action` は、CLI が `browser tab` サブコマンド （`{"action":"new"|"label"|"select"|"close"|"list", ...}`）に内部で使用するバッチ形式です。 直接スクリプトを書く場合は、上記の単一目的のタブルートを優先してください。 すべてのエンドポイントは `?profile=` を受け付けます。`POST /start?headless=true` は、 永続化されたブラウザー設定を変更せずに、ローカル管理プロファイルの 1 回限りのヘッドレス起動を要求します。OpenClaw はそれらのブラウザープロセスを起動しないため、 アタッチ専用、リモート CDP、既存セッションプロファイルはその上書きを拒否します。 タブエンドポイントでは、`targetId` は互換性のためのフィールド名です。`GET /tabs` または `POST /tabs/open` から得た `suggestedTargetId` を渡すことを推奨します。ラベルと、`t1` のような `tabId` ハンドルも受け付けます。生の CDP target id と一意な生の target-id 接頭辞も引き続き動作しますが、これらは揮発的な診断用ハンドルです。 共有シークレットの gateway 認証が設定されている場合、ブラウザー HTTP ルートにも認証が必要です。 * `Authorization: Bearer ` * `x-openclaw-password: ` またはそのパスワードを使った HTTP Basic 認証 注: * このスタンドアロンのループバックブラウザー API は、trusted-proxy または Tailscale Serve の identity header を**消費しません**。 * `gateway.auth.mode` が `none` または `trusted-proxy` の場合、これらのループバックブラウザー ルートは、それらの identity-bearing モードを継承しません。ループバック専用に保ってください。 ### `/act` エラー契約 `POST /act` は、ルートレベルの検証と ポリシー失敗に対して構造化エラーレスポンスを使用します。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "error": "", "code": "ACT_*" } ``` 現在の `code` 値: * `ACT_KIND_REQUIRED` (HTTP 400): `kind` が欠落しているか認識されません。 * `ACT_INVALID_REQUEST` (HTTP 400): アクションペイロードの正規化または検証に失敗しました。 * `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` がサポートされていないアクション種別で使用されました。 * `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate`（または `wait --fn`）が設定で無効化されています。 * `ACT_TARGET_ID_MISMATCH` (HTTP 403): トップレベルまたはバッチ内の `targetId` がリクエストターゲットと競合しています。 * `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): 既存セッションプロファイルではアクションがサポートされていません。 その他のランタイム失敗では、`code` フィールドなしで `{ "error": "" }` が返る場合があります。 ### Playwright 要件 一部の機能（navigate/act/AI スナップショット/role スナップショット、要素スクリーンショット、 PDF）には Playwright が必要です。Playwright がインストールされていない場合、それらのエンドポイントは 明確な 501 エラーを返します。 Playwright なしでも動作するもの: * ARIA スナップショット * タブごとの CDP WebSocket が利用可能な場合の role-style アクセシビリティスナップショット（`--interactive`, `--compact`, `--depth`, `--efficient`）。これは検査と ref 検出のための フォールバックです。Playwright は引き続き主要な アクションエンジンです。 * タブごとの CDP WebSocket が利用可能な場合の管理対象 `openclaw` ブラウザーのページスクリーンショット * `existing-session` / Chrome MCP プロファイルのページスクリーンショット * スナップショット出力からの `existing-session` ref ベースのスクリーンショット（`--ref`） 引き続き Playwright が必要なもの: * `navigate` * `act` * Playwright のネイティブ AI スナップショット形式に依存する AI スナップショット * CSS セレクター要素スクリーンショット（`--element`） * ブラウザー全体の PDF エクスポート 要素スクリーンショットは `--full-page` も拒否します。このルートは `fullPage is not supported for element screenshots` を返します。 `Playwright is not available in this gateway build` が表示される場合、パッケージ化された Gateway にコアブラウザーランタイム依存関係がありません。OpenClaw を再インストールまたは更新してから、 gateway を再起動してください。Docker の場合は、以下に示すように Chromium ブラウザーバイナリもインストールしてください。 #### Docker Playwright インストール Gateway を Docker で実行している場合は、`npx playwright` を避けてください（npm override が競合します）。 カスタムイメージでは、Chromium をイメージに組み込みます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh ``` 既存のイメージでは、代わりにバンドルされた CLI 経由でインストールします。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` ブラウザーダウンロードを永続化するには、`PLAYWRIGHT_BROWSERS_PATH`（例: `/home/node/.cache/ms-playwright`）を設定し、`/home/node` が `OPENCLAW_HOME_VOLUME` または bind mount で永続化されていることを確認してください。OpenClaw は Linux 上で永続化された Chromium を自動検出します。[Docker](/ja-JP/install/docker) を参照してください。 ## 仕組み（内部） 小さなループバック制御サーバーが HTTP リクエストを受け付け、CDP 経由で Chromium ベースのブラウザーに接続します。高度なアクション（click/type/snapshot/PDF）は CDP 上の Playwright を経由します。Playwright がない場合は、非 Playwright 操作のみ利用できます。ローカル/リモートブラウザーとプロファイルが背後で自由に入れ替わっても、agent からは 1 つの安定したインターフェイスとして見えます。 ## CLI クイックリファレンス すべてのコマンドは、特定のプロファイルを対象にする `--browser-profile ` と、機械可読出力用の `--json` を受け付けます。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw browser status openclaw browser doctor openclaw browser doctor --deep # add a live snapshot probe openclaw browser start openclaw browser start --headless # one-shot local managed headless launch openclaw browser stop # also clears emulation on attach-only/remote CDP openclaw browser reset-profile # moves the profile's browser data to Trash openclaw browser tabs openclaw browser tab # shortcut for current tab openclaw browser tab new openclaw browser tab new --label research openclaw browser tab label abcd1234 research openclaw browser tab select 2 openclaw browser tab close 2 openclaw browser open https://example.com openclaw browser focus abcd1234 openclaw browser close abcd1234 ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw browser profiles openclaw browser create-profile --name research --color "#0066CC" openclaw browser create-profile --name attach --driver existing-session --cdp-url http://127.0.0.1:9222 openclaw browser delete-profile --name research ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw browser screenshot openclaw browser screenshot --full-page openclaw browser screenshot --ref 12 # or --ref e12 openclaw browser screenshot --labels openclaw browser snapshot openclaw browser snapshot --format aria --limit 200 openclaw browser snapshot --interactive --compact --depth 6 openclaw browser snapshot --efficient openclaw browser snapshot --labels openclaw browser snapshot --urls openclaw browser snapshot --selector "#main" --interactive openclaw browser snapshot --frame "iframe#main" --interactive openclaw browser snapshot --out snapshot.txt openclaw browser console --level error openclaw browser errors --clear openclaw browser requests --filter api --clear openclaw browser pdf openclaw browser responsebody "**/api" --max-chars 5000 ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw browser navigate https://example.com openclaw browser resize 1280 720 openclaw browser click 12 --double # or e12 for role refs openclaw browser click-coords 120 340 # viewport coordinates openclaw browser type 23 "hello" --submit openclaw browser press Enter openclaw browser hover 44 openclaw browser scrollintoview e12 openclaw browser drag 10 11 openclaw browser select 9 OptionA OptionB openclaw browser download e12 report.pdf openclaw browser waitfordownload report.pdf openclaw browser upload /tmp/openclaw/uploads/file.pdf openclaw browser upload media://inbound/file.pdf openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]' openclaw browser dialog --accept openclaw browser dialog --dismiss --dialog-id d1 openclaw browser wait --text "Done" openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true" openclaw browser evaluate --fn '(el) => el.textContent' --ref 7 openclaw browser evaluate --fn 'const title = document.title; return title;' openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }' openclaw browser highlight e12 openclaw browser trace start openclaw browser trace stop ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw browser cookies openclaw browser cookies set session abc123 --url "https://example.com" openclaw browser cookies clear openclaw browser storage local get openclaw browser storage local set theme dark openclaw browser storage session clear openclaw browser set offline on openclaw browser set headers --headers-json '{"X-Debug":"1"}' openclaw browser set credentials user pass # --clear to remove openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com" openclaw browser set media dark openclaw browser set timezone America/New_York openclaw browser set locale en-US openclaw browser set device "iPhone 14" ``` 注: * `upload` と `dialog` は**準備**呼び出しです。chooser/dialog をトリガーする click/press の前に実行してください。アクションがモーダルを開く場合、アクションレスポンスには `blockedByDialog` と `browserState.dialogs.pending` が含まれます。その `dialogId` を渡して直接応答してください。OpenClaw の外部で処理されたダイアログは `browserState.dialogs.recent` に表示されます。 * `click`/`type`/その他には、`snapshot` からの `ref`（数値 `12`、role ref `e12`、または操作可能な ARIA ref `ax12`）が必要です。CSS セレクターは、アクションでは意図的にサポートされていません。表示中のビューポート位置だけが信頼できるターゲットである場合は、`click-coords` を使用してください。 * ダウンロードと trace のパスは OpenClaw の一時ルート `/tmp/openclaw{,/downloads}`（フォールバック: `${os.tmpdir()}/openclaw/...`）に制限されます。 * `upload` は、OpenClaw の一時 uploads ルートと OpenClaw 管理の inbound media からファイルを受け付けます。管理対象の inbound media は `media://inbound/`、サンドボックス相対の `media/inbound/`、または管理対象 inbound media ディレクトリ内の解決済み パスとして参照できます。ネストした media ref、 traversal、symlink、hardlink、任意のローカルパスは引き続き拒否されます。 * `upload` は、`--input-ref` または `--element` 経由で file input を直接設定することもできます。 OpenClaw が置換後のタブを証明できる場合、たとえば同じ URL である場合や、フォーム送信後に単一の古いタブが単一の新しいタブになった場合、安定したタブ ID とラベルは Chromium の raw-target 置換後も維持されます。Raw target ID は引き続き揮発的です。スクリプトでは `tabs` の `suggestedTargetId` を優先してください。 Snapshot フラグの概要: * `--format ai` (Playwright 使用時のデフォルト): 数値 refs (`aria-ref=""`) を含む AI snapshot。 * `--format aria`: `axN` refs を含むアクセシビリティツリー。Playwright が利用可能な場合、OpenClaw は refs をバックエンド DOM ID でライブページにバインドするため、後続アクションで使用できます。それ以外の場合は、出力を検査専用として扱ってください。 * `--efficient` (または `--mode efficient`): コンパクトな role snapshot プリセット。これをデフォルトにするには `browser.snapshotDefaults.mode: "efficient"` を設定します ([Gateway 設定](/ja-JP/gateway/configuration-reference#browser)を参照)。 * `--interactive`、`--compact`、`--depth`、`--selector` は `ref=e12` refs を含む role snapshot を強制します。`--frame "