Araç Arama

Araç Arama, deneysel bir OpenClaw ajan çalışma zamanı özelliğidir. Ajanlara büyük araç kataloglarını keşfetmek ve çağırmak için tek ve kompakt bir yol sunar. Çalıştırmada çok sayıda kullanılabilir araç olduğunda, ancak modelin bunlardan yalnızca birkaçına ihtiyaç duyması beklendiğinde kullanışlıdır.

Bu sayfa OpenClaw Araç Arama özelliğini belgeler. Codex'e özgü araç arama veya dinamik araçlar yüzeyi değildir. Codex'e özgü kod modu, araç arama, ertelenmiş dinamik araçlar ve iç içe araç çağrıları kararlı Codex çalıştırma altyapısı yüzeyleridir ve tools.toolSearch öğesine bağlı değildir.

Araç Arama denetimleri yerine QuickJS-WASI exec/wait yüzeyi sunan genel OpenClaw çalışma zamanı için Kod Modu bölümüne bakın.

OpenClaw çalıştırmaları için etkinleştirildiğinde model, varsayılan olarak tek bir tool_search_code aracı ile yapılandırılmış sonuçları kompakt köprüden geçemeyen tüm yalnızca doğrudan araçları alır. Kod aracı, yalıtılmış bir Node alt sürecinde openclaw.tools köprüsüyle kısa bir JavaScript gövdesi çalıştırır:

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; kataloğa uygun OpenClaw araçlarını, plugin araçlarını, MCP araçlarını ve istemci tarafından sağlanan araçları içerebilir. Model, kataloglanan her şemayı başlangıçta görmez. Bunun yerine kompakt tanımlayıcılarda arama yapar, tam şemaya ihtiyaç duyduğunda seçilen bir aracı açıklar ve bu aracı OpenClaw üzerinden çağırır. Yalnızca doğrudan araçlar model tarafından görünür kalır ve kataloğa eklenmez.

Codex çalıştırma altyapısı çalıştırmaları bu deneysel OpenClaw Araç Arama denetimlerini almaz. OpenClaw, ürün yeteneklerini Codex'e dinamik araçlar olarak aktarır; kararlı yerel kod modu, yerel araç arama, ertelenmiş dinamik araçlar ve iç içe araç çağrılarının sahibi Codex'tir.

Bir turun çalışma şekli

Planlama sırasında OpenClaw yerleşik çalıştırıcısı, çalıştırma için geçerli kataloğu oluşturur:

1. Ajan, profil, korumalı alan ve oturum için etkin araç politikasını çözümleyin.
2. Uygun OpenClaw ve plugin araçlarını listeleyin.
3. Oturum MCP çalışma zamanı üzerinden uygun MCP araçlarını listeleyin.
4. Geçerli çalıştırma için sağlanan uygun istemci araçlarını ekleyin.
5. Yalnızca doğrudan araçları model tarafından görünür tutun ve kataloğa uygun kalan araçların kompakt tanımlayıcılarını dizine ekleyin.
6. OpenClaw kod köprüsünü, yapılandırılmış geri dönüş araçlarını veya kompakt dizin yüzeyini bu yalnızca doğrudan araçların yanında sunun.

Yürütme sırasında her gerçek araç çağrısı OpenClaw'a geri döner. Yalıtılmış Node çalışma zamanı plugin uygulamalarını, MCP istemci nesnelerini veya gizli bilgileri barındırmaz. openclaw.tools.call(...), köprüden Gateway'e geri geçer; burada normal politika, onay, kanca, günlükleme ve sonuç işleme süreçleri uygulanmaya devam eder.

Modlar

tools.toolSearch, modele yönelik üç moda sahiptir:

• code: yalnızca doğrudan araçların yanında varsayılan kompakt JavaScript köprüsü olan tool_search_code öğesini sunar.
• tools: kod almaması gereken sağlayıcılar için yalnızca doğrudan araçların yanında tool_search, tool_describe ve tool_call öğelerini düz yapılandırılmış araçlar olarak sunar.
• directory: her tam şemayı görmeden araç adlarını görmesi gereken sağlayıcılar için tool_search, tool_describe ve tool_call öğelerinin yanı sıra kullanılabilir araç adları ve açıklamalarından oluşan sınırlı bir istem dizini sunar. OpenClaw ayrıca geçerli tur için muhtemel veya gerekli araç şemalarından oluşan küçük, sınırlı bir kümeyi doğrudan sunabilir. Yalnızca doğrudan araçlar bu modda da görünür kalır.

Tüm modlar, aynı politika filtreli kataloğu ve normal OpenClaw yürütme yolunu kullanır. catalogMode: "direct-only" olarak işaretlenen araçlar bu kataloğun dışında kalır ve model tarafından görünür olmaya devam eder. Geçerli çalışma zamanı yalıtılmış Node kod modu alt sürecini başlatamıyorsa varsayılan code modu, katalog sıkıştırmasından önce tools moduna geri döner. directory modunda, OpenClaw araçları, plugin araçları ve MCP araçları dizin kataloğunun arkasında sıkıştırılabilirken istemci tarafından sağlanan araçlar geçerli çalıştırma için doğrudan görünür kalır. Tam bir gizli dizin adına yapılan doğrudan çağrı, yürütmeden önce aynı yetkili katalogdan yüklenir.

Tüm modlar deneyseldir. Küçük OpenClaw araç katalogları için doğrudan araç sunumunu, Codex çalıştırma altyapısı çalıştırmaları içinse Codex'e özgü kararlı yüzeyleri tercih edin.

Ayrı bir kaynak seçimi yapılandırması yoktur. Araç Arama etkinleştirildiğinde katalog, normal politika filtrelemesinden sonra kataloğa uygun OpenClaw, MCP ve istemci araçlarını içerir; yalnızca doğrudan araçlar ayrı tutulur.

Neden var?

Büyük kataloglar kullanışlıdır ancak maliyetlidir. Her araç şemasını modele göndermek isteği büyütür, planlamayı yavaşlatır ve yanlışlıkla araç seçilmesi olasılığını artırır.

Araç Arama yapıyı değiştirir:

• doğrudan araçlar: model, ilk token'dan önce seçilen her şemayı görür
• Araç Arama kod modu: model tek bir kompakt kod aracını, kısa bir API sözleşmesini ve tüm yalnızca doğrudan araçları görür
• Araç Arama araç modu: model üç kompakt yapılandırılmış geri dönüş aracını ve tüm yalnızca doğrudan araçları görür
• Araç Arama dizin modu: model sınırlı bir dizini, arama/açıklama/çağrı denetimlerini, muhtemel veya gerekli şemalardan oluşan küçük ve sınırlı bir kümeyi ve tüm yalnızca doğrudan araçları görür
• tur sırasında: model kalan şemaları gerektiğinde yükleyebilir

Doğrudan araç sunumu, küçük kataloglar için hâlâ doğru varsayılandır. Araç Arama, özellikle MCP sunucularından veya istemci tarafından sağlanan uygulama araçlarından çok sayıda aracın tek bir çalıştırmada görülebildiği durumlarda en uygundur.

API

openclaw.tools.search(query, options?)

Geçerli çalıştırmanın etkin kataloğunda arama yapar. Sonuçlar kompakttır ve istem bağlamına güvenle geri eklenebilir. Her eşleşme, { id: string; mode?: "drip" | "flood" } gibi sınırlı, TypeScript tarzında bir input imzası içerir; böylece bu imza yeterliyse model describe işlemini atlayabilir. Güvenilir bir OpenClaw çekirdek veya plugin aracı, Array<{ id: string; paid: boolean }> gibi kompakt bir output ipucu da içerebilir. MCP ve istemci çıktı şeması iddiaları bu güvenilir ipucuna yükseltilmez. Güvenilmeyen giriş şemaları da input: "unknown" olarak ertelenir; bunları çağırmadan önce describe kullanın. Açık, aşırı büyük veya başka bir şekilde kısmi çıktı şemaları ipucunu içermez ve bunun yerine describe üzerinden kullanılabilir olmaya devam eder.

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

openclaw.tools.describe(id)

Tam giriş şeması ve araç tarafından bildirilmişse güvenilir tam outputSchema dâhil olmak üzere bir arama sonucunun tüm meta verilerini yükler.

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

openclaw.tools.call(id, args)

Seçilen bir aracı OpenClaw üzerinden çağırır ve ham { tool, result } zarfını döndürür. JSON döndüren araçlar normalde değerlerini result.details içine yerleştirir. Güvenilir bir araç outputSchema bildirirse OpenClaw, yürütmeden önce şemayı derler ve katalog çağrısını döndürmeden önce normal araç kancalarının ardından nihai details değerini doğrular.

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

Araç yazarları çıktı sözleşmelerini aracın outputSchema özelliğinde bildirir. Bu özellik, işlenmiş içerik bloklarını değil AgentToolResult.details öğesini açıklar. Hata oluşturmayan tüm varyantları dâhil edin veya kararsız sonuçlar için bunu atlayın. Kod Modu çıktı sözleşmeleri ve Araç pluginleri bölümlerine bakın.

Yapılandırılmış geri dönüş modu, aynı işlemleri araçlar olarak sunar:

• tool_search
• tool_describe
• tool_call

Dizin modu şunları sunar:

• tool_search
• tool_describe
• tool_call

Ayrıca istemci tarafından sağlanan araçları ve tüm yalnızca doğrudan araçları doğrudan görünür tutar; geçerli tur için muhtemel veya gerekli katalog araç şemalarından oluşan küçük, sınırlı bir kümeyi de doğrudan sunabilir. Sınırlı dizinde bazı girdiler yoksa bunları bulmak için tool_search kullanın. Model tam bir gizli dizin aracı adını doğrudan isterse OpenClaw, normal yürütmeden önce bu aracı yetkili katalogdan yükler. Tam ertelenmiş gönderim bu adları kullandığından dizin modundaki istemci aracı adları OpenClaw, plugin veya MCP araç adlarıyla çakışmamalıdır.

Çalışma zamanı sınırı

Kod köprüsü kısa ömürlü bir Node alt sürecinde çalışır. Alt süreç; Node izin modu etkin, boş bir ortamla, dosya sistemi veya ağ izni olmadan ve alt süreç ya da worker izni olmadan başlar. OpenClaw, üst süreçte gerçek zamanlı bir zaman aşımı uygular ve zaman uyumsuz devam işlemlerinden sonra bile zaman aşımında alt süreci sonlandırır.

Çalışma zamanı yalnızca şunları sunar:

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

Normal OpenClaw davranışı nihai çağrılar için uygulanmaya devam eder:

• araç izin ve reddetme politikaları
• ajan ve korumalı alan başına araç kısıtlamaları
• kanal/çalışma zamanı araç politikası
• onay kancaları
• plugin before_tool_call kancaları
• oturum kimliği, günlükler ve telemetri

Yapılandırma

OpenClaw çalıştırmaları için Araç Arama'yı varsayılan kod köprüsüyle etkinleştirin:

openclaw config set tools.toolSearch true

Eşdeğer JSON:

{  tools: {    toolSearch: true,  },}

OpenClaw çalıştırmaları için bunun yerine yapılandırılmış geri dönüş araçlarını kullanın:

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

OpenClaw çalıştırmaları için bunun yerine kompakt dizin yüzeyini kullanın:

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

Kod modu zaman aşımını ve arama sonucu sınırlarını ayarlayın (gösterilen değerler varsayılanlardır):

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

Çalışma zamanı codeTimeoutMs değerini 1000-60000, maxSearchLimit değerini 1-50 ve searchDefaultLimit değerini 1..maxSearchLimit aralığıyla sınırlar.

Devre dışı bırakın:

{  tools: {    toolSearch: false,  },}

İstem ve telemetri

Araç Arama, doğrudan araç sunumuyla karşılaştırma yapmaya yetecek kadar telemetri kaydeder:

• çalıştırma altyapısına gönderilen toplam serileştirilmiş araç ve istem baytı
• katalog boyutu ve kaynak dağılımı
• arama, açıklama ve çağrı sayıları
• OpenClaw üzerinden yürütülen nihai araç çağrıları
• seçilen araç kimlikleri ve kaynakları

Oturum günlükleri şu soruların yanıtlanmasını mümkün kılmalıdır:

• modelin başlangıçta kaç araç şeması gördüğü
• kaç arama ve açıklama işlemi gerçekleştirdiği
• hangi nihai aracın çağrıldığı
• sonucun OpenClaw, MCP veya bir istemci aracından gelip gelmediği

E2E doğrulaması

QA Lab Gateway senaryosu, OpenClaw çalışma zamanı ile her iki yolu da doğrular:

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

Büyük bir araç kataloğuna sahip geçici bir sahte plugin oluşturur, sahte OpenAI sağlayıcısını başlatır, Gateway'i bir kez doğrudan modda ve bir kez Araç Arama etkin olarak başlatır, ardından sağlayıcı istek yüklerini ve oturum günlüklerini karşılaştırır.

Regresyon şunları doğrular:

1. Doğrudan mod, sahte plugin aracını çağırabilir.
2. Araç Arama, aynı sahte plugin aracını çağırabilir.
3. Doğrudan mod, sahte plugin aracı şemalarını doğrudan sağlayıcıya sunar.
4. Araç Arama, yalnızca kompakt köprüyü ve doğrudan moda özel araçları sunar.
5. Araç Arama isteği yükü, büyük sahte katalog için daha küçüktür.
6. Oturum günlükleri, beklenen araç çağrısı sayılarını ve köprülenen çağrı telemetrisini gösterir.

Hata davranışı

Araç Arama, hata durumunda erişimi engellemelidir:

• bir araç etkin politikada yer almıyorsa arama bu aracı döndürmemelidir
• seçilen bir araç kullanılamaz hâle gelirse tool_call başarısız olmalıdır
• politika veya onay yürütmeyi engelliyorsa çağrı sonucu, engeli atlamak yerine bu engeli bildirmelidir
• kod köprüsü yalıtılmış bir çalışma zamanı oluşturamıyorsa mode: "tools" kullanın veya bu dağıtım için Araç Arama'yı devre dışı bırakın

İlgili

• Araçlar ve pluginler
• Çok aracılı korumalı alan ve araçlar
• Exec aracı
• ACP aracılarını ayarlama
• Plugin geliştirme