Tools roepen de API aan

• POST /tools/invoke
• Dezelfde poort als de Gateway (WS + HTTP-multiplexing): http://<gateway-host>:<port>/tools/invoke
• Standaard maximale grootte van de aanvraagbody: 2 MB

​

Authenticatie

• authenticatie met gedeeld geheim (gateway.auth.mode="token" of "password"): Authorization: Bearer <token-or-password>
• vertrouwde HTTP-authenticatie met identiteit (gateway.auth.mode="trusted-proxy"): routeer via de geconfigureerde identiteitsbewuste proxy en laat deze de vereiste identiteitsheaders invoegen
• open authenticatie voor private ingress (gateway.auth.mode="none"): geen authenticatieheader vereist

• mode="token" gebruikt gateway.auth.token (of OPENCLAW_GATEWAY_TOKEN).
• mode="password" gebruikt gateway.auth.password (of OPENCLAW_GATEWAY_PASSWORD).
• mode="trusted-proxy" vereist dat de HTTP-aanvraag afkomstig is van een geconfigureerde vertrouwde proxybron; loopbackproxy’s op dezelfde host vereisen expliciet gateway.auth.trustedProxy.allowLoopback = true.
• Interne aanroepers op dezelfde host die de proxy omzeilen, kunnen gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD gebruiken als lokale directe fallback. Bewijs in een Forwarded-, X-Forwarded-*- of X-Real-IP-header houdt de aanvraag in plaats daarvan op het pad voor vertrouwde proxy’s.
• Als gateway.auth.rateLimit is geconfigureerd en er te veel authenticatiefouten optreden, retourneert het eindpunt 429 met Retry-After.

​

Beveiligingsgrens (belangrijk)

• HTTP-bearer-authenticatie is hier geen model met een beperkte scope per gebruiker.
• Een geldig Gateway-token/wachtwoord voor dit eindpunt moet worden beschouwd als een referentie van een eigenaar/operator.
• Voor authenticatiemodi met een gedeeld geheim (token en password) herstelt het eindpunt de normale volledige operatorstandaardwaarden, zelfs als de aanroeper een beperktere x-openclaw-scopes-header verzendt.
• Authenticatie met een gedeeld geheim behandelt rechtstreekse toolaanroepen op dit eindpunt ook als beurten van de eigenaar-afzender.
• Vertrouwde HTTP-modi met identiteit (authenticatie via een vertrouwde proxy, of gateway.auth.mode="none" op een private ingress) respecteren x-openclaw-scopes wanneer aanwezig en vallen anders terug op de normale set standaardscopes voor operators.
• Houd dit eindpunt uitsluitend op loopback/tailnet/private ingress; stel het niet rechtstreeks bloot aan het openbare internet.

​

Aanvraagbody

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

• tool / name (tekenreeks, vereist): naam van de aan te roepen tool. name heeft voorrang als beide worden verzonden.
• action (tekenreeks, optioneel): wordt samengevoegd in args.action als het toolschema een action-eigenschap ondersteunt en args er nog geen heeft ingesteld.
• args (object, optioneel): toolspecifieke argumenten.
• sessionKey (tekenreeks, optioneel): sleutel van de doelsessie. Indien weggelaten of "main", gebruikt de Gateway de geconfigureerde sleutel van de hoofdsessie (respecteert session.mainKey en de standaardagent, of global binnen de globale sessiescope).
• agentId (tekenreeks, optioneel): bepaalt de sessiesleutel voor die agent. Geeft een fout met 400 als deze conflicteert met een expliciete sessionKey die al aan een andere agent is gekoppeld.
• idempotencyKey (tekenreeks, optioneel): wordt gebruikt om een stabiele toolaanroep-id voor de aanroep af te leiden.
• dryRun (booleaans, optioneel): gereserveerd voor toekomstig gebruik; wordt momenteel genegeerd.

​

Beleids- en routeringsgedrag

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• groepsbeleid (als de sessiesleutel aan een groep of kanaal is gekoppeld)
• subagentbeleid (bij aanroepen met de sessiesleutel van een subagent)

• Uitvoeringsgoedkeuringen zijn veiligheidsmaatregelen voor operators, geen afzonderlijke autorisatiegrens voor dit HTTP-eindpunt. Als een tool hier bereikbaar is via Gateway-authenticatie + toolbeleid, voegt /tools/invoke geen extra goedkeuringsprompt per aanroep toe.
• Als exec hier bereikbaar is, beschouw deze dan als een muterend shell-oppervlak. Het weigeren van write, edit, apply_patch of HTTP-tools die naar het bestandssysteem schrijven, maakt shell-uitvoering niet alleen-lezen.
• Deel Gateway-bearer-referenties niet met niet-vertrouwde aanroepers. Als scheiding tussen vertrouwensgrenzen nodig is, voer dan afzonderlijke Gateways uit (bij voorkeur onder afzonderlijke OS-gebruikers/op hosts).

{
  gateway: {
    tools: {
      // Extra tools om via HTTP /tools/invoke te blokkeren
      deny: ["browser"],
      // Tools voor aanroepers met eigenaar-/beheerdersrechten uit de standaardblokkeerlijst verwijderen
      allow: ["gateway"],
    },
  },
}

• x-openclaw-message-channel: <channel> (voorbeeld: slack, telegram)
• x-openclaw-account-id: <accountId> (wanneer er meerdere accounts bestaan)
• x-openclaw-message-to: <target> (afleverdoel voor beleid van de berichtentool)
• x-openclaw-thread-id: <threadId> (threadcontext voor beleid van de berichtentool)

​

Antwoorden

​

Voorbeeld

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": {}
  }'

​

Gerelateerd

• Gateway-protocol
• Tools en plugins