OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Tools

ツール検索

Tool Search は、OpenClaw エージェントランタイムの実験的機能です。エージェントが大規模なツールカタログを検出して呼び出すための、単一のコンパクトな手段を提供します。実行時に多数のツールを利用できるものの、モデルが必要とする可能性が高いツールがそのうち数個だけの場合に役立ちます。

このページでは、OpenClaw Tool Search について説明します。これは Codex ネイティブのツール検索や動的ツールのサーフェスではありません。Codex ネイティブのコードモード、ツール検索、遅延動的ツール、ネストされたツール呼び出しは、安定した Codex ハーネスのサーフェスであり、tools.toolSearch には依存しません。

Tool Search コントロールの代わりに QuickJS-WASI exec/wait サーフェスを公開する汎用 OpenClaw ランタイムについては、コードモードを参照してください。

OpenClaw の実行で有効にすると、モデルはデフォルトで 1 つの tool_search_code ツールに加えて、構造化された結果をコンパクトブリッジ経由で渡せない直接専用ツールを受け取ります。コードツールは、openclaw.tools ブリッジを備えた隔離済み Node サブプロセス内で、短い JavaScript 本文を実行します。

js
const hits = await openclaw.tools.search("GitHub issue を作成する");const tool = await openclaw.tools.describe(hits[0].id);return await openclaw.tools.call(tool.id, {  title: "起動時にクラッシュする",  body: "再現手順...",});

カタログには、カタログ登録の対象となる OpenClaw ツール、Plugin ツール、MCP ツール、クライアント提供ツールを含めることができます。モデルには、カタログ内のすべてのスキーマが最初から提示されるわけではありません。代わりに、コンパクトな記述子を検索し、正確なスキーマが必要になったときに選択したツールの詳細を取得して、そのツールを OpenClaw 経由で呼び出します。直接専用ツールはモデルから引き続き見える状態に保たれ、カタログには追加されません。

Codex ハーネスの実行では、これらの実験的な OpenClaw Tool Search コントロールは提供されません。OpenClaw は製品機能を動的ツールとして Codex に渡し、安定したネイティブコードモード、ネイティブツール検索、遅延動的ツール、ネストされたツール呼び出しは Codex が担います。

ターンの実行方法

計画時に、OpenClaw の組み込みランナーが実行用の有効なカタログを構築します。

  1. エージェント、プロファイル、サンドボックス、セッションに対して有効なツールポリシーを解決します。
  2. 対象となる OpenClaw ツールと Plugin ツールを一覧化します。
  3. セッションの MCP ランタイムを通じて対象となる MCP ツールを一覧化します。
  4. 現在の実行用に提供された対象となるクライアントツールを追加します。
  5. 直接専用ツールをモデルから見える状態に保ち、残りのカタログ登録対象ツールについてコンパクトな記述子のインデックスを作成します。
  6. それらの直接専用ツールとともに、OpenClaw コードブリッジ、構造化フォールバックツール、またはコンパクトなディレクトリサーフェスを公開します。

実行時には、実際のツール呼び出しはすべて OpenClaw に戻ります。隔離された Node ランタイムは、Plugin の実装、MCP クライアントオブジェクト、シークレットを保持しません。openclaw.tools.call(...) はブリッジを経由して Gateway に戻り、そこで通常のポリシー、承認、フック、ログ記録、結果処理が引き続き適用されます。

モード

tools.toolSearch には、モデル向けの 3 つのモードがあります。

  • code: 直接専用ツールとともに、デフォルトのコンパクトな JavaScript ブリッジである tool_search_code を公開します。
  • tools: コードを受け取るべきではないプロバイダー向けに、tool_search、tool_describe、tool_call を通常の構造化ツールとして、直接専用ツールとともに公開します。
  • directory: すべての完全なスキーマを提示せずにツール名を確認すべきプロバイダー向けに、tool_search、tool_describe、tool_call に加え、利用可能なツール名と説明を含む上限付きのプロンプトディレクトリを公開します。OpenClaw は、現在のターンで使用される可能性が高い、または必要とされるツールスキーマの小規模な上限付きセットを直接公開することもできます。このモードでも、直接専用ツールは引き続き表示されます。

すべてのモードで、同じポリシーフィルタリング済みカタログと通常の OpenClaw 実行パスが使用されます。catalogMode: "direct-only" とマークされたツールはそのカタログの外部に留まり、モデルから見える状態が維持されます。現在のランタイムが隔離された Node コードモードの子プロセスを起動できない場合、デフォルトの code モードは、カタログを圧縮する前に tools へフォールバックします。directory モードでは、クライアント提供ツールは現在の実行で直接表示されたままとなり、OpenClaw ツール、Plugin ツール、MCP ツールはディレクトリカタログの背後に圧縮できます。非表示になっている正確なディレクトリ名を直接呼び出すと、実行前に同じ認可済みカタログからハイドレートされます。

すべてのモードは実験的です。OpenClaw のツールカタログが小さい場合はツールを直接公開し、Codex ハーネスの実行には安定した Codex ネイティブのサーフェスを使用してください。

ソース選択用の個別の設定はありません。Tool Search を有効にすると、通常のポリシーフィルタリング後に、カタログ登録の対象となる OpenClaw、MCP、クライアントツールがカタログに含まれます。直接専用ツールは別途保持されます。

この機能が存在する理由

大規模なカタログは便利ですが、コストもかかります。すべてのツールスキーマをモデルに送信すると、リクエストが大きくなり、計画が遅くなり、誤ってツールを選択する可能性が高まります。

Tool Search はこの構成を次のように変えます。

  • 直接ツール: モデルは最初のトークンの前に、選択されたすべてのスキーマを確認します
  • Tool Search コードモード: モデルは 1 つのコンパクトなコードツール、短い API コントラクト、および直接専用ツールを確認します
  • Tool Search ツールモード: モデルは 3 つのコンパクトな構造化フォールバックツールと直接専用ツールを確認します
  • Tool Search ディレクトリモード: モデルは上限付きディレクトリ、検索・詳細取得・呼び出しのコントロール、使用される可能性が高い、または必要とされるスキーマの小規模な上限付きセット、および直接専用ツールを確認します
  • ターン中: モデルは必要に応じて残りのスキーマを読み込めます

小規模なカタログでは、ツールの直接公開が引き続き適切なデフォルトです。Tool Search は、1 回の実行で多数のツールを参照できる場合、特に MCP サーバーやクライアント提供のアプリツールがある場合に最適です。

API

openclaw.tools.search(query, options?)

現在の実行用の有効なカタログを検索します。結果はコンパクトで、プロンプトコンテキストに安全に戻せます。各ヒットには、{ id: string; mode?: "drip" | "flood" } のような上限付きの TypeScript 形式の input シグネチャが含まれるため、そのシグネチャで十分な場合、モデルは describe を省略できます。信頼できる OpenClaw コアツールまたは Plugin ツールには、Array<{ id: string; paid: boolean }> のようなコンパクトな output ヒントが含まれることもあります。MCP とクライアントの出力スキーマ宣言は、この信頼済みヒントには昇格されません。それらの信頼されていない入力スキーマも input: "unknown" として遅延されます。呼び出す前に describe を使用してください。オープン、過大、またはその他の理由で部分的な出力スキーマではヒントが省略され、代わりに describe を通じて引き続き利用できます。

js
const hits = await openclaw.tools.search("カレンダーイベント", { limit: 5 });

openclaw.tools.describe(id)

1 件の検索結果について、正確な入力スキーマと、ツールで宣言されている場合は信頼済みの完全な outputSchema を含む、完全なメタデータを読み込みます。

js
const calendarCreate = await openclaw.tools.describe("mcp:calendar:create_event");

openclaw.tools.call(id, args)

選択したツールを OpenClaw 経由で呼び出し、生の { tool, result } エンベロープを返します。JSON を返すツールは通常、その値を result.details に格納します。信頼できるツールで outputSchema が宣言されている場合、OpenClaw は実行前にスキーマをコンパイルし、通常のツールフックの実行後、カタログ呼び出しを返す前に最終的な details を検証します。

js
await openclaw.tools.call(calendarCreate.id, {  summary: "計画",  start: "2026-05-09T14:00:00Z",});

ツール作成者は、ツールの outputSchema プロパティで出力コントラクトを宣言します。これはレンダリング済みコンテンツブロックではなく、AgentToolResult.details を記述します。例外をスローしないすべてのバリアントを含めるか、結果が不安定な場合は省略してください。コードモードの出力コントラクトおよびツール Pluginを参照してください。

構造化フォールバックモードでは、同じ操作をツールとして公開します。

  • tool_search
  • tool_describe
  • tool_call

ディレクトリモードでは、以下を公開します。

  • tool_search
  • tool_describe
  • tool_call

また、クライアント提供ツールとすべての直接専用ツールを直接表示したままにし、現在のターンで使用される可能性が高い、または必要とされるカタログツールスキーマの小規模な上限付きセットを直接公開することもあります。上限付きディレクトリでエントリが省略されている場合は、tool_search を使用して検索してください。モデルが非表示の正確なディレクトリツール名を直接要求した場合、OpenClaw は通常の実行前に、認可済みカタログからそのツールをハイドレートします。 正確な遅延ディスパッチではこれらの名前を使用するため、ディレクトリモードのクライアントツール名は、OpenClaw、Plugin、MCP のツール名と競合してはなりません。

ランタイム境界

コードブリッジは短時間だけ存続する Node サブプロセス内で実行されます。サブプロセスは、Node のパーミッションモードを有効化し、空の環境を使用し、ファイルシステム権限、ネットワーク権限、子プロセス権限、ワーカー権限がない状態で起動します。OpenClaw は親プロセス側で実時間タイムアウトを適用し、非同期継続処理の後を含め、タイムアウト時にサブプロセスを終了します。

ランタイムが公開するのは以下のみです。

  • console.log、console.warn、console.error
  • openclaw.tools.search
  • openclaw.tools.describe
  • openclaw.tools.call

最終的な呼び出しには、通常の OpenClaw の動作が引き続き適用されます。

  • ツールの許可および拒否ポリシー
  • エージェント単位およびサンドボックス単位のツール制限
  • チャンネル／ランタイムのツールポリシー
  • 承認フック
  • Plugin の before_tool_call フック
  • セッション ID、ログ、テレメトリ

設定

デフォルトのコードブリッジを使用して、OpenClaw の実行で Tool Search を有効にします。

bash
openclaw config set tools.toolSearch true

同等の JSON:

json5
{  tools: {    toolSearch: true,  },}

OpenClaw の実行で、代わりに構造化フォールバックツールを使用します。

json5
{  tools: {    toolSearch: {      mode: "tools",    },  },}

OpenClaw の実行で、代わりにコンパクトなディレクトリサーフェスを使用します。

json5
{  tools: {    toolSearch: {      mode: "directory",    },  },}

コードモードのタイムアウトと検索結果の上限を調整します（表示されている値はデフォルトです）。

json5
{  tools: {    toolSearch: {      mode: "code",      codeTimeoutMs: 10000,      searchDefaultLimit: 8,      maxSearchLimit: 20,    },  },}

ランタイムは、codeTimeoutMs を 1000-60000、maxSearchLimit を 1-50、searchDefaultLimit を 1..maxSearchLimit に制限します。

無効にするには、次のように設定します。

json5
{  tools: {    toolSearch: false,  },}

プロンプトとテレメトリ

Tool Search は、ツールの直接公開と比較するために十分なテレメトリを記録します。

  • ハーネスに送信された、シリアライズ済みツールとプロンプトの合計バイト数
  • カタログサイズとソース別の内訳
  • 検索、詳細取得、呼び出しの回数
  • OpenClaw 経由で実行された最終的なツール呼び出し
  • 選択されたツール ID とソース

セッションログから、以下を確認できる必要があります。

  • モデルが最初に確認したツールスキーマの数
  • 実行した検索操作と詳細取得操作の回数
  • 最終的に呼び出されたツール
  • 結果の取得元が OpenClaw、MCP、クライアントツールのいずれであったか

E2E 検証

QA Lab の Gateway シナリオでは、OpenClaw ランタイムを使用して両方のパスを検証します。

bash
pnpm openclaw qa suite --provider-mode mock-openai --scenario tool-search-gateway-e2e

このシナリオは、大規模なツールカタログを備えた一時的な偽 Plugin を作成し、モック OpenAI プロバイダーを起動して、Gateway を直接モードで 1 回、Tool Search を有効にして 1 回起動した後、プロバイダーのリクエストペイロードとセッションログを比較します。

この回帰テストでは、以下を検証します。

  1. ダイレクトモードでは、偽の Plugin ツールを呼び出せます。
  2. Tool Search でも、同じ偽の Plugin ツールを呼び出せます。
  3. ダイレクトモードでは、偽の Plugin ツールのスキーマがプロバイダーに直接公開されます。
  4. Tool Search では、コンパクトなブリッジとダイレクトモード専用ツールのみが公開されます。
  5. 大規模な偽のカタログでは、Tool Search のリクエストペイロードの方が小さくなります。
  6. セッションログには、想定どおりのツール呼び出し回数と、ブリッジ経由の呼び出しに関するテレメトリが記録されます。

障害時の動作

Tool Search はフェイルクローズで動作する必要があります。

  • ツールが有効なポリシーに含まれていない場合、検索でそのツールを返してはなりません
  • 選択したツールが利用できなくなった場合、tool_call は失敗する必要があります
  • ポリシーまたは承認によって実行がブロックされた場合、呼び出し結果では、それを迂回せずに ブロックされたことを報告する必要があります
  • コードブリッジで分離されたランタイムを作成できない場合、そのデプロイでは mode: "tools" を使用するか、 Tool Search を無効にしてください

関連項目

Was this useful?
On this page

On this page