Webツール

OpenClawには2つの軽量Webツールが組み込まれています:

web_search — Brave Search API、GoogleSearch接地付きGemini、Grok、Kimi、またはPerplexity Search APIを使ったWeb検索。
web_fetch — HTTP取得＋読みやすい形式への変換（HTML → markdown/text）。

これらはブラウザ自動化ではありません。JS多用のサイトやログインが必要な場合はBrowserツールを使用してください。

仕組み

web_searchは設定されたプロバイダーを呼び出し、結果を返します。
結果はクエリごとに15分間キャッシュされます（設定可能）。
web_fetchはプレーンなHTTP GETで読みやすいコンテンツを抽出します（HTML → markdown/text）。JavaScriptは実行しません。
web_fetchはデフォルトで有効です（明示的に無効化しない限り）。

プロバイダー固有の詳細はBrave Search設定とPerplexity Search設定を参照してください。

検索プロバイダーの選択

プロバイダー	結果の形式	プロバイダー固有のフィルター	備考	APIキー
Brave Search API	スニペット付き構造化結果	`country`、`language`、`ui_lang`、time	Brave `llm-context`モードに対応	`BRAVE_API_KEY`
Gemini	AI合成回答＋引用	—	Google Search接地を使用	`GEMINI_API_KEY`
Grok	AI合成回答＋引用	—	xAI Web接地レスポンスを使用	`XAI_API_KEY`
Kimi	AI合成回答＋引用	—	Moonshot Web検索を使用	`KIMI_API_KEY` / `MOONSHOT_API_KEY`
Perplexity Search API	スニペット付き構造化結果	`country`、`language`、time、`domain_filter`	コンテンツ抽出制御に対応。OpenRouterはSonar互換パスを使用	`PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY`

自動検出

上の表はアルファベット順です。providerが明示的に設定されていない場合、ランタイム自動検出は以下の順序でプロバイダーをチェックします:

Brave — BRAVE_API_KEY環境変数またはtools.web.search.apiKey設定
Gemini — GEMINI_API_KEY環境変数またはtools.web.search.gemini.apiKey設定
Grok — XAI_API_KEY環境変数またはtools.web.search.grok.apiKey設定
Kimi — KIMI_API_KEY / MOONSHOT_API_KEY環境変数またはtools.web.search.kimi.apiKey設定
Perplexity — PERPLEXITY_API_KEY、OPENROUTER_API_KEY、またはtools.web.search.perplexity.apiKey設定

キーが見つからない場合、Braveにフォールバックします（設定を促すキー不足エラーが表示されます）。

ランタイムSecretRefの動作:

WebツールのSecretRefはGateway起動/リロード時にアトミックに解決されます。
自動検出モードでは、選択されたプロバイダーキーのみ解決。未選択のプロバイダーSecretRefは選択されるまで非アクティブ。
選択されたプロバイダーSecretRefが未解決で、プロバイダー環境変数フォールバックもない場合、起動/リロードはフェイルファスト。

Web検索の設定

openclaw configure --section webでAPIキーの設定とプロバイダーの選択ができます。

Brave Search

brave.com/search/apiでBrave Search APIアカウントを作成
ダッシュボードでSearchプランを選択し、APIキーを生成
openclaw configure --section webでキーを設定に保存するか、環境変数にBRAVE_API_KEYを設定

Braveの各プランには月額$5の無料クレジット（更新あり）が含まれます。Searchプランは1,000リクエストにつき$5なので、クレジットで月1,000クエリをカバーできます。予想外の課金を避けるために、Braveダッシュボードで使用量制限を設定してください。現在のプランと価格はBrave APIポータルを参照。

Perplexity Search

perplexity.ai/settings/apiでPerplexityアカウントを作成
ダッシュボードでAPIキーを生成
openclaw configure --section webでキーを設定に保存するか、環境変数にPERPLEXITY_API_KEYを設定

レガシーのSonar/OpenRouter互換には、代わりにOPENROUTER_API_KEYを設定するか、tools.web.search.perplexity.apiKeyにsk-or-...キーを設定。tools.web.search.perplexity.baseUrlやmodelの設定でもPerplexityはchat-completions互換パスに切り替わります。

詳細はPerplexity Search APIドキュメントを参照。

キーの保存場所

設定経由: openclaw configure --section webを実行。キーはプロバイダー固有の設定パスに保存されます:

Brave: tools.web.search.apiKey
Gemini: tools.web.search.gemini.apiKey
Grok: tools.web.search.grok.apiKey
Kimi: tools.web.search.kimi.apiKey
Perplexity: tools.web.search.perplexity.apiKey

上記すべてのフィールドはSecretRefオブジェクトにも対応しています。

環境変数経由: Gatewayプロセス環境にプロバイダー環境変数を設定:

Brave: BRAVE_API_KEY
Gemini: GEMINI_API_KEY
Grok: XAI_API_KEY
Kimi: KIMI_API_KEYまたはMOONSHOT_API_KEY
Perplexity: PERPLEXITY_API_KEYまたはOPENROUTER_API_KEY

Gatewayインストールの場合、~/.openclaw/.env（またはサービス環境）に設定。環境変数を参照。

設定例

Brave Search:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
      },
    },
  },
}

Brave LLM Contextモード:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
        brave: {
          mode: "llm-context",
        },
      },
    },
  },
}

llm-contextは標準のBraveスニペットの代わりに、グラウンディング用の抽出ページチャンクを返します。このモードでもcountryとlanguage / search_langは動作しますが、ui_lang、freshness、date_after、date_beforeは拒否されます。

Perplexity Search:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...", // optional if PERPLEXITY_API_KEY is set
        },
      },
    },
  },
}

Perplexity via OpenRouter / Sonar互換:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "<openrouter-api-key>", // optional if OPENROUTER_API_KEY is set
          baseUrl: "https://openrouter.ai/api/v1",
          model: "perplexity/sonar-pro",
        },
      },
    },
  },
}

Geminiの使用（Google Search接地）

Geminiモデルは組み込みのGoogle Search接地に対応しており、引用付きのライブGoogle Search結果に裏付けられたAI合成回答を返します。

Gemini APIキーの取得

Google AI Studioにアクセス
APIキーを作成
Gateway環境にGEMINI_API_KEYを設定するか、tools.web.search.gemini.apiKeyを設定

Gemini検索の設定

{
  tools: {
    web: {
      search: {
        provider: "gemini",
        gemini: {
          // APIキー（GEMINI_API_KEYが設定されている場合はオプション）
          apiKey: "AIza...",
          // モデル（デフォルトは"gemini-2.5-flash"）
          model: "gemini-2.5-flash",
        },
      },
    },
  },
}

環境変数の代替: Gateway環境にGEMINI_API_KEYを設定。 Gatewayインストールの場合、~/.openclaw/.envに記述。

注意事項

Gemini接地からの引用URLは、Googleのリダイレクト URLから直接URLに自動解決されます。
リダイレクト解決はSSRFガードパス（HEAD＋リダイレクトチェック＋http/httpsバリデーション）を使用してから最終引用URLを返します。
リダイレクト解決は厳格なSSRFデフォルトを使用するため、プライベート/内部ターゲットへのリダイレクトはブロックされます。
デフォルトモデル（gemini-2.5-flash）は高速でコスト効率が良いです。接地に対応するGeminiモデルであれば使用可能。

web_search

設定されたプロバイダーでWeb検索を実行します。

要件

tools.web.search.enabledがfalseでないこと（デフォルト: 有効）
選択したプロバイダーのAPIキー:
- Brave: BRAVE_API_KEYまたはtools.web.search.apiKey
- Gemini: GEMINI_API_KEYまたはtools.web.search.gemini.apiKey
- Grok: XAI_API_KEYまたはtools.web.search.grok.apiKey
- Kimi: KIMI_API_KEY、MOONSHOT_API_KEY、またはtools.web.search.kimi.apiKey
- Perplexity: PERPLEXITY_API_KEY、OPENROUTER_API_KEY、またはtools.web.search.perplexity.apiKey
上記すべてのプロバイダーキーフィールドはSecretRefオブジェクトに対応。

設定

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE", // optional if BRAVE_API_KEY is set
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

ツールパラメータ

特に記載がない限り、すべてのパラメータはBraveおよびネイティブPerplexity Search APIで動作します。

PerplexityのOpenRouter / Sonar互換パスはqueryとfreshnessのみ対応。 tools.web.search.perplexity.baseUrl / modelを設定するか、OPENROUTER_API_KEYを使用するか、sk-or-...キーを設定している場合、Search API専用フィルターは明示的なエラーを返します。

パラメータ	説明
`query`	検索クエリ（必須）
`count`	返す結果数（1-10、デフォルト: 5）
`country`	2文字のISO国コード（例: “US”、“DE”）
`language`	ISO 639-1言語コード（例: “en”、“de”）
`freshness`	時間フィルター: `day`、`week`、`month`、または`year`
`date_after`	この日付以降の結果（YYYY-MM-DD）
`date_before`	この日付以前の結果（YYYY-MM-DD）
`ui_lang`	UI言語コード（Braveのみ）
`domain_filter`	ドメイン許可/拒否リスト配列（Perplexityのみ）
`max_tokens`	合計コンテンツバジェット、デフォルト25000（Perplexityのみ）
`max_tokens_per_page`	ページごとのトークン制限、デフォルト2048（Perplexityのみ）

例:

// ドイツ向け検索
await web_search({
  query: "TV online schauen",
  country: "DE",
  language: "de",
});

// 直近の結果（過去1週間）
await web_search({
  query: "TMBG interview",
  freshness: "week",
});

// 日付範囲検索
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// ドメインフィルタリング（Perplexityのみ）
await web_search({
  query: "climate research",
  domain_filter: ["nature.com", "science.org", ".edu"],
});

// ドメイン除外（Perplexityのみ）
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

// より多くのコンテンツ抽出（Perplexityのみ）
await web_search({
  query: "detailed AI research",
  max_tokens: 50000,
  max_tokens_per_page: 4096,
});

Brave llm-contextモードが有効な場合、ui_lang、freshness、date_after、date_beforeは非対応。これらのフィルターにはBrave webモードを使用してください。

web_fetch

URLからコンテンツを取得し、読みやすい形式に抽出します。

web_fetchの要件

tools.web.fetch.enabledがfalseでないこと（デフォルト: 有効）
オプションのFirecrawlフォールバック: tools.web.fetch.firecrawl.apiKeyまたはFIRECRAWL_API_KEYを設定。
tools.web.fetch.firecrawl.apiKeyはSecretRefオブジェクトに対応。

web_fetchの設定

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
        readability: true,
        firecrawl: {
          enabled: true,
          apiKey: "FIRECRAWL_API_KEY_HERE", // optional if FIRECRAWL_API_KEY is set
          baseUrl: "https://api.firecrawl.dev",
          onlyMainContent: true,
          maxAgeMs: 86400000, // ms (1 day)
          timeoutSeconds: 60,
        },
      },
    },
  },
}

web_fetchのツールパラメータ

url（必須、http/httpsのみ）
extractMode（markdown | text）
maxChars（長いページの切り詰め）

注意事項:

web_fetchはまずReadability（メインコンテンツ抽出）を使い、次にFirecrawl（設定されている場合）を使用。両方が失敗した場合、ツールはエラーを返します。
Firecrawlリクエストはボット回避モードを使用し、デフォルトで結果をキャッシュします。
FirecrawlのSecretRefはFirecrawlがアクティブ（tools.web.fetch.enabled !== falseかつtools.web.fetch.firecrawl.enabled !== false）な場合のみ解決。
Firecrawlがアクティブでそのecreftが未解決、FIRECRAWL_API_KEYフォールバックもない場合、起動/リロードはフェイルファスト。
web_fetchはデフォルトでChromeライクなUser-AgentとAccept-Languageを送信。必要に応じてuserAgentをオーバーライド。
web_fetchはプライベート/内部ホスト名をブロックし、リダイレクトを再チェック（maxRedirectsで制限）。
maxCharsはtools.web.fetch.maxCharsCapで上限設定。
web_fetchはパース前にダウンロードしたレスポンスボディサイズをtools.web.fetch.maxResponseBytesで制限。超過したレスポンスは切り詰められ、警告が含まれます。
web_fetchはベストエフォートの抽出です。一部のサイトにはbrowserツールが必要。
キーの設定とサービス詳細はFirecrawlを参照。
レスポンスはキャッシュされます（デフォルト15分）。繰り返しの取得を削減。
ツールプロファイル/許可リストを使用する場合、web_search/web_fetchまたはgroup:webを追加してください。
APIキーが不足している場合、web_searchはドキュメントリンク付きの短い設定ヒントを返します。