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ının yanı sıra araç politikasını kullanır. OpenAI uyumlu /v1/* yüzeyinde olduğu gibi, paylaşılan gizli anahtara dayalı taşıyıcı kimlik doğrulaması, Gateway'in tamamı için güvenilir operatör erişimi olarak değerlendirilir.

• POST /tools/invoke
• Gateway ile aynı bağlantı noktası (WS + HTTP çoğullama): http://<gateway-host>:<port>/tools/invoke
• Varsayılan en yüksek 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"): isteği 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ğrulaması (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 local loopback proxy'ler için açıkça gateway.auth.trustedProxy.allowLoopback = true ayarlanmalıdır.
• 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 üstbilgisi kanıtı, isteğin bunun yerine güvenilir proxy yolunda kalmasını sağlar.
• 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şimi sağlayan 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önderen etkileşimleri 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 üstbilgisini dikkate alır; aksi hâlde normal varsayılan operatör kapsamı kümesine geri döner.
• Bu uç noktayı yalnızca local loopback/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, zorunlu): çağrılacak aracın adı. Her ikisi de gönderilirse name önceliklidir.
• action (dize, isteğe bağlı): araç şeması bir action özelliğini destekliyorsa ve args içinde zaten ayarlanmamış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ı. Belirtilmezse veya "main" ise Gateway, yapılandırılmış ana oturum anahtarını kullanır (session.mainKey ve varsayılan aracıyı ya da genel oturum kapsamında global değerini dikkate alır).
• agentId (dize, isteğe bağlı): ilgili aracı için oturum anahtarını çözümler. Zaten farklı bir aracıyla eşleşen 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ı): ileride kullanılmak üzere ayrılmıştır; şu anda yok sayılır.

Politika ve yönlendirme davranışı

Araç kullanılabilirliği, Gateway aracıları tarafından kullanılan aynı 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 aracı politikası (bir alt aracı 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ı:

• Exec onayları, bu HTTP uç noktası için ayrı bir yetkilendirme sınırı değil, operatör koruma önlemleridir. Bir araca burada Gateway kimlik doğrulaması ve 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ı reddetmek, 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ı/ana makineleri üzerinde).

Gateway HTTP ayrıca varsayılan olarak kesin bir engelleme listesi uygular (oturum politikası araca izin verse bile):

cron, gateway ve nodes ayrıca yalnızca sahip içindir: bu varsayılan engelleme listesinin dışında olsalar bile sahip olmayan çağıranlar bunları bu yüzeyde çağıramaz.

Genel engelleme listesini gateway.tools üzerinden özelleştirin:

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

gateway.tools.allow bir erişime açma geçersiz kılmasıdır, kapsam yükseltmesi değildir. 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ı, yukarıdaki tam güvenilir operatör kuralını izlemeye devam eder.

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 olduğunda)
• x-openclaw-message-to: <target> (ileti aracı politikası için teslimat hedefi)
• x-openclaw-thread-id: <threadId> (ileti aracı politikası için ileti dizisi 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 Plugin'ler