Araçlar API'yi çağırır

• POST /tools/invoke
• Gateway ile aynı bağlantı noktası (WS + HTTP çoklama): http://<gateway-host>:<port>/tools/invoke
• Varsayılan maksimum istek gövdesi boyutu: 2 MB

​

Kimlik doğrulama

• paylaşılan gizli anahtar kimlik doğrulaması (gateway.auth.mode="token" veya "password"): Authorization: Bearer <token-or-password>
• kimlik bilgisi taşıyan güvenilir HTTP kimlik doğrulaması (gateway.auth.mode="trusted-proxy"): yapılandırılmış kimlik duyarlı proxy üzerinden yönlendirin ve gerekli kimlik üstbilgilerini eklemesini sağlayın
• özel girişte açık kimlik doğrulama (gateway.auth.mode="none"): kimlik doğrulama üstbilgisi gerekmez

• mode="token", gateway.auth.token (veya OPENCLAW_GATEWAY_TOKEN) kullanır.
• mode="password", gateway.auth.password (veya OPENCLAW_GATEWAY_PASSWORD) kullanır.
• mode="trusted-proxy", HTTP isteğinin yapılandırılmış güvenilir bir proxy kaynağından gelmesini gerektirir; aynı ana makinedeki geri döngü proxy’leri açıkça gateway.auth.trustedProxy.allowLoopback = true gerektirir.
• Proxy’yi atlayan aynı ana makinedeki dahili çağıranlar, yerel doğrudan geri dönüş olarak gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD kullanabilir. Herhangi bir Forwarded, X-Forwarded-* veya X-Real-IP üstbilgi kanıtı, isteği bunun yerine güvenilir proxy yolunda tutar.
• 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 taşıyıcı kimlik doğrulaması, kullanıcı başına dar kapsamlı bir model değildir.
• Bu uç nokta için geçerli bir Gateway belirteci/parolası, sahip/operatör kimlik bilgisi gibi değerlendirilmelidir.
• Paylaşılan gizli anahtar kimlik doğrulama modlarında (token ve password), çağıran daha dar bir x-openclaw-scopes üstbilgisi 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ı da sahip-gönderici turları olarak değerlendirir.
• Kimlik bilgisi taşıyan güvenilir HTTP modları (güvenilir proxy kimlik doğrulaması veya özel girişte gateway.auth.mode="none"), mevcut olduğunda x-openclaw-scopes değerine uyar; aksi takdirde normal varsayılan operatör kapsam kümesine geri döner.
• Bu uç noktayı yalnızca geri döngü/tailnet/özel giriş üzerinde tutun; doğrudan genel internete açmayın.

​

İstek gövdesi

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

• tool / name (dize, gerekli): çağrılacak araç adı. Her ikisi de gönderilirse name önceliklidir.
• action (dize, isteğe bağlı): araç şeması bir action özelliğini destekliyorsa ve args zaten bir değer ayarlamamışsa args.action ile birleştirilir.
• 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 agente ya da genel oturum kapsamında global değerine uyar).
• agentId (dize, isteğe bağlı): söz konusu agent için oturum anahtarını çözümler. Farklı bir agente zaten eşlenen açık bir sessionKey ile çakışırsa 400 hatası verir.
• idempotencyKey (dize, isteğe bağlı): çağrı için kararlı bir araç çağrısı kimliği türetmek amacıyla kullanılır.
• dryRun (boole, isteğe bağlı): gelecekte kullanılmak üzere ayrılmıştır; şu anda yok sayılır.

​

Politika + yönlendirme davranışı

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• grup politikaları (oturum anahtarı bir grup veya kanalla eşleşiyorsa)
• alt agent politikası (bir alt agent oturum anahtarıyla çağrı yapıldığında)

• Çalıştırma onayları, bu HTTP uç noktası için ayrı bir yetkilendirme sınırı değil, operatör güvenlik önlemleridir. Bir araca burada Gateway kimlik doğrulaması + araç politikası aracılığıyla erişilebiliyorsa /tools/invoke, çağrı başına ek bir onay istemi eklemez.
• exec aracına buradan erişilebiliyorsa bunu değişiklik yapan bir kabuk yüzeyi olarak değerlendirin. write, edit, apply_patch veya HTTP dosya sistemi yazma araçlarının reddedilmesi, kabuk yürütmesini salt okunur hâle getirmez.
• Gateway taşıyıcı kimlik bilgilerini güvenilmeyen çağıranlarla paylaşmayın. Güven sınırları arasında ayrım gerekiyorsa ayrı Gateway’ler çalıştırın (tercihen ayrı işletim sistemi kullanıcılarında/ana makinelerinde).

{
  gateway: {
    tools: {
      // HTTP /tools/invoke üzerinden engellenecek ek araçlar
      deny: ["browser"],
      // Sahip/yönetici çağıranlar için araçları varsayılan ret listesinden kaldırın
      allow: ["gateway"],
    },
  },
}

• x-openclaw-message-channel: <channel> (örnek: slack, telegram)
• x-openclaw-account-id: <accountId> (birden fazla hesap varsa)
• x-openclaw-message-to: <target> (ileti aracı politikası için teslimat hedefi)
• x-openclaw-thread-id: <threadId> (ileti aracı politikası için iş parçacığı bağlamı)

​

Yanıtlar

​

Ö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