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

OpenClaw'ın Gateway'i, tek bir aracı doğrudan çağırmak için bir HTTP uç noktası sunar. Bu uç nokta her zaman etkindir ve Gateway kimlik doğrulaması ile araç politikasını kullanır. OpenAI uyumlu /v1/* yüzeyinde olduğu gibi, paylaşılan gizli anahtara dayalı taşıyıcı kimlik doğrulaması tüm Gateway için güvenilir operatör erişimi olarak değerlendirilir.

• 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

Gateway kimlik doğrulama yapılandırmasını kullanır.

Yaygın HTTP kimlik doğrulama yolları:

• 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

Notlar:

• 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)

Bu uç noktayı Gateway örneği için tam operatör erişimli bir yüzey olarak değerlendirin.

• 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.

Kimlik doğrulama matrisi:

İstek gövdesi

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

Alanlar:

• 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ışı

Araç kullanılabilirliği, Gateway agentlerinin kullandığı politika zinciri üzerinden filtrelenir:

• 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)

Bir araca politika tarafından izin verilmiyorsa uç nokta 404 döndürür.

Önemli sınır notları:

• Ç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 HTTP, oturum politikası araca izin verse bile varsayılan olarak katı bir ret listesi de uygular:

cron, gateway ve nodes de yalnızca sahiplere açıktır: varsayılan ret listesinin dışında olsalar bile sahip olmayan çağıranlar bu yüzeyde bunları çağıramaz.

Genel ret listesini gateway.tools aracılığıyla özelleştirin:

{  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"],    },  },}

gateway.tools.allow bir kapsam yükseltmesi değil, erişime açma geçersiz kılmasıdır. Kimlik bilgisi taşıyan HTTP modlarında cron, gateway ve nodes, gateway.tools.allow içinde listelenseler bile sahip/yönetici kimliği (operator.admin) olmayan çağıranlar tarafından kullanılamaz. Paylaşılan gizli anahtara dayalı taşıyıcı kimlik doğrulaması yine yukarıdaki tam güvenilir operatör kuralını izler.

Grup politikalarının bağlamı çözümlemesine yardımcı olmak için isteğe bağlı olarak şunları ayarlayabilirsiniz:

• 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