​

Tools Invoke (HTTP)

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

​

Kimlik doğrulama

• paylaşılan gizli auth (gateway.auth.mode="token" veya "password"): Authorization: Bearer <token-or-password>
• güvenilir kimlik taşıyan HTTP auth (gateway.auth.mode="trusted-proxy"): yapılandırılmış kimlik farkında proxy üzerinden yönlendirin ve gerekli kimlik üstbilgilerini onun eklemesine izin verin
• özel girişte açık auth (gateway.auth.mode="none"): auth üstbilgisi 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ış loopback olmayan güvenilir bir proxy kaynağından gelmelidir; aynı ana makinedeki loopback proxy’leri bu modu karşılamaz.
• gateway.auth.rateLimit yapılandırılmışsa ve çok fazla auth hatası oluşursa uç nokta Retry-After ile birlikte 429 döndürür.

​

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

• Buradaki HTTP bearer auth dar kapsamlı kullanıcı başına bir model değildir.
• Bu uç nokta için geçerli bir Gateway token/password değeri sahip/operatör kimlik bilgisi gibi değerlendirilmelidir.
• Paylaşılan gizli auth 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 auth ayrıca bu uç noktadaki doğrudan araç çağrılarını owner-sender turu olarak değerlendirir.
• Güvenilir kimlik taşıyan HTTP modları (örneğin trusted proxy auth veya özel girişte gateway.auth.mode="none") varsa x-openclaw-scopes üstbilgisini uygular, yoksa normal operatör varsayılan kapsam kümesine geri döner.
• Bu uç noktayı yalnızca loopback/tailnet/özel girişte tutun; doğrudan genel internete açmayın.

• gateway.auth.mode="token" veya "password" + Authorization: Bearer ...
  • paylaşılan gateway operatör gizli verisine 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ı owner-sender turu olarak değerlendirir
• güvenilir kimlik taşıyan HTTP modları (örneğin trusted proxy auth veya özel girişte gateway.auth.mode="none")
  • bazı dış güvenilir kimlik veya dağıtım sınırlarını doğrular
  • üstbilgi mevcut olduğunda x-openclaw-scopes değerini uygular
  • üstbilgi 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 owner anlamını kaybeder

​

İstek gövdesi

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

• tool (string, zorunlu): çağrılacak araç adı.
• action (string, isteğe bağlı): araç şeması action alanını destekliyorsa ve args payload’ı bunu atladıysa args içine eşlenir.
• args (object, isteğe bağlı): araca özgü bağımsız değişkenler.
• sessionKey (string, 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 aracıyı veya global kapsamda global değerini dikkate alı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 gruba veya kanala eşleniyorsa)
• alt aracı ilkesi (bir subagent oturum anahtarı ile çağrılıyorsa)

• Exec onayları, bu HTTP uç noktası için ayrı bir yetkilendirme sınırı değil, operatör korkuluklarıdır. Bir araca burada Gateway auth + araç ilkesi aracılığıyla erişilebiliyorsa /tools/invoke, çağrı başına ek bir onay istemi eklemez.
• Gateway bearer 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 (ve ideal olarak ayrı OS kullanıcıları/ana makineler).

• exec — doğrudan komut yürütme (RCE yüzeyi)
• spawn — keyfi alt süreç oluşturma (RCE yüzeyi)
• shell — shell komutu yürütme (RCE yüzeyi)
• fs_write — ana makinede keyfi dosya değiştirme
• fs_delete — ana makinede keyfi dosya silme
• fs_move — ana makinede keyfi dosya taşıma/yeniden adlandırma
• apply_patch — yama uygulama keyfi dosyaları yeniden yazabilir
• sessions_spawn — oturum orkestrasyonu; uzaktan aracı 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 — node komut aktarma paired ana makinelerde system.run işlevine ulaşabilir
• whatsapp_login — terminalde QR taraması gerektiren etkileşimli kurulum; HTTP üzerinde takılır

{
  gateway: {
    tools: {
      // HTTP /tools/invoke üzerinden engellenecek ek araçlar
      deny: ["browser"],
      // Varsayılan deny list içinden araç kaldır
      allow: ["gateway"],
    },
  },
}

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

​

Yanıtlar

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (geçersiz istek veya araç girdisi hatası)
• 401 → yetkisiz
• 429 → auth hız sınırına takıldı (Retry-After ayarlıdır)
• 404 → araç kullanılamıyor (bulunamadı veya allowlist’te 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": {}
  }'