Araç çağırma API'si

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• POST /tools/invoke
• Gateway ile aynı port (WS + HTTP çoklama): http://<gateway-host>:<port>/tools/invoke

​

Kimlik Doğrulama

• paylaşılan gizli anahtar kimlik doğrulaması (gateway.auth.mode="token" veya "password"): Authorization: Bearer <token-or-password>
• güvenilir kimlik taşıyan HTTP kimlik doğrulaması (gateway.auth.mode="trusted-proxy"): yapılandırılmış kimlik duyarlı proxy üzerinden yönlendirin ve gerekli kimlik başlıklarını onun eklemesine izin verin
• özel-ingress açık kimlik doğrulaması (gateway.auth.mode="none"): kimlik doğrulama başlığı gerekmez

• gateway.auth.mode="token" olduğunda, gateway.auth.token (veya OPENCLAW_GATEWAY_TOKEN) kullanın.
• gateway.auth.mode="password" olduğunda, gateway.auth.password (veya OPENCLAW_GATEWAY_PASSWORD) kullanın.
• gateway.auth.mode="trusted-proxy" olduğunda, HTTP isteği yapılandırılmış bir güvenilir proxy kaynağından gelmelidir; aynı ana makinedeki loopback proxy’leri açıkça gateway.auth.trustedProxy.allowLoopback = true gerektirir.
• gateway.auth.rateLimit yapılandırılmışsa ve çok fazla kimlik doğrulama hatası oluşursa, uç nokta Retry-After ile birlikte 429 döndürür.

​

Güvenlik sınırı (önemli)

• Buradaki HTTP bearer kimlik doğrulaması dar bir kullanıcı başına kapsam modeli değildir.
• Bu uç nokta için geçerli bir Gateway token’ı/parolası, sahip/operatör kimlik bilgisi gibi ele alınmalıdır.
• Paylaşılan gizli anahtar kimlik doğrulama modlarında (token ve password), çağıran daha dar bir x-openclaw-scopes başlığı gönderse bile uç nokta normal tam operatör varsayılanlarını geri yükler.
• Paylaşılan gizli anahtar kimlik doğrulaması, bu uç noktadaki doğrudan araç çağrılarını sahip-gönderen turları olarak da ele alır.
• Güvenilir kimlik taşıyan HTTP modları (örneğin güvenilir proxy kimlik doğrulaması veya özel bir ingress üzerinde gateway.auth.mode="none"), mevcut olduğunda x-openclaw-scopes değerini dikkate alır; aksi halde normal operatör varsayılan kapsam kümesine geri döner.
• Bu uç noktayı yalnızca loopback/tailnet/özel ingress üzerinde tutun; doğrudan genel internete açmayın.

• gateway.auth.mode="token" veya "password" + Authorization: Bearer ...
  • paylaşılan gateway operatör gizli anahtarına sahip olunduğunu kanıtlar
  • daha dar x-openclaw-scopes değerlerini yok sayar
  • tam varsayılan operatör kapsam kümesini geri yükler: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • bu uç noktadaki doğrudan araç çağrılarını sahip-gönderen turları olarak ele alır
• güvenilir kimlik taşıyan HTTP modları (örneğin güvenilir proxy kimlik doğrulaması veya özel ingress üzerinde gateway.auth.mode="none")
  • bir dış güvenilir kimliği veya dağıtım sınırını doğrular
  • başlık mevcut olduğunda x-openclaw-scopes değerini dikkate alır
  • başlık yoksa normal operatör varsayılan kapsam kümesine geri döner
  • yalnızca çağıran kapsamları açıkça daraltıp operator.admin değerini atladığında sahip semantiğini kaybeder

​

İstek gövdesi

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}

• tool (dize, zorunlu): çağrılacak araç adı.
• action (dize, isteğe bağlı): araç şeması action destekliyorsa ve args yükü bunu atladıysa args içine eşlenir.
• args (nesne, isteğe bağlı): araca özgü bağımsız değişkenler.
• sessionKey (dize, isteğe bağlı): hedef oturum anahtarı. Atlanırsa veya "main" ise, Gateway yapılandırılmış ana oturum anahtarını kullanır (session.mainKey ve varsayılan ajanı dikkate alır ya da global kapsamda global kullanır).
• dryRun (boolean, isteğe bağlı): gelecekte kullanım için ayrılmıştır; şu anda yok sayılır.

​

İlke + yönlendirme davranışı

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• grup ilkeleri (oturum anahtarı bir grup veya kanala eşleniyorsa)
• alt ajan ilkesi (bir alt ajan oturum anahtarıyla çağırırken)

• Exec onayları operatör koruma sınırlarıdır; bu HTTP uç noktası için ayrı bir yetkilendirme sınırı değildir. Bir araca burada Gateway kimlik doğrulaması + araç ilkesi aracılığıyla erişilebiliyorsa, /tools/invoke ek bir çağrı başına onay istemi eklemez.
• exec burada erişilebilir durumdaysa, bunu değişiklik yapabilen bir shell yüzeyi olarak ele alın. write, edit, apply_patch veya HTTP dosya sistemi yazma araçlarını reddetmek shell yürütmesini salt okunur yapmaz.
• Gateway bearer kimlik bilgilerini güvenilmeyen çağıranlarla paylaşmayın. Güven sınırları arasında ayrım gerekiyorsa ayrı gateway’ler (ve ideal olarak ayrı işletim sistemi kullanıcıları/ana makineleri) çalıştırın.

• exec - doğrudan komut yürütme (RCE yüzeyi)
• spawn - rastgele alt süreç oluşturma (RCE yüzeyi)
• shell - shell komutu yürütme (RCE yüzeyi)
• fs_write - ana makinede rastgele dosya değişikliği
• fs_delete - ana makinede rastgele dosya silme
• fs_move - ana makinede rastgele dosya taşıma/yeniden adlandırma
• apply_patch - yama uygulaması rastgele dosyaları yeniden yazabilir
• sessions_spawn - oturum orkestrasyonu; ajanları uzaktan başlatmak RCE’dir
• sessions_send - oturumlar arası mesaj enjeksiyonu
• cron - kalıcı otomasyon kontrol düzlemi
• gateway - gateway kontrol düzlemi; HTTP üzerinden yeniden yapılandırmayı önler
• nodes - düğüm komut aktarma, eşleştirilmiş ana makinelerde system.run’a ulaşabilir
• whatsapp_login - terminal QR taraması gerektiren etkileşimli kurulum; HTTP üzerinde takılı kalır

{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list
      allow: ["gateway"],
    },
  },
}

• x-openclaw-message-channel: <channel> (örnek: slack, telegram)
• x-openclaw-account-id: <accountId> (birden fazla hesap olduğunda)

​

Yanıtlar

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (geçersiz istek veya araç girdi hatası)
• 401 → yetkisiz
• 429 → kimlik doğrulama hız sınırına takıldı (Retry-After ayarlı)
• 404 → araç kullanılamıyor (bulunamadı veya izin listesinde değil)
• 405 → yönteme izin verilmiyor
• 500 → { ok: false, error: { type, message } } (beklenmeyen araç yürütme hatası; temizlenmiş mesaj)

​

Örnek

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'

​

İlgili

• Gateway protokolü
• Araçlar ve pluginler