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

Tools

Pencarian Alat

Tool Search adalah fitur eksperimental runtime agen OpenClaw. Fitur ini memberikan satu cara ringkas bagi agen untuk menemukan dan memanggil katalog alat yang besar. Fitur ini berguna ketika proses memiliki banyak alat yang tersedia, tetapi model kemungkinan hanya memerlukan beberapa di antaranya.

Halaman ini mendokumentasikan Tool Search OpenClaw. Ini bukan permukaan pencarian alat atau alat dinamis bawaan Codex. Mode kode bawaan Codex, pencarian alat, alat dinamis tertunda, dan pemanggilan alat bertingkat adalah permukaan harness Codex yang stabil dan tidak bergantung pada tools.toolSearch.

Saat diaktifkan untuk proses OpenClaw, secara default model menerima satu alat tool_search_code, ditambah alat khusus-langsung yang hasil terstrukturnya tidak dapat melewati jembatan ringkas. Alat kode menjalankan isi JavaScript singkat dalam subproses Node terisolasi dengan jembatan openclaw.tools:

js
const hits = await openclaw.tools.search("create a GitHub issue");const tool = await openclaw.tools.describe(hits[0].id);return await openclaw.tools.call(tool.id, {  title: "Crash on startup",  body: "Steps to reproduce...",});

Katalog dapat mencakup alat OpenClaw yang memenuhi syarat katalog, alat Plugin, alat MCP, dan alat yang disediakan klien. Model tidak melihat setiap skema yang dikatalogkan sejak awal. Sebagai gantinya, model mencari deskriptor ringkas, mendeskripsikan satu alat yang dipilih ketika memerlukan skema persisnya, dan memanggil alat tersebut melalui OpenClaw. Alat khusus-langsung tetap terlihat oleh model dan tidak ditambahkan ke katalog.

Proses harness Codex tidak menerima kontrol Tool Search OpenClaw eksperimental ini. OpenClaw meneruskan kapabilitas produk ke Codex sebagai alat dinamis, dan Codex memiliki mode kode bawaan yang stabil, pencarian alat bawaan, alat dinamis tertunda, dan pemanggilan alat bertingkat.

Cara giliran dijalankan

Pada waktu perencanaan, runner tertanam OpenClaw membangun katalog efektif untuk proses tersebut:

  1. Menentukan kebijakan alat aktif untuk agen, profil, sandbox, dan sesi.
  2. Mencantumkan alat OpenClaw dan Plugin yang memenuhi syarat.
  3. Mencantumkan alat MCP yang memenuhi syarat melalui runtime MCP sesi.
  4. Menambahkan alat klien yang memenuhi syarat dan disediakan untuk proses saat ini.
  5. Mempertahankan alat khusus-langsung agar terlihat oleh model dan mengindeks deskriptor ringkas untuk alat lain yang memenuhi syarat katalog.
  6. Mengekspos jembatan kode OpenClaw, alat fallback terstruktur, atau permukaan direktori ringkas bersama alat khusus-langsung tersebut.

Pada waktu eksekusi, setiap pemanggilan alat yang sebenarnya kembali ke OpenClaw. Runtime Node terisolasi tidak menyimpan implementasi Plugin, objek klien MCP, atau rahasia. openclaw.tools.call(...) melintasi jembatan kembali ke Gateway, tempat kebijakan, persetujuan, hook, pencatatan, dan penanganan hasil normal tetap berlaku.

Mode

tools.toolSearch memiliki tiga mode yang dihadapkan ke model:

  • code: mengekspos tool_search_code, jembatan JavaScript ringkas default, bersama alat khusus-langsung.
  • tools: mengekspos tool_search, tool_describe, dan tool_call sebagai alat terstruktur biasa bagi penyedia yang tidak boleh menerima kode, bersama alat khusus-langsung.
  • directory: mengekspos tool_search, tool_describe, dan tool_call beserta direktori prompt terbatas berisi nama dan deskripsi alat yang tersedia bagi penyedia yang harus melihat nama alat tanpa setiap skema lengkap. OpenClaw juga dapat mengekspos sekumpulan kecil dan terbatas skema alat yang kemungkinan diperlukan atau diwajibkan secara langsung untuk giliran saat ini. Alat khusus-langsung juga tetap terlihat dalam mode ini.

Semua mode menggunakan katalog terfilter kebijakan yang sama dan jalur eksekusi OpenClaw normal. Alat yang ditandai catalogMode: "direct-only" tetap berada di luar katalog tersebut dan tetap terlihat oleh model. Jika runtime saat ini tidak dapat meluncurkan proses anak mode kode Node terisolasi, mode code default beralih ke tools sebelum Compaction katalog. Dalam mode directory, alat yang disediakan klien tetap terlihat secara langsung untuk proses saat ini, sedangkan alat OpenClaw, alat Plugin, dan alat MCP dapat diringkas di balik katalog direktori. Pemanggilan langsung ke nama direktori tersembunyi yang persis akan dihidrasi dari katalog terotorisasi yang sama sebelum eksekusi.

Semua mode bersifat eksperimental. Utamakan eksposur alat langsung untuk katalog alat OpenClaw yang kecil, dan utamakan permukaan stabil bawaan Codex untuk proses harness Codex.

Tidak ada konfigurasi pemilihan sumber terpisah. Saat Tool Search diaktifkan, katalog mencakup alat OpenClaw, MCP, dan klien yang memenuhi syarat katalog setelah pemfilteran kebijakan normal; alat khusus-langsung dipertahankan secara terpisah.

Alasan fitur ini ada

Katalog besar berguna tetapi mahal. Mengirim setiap skema alat ke model memperbesar permintaan, memperlambat perencanaan, dan meningkatkan pemilihan alat yang tidak disengaja.

Tool Search mengubah bentuknya:

  • alat langsung: model melihat setiap skema yang dipilih sebelum token pertama
  • mode kode Tool Search: model melihat satu alat kode ringkas, kontrak API singkat, dan semua alat khusus-langsung
  • mode alat Tool Search: model melihat tiga alat fallback terstruktur yang ringkas beserta semua alat khusus-langsung
  • mode direktori Tool Search: model melihat direktori terbatas beserta kontrol pencarian/deskripsi/pemanggilan dan sekumpulan kecil serta terbatas skema yang kemungkinan diperlukan atau diwajibkan, ditambah semua alat khusus-langsung
  • selama giliran: model dapat memuat skema lainnya sesuai kebutuhan

Eksposur alat langsung tetap merupakan pilihan default yang tepat untuk katalog kecil. Tool Search paling sesuai ketika satu proses dapat melihat banyak alat, terutama dari server MCP atau alat aplikasi yang disediakan klien.

API

openclaw.tools.search(query, options?)

Mencari katalog efektif untuk proses saat ini. Hasilnya ringkas dan aman untuk dimasukkan kembali ke dalam konteks prompt.

js
const hits = await openclaw.tools.search("calendar event", { limit: 5 });

openclaw.tools.describe(id)

Memuat metadata lengkap untuk satu hasil pencarian, termasuk skema input yang persis.

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

openclaw.tools.call(id, args)

Memanggil alat yang dipilih melalui OpenClaw.

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

Mode fallback terstruktur mengekspos operasi yang sama sebagai alat:

  • tool_search
  • tool_describe
  • tool_call

Mode direktori mengekspos:

  • tool_search
  • tool_describe
  • tool_call

Mode ini juga mempertahankan alat yang disediakan klien dan semua alat khusus-langsung agar terlihat secara langsung, serta dapat mengekspos sekumpulan kecil dan terbatas skema alat katalog yang kemungkinan diperlukan atau diwajibkan secara langsung untuk giliran saat ini. Jika direktori terbatas menghilangkan entri, gunakan tool_search untuk menemukannya. Jika model meminta nama alat direktori tersembunyi yang persis secara langsung, OpenClaw menghidrasinya dari katalog terotorisasi sebelum eksekusi normal. Nama alat klien dalam mode direktori tidak boleh bertabrakan dengan nama alat OpenClaw, Plugin, atau MCP karena pengiriman tertunda yang persis menggunakan nama-nama tersebut.

Batas runtime

Jembatan kode berjalan dalam subproses Node berumur pendek. Subproses dimulai dengan mode izin Node aktif, lingkungan kosong, tanpa izin sistem berkas atau jaringan, serta tanpa izin proses anak atau worker. OpenClaw memberlakukan batas waktu jam dinding pada proses induk dan menghentikan subproses saat batas waktu habis, termasuk setelah kelanjutan asinkron.

Runtime hanya mengekspos:

  • console.log, console.warn, dan console.error
  • openclaw.tools.search
  • openclaw.tools.describe
  • openclaw.tools.call

Perilaku normal OpenClaw tetap berlaku untuk pemanggilan akhir:

  • kebijakan izin dan penolakan alat
  • pembatasan alat per agen dan per sandbox
  • kebijakan alat kanal/runtime
  • hook persetujuan
  • hook Plugin before_tool_call
  • identitas sesi, log, dan telemetri

Konfigurasi

Aktifkan Tool Search untuk proses OpenClaw dengan jembatan kode default:

bash
openclaw config set tools.toolSearch true

JSON yang setara:

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

Gunakan alat fallback terstruktur sebagai gantinya untuk proses OpenClaw:

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

Gunakan permukaan direktori ringkas sebagai gantinya untuk proses OpenClaw:

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

Sesuaikan batas waktu mode kode dan batas hasil pencarian (nilai yang ditampilkan adalah nilai default):

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

Runtime membatasi codeTimeoutMs ke 1000-60000, maxSearchLimit ke 1-50, dan searchDefaultLimit ke 1..maxSearchLimit.

Nonaktifkan:

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

Prompt dan telemetri

Tool Search mencatat telemetri yang cukup untuk membandingkannya dengan eksposur alat langsung:

  • total bita alat dan prompt terserialisasi yang dikirim ke harness
  • ukuran katalog dan perincian sumber
  • jumlah pencarian, deskripsi, dan pemanggilan
  • pemanggilan alat akhir yang dieksekusi melalui OpenClaw
  • ID dan sumber alat yang dipilih

Log sesi harus memungkinkan untuk menjawab:

  • berapa banyak skema alat yang dilihat model sejak awal
  • berapa banyak operasi pencarian dan deskripsi yang dilakukannya
  • alat akhir mana yang dipanggil
  • apakah hasilnya berasal dari OpenClaw, MCP, atau alat klien

Validasi E2E

Skenario Gateway QA Lab membuktikan kedua jalur dengan runtime OpenClaw:

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

Skenario ini membuat Plugin palsu sementara dengan katalog alat yang besar, memulai penyedia OpenAI tiruan, memulai Gateway sekali dalam mode langsung dan sekali dengan Tool Search diaktifkan, lalu membandingkan payload permintaan penyedia dan log sesi.

Regresi tersebut membuktikan:

  1. Mode langsung dapat memanggil alat Plugin palsu.
  2. Tool Search dapat memanggil alat Plugin palsu yang sama.
  3. Mode langsung mengekspos skema alat Plugin palsu secara langsung kepada penyedia.
  4. Tool Search hanya mengekspos jembatan ringkas beserta semua alat khusus-langsung.
  5. Payload permintaan Tool Search lebih kecil untuk katalog palsu yang besar.
  6. Log sesi menunjukkan jumlah pemanggilan alat dan telemetri pemanggilan yang dijembatani sesuai harapan.

Perilaku kegagalan

Tool Search harus gagal secara tertutup:

  • jika suatu alat tidak ada dalam kebijakan efektif, pencarian tidak boleh mengembalikannya
  • jika alat yang dipilih menjadi tidak tersedia, tool_call harus gagal
  • jika kebijakan atau persetujuan memblokir eksekusi, hasil pemanggilan harus melaporkan pemblokiran tersebut alih-alih melewatinya
  • jika jembatan kode tidak dapat membuat runtime terisolasi, gunakan mode: "tools" atau nonaktifkan Tool Search untuk penerapan tersebut

Terkait

Was this useful?
On this page

On this page