diff --git a/docs/ja-JP/gateway/local-models.md b/docs/ja-JP/gateway/local-models.md index 4e8cdd6fe..6c97af072 100644 --- a/docs/ja-JP/gateway/local-models.md +++ b/docs/ja-JP/gateway/local-models.md @@ -1,28 +1,28 @@ --- read_when: - 自分のGPUマシンからモデルを提供したい場合 - - LM StudioまたはOpenAI互換プロキシを接続している場合 + - LM StudioまたはOpenAI互換プロキシを設定している場合 - 最も安全なローカルモデルのガイダンスが必要な場合 -summary: ローカルLLM（LM Studio、vLLM、LiteLLM、カスタムOpenAIエンドポイント）でOpenClawを実行する +summary: OpenClawをローカルLLM（LM Studio、vLLM、LiteLLM、カスタムOpenAIエンドポイント）で実行する title: ローカルモデル x-i18n: - generated_at: "2026-04-13T08:50:36Z" + generated_at: "2026-04-14T13:04:22Z" model: gpt-5.4 provider: openai - source_hash: 3ecb61b3e6e34d3666f9b688cd694d92c5fb211cf8c420fa876f7ccf5789154a + source_hash: 1544c522357ba4b18dfa6d05ea8d60c7c6262281b53863d9aee7002464703ca7 source_path: gateway/local-models.md workflow: 15 --- # ローカルモデル -ローカルでも利用できますが、OpenClawは大きなコンテキストと、プロンプトインジェクションに対する強力な防御を前提としています。小規模なGPUではコンテキストが切り詰められ、安全性も損なわれます。目安としては、**最大構成のMac Studioを2台以上、または同等のGPUリグ（約3万ドル以上）** を推奨します。単一の**24 GB** GPUでも、より軽いプロンプトなら動作しますが、レイテンシは高くなります。実行可能な中で**最大 / フルサイズのモデルバリアント**を使ってください。強く量子化されたチェックポイントや「small」モデルは、プロンプトインジェクションのリスクを高めます（[Security](/ja-JP/gateway/security)を参照）。 +ローカル運用は可能ですが、OpenClawは大きなコンテキストと強力なプロンプトインジェクション耐性を前提としています。小規模なカードではコンテキストが切り詰められ、安全性も低下します。目標は高く設定してください: **最大構成のMac Studioを2台以上、または同等のGPUリグ（約$30k以上）**。単一の**24 GB** GPUで動かせるのは、より軽いプロンプトに限られ、レイテンシも高くなります。実行可能な中で**最大 / フルサイズのモデルバリアント**を使ってください。強く量子化された、または「small」なチェックポイントは、プロンプトインジェクションのリスクを高めます（[Security](/ja-JP/gateway/security)を参照）。 -最も手間の少ないローカル構成を望むなら、まずは [LM Studio](/ja-JP/providers/lmstudio) または [Ollama](/ja-JP/providers/ollama) と `openclaw onboard` から始めてください。このページは、より高性能なローカルスタックと、カスタムのOpenAI互換ローカルサーバー向けの実践的ガイドです。 +最も手間の少ないローカルセットアップを望むなら、[LM Studio](/ja-JP/providers/lmstudio)または[Ollama](/ja-JP/providers/ollama)から始めて、`openclaw onboard`を実行してください。このページは、より高性能なローカルスタックやカスタムのOpenAI互換ローカルサーバー向けの、方針を明確にしたガイドです。 ## 推奨: LM Studio + 大規模ローカルモデル（Responses API） -現時点で最良のローカル構成です。LM Studioで大規模モデル（たとえば、フルサイズのQwen、DeepSeek、またはLlamaビルド）を読み込み、ローカルサーバー（デフォルトは `http://127.0.0.1:1234`）を有効にして、Responses APIを使い、推論を最終テキストから分離してください。 +現時点で最適なローカルスタックです。LM Studioに大規模モデル（たとえばフルサイズのQwen、DeepSeek、Llamaビルド）を読み込み、ローカルサーバー（デフォルトは`http://127.0.0.1:1234`）を有効にし、推論を最終テキストから分離するためにResponses APIを使用します。 ```json5 { @@ -62,13 +62,13 @@ x-i18n: **セットアップチェックリスト** - LM Studioをインストール: [https://lmstudio.ai](https://lmstudio.ai) -- LM Studioで、利用可能な中で**最大のモデルビルド**をダウンロードし（「small」や強く量子化されたバリアントは避けてください）、サーバーを起動し、`http://127.0.0.1:1234/v1/models` に一覧表示されることを確認します。 -- `my-local-model` を、LM Studioに表示される実際のモデルIDに置き換えます。 -- モデルを読み込んだままにしてください。コールドロードは起動時レイテンシを追加します。 -- LM Studioのビルドに応じて `contextWindow` / `maxTokens` を調整します。 +- LM Studioで、**利用可能な中で最大のモデルビルド**をダウンロードし（「small」や強い量子化バリアントは避ける）、サーバーを起動して、`http://127.0.0.1:1234/v1/models`に一覧表示されることを確認します。 +- `my-local-model`を、LM Studioに表示されている実際のモデルIDに置き換えます。 +- モデルは読み込んだままにしてください。コールドロードは起動レイテンシを増やします。 +- LM Studioのビルドに応じて`contextWindow`と`maxTokens`を調整します。 - WhatsAppでは、最終テキストだけが送信されるよう、Responses APIを使ってください。 -ローカルで実行する場合でも、ホスト型モデルは設定したままにしてください。フォールバックを利用できるように、`models.mode: "merge"` を使います。 +ローカル運用時でもホスト型モデルは設定しておいてください。`models.mode: "merge"`を使えば、フォールバックを利用可能なままにできます。 ### ハイブリッド構成: ホスト型をプライマリ、ローカルをフォールバック @@ -111,18 +111,18 @@ x-i18n: } ``` -### ローカル優先 + ホスト型の安全網 +### ローカル優先、ホスト型をセーフティネットにする構成 -プライマリとフォールバックの順序を入れ替えてください。ローカル環境が停止したときにSonnetやOpusへフォールバックできるよう、同じprovidersブロックと `models.mode: "merge"` を維持します。 +プライマリとフォールバックの順序を入れ替えてください。`providers`ブロックと`models.mode: "merge"`はそのまま維持し、ローカルマシンが停止しているときにSonnetやOpusへフォールバックできるようにします。 ### リージョナルホスティング / データルーティング -- ホスト型のMiniMax / Kimi / GLMバリアントは、リージョン固定エンドポイント（例: USホスト）付きでOpenRouter上でも利用できます。そこではリージョナルバリアントを選ぶことで、`models.mode: "merge"` を使ってAnthropic/OpenAIのフォールバックを維持しつつ、トラフィックを選択した法域内に留められます。 -- ローカル専用構成が、プライバシーの面では最も強力です。ホスト型のリージョナルルーティングは、プロバイダー機能が必要だがデータフローも制御したい場合の中間案です。 +- ホスト型のMiniMax/Kimi/GLMバリアントは、リージョン固定エンドポイント（例: USホスト）付きでOpenRouter上にも存在します。そこでリージョナルバリアントを選べば、`models.mode: "merge"`を使ったAnthropic/OpenAIフォールバックを維持しながら、トラフィックを選択した法域内にとどめられます。 +- ローカル専用は依然として最も強いプライバシー手段です。ホスト型のリージョナルルーティングは、プロバイダー機能が必要だがデータフローも制御したい場合の中間的な選択肢です。 ## その他のOpenAI互換ローカルプロキシ -vLLM、LiteLLM、OAI-proxy、またはカスタムGatewayは、OpenAI形式の `/v1` エンドポイントを公開していれば動作します。上記のproviderブロックを、自分のエンドポイントとモデルIDに置き換えてください。 +vLLM、LiteLLM、OAI-proxy、またはカスタムGatewayでも、OpenAI形式の`/v1`エンドポイントを公開していれば動作します。上記のプロバイダーブロックを、利用するエンドポイントとモデルIDに置き換えてください。 ```json5 { @@ -150,25 +150,26 @@ vLLM、LiteLLM、OAI-proxy、またはカスタムGatewayは、OpenAI形式の ` } ``` -ホスト型モデルをフォールバックとして利用できるよう、`models.mode: "merge"` を維持してください。 +ホスト型モデルをフォールバックとして引き続き使えるように、`models.mode: "merge"`を維持してください。 -ローカル / プロキシ `/v1` バックエンドに関する動作メモ: +ローカル / プロキシされた`/v1`バックエンドの動作に関する注意: -- OpenClawはこれらを、ネイティブなOpenAIエンドポイントではなく、プロキシ形式のOpenAI互換ルートとして扱います -- そのため、OpenAIネイティブ専用のリクエスト整形はここでは適用されません: `service_tier` なし、Responsesの `store` なし、OpenAIのreasoning互換ペイロード整形なし、プロンプトキャッシュヒントなし -- 非表示のOpenClaw属性ヘッダー（`originator`, `version`, `User-Agent`）は、これらのカスタムプロキシURLには挿入されません +- OpenClawはこれらを、ネイティブなOpenAIエンドポイントではなく、プロキシ型のOpenAI互換ルートとして扱います +- ここではOpenAIネイティブ専用のリクエスト整形は適用されません: `service_tier`、Responsesの`store`、OpenAI reasoning互換ペイロード整形、プロンプトキャッシュヒントは使われません +- 隠しOpenClaw属性ヘッダー（`originator`、`version`、`User-Agent`）は、これらのカスタムプロキシURLには挿入されません -より厳格なOpenAI互換バックエンド向けの互換性メモ: +より厳格なOpenAI互換バックエンド向けの互換性に関する注意: -- 一部のサーバーは、Chat Completionsで構造化されたcontent-part配列ではなく、文字列の `messages[].content` のみを受け付けます。そのようなエンドポイントでは、`models.providers..models[].compat.requiresStringContent: true` を設定してください。 -- より小規模または厳格なローカルバックエンドの中には、特にツールスキーマが含まれる場合、OpenClawの完全なagent-runtimeプロンプト形状で不安定になるものがあります。小さな直接 `/v1/chat/completions` 呼び出しでは動作しても、通常のOpenClaw agentターンでは失敗する場合は、まず `models.providers..models[].compat.supportsTools: false` を試してください。 -- それでも大きなOpenClaw実行時にのみバックエンドが失敗する場合、残っている問題は通常、OpenClawのトランスポート層ではなく、上流のモデル / サーバー容量、またはバックエンドのバグです。 +- 一部のサーバーは、Chat Completionsで構造化コンテンツパート配列ではなく、文字列の`messages[].content`しか受け付けません。そのようなエンドポイントでは、`models.providers..models[].compat.requiresStringContent: true`を設定してください。 +- 一部の小規模または厳格なローカルバックエンドは、特にツールスキーマが含まれる場合、OpenClawの完全なエージェントランタイム用プロンプト形状では不安定です。バックエンドが小さな直接`/v1/chat/completions`呼び出しでは動作しても、通常のOpenClawエージェントターンで失敗する場合は、まず`models.providers..models[].compat.supportsTools: false`を試してください。 +- それでも大きめのOpenClaw実行時にのみバックエンドが失敗する場合、残る問題は通常、OpenClawのトランスポート層ではなく、上流のモデル / サーバー容量またはバックエンドのバグです。 ## トラブルシューティング - Gatewayはプロキシに到達できますか？ `curl http://127.0.0.1:1234/v1/models` -- LM Studioのモデルはアンロードされていませんか？ 再読み込みしてください。コールドスタートは「固まって見える」一般的な原因です。 -- コンテキストエラーですか？ `contextWindow` を下げるか、サーバー側の上限を引き上げてください。 -- OpenAI互換サーバーが `messages[].content ... expected a string` を返しますか？ そのモデルエントリに `compat.requiresStringContent: true` を追加してください。 -- 直接の小さな `/v1/chat/completions` 呼び出しは動作するのに、`openclaw infer model run` がGemmaや他のローカルモデルで失敗しますか？ まず `compat.supportsTools: false` でツールスキーマを無効化し、その後で再テストしてください。それでも大きなOpenClawプロンプトでのみサーバーがクラッシュするなら、上流のサーバー / モデルの制限として扱ってください。 -- 安全性: ローカルモデルではプロバイダー側のフィルターが適用されません。プロンプトインジェクションの影響範囲を抑えるため、agentは限定的に保ち、Compactionを有効にしてください。 +- LM Studioのモデルがアンロードされていますか？ 再読み込みしてください。コールドスタートは「ハングしている」ように見える一般的な原因です。 +- 検出されたコンテキストウィンドウが**32k**未満の場合、OpenClawは警告を出し、**16k**未満ではブロックします。その事前チェックに引っかかった場合は、サーバー / モデルのコンテキスト上限を引き上げるか、より大きなモデルを選んでください。 +- コンテキストエラーですか？ `contextWindow`を下げるか、サーバー上限を引き上げてください。 +- OpenAI互換サーバーが`messages[].content ... expected a string`を返しますか？ そのモデルエントリーに`compat.requiresStringContent: true`を追加してください。 +- 小さな直接`/v1/chat/completions`呼び出しは動作するのに、`openclaw infer model run`がGemmaや他のローカルモデルで失敗しますか？ まず`compat.supportsTools: false`でツールスキーマを無効にしてから再テストしてください。それでも大きめのOpenClawプロンプトでのみサーバーがクラッシュする場合は、上流のサーバー / モデルの制限として扱ってください。 +- 安全性: ローカルモデルはプロバイダー側フィルターを通りません。プロンプトインジェクションの影響範囲を制限するため、エージェントは用途を絞り、Compactionを有効にしてください。 diff --git a/docs/ja-JP/tools/browser.md b/docs/ja-JP/tools/browser.md index f5ad18069..04b276fb0 100644 --- a/docs/ja-JP/tools/browser.md +++ b/docs/ja-JP/tools/browser.md @@ -1,20 +1,20 @@ --- read_when: - - エージェント制御のブラウザ自動化の追加 - - OpenClaw が自分の Chrome に干渉している理由のデバッグ - - macOS アプリでのブラウザ設定とライフサイクルの実装 + - エージェント制御のブラウザ自動化を追加する + - openclaw が自分の Chrome に干渉している理由をデバッグする + - macOSアプリでブラウザ設定 + ライフサイクルを実装する summary: 統合ブラウザ制御サービス + アクションコマンド -title: ブラウザ（OpenClaw 管理） +title: ブラウザ（OpenClaw管理） x-i18n: - generated_at: "2026-04-11T02:48:37Z" + generated_at: "2026-04-14T13:04:29Z" model: gpt-5.4 provider: openai - source_hash: da6fed36a6f40a50e825f90e5616778954545bd7e52397f7e088b85251ee024f + source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2 source_path: tools/browser.md workflow: 15 --- -# ブラウザ（openclaw 管理） +# ブラウザ（openclaw管理） OpenClaw は、エージェントが制御する**専用の Chrome/Brave/Edge/Chromium プロファイル**を実行できます。 これは個人用ブラウザから分離されており、Gateway 内の小さなローカル @@ -23,19 +23,19 @@ OpenClaw は、エージェントが制御する**専用の Chrome/Brave/Edge/Ch 初心者向けの見方: - これは**エージェント専用の別ブラウザ**だと考えてください。 -- `openclaw` プロファイルは個人用ブラウザプロファイルには**触れません**。 -- エージェントは安全なレーン内で**タブを開き、ページを読み取り、クリックし、入力**できます。 -- 組み込みの `user` プロファイルは、Chrome MCP を通じて、実際にサインイン済みの Chrome セッションに接続します。 +- `openclaw` プロファイルは、個人用ブラウザプロファイルには**触れません**。 +- エージェントは安全なレーンで**タブを開き、ページを読み取り、クリックし、入力**できます。 +- 組み込みの `user` プロファイルは、Chrome MCP 経由で実際のサインイン済み Chrome セッションに接続します。 -## できること +## 利用できるもの -- **openclaw** という名前の別ブラウザプロファイル（デフォルトでオレンジのアクセント）。 -- 決定論的なタブ制御（一覧表示/開く/フォーカス/閉じる）。 +- **openclaw** という名前の別ブラウザプロファイル（デフォルトではオレンジのアクセント）。 +- 決定的なタブ制御（一覧表示/開く/フォーカス/閉じる）。 - エージェントアクション（クリック/入力/ドラッグ/選択）、スナップショット、スクリーンショット、PDF。 -- 任意のマルチプロファイル対応（`openclaw`、`work`、`remote`、...）。 +- オプションのマルチプロファイル対応（`openclaw`、`work`、`remote`、...）。 -このブラウザは日常使いのブラウザ**ではありません**。これは -エージェント自動化と検証のための、安全で分離されたサーフェスです。 +このブラウザは日常使いのメインブラウザでは**ありません**。これは +エージェントの自動化と検証のための、安全で分離された画面です。 ## クイックスタート @@ -46,17 +46,16 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -「Browser disabled」と表示される場合は、config で有効にし（以下を参照）、 -Gateway を再起動してください。 +「Browser disabled」と表示される場合は、config で有効にし（下記参照）、Gateway を +再起動してください。 -`openclaw browser` 自体が存在しない、またはエージェントが browser tool -を利用できないと言う場合は、[Missing browser command or tool](/ja-JP/tools/browser#missing-browser-command-or-tool) に進んでください。 +`openclaw browser` 自体が見つからない場合、またはエージェントがブラウザツール +を利用できないと言う場合は、[ブラウザコマンドまたはツールが見つからない](/ja-JP/tools/browser#missing-browser-command-or-tool) に進んでください。 -## plugin 制御 +## Plugin 制御 -デフォルトの `browser` tool は、現在デフォルトで有効な -バンドル plugin です。つまり、OpenClaw の残りの plugin システムを削除せずに、 -これを無効化または置き換えできます: +デフォルトの `browser` ツールは、現在はデフォルトで有効になっているバンドル済み Plugin です。 +つまり、OpenClaw の残りの Plugin システムを削除せずに、これを無効化または置き換えできます: ```json5 { @@ -70,33 +69,32 @@ Gateway を再起動してください。 } ``` -同じ `browser` tool 名を提供する別の plugin をインストールする前に、 -バンドル plugin を無効にしてください。デフォルトのブラウザ体験には次の両方が必要です: +同じ `browser` ツール名を提供する別の Plugin をインストールする前に、バンドル済み Plugin を無効化してください。デフォルトのブラウザ体験には次の両方が必要です: - `plugins.entries.browser.enabled` が無効化されていないこと - `browser.enabled=true` -plugin だけをオフにすると、バンドルされた browser CLI（`openclaw browser`）、 -gateway メソッド（`browser.request`）、エージェント tool、およびデフォルトの browser 制御 -サービスがすべて一緒に消えます。`browser.*` config はそのまま残るため、 -置き換え plugin が再利用できます。 +Plugin だけをオフにすると、バンドル済みブラウザ CLI（`openclaw browser`）、 +Gateway メソッド（`browser.request`）、エージェントツール、デフォルトのブラウザ制御 +サービスはすべてまとめて消えます。置き換え用 Plugin が再利用できるように、 +`browser.*` config はそのまま保持されます。 -バンドル browser plugin は、現在 browser ランタイム実装も所有しています。 -core には共有 Plugin SDK ヘルパーと、 -古い内部 import パス向けの互換性 re-export だけが残ります。実際には、 -browser plugin パッケージを削除または置き換えると、 -2つ目の core 所有ランタイムが残るのではなく、browser 機能セット自体がなくなります。 +バンドル済みブラウザ Plugin は、現在ブラウザランタイム実装も所有しています。 +core には共有の Plugin SDK ヘルパーと、古い内部 import パス向けの互換性 +re-export だけが残ります。実際には、ブラウザ Plugin パッケージを削除または +置き換えると、core が所有する 2 つ目のランタイムが残るのではなく、ブラウザ機能 +一式が削除されます。 -browser config の変更は引き続き Gateway の再起動が必要です。これはバンドル plugin が -新しい設定で browser サービスを再登録するためです。 +ブラウザ config の変更では、バンドル済み Plugin が新しい設定でブラウザサービスを +再登録できるように、引き続き Gateway の再起動が必要です。 -## browser コマンドまたは tool が見つからない +## ブラウザコマンドまたはツールが見つからない -アップグレード後に `openclaw browser` が突然 unknown command になったり、 -エージェントが browser tool がないと報告したりする場合、最も一般的な原因は、 -`browser` を含まない制限付き `plugins.allow` リストです。 +アップグレード後に `openclaw browser` が突然 unknown command になった場合、 +またはエージェントがブラウザツールが見つからないと報告する場合、最も一般的な +原因は `browser` を含まない制限的な `plugins.allow` リストです。 -問題のある config の例: +壊れた config の例: ```json5 { @@ -106,7 +104,7 @@ browser config の変更は引き続き Gateway の再起動が必要です。 } ``` -修正するには、plugin allowlist に `browser` を追加します: +Plugin allowlist に `browser` を追加して修正してください: ```json5 { @@ -116,51 +114,49 @@ browser config の変更は引き続き Gateway の再起動が必要です。 } ``` -重要な注意: +重要な注意点: -- `plugins.allow` が設定されている場合、`browser.enabled=true` だけでは不十分です。 -- `plugins.allow` が設定されている場合、`plugins.entries.browser.enabled=true` だけでも不十分です。 -- `tools.alsoAllow: ["browser"]` はバンドルされた browser plugin を読み込み**ません**。これは plugin がすでに読み込まれた後に tool ポリシーを調整するだけです。 -- 制限付き plugin allowlist が不要なら、`plugins.allow` を削除してもデフォルトのバンドル browser 動作に戻せます。 +- `browser.enabled=true` だけでは、`plugins.allow` が設定されている場合は不十分です。 +- `plugins.entries.browser.enabled=true` だけでも、`plugins.allow` が設定されている場合は不十分です。 +- `tools.alsoAllow: ["browser"]` はバンドル済みブラウザ Plugin を読み込み**ません**。これは、Plugin がすでに読み込まれた後にツールポリシーを調整するだけです。 +- 制限的な Plugin allowlist が不要であれば、`plugins.allow` を削除することでもデフォルトのバンドル済みブラウザ動作が復元されます。 典型的な症状: - `openclaw browser` が unknown command になる。 -- `browser.request` が存在しない。 -- エージェントが browser tool を利用不可または欠落と報告する。 +- `browser.request` が見つからない。 +- エージェントがブラウザツールを利用不可または未検出として報告する。 ## プロファイル: `openclaw` と `user` - `openclaw`: 管理された分離ブラウザ（拡張機能不要）。 -- `user`: 実際にサインイン済みの Chrome - セッション向けの組み込み Chrome MCP 接続プロファイル。 +- `user`: 実際の**サインイン済み Chrome** セッションに接続する組み込み Chrome MCP アタッチプロファイル。 -エージェント browser tool 呼び出しでは: +エージェントのブラウザツール呼び出しでは: -- デフォルト: 分離された `openclaw` ブラウザを使います。 -- 既存のログイン済みセッションが重要で、ユーザーが - コンピューターの前にいて接続プロンプトをクリック/承認できる場合は、`profile="user"` を優先します。 -- `profile` は、特定のブラウザモードを使いたいときの明示的な上書きです。 +- デフォルト: 分離された `openclaw` ブラウザを使用します。 +- 既存のログイン済みセッションが重要で、ユーザーが PC の前にいてアタッチプロンプトをクリック/承認できる場合は `profile="user"` を優先します。 +- `profile` は、特定のブラウザモードを使いたいときの明示的なオーバーライドです。 -管理モードをデフォルトにしたい場合は `browser.defaultProfile: "openclaw"` を設定します。 +デフォルトで managed モードを使いたい場合は `browser.defaultProfile: "openclaw"` を設定してください。 ## 設定 -browser 設定は `~/.openclaw/openclaw.json` にあります。 +ブラウザ設定は `~/.openclaw/openclaw.json` にあります。 ```json5 { browser: { - enabled: true, // デフォルト: true + enabled: true, // default: true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 信頼できるプライベートネットワークアクセスにのみ opt in + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // legacy な単一プロファイル上書き - remoteCdpTimeoutMs: 1500, // リモート CDP HTTP タイムアウト（ms） - remoteCdpHandshakeTimeoutMs: 3000, // リモート CDP WebSocket ハンドシェイクタイムアウト（ms） + // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override + remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms) + remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms) defaultProfile: "openclaw", color: "#FF4500", headless: false, @@ -189,32 +185,32 @@ browser 設定は `~/.openclaw/openclaw.json` にあります。 注意: -- browser 制御サービスは `gateway.port` から導出されるポートで loopback にバインドします - （デフォルト: `18791`。gateway + 2）。 -- Gateway ポート（`gateway.port` または `OPENCLAW_GATEWAY_PORT`）を上書きすると、 - 派生 browser ポートも同じ「ファミリー」に収まるように移動します。 -- `cdpUrl` が未設定の場合、デフォルトは管理されたローカル CDP ポートです。 -- `remoteCdpTimeoutMs` は、リモート（非 loopback）CDP 到達性チェックに適用されます。 -- `remoteCdpHandshakeTimeoutMs` は、リモート CDP WebSocket 到達性チェックに適用されます。 -- browser の navigation/open-tab は、ナビゲーション前に SSRF ガードされ、 - ナビゲーション後の最終 `http(s)` URL に対してもベストエフォートで再チェックされます。 -- strict SSRF モードでは、リモート CDP エンドポイントのディスカバリー/probe（`cdpUrl`。`/json/version` 参照を含む）もチェック対象です。 -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` はデフォルトで無効です。意図的にプライベートネットワーク browser アクセスを信頼する場合にのみ `true` に設定してください。 -- `browser.ssrfPolicy.allowPrivateNetwork` は、互換性のための legacy alias として引き続きサポートされます。 -- `attachOnly: true` は「ローカルブラウザを起動しない。すでに実行中なら接続のみ行う」という意味です。 -- `color` とプロファイルごとの `color` は browser UI に色を付け、どのプロファイルがアクティブかを見分けやすくします。 -- デフォルトプロファイルは `openclaw`（OpenClaw 管理のスタンドアロンブラウザ）です。サインイン済みユーザーブラウザに opt in するには `defaultProfile: "user"` を使います。 -- 自動検出順序: システムデフォルトブラウザが Chromium ベースならそれを使用し、そうでなければ Chrome → Brave → Edge → Chromium → Chrome Canary の順です。 -- ローカル `openclaw` プロファイルは `cdpPort`/`cdpUrl` を自動割り当てするため、これらを設定するのはリモート CDP の場合だけにしてください。 -- `driver: "existing-session"` は、生の CDP ではなく Chrome DevTools MCP を使います。 - この driver には `cdpUrl` を設定しないでください。 -- Brave や Edge のような非デフォルトの Chromium ユーザープロファイルに - existing-session プロファイルを接続させるには、`browser.profiles..userDataDir` を設定してください。 +- ブラウザ制御サービスは `gateway.port` から導出されたポートで loopback にバインドされます + （デフォルト: `18791`、つまり gateway + 2）。 +- Gateway ポート（`gateway.port` または `OPENCLAW_GATEWAY_PORT`）をオーバーライドすると、 + 同じ「ファミリー」を保つために導出ブラウザポートもずれます。 +- `cdpUrl` が未設定の場合は、managed なローカル CDP ポートがデフォルトになります。 +- `remoteCdpTimeoutMs` は remote（非 loopback）CDP 到達性チェックに適用されます。 +- `remoteCdpHandshakeTimeoutMs` は remote CDP WebSocket 到達性チェックに適用されます。 +- ブラウザのナビゲーション/タブを開く処理は、ナビゲーション前に SSRF ガードされ、ナビゲーション後の最終 `http(s)` URL に対してベストエフォートで再チェックされます。 +- strict SSRF モードでは、remote CDP エンドポイントの検出/プローブ（`cdpUrl`、`/json/version` 参照を含む）もチェックされます。 +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` はデフォルトで無効です。意図的に private-network ブラウザアクセスを信頼する場合にのみ `true` に設定してください。 +- `browser.ssrfPolicy.allowPrivateNetwork` は互換性のための legacy alias として引き続きサポートされています。 +- `attachOnly: true` は「ローカルブラウザを決して起動せず、すでに実行中の場合のみ接続する」ことを意味します。 +- `color` とプロファイルごとの `color` はブラウザ UI を色付けし、どのプロファイルがアクティブかを見分けられるようにします。 +- デフォルトプロファイルは `openclaw`（OpenClaw 管理のスタンドアロンブラウザ）です。サインイン済みユーザーブラウザを使うには `defaultProfile: "user"` を指定してください。 +- 自動検出順序: システムのデフォルトブラウザが Chromium ベースならそれを使用し、そうでなければ Chrome → Brave → Edge → Chromium → Chrome Canary の順です。 +- ローカル `openclaw` プロファイルは `cdpPort`/`cdpUrl` を自動割り当てします。これらは remote CDP に対してのみ設定してください。 +- `driver: "existing-session"` は raw CDP の代わりに Chrome DevTools MCP を使用します。この + driver には `cdpUrl` を設定しないでください。 +- `browser.profiles..userDataDir` は、existing-session プロファイルを + Brave や Edge などの非デフォルト Chromium ユーザープロファイルに接続させたい場合に設定してください。 ## Brave（または別の Chromium ベースブラウザ）を使う -**システムデフォルト**ブラウザが Chromium ベース（Chrome/Brave/Edge など）の場合、 -OpenClaw は自動的にそれを使います。自動検出を上書きするには `browser.executablePath` を設定します: +**システムのデフォルト**ブラウザが Chromium ベース（Chrome/Brave/Edge など）の場合、 +OpenClaw は自動的にそれを使用します。自動検出をオーバーライドするには +`browser.executablePath` を設定してください: CLI の例: @@ -248,49 +244,50 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## ローカル制御とリモート制御 - **ローカル制御（デフォルト）:** Gateway が loopback 制御サービスを起動し、ローカルブラウザを起動できます。 -- **リモート制御（node host）:** ブラウザがあるマシン上で node host を実行し、Gateway が browser アクションをその node にプロキシします。 -- **リモート CDP:** リモートの Chromium ベースブラウザに接続するには `browser.profiles..cdpUrl`（または `browser.cdpUrl`）を設定します。この場合、OpenClaw はローカルブラウザを起動しません。 +- **リモート制御（node host）:** ブラウザを持つマシン上で node host を実行すると、Gateway がブラウザアクションをそこへプロキシします。 +- **remote CDP:** `browser.profiles..cdpUrl`（または `browser.cdpUrl`）を設定すると、 + remote の Chromium ベースブラウザに接続できます。この場合、OpenClaw はローカルブラウザを起動しません。 -停止動作はプロファイルモードによって異なります: +停止時の動作はプロファイルモードによって異なります: -- ローカル管理プロファイル: `openclaw browser stop` は - OpenClaw が起動した browser プロセスを停止します -- attach-only およびリモート CDP プロファイル: `openclaw browser stop` は、アクティブな - 制御セッションを閉じ、Playwright/CDP のエミュレーション上書き（viewport、 - color scheme、locale、timezone、offline mode などの状態）を解除します。 - OpenClaw 自体が browser プロセスを起動していない場合でも同様です +- ローカル managed プロファイル: `openclaw browser stop` は + OpenClaw が起動したブラウザプロセスを停止します +- attach-only および remote CDP プロファイル: `openclaw browser stop` はアクティブな + 制御セッションを閉じ、Playwright/CDP のエミュレーションオーバーライド（ビューポート、 + カラースキーム、ロケール、タイムゾーン、オフラインモード、その他同様の状態）を解除します。 + OpenClaw がブラウザプロセスを起動していない場合でも同様です -リモート CDP URL には auth を含めることができます: +remote CDP URL には auth を含めることができます: - クエリトークン（例: `https://provider.example?token=`） - HTTP Basic auth（例: `https://user:pass@provider.example`） -OpenClaw は `/json/*` エンドポイント呼び出し時と -CDP WebSocket 接続時の両方で auth を保持します。 -トークンは config ファイルにコミットするのではなく、環境変数やシークレットマネージャーを使うことを推奨します。 +OpenClaw は `/json/*` エンドポイントを呼び出すときも、CDP WebSocket に接続するときも +その auth を保持します。トークンは config ファイルにコミットするのではなく、 +環境変数や secrets manager を使うことを推奨します。 -## Node browser プロキシ（ゼロ設定デフォルト） +## Node ブラウザプロキシ（ゼロ設定デフォルト） -browser があるマシンで **node host** を実行している場合、OpenClaw は -追加の browser 設定なしで browser tool 呼び出しをその node に自動ルーティングできます。 -これはリモート Gateway のデフォルト経路です。 +ブラウザがあるマシンで **node host** を実行している場合、OpenClaw は +追加のブラウザ設定なしでブラウザツール呼び出しをその node に自動ルーティングできます。 +これは remote gateway のデフォルト経路です。 注意: -- node host は、そのローカル browser 制御サーバーを **proxy command** として公開します。 -- プロファイルは node 側の `browser.profiles` 設定（ローカルと同じ）から取得されます。 -- `nodeHost.browserProxy.allowProfiles` は任意です。空のままにすると legacy/デフォルト動作になり、設定済みのすべてのプロファイルがプロキシ経由で到達可能なままです。プロファイル作成/削除ルートも含まれます。 -- `nodeHost.browserProxy.allowProfiles` を設定すると、OpenClaw はそれを最小権限境界として扱います: allowlist に含まれるプロファイルだけを対象にでき、永続プロファイル作成/削除ルートはプロキシサーフェス上でブロックされます。 -- 不要なら無効化できます: +- node host はそのローカルブラウザ制御サーバーを**プロキシコマンド**として公開します。 +- プロファイルは node 自身の `browser.profiles` config から取得されます（ローカルと同じ）。 +- `nodeHost.browserProxy.allowProfiles` はオプションです。空のままにすると legacy/default の動作になり、プロファイル作成/削除ルートを含め、設定済みのすべてのプロファイルがプロキシ経由で到達可能なままになります。 +- `nodeHost.browserProxy.allowProfiles` を設定すると、OpenClaw はそれを最小権限境界として扱います。allowlist に載ったプロファイルだけを対象にでき、永続プロファイルの作成/削除ルートはプロキシ画面でブロックされます。 +- 不要であれば無効化してください: - node 側: `nodeHost.browserProxy.enabled=false` - gateway 側: `gateway.nodes.browser.mode="off"` -## Browserless（ホスト型リモート CDP） +## Browserless（ホスト型 remote CDP） -[Browserless](https://browserless.io) は、 -HTTPS および WebSocket 経由で CDP 接続 URL を公開するホスト型 Chromium サービスです。OpenClaw はどちらの形式も使用できますが、 -リモート browser プロファイルでは Browserless の接続ドキュメントにある -直接 WebSocket URL が最も簡単です。 +[Browserless](https://browserless.io) は、HTTPS と WebSocket 経由で +CDP 接続 URL を公開するホスト型 Chromium サービスです。OpenClaw はどちらの形式も使用できますが、 +remote ブラウザプロファイルでは、最も簡単な方法は Browserless の接続ドキュメントにある +直接 WebSocket URL を使うことです。 例: @@ -313,29 +310,29 @@ HTTPS および WebSocket 経由で CDP 接続 URL を公開するホスト型 C 注意: -- `` は実際の Browserless token に置き換えてください。 -- Browserless アカウントに対応するリージョン endpoint を選んでください（詳細は Browserless のドキュメントを参照）。 +- `` は実際の Browserless トークンに置き換えてください。 +- Browserless アカウントに対応するリージョンエンドポイントを選んでください（詳細は各種ドキュメントを参照）。 - Browserless から HTTPS ベース URL が提供される場合は、それを - 直接 CDP 接続用に `wss://` に変換することも、 - HTTPS URL のまま使って OpenClaw に `/json/version` をディスカバーさせることもできます。 + 直接 CDP 接続用の `wss://` に変換するか、HTTPS URL のままにして OpenClaw に + `/json/version` を検出させることができます。 -## 直接 WebSocket CDP provider +## 直接 WebSocket CDP プロバイダー -一部のホスト型 browser サービスは、標準の HTTP ベース CDP ディスカバリー（`/json/version`）ではなく、 -**直接 WebSocket** endpoint を公開しています。OpenClaw は両方をサポートします: +一部のホスト型ブラウザサービスは、標準の HTTP ベース CDP 検出（`/json/version`）ではなく +**直接 WebSocket** エンドポイントを公開しています。OpenClaw は両方をサポートします: - **HTTP(S) エンドポイント** — OpenClaw は `/json/version` を呼び出して - WebSocket debugger URL を検出してから接続します。 -- **WebSocket エンドポイント**（`ws://` / `wss://`）— OpenClaw は `/json/version` をスキップして直接接続します。これは + WebSocket デバッガー URL を検出し、その後接続します。 +- **WebSocket エンドポイント**（`ws://` / `wss://`）— OpenClaw は直接接続し、 + `/json/version` をスキップします。これは [Browserless](https://browserless.io)、 - [Browserbase](https://www.browserbase.com)、または - WebSocket URL を提供する任意の provider で使用してください。 + [Browserbase](https://www.browserbase.com)、または WebSocket URL を渡す + 任意のプロバイダーのようなサービスに使用してください。 ### Browserbase -[Browserbase](https://www.browserbase.com) は、 -組み込み CAPTCHA 解決、stealth mode、および residential -proxy を備えた headless browser 実行用クラウドプラットフォームです。 +[Browserbase](https://www.browserbase.com) は、組み込みの CAPTCHA 解決、ステルスモード、 +住宅用プロキシを備えた headless ブラウザ実行用のクラウドプラットフォームです。 ```json5 { @@ -356,65 +353,62 @@ proxy を備えた headless browser 実行用クラウドプラットフォー 注意: -- [Sign up](https://www.browserbase.com/sign-up) して、 - [Overview dashboard](https://www.browserbase.com/overview) から **API Key** +- [登録](https://www.browserbase.com/sign-up) して、[Overview ダッシュボード](https://www.browserbase.com/overview)から **API Key** をコピーしてください。 -- `` は実際の Browserbase API key に置き換えてください。 -- Browserbase は WebSocket 接続時に browser session を自動作成するため、 - 手動のセッション作成手順は不要です。 -- 無料プランでは、同時セッション 1 つ、月あたり browser 1 時間まで利用できます。 - 有料プランの上限については [pricing](https://www.browserbase.com/pricing) を参照してください。 -- 完全な API - リファレンス、SDK ガイド、および統合例については [Browserbase docs](https://docs.browserbase.com) を参照してください。 +- `` は実際の Browserbase API キーに置き換えてください。 +- Browserbase は WebSocket 接続時にブラウザセッションを自動作成するため、 + 手動のセッション作成ステップは不要です。 +- 無料プランでは、同時セッション 1 つ、月あたり 1 ブラウザ時間まで利用できます。 + 有料プランの上限は [pricing](https://www.browserbase.com/pricing) を参照してください。 +- 完全な API リファレンス、SDK ガイド、統合例については + [Browserbase docs](https://docs.browserbase.com) を参照してください。 ## セキュリティ 重要な考え方: -- browser 制御は loopback 専用です。アクセスは Gateway の auth または node pairing を通じて流れます。 -- スタンドアロンの loopback browser HTTP API は、**shared-secret auth のみ**を使用します: +- ブラウザ制御は loopback 専用です。アクセスは Gateway の auth または node ペアリングを通ります。 +- スタンドアロンの loopback ブラウザ HTTP API は**shared-secret auth のみ**を使用します: gateway token bearer auth、`x-openclaw-password`、または - 設定された gateway password を使う HTTP Basic auth です。 -- Tailscale Serve の identity headers と `gateway.auth.mode: "trusted-proxy"` は、 - このスタンドアロン loopback browser API の認証には**なりません**。 -- browser 制御が有効で、shared-secret auth が設定されていない場合、OpenClaw は - 起動時に `gateway.auth.token` を自動生成し、config に永続化します。 -- `gateway.auth.mode` が - すでに `password`、`none`、または `trusted-proxy` の場合、OpenClaw はその token を自動生成**しません**。 -- Gateway とすべての node host はプライベートネットワーク（Tailscale）上に保ち、 - 公開インターネットに露出させないでください。 -- リモート CDP URL/token はシークレットとして扱い、環境変数やシークレットマネージャーを優先してください。 + 設定済み gateway password を使う HTTP Basic auth です。 +- Tailscale Serve の identity header と `gateway.auth.mode: "trusted-proxy"` は + このスタンドアロン loopback ブラウザ API を**認証しません**。 +- ブラウザ制御が有効で、shared-secret auth が未設定の場合、OpenClaw は + 起動時に `gateway.auth.token` を自動生成して config に永続化します。 +- `gateway.auth.mode` がすでに + `password`、`none`、または `trusted-proxy` の場合、OpenClaw はその token を自動生成**しません**。 +- Gateway と node host は private network（Tailscale）上に維持し、public に公開しないでください。 +- remote CDP URL/token は secrets として扱い、環境変数や secrets manager を優先してください。 -リモート CDP のヒント: +remote CDP のヒント: -- 可能であれば暗号化されたエンドポイント（HTTPS または WSS）と短命トークンを使ってください。 -- 長期トークンを config ファイルに直接埋め込むのは避けてください。 +- 可能であれば暗号化されたエンドポイント（HTTPS または WSS）と短命トークンを優先してください。 +- 長期間有効なトークンを config ファイルに直接埋め込むのは避けてください。 ## プロファイル（マルチブラウザ） -OpenClaw は複数の名前付きプロファイル（ルーティング設定）をサポートします。プロファイルには次の種類があります: +OpenClaw は複数の名前付きプロファイル（ルーティング設定）をサポートしています。プロファイルには次の種類があります: -- **openclaw-managed**: 専用の Chromium ベース browser インスタンス。独自の user data directory + CDP port を持ちます -- **remote**: 明示的な CDP URL（別の場所で動作している Chromium ベース browser） -- **existing session**: Chrome DevTools MCP 自動接続を通じた既存の Chrome プロファイル +- **openclaw-managed**: 専用の user data directory + CDP port を持つ、専用の Chromium ベースブラウザインスタンス +- **remote**: 明示的な CDP URL（別の場所で実行中の Chromium ベースブラウザ） +- **existing session**: Chrome DevTools MCP 自動接続経由の、既存の Chrome プロファイル デフォルト: -- `openclaw` プロファイルは、存在しない場合に自動作成されます。 -- `user` プロファイルは、Chrome MCP の existing-session 接続用に組み込まれています。 -- existing-session プロファイルは `user` 以外では opt-in です。`--driver existing-session` で作成してください。 +- `openclaw` プロファイルは、存在しない場合は自動作成されます。 +- `user` プロファイルは、Chrome MCP existing-session 接続用に組み込まれています。 +- existing-session プロファイルは `user` 以外ではオプトインです。`--driver existing-session` で作成してください。 - ローカル CDP ポートはデフォルトで **18800–18899** から割り当てられます。 -- プロファイルを削除すると、そのローカルデータディレクトリは Trash に移動されます。 +- プロファイルを削除すると、そのローカル data directory は Trash に移動されます。 -すべての制御エンドポイントは `?profile=` を受け付けます。CLI では `--browser-profile` を使います。 +すべての制御エンドポイントは `?profile=` を受け付けます。CLI は `--browser-profile` を使用します。 ## Chrome DevTools MCP 経由の existing-session -OpenClaw は、公式の Chrome DevTools MCP サーバーを通じて、 -実行中の Chromium ベース browser プロファイルにも接続できます。これにより、その browser プロファイルですでに -開かれているタブとログイン状態を再利用できます。 +OpenClaw は、公式の Chrome DevTools MCP サーバーを通じて、実行中の Chromium ベースブラウザプロファイルにも接続できます。 +これにより、そのブラウザプロファイルですでに開かれているタブとログイン状態を再利用できます。 -公式の背景説明とセットアップ参照: +公式の背景情報とセットアップ参照: - [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) @@ -423,15 +417,15 @@ OpenClaw は、公式の Chrome DevTools MCP サーバーを通じて、 - `user` -任意: 名前、色、または browser data directory を変えたい場合は、 +オプション: 別の名前、色、または browser data directory を使いたい場合は、 独自の custom existing-session プロファイルを作成できます。 デフォルト動作: -- 組み込みの `user` プロファイルは Chrome MCP auto-connect を使い、 - デフォルトのローカル Google Chrome プロファイルを対象にします。 +- 組み込みの `user` プロファイルは Chrome MCP auto-connect を使用し、 + ローカルのデフォルト Google Chrome プロファイルを対象にします。 -Brave、Edge、Chromium、またはデフォルト以外の Chrome プロファイルには `userDataDir` を使います: +Brave、Edge、Chromium、またはデフォルト以外の Chrome プロファイルには `userDataDir` を使ってください: ```json5 { @@ -448,11 +442,11 @@ Brave、Edge、Chromium、またはデフォルト以外の Chrome プロファ } ``` -次に、対応する browser 側で次を行います: +次に、対応するブラウザで以下を行います: -1. その browser の inspect page for remote debugging を開きます。 -2. remote debugging を有効にします。 -3. browser を起動したままにし、OpenClaw が接続するときに接続プロンプトを承認します。 +1. そのブラウザのリモートデバッグ用 inspect page を開きます。 +2. リモートデバッグを有効にします。 +3. ブラウザを起動したままにし、OpenClaw が接続するときに接続確認プロンプトを承認します。 一般的な inspect page: @@ -460,7 +454,7 @@ Brave、Edge、Chromium、またはデフォルト以外の Chrome プロファ - Brave: `brave://inspect/#remote-debugging` - Edge: `edge://inspect/#remote-debugging` -ライブ接続スモークテスト: +ライブ接続のスモークテスト: ```bash openclaw browser --browser-profile user start @@ -469,73 +463,71 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -成功時の見え方: +成功時の状態: - `status` に `driver: existing-session` が表示される - `status` に `transport: chrome-mcp` が表示される - `status` に `running: true` が表示される -- `tabs` に、すでに開いている browser タブが一覧表示される -- `snapshot` が、選択されたライブタブから refs を返す +- `tabs` に、すでに開いているブラウザタブが一覧表示される +- `snapshot` が選択中のライブタブから refs を返す -接続がうまくいかない場合の確認事項: +接続できない場合に確認すること: -- 対象の Chromium ベース browser がバージョン `144+` である -- その browser の inspect page で remote debugging が有効である -- browser に接続同意プロンプトが表示され、それを承認した -- `openclaw doctor` は古い拡張機能ベースの browser config を移行し、 +- 対象の Chromium ベースブラウザがバージョン `144+` である +- そのブラウザの inspect page でリモートデバッグが有効になっている +- ブラウザに接続確認プロンプトが表示され、それを承認した +- `openclaw doctor` は古い拡張機能ベースのブラウザ config を移行し、 デフォルト auto-connect プロファイル用に Chrome がローカルにインストールされているかを確認しますが、 - browser 側の remote debugging を代わりに有効化することはできません + ブラウザ側のリモートデバッグを代わりに有効化することはできません -エージェント利用: +エージェントでの使用: -- ユーザーのログイン済み browser 状態が必要な場合は `profile="user"` を使います。 -- custom existing-session プロファイルを使う場合は、その明示的なプロファイル名を渡してください。 -- このモードは、ユーザーがコンピューターの前にいて接続 - プロンプトを承認できる場合にのみ選んでください。 +- ユーザーのログイン済みブラウザ状態が必要な場合は `profile="user"` を使用します。 +- custom existing-session プロファイルを使う場合は、その明示的なプロファイル名を渡します。 +- このモードは、ユーザーが PC の前にいて接続確認プロンプトを承認できる場合にのみ選択してください。 - Gateway または node host は `npx chrome-devtools-mcp@latest --autoConnect` を起動できます 注意: -- この経路は、サインイン済み browser セッション内で - 操作できるため、分離された `openclaw` プロファイルより高リスクです。 -- OpenClaw はこの driver では browser を起動せず、 - 既存セッションにのみ接続します。 +- この経路は分離された `openclaw` プロファイルより高リスクです。サインイン済みブラウザセッション内で操作できるためです。 +- この driver では OpenClaw はブラウザを起動しません。既存セッションにのみ接続します。 - OpenClaw はここで公式の Chrome DevTools MCP `--autoConnect` フローを使用します。 `userDataDir` が設定されている場合、OpenClaw はそれを渡して、その明示的な Chromium user data directory を対象にします。 -- existing-session のスクリーンショットは、snapshot からのページキャプチャと `--ref` 要素 +- existing-session のスクリーンショットは、ページキャプチャとスナップショットからの `--ref` 要素 キャプチャをサポートしますが、CSS `--element` セレクターはサポートしません。 -- existing-session のページスクリーンショットは、Playwright なしで Chrome MCP 経由で動作します。 - ref ベースの要素スクリーンショット（`--ref`）もそこでは動作しますが、`--full-page` +- existing-session のページスクリーンショットは、Chrome MCP 経由で Playwright なしでも動作します。 + ref ベースの要素スクリーンショット（`--ref`）も同様に動作しますが、`--full-page` は `--ref` や `--element` と組み合わせられません。 -- existing-session のアクションは、依然として managed browser - 経路より制限があります: - - `click`、`type`、`hover`、`scrollIntoView`、`drag`、`select` には - CSS セレクターではなく snapshot refs が必要です - - `click` は左ボタンのみ対応です（ボタン上書きや modifier は不可） - - `type` は `slowly=true` をサポートしません。`fill` または `press` を使ってください +- existing-session のアクションは、managed browser の + 経路よりもまだ制限があります: + - `click`、`type`、`hover`、`scrollIntoView`、`drag`、`select` は + CSS セレクターではなく snapshot refs を必要とします + - `click` は左ボタンのみです（ボタンオーバーライドや修飾キーは不可） + - `type` は `slowly=true` をサポートしません。`fill` または `press` を使用してください - `press` は `delayMs` をサポートしません - `hover`、`scrollIntoView`、`drag`、`select`、`fill`、`evaluate` は - 呼び出しごとの timeout 上書きをサポートしません + 呼び出しごとの timeout オーバーライドをサポートしません - `select` は現在 1 つの値のみサポートします -- existing-session の `wait --url` は、他の browser driver と同様に完全一致、部分一致、および glob パターンをサポートします。`wait --load networkidle` はまだサポートされていません。 -- existing-session の upload hook には `ref` または `inputRef` が必要で、 - 一度に 1 ファイルのみサポートし、CSS `element` ターゲティングはサポートしません。 -- existing-session の dialog hook は timeout 上書きをサポートしません。 -- batch - actions、PDF エクスポート、ダウンロードインターセプト、`responsebody` など、一部の機能は依然として managed browser 経路を必要とします。 -- existing-session はホストローカルです。Chrome が別のマシン上、または - 別のネットワーク名前空間にある場合は、代わりに remote CDP または node host を使ってください。 +- existing-session の `wait --url` は、他の browser driver と同様に exact、substring、 + glob パターンをサポートします。`wait --load networkidle` はまだサポートされていません。 +- existing-session の upload hook は `ref` または `inputRef` を必要とし、 + 1 度に 1 ファイルのみサポートし、CSS `element` ターゲティングはサポートしません。 +- existing-session の dialog hook は timeout オーバーライドをサポートしません。 +- 一部の機能は依然として managed browser の経路が必要です。これには batch + actions、PDF export、download interception、`responsebody` が含まれます。 +- existing-session は host-local です。Chrome が別のマシン上にあるか、 + 別の network namespace にある場合は、代わりに remote CDP または node host を使用してください。 -## 分離保証 +## 分離の保証 -- **専用 user data dir**: 個人用 browser プロファイルには決して触れません。 -- **専用ポート**: 開発ワークフローとの衝突を避けるため `9222` を使いません。 -- **決定論的タブ制御**: 「最後のタブ」ではなく `targetId` でタブを対象にします。 +- **専用 user data dir**: 個人用ブラウザプロファイルには一切触れません。 +- **専用ポート**: 開発ワークフローとの衝突を避けるため `9222` を使用しません。 +- **決定的なタブ制御**: 「最後のタブ」ではなく `targetId` でタブを対象指定します。 -## browser 選択 +## ブラウザの選択 -ローカル起動時、OpenClaw は利用可能なもののうち最初のものを選びます: +ローカルで起動する場合、OpenClaw は利用可能な最初のものを選びます: 1. Chrome 2. Brave @@ -543,7 +535,7 @@ openclaw browser --browser-profile user snapshot --format ai 4. Chromium 5. Chrome Canary -`browser.executablePath` で上書きできます。 +`browser.executablePath` でオーバーライドできます。 プラットフォーム: @@ -551,41 +543,41 @@ openclaw browser --browser-profile user snapshot --format ai - Linux: `google-chrome`、`brave`、`microsoft-edge`、`chromium` などを探します。 - Windows: 一般的なインストール場所を確認します。 -## 制御 API（任意） +## 制御 API（オプション） ローカル統合専用として、Gateway は小さな loopback HTTP API を公開します: -- ステータス/開始/停止: `GET /`、`POST /start`、`POST /stop` -- タブ: `GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId` -- スナップショット/スクリーンショット: `GET /snapshot`、`POST /screenshot` -- アクション: `POST /navigate`、`POST /act` -- フック: `POST /hooks/file-chooser`、`POST /hooks/dialog` -- ダウンロード: `POST /download`、`POST /wait/download` -- デバッグ: `GET /console`、`POST /pdf` -- デバッグ: `GET /errors`、`GET /requests`、`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` +- Status/start/stop: `GET /`、`POST /start`、`POST /stop` +- Tabs: `GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId` +- Snapshot/screenshot: `GET /snapshot`、`POST /screenshot` +- Actions: `POST /navigate`、`POST /act` +- Hooks: `POST /hooks/file-chooser`、`POST /hooks/dialog` +- Downloads: `POST /download`、`POST /wait/download` +- Debugging: `GET /console`、`POST /pdf` +- Debugging: `GET /errors`、`GET /requests`、`POST /trace/start`、`POST /trace/stop`、`POST /highlight` +- Network: `POST /response/body` +- State: `GET /cookies`、`POST /cookies/set`、`POST /cookies/clear` +- State: `GET /storage/:kind`、`POST /storage/:kind/set`、`POST /storage/:kind/clear` +- Settings: `POST /set/offline`、`POST /set/headers`、`POST /set/credentials`、`POST /set/geolocation`、`POST /set/media`、`POST /set/timezone`、`POST /set/locale`、`POST /set/device` すべてのエンドポイントは `?profile=` を受け付けます。 -shared-secret gateway auth が設定されている場合、browser HTTP ルートにも auth が必要です: +shared-secret gateway auth が設定されている場合、ブラウザ HTTP ルートにも auth が必要です: - `Authorization: Bearer ` - `x-openclaw-password: ` またはその password を使う HTTP Basic auth 注意: -- このスタンドアロン loopback browser API は、trusted-proxy や - Tailscale Serve の identity headers を**利用しません**。 +- このスタンドアロン loopback ブラウザ API は `trusted-proxy` や + Tailscale Serve の identity header を使用しません。 - `gateway.auth.mode` が `none` または `trusted-proxy` の場合、これらの loopback browser - ルートはそれらの identity-bearing モードを継承しません。loopback 専用に保ってください。 + ルートはそれらの identity-bearing モードを継承しません。loopback 専用のままにしてください。 -### `/act` のエラー契約 +### `/act` エラー契約 -`POST /act` は、ルートレベルの検証および -ポリシー失敗に対して構造化エラーレスポンスを使います: +`POST /act` は、ルートレベルのバリデーションと +ポリシー失敗に対して構造化されたエラーレスポンスを使用します: ```json { "error": "", "code": "ACT_*" } @@ -594,28 +586,28 @@ shared-secret gateway auth が設定されている場合、browser HTTP ルー 現在の `code` 値: - `ACT_KIND_REQUIRED`（HTTP 400）: `kind` が欠落しているか認識されません。 -- `ACT_INVALID_REQUEST`（HTTP 400）: アクションペイロードの正規化または検証に失敗しました。 -- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）: 未対応のアクション種別で `selector` が使用されました。 +- `ACT_INVALID_REQUEST`（HTTP 400）: アクションペイロードの正規化またはバリデーションに失敗しました。 +- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）: 未対応のアクション種別で `selector` が使われました。 - `ACT_EVALUATE_DISABLED`（HTTP 403）: config により `evaluate`（または `wait --fn`）が無効です。 -- `ACT_TARGET_ID_MISMATCH`（HTTP 403）: トップレベルまたは batch の `targetId` がリクエスト対象と競合しています。 -- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）: existing-session プロファイルではそのアクションはサポートされていません。 +- `ACT_TARGET_ID_MISMATCH`（HTTP 403）: トップレベルまたはバッチ化された `targetId` がリクエスト対象と競合しています。 +- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）: このアクションは existing-session プロファイルではサポートされません。 -その他のランタイム失敗では、依然として `code` -フィールドなしの `{ "error": "" }` が返る場合があります。 +その他のランタイム失敗では、依然として +`code` フィールドなしの `{ "error": "" }` が返る場合があります。 ### Playwright 要件 一部の機能（navigate/act/AI snapshot/role snapshot、要素スクリーンショット、 -PDF）には Playwright が必要です。Playwright がインストールされていない場合、それらのエンドポイントは -明確な 501 エラーを返します。 +PDF）には Playwright が必要です。Playwright がインストールされていない場合、 +それらのエンドポイントは明確な 501 エラーを返します。 -Playwright なしでも動作するもの: +Playwright なしでも引き続き動作するもの: -- ARIA スナップショット -- タブごとの CDP - WebSocket が利用可能な場合の managed `openclaw` browser 向けページスクリーンショット -- `existing-session` / Chrome MCP プロファイル向けページスクリーンショット -- snapshot 出力からの `existing-session` ref ベーススクリーンショット（`--ref`） +- ARIA snapshots +- タブごとの CDP WebSocket が利用可能な場合の、managed `openclaw` browser のページ + スクリーンショット +- `existing-session` / Chrome MCP プロファイルのページスクリーンショット +- snapshot 出力からの `existing-session` の ref ベーススクリーンショット（`--ref`） 引き続き Playwright が必要なもの: @@ -623,41 +615,46 @@ Playwright なしでも動作するもの: - `act` - AI snapshots / role snapshots - CSS セレクター要素スクリーンショット（`--element`） -- 完全な browser PDF エクスポート +- 完全な browser PDF export 要素スクリーンショットでは `--full-page` も拒否されます。このルートは `fullPage is not supported for element screenshots` を返します。 -Playwright is not available in this gateway build` と表示された場合は、完全な -Playwright パッケージ（`playwright-core` ではなく）をインストールして Gateway を再起動するか、 -browser サポート付きで OpenClaw を再インストールしてください。 +`Playwright is not available in this gateway build` と表示された場合は、完全な +Playwright パッケージ（`playwright-core` ではなく）をインストールして gateway を再起動するか、 +ブラウザサポート付きで OpenClaw を再インストールしてください。 #### Docker での Playwright インストール -Gateway が Docker で動作している場合は、`npx playwright` を避けてください（npm override の競合があります）。 -代わりにバンドルされた CLI を使います: -__OC_I18N_900012__ -browser ダウンロードを永続化するには、`PLAYWRIGHT_BROWSERS_PATH`（たとえば -`/home/node/.cache/ms-playwright`）を設定し、`/home/node` が -`OPENCLAW_HOME_VOLUME` または bind mount によって永続化されていることを確認してください。[Docker](/install/docker) を参照してください。 +Gateway が Docker 上で動作している場合は、`npx playwright` を避けてください（npm の override 競合が発生します）。 +代わりに、バンドル済み CLI を使用してください: + +```bash +docker compose run --rm openclaw-cli \ + node /app/node_modules/playwright-core/cli.js install chromium +``` + +ブラウザダウンロードを永続化するには、`PLAYWRIGHT_BROWSERS_PATH`（例: +`/home/node/.cache/ms-playwright`）を設定し、`OPENCLAW_HOME_VOLUME` または bind mount によって +`/home/node` が永続化されるようにしてください。[Docker](/ja-JP/install/docker) を参照してください。 ## 仕組み（内部） -高レベルの流れ: +高レベルのフロー: -- 小さな **control server** が HTTP リクエストを受け付けます。 -- **CDP** を通じて Chromium ベース browser（Chrome/Brave/Edge/Chromium）に接続します。 -- 高度なアクション（クリック/入力/スナップショット/PDF）には、 - CDP 上で **Playwright** を使います。 -- Playwright がない場合は、Playwright 非依存の操作のみ利用できます。 +- 小さな**制御サーバー**が HTTP リクエストを受け付けます。 +- **CDP** 経由で Chromium ベースブラウザ（Chrome/Brave/Edge/Chromium）に接続します。 +- 高度なアクション（クリック/入力/スナップショット/PDF）には、CDP の上に + **Playwright** を使用します。 +- Playwright がない場合は、Playwright を必要としない操作のみ利用できます。 -この設計により、エージェントは安定した決定論的インターフェース上に保たれつつ、 -ローカル/リモート browser やプロファイルを切り替えられます。 +この設計により、エージェントは安定した決定的インターフェース上で動作しつつ、 +ローカル/リモートのブラウザやプロファイルを切り替えられます。 ## CLI クイックリファレンス -すべてのコマンドは、特定プロファイルを対象にするため `--browser-profile ` を受け付けます。 -すべてのコマンドは、機械可読な出力（安定したペイロード）のため `--json` も受け付けます。 +すべてのコマンドは、特定のプロファイルを対象にするために `--browser-profile ` を受け付けます。 +また、すべてのコマンドは machine-readable な出力（安定したペイロード）のために `--json` も受け付けます。 基本: @@ -673,7 +670,7 @@ browser ダウンロードを永続化するには、`PLAYWRIGHT_BROWSERS_PATH` - `openclaw browser focus abcd1234` - `openclaw browser close abcd1234` -調査: +検査: - `openclaw browser screenshot` - `openclaw browser screenshot --full-page` @@ -690,10 +687,10 @@ browser ダウンロードを永続化するには、`PLAYWRIGHT_BROWSERS_PATH` ライフサイクルに関する注意: -- attach-only およびリモート CDP プロファイルでは、テスト後のクリーンアップコマンドとしても - `openclaw browser stop` が正しい選択です。これは - 基盤となる browser を終了するのではなく、アクティブな制御セッションを閉じて - 一時的なエミュレーション上書きを解除します。 +- attach-only および remote CDP プロファイルでは、テスト後の適切なクリーンアップコマンドは + 引き続き `openclaw browser stop` です。これは、基盤となる + ブラウザを終了する代わりに、アクティブな制御セッションを閉じて + 一時的なエミュレーションオーバーライドをクリアします。 - `openclaw browser errors --clear` - `openclaw browser requests --filter api --clear` - `openclaw browser pdf` @@ -744,84 +741,99 @@ browser ダウンロードを永続化するには、`PLAYWRIGHT_BROWSERS_PATH` 注意: -- `upload` と `dialog` は **準備用** 呼び出しです。ファイル選択やダイアログを引き起こす click/press - の前に実行してください。 -- ダウンロードおよび trace の出力パスは OpenClaw の temp ルートに制限されます: +- `upload` と `dialog` は**事前準備**の呼び出しです。ファイル選択ダイアログ/ダイアログを + 発生させる click/press の前に実行してください。 +- ダウンロードと trace の出力パスは OpenClaw の temp ルートに制限されています: - traces: `/tmp/openclaw`（フォールバック: `${os.tmpdir()}/openclaw`） - downloads: `/tmp/openclaw/downloads`（フォールバック: `${os.tmpdir()}/openclaw/downloads`） -- upload パスも OpenClaw の temp uploads ルートに制限されます: +- upload パスは OpenClaw の temp uploads ルートに制限されています: - uploads: `/tmp/openclaw/uploads`（フォールバック: `${os.tmpdir()}/openclaw/uploads`） -- `upload` は `--input-ref` または `--element` によってファイル入力を直接設定することもできます。 +- `upload` は `--input-ref` または `--element` を使って file input を直接設定することもできます。 - `snapshot`: - - `--format ai`（Playwright がインストールされている場合のデフォルト）: 数値 ref（`aria-ref=""`）を含む AI スナップショットを返します。 - - `--format aria`: アクセシビリティツリーを返します（ref なし。調査専用）。 - - `--efficient`（または `--mode efficient`）: コンパクトな role snapshot プリセット（interactive + compact + depth + 低い maxChars）。 - - config デフォルト（tool/CLI のみ）: 呼び出し側が mode を渡さない場合に efficient snapshot を使うには `browser.snapshotDefaults.mode: "efficient"` を設定します（[Gateway configuration](/gateway/configuration-reference#browser) を参照）。 - - Role snapshot オプション（`--interactive`、`--compact`、`--depth`、`--selector`）は、`ref=e12` のような ref を持つ role ベースの snapshot を強制します。 - - `--frame "