API voor toolaanroepen

• POST /tools/invoke
• Dezelfde poort als de Gateway (WS + HTTP multiplex): http://<gateway-host>:<port>/tools/invoke

​

Authenticatie

• shared-secret-authenticatie (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 identity-aware proxy en laat die de vereiste identiteitsheaders injecteren
• open authenticatie via private ingress (gateway.auth.mode="none"): geen authenticatieheader vereist

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

​

Beveiligingsgrens (belangrijk)

• HTTP bearer-authenticatie hier is geen nauw scope-model per gebruiker.
• Een geldig Gateway-token/wachtwoord voor dit eindpunt moet worden behandeld als een owner/operator-referentie.
• Voor shared-secret-authenticatiemodi (token en password) herstelt het eindpunt de normale volledige operatorstandaarden, zelfs als de aanroeper een smallere x-openclaw-scopes-header verzendt.
• Shared-secret-authenticatie behandelt directe toolaanroepen op dit eindpunt ook als owner-sender-beurten.
• Vertrouwde HTTP-modi met identiteit (bijvoorbeeld trusted-proxy-authenticatie of gateway.auth.mode="none" op een private ingress) respecteren x-openclaw-scopes wanneer aanwezig en vallen anders terug op de normale standaardset operatorscopes.
• Houd dit eindpunt alleen op loopback/tailnet/private ingress; stel het niet direct bloot aan het openbare internet.

• gateway.auth.mode="token" of "password" + Authorization: Bearer ...
  • bewijst bezit van het gedeelde Gateway-operatorgeheim
  • negeert smallere x-openclaw-scopes
  • herstelt de volledige standaardset operatorscopes: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • behandelt directe toolaanroepen op dit eindpunt als owner-sender-beurten
• vertrouwde HTTP-modi met identiteit (bijvoorbeeld trusted-proxy-authenticatie, of gateway.auth.mode="none" op private ingress)
  • authenticeren een externe vertrouwde identiteit of deploymentgrens
  • respecteren x-openclaw-scopes wanneer de header aanwezig is
  • vallen terug op de normale standaardset operatorscopes wanneer de header afwezig is
  • verliezen owner-semantiek alleen wanneer de aanroeper scopes expliciet vernauwt en operator.admin weglaat

​

Request-body

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

• tool (string, vereist): toolnaam om aan te roepen.
• action (string, optioneel): wordt naar args gemapt als het toolschema action ondersteunt en de args-payload dit heeft weggelaten.
• args (object, optioneel): toolspecifieke argumenten.
• sessionKey (string, optioneel): doelsessiesleutel. Indien weggelaten of "main", gebruikt de Gateway de geconfigureerde hoofdsessiesleutel (respecteert session.mainKey en standaardagent, of global in globale scope).
• dryRun (boolean, optioneel): gereserveerd voor toekomstig gebruik; momenteel genegeerd.

​

Beleid + routinggedrag

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• groepsbeleid (als de sessiesleutel naar een groep of kanaal verwijst)
• subagentbeleid (bij aanroepen met een subagent-sessiesleutel)

• Exec-goedkeuringen zijn operatorvangrails, geen aparte 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, behandel het dan als een muterend shelloppervlak. Het weigeren van write, edit, apply_patch of HTTP-tools voor filesystem-write maakt shelluitvoering niet alleen-lezen.
• Deel Gateway-bearer-referenties niet met niet-vertrouwde aanroepers. Als je scheiding tussen vertrouwensgrenzen nodig hebt, voer dan aparte gateways uit (en idealiter aparte OS-gebruikers/hosts).

• exec - directe opdrachtuitvoering (RCE-oppervlak)
• spawn - willekeurige aanmaak van childprocessen (RCE-oppervlak)
• shell - uitvoering van shellopdrachten (RCE-oppervlak)
• fs_write - willekeurige bestandsmutatie op de host
• fs_delete - willekeurige bestandsverwijdering op de host
• fs_move - willekeurige bestandsverplaatsing/-hernoeming op de host
• apply_patch - patchtoepassing kan willekeurige bestanden herschrijven
• sessions_spawn - sessieorkestratie; agents op afstand starten is RCE
• sessions_send - berichtinjectie tussen sessies
• cron - persistent automatiseringsbesturingsvlak
• gateway - Gateway-besturingsvlak; voorkomt herconfiguratie via HTTP
• nodes - node-opdrachtdoorsturing kan system.run bereiken op gekoppelde hosts
• whatsapp_login - interactieve setup waarvoor een terminal-QR-scan nodig is; blijft hangen via HTTP

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

• x-openclaw-message-channel: <channel> (voorbeeld: slack, telegram)
• x-openclaw-account-id: <accountId> (wanneer er meerdere accounts bestaan)

​

Responses

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (ongeldig verzoek of fout in toolinvoer)
• 401 → unauthorized
• 429 → authenticatie rate-limited (Retry-After ingesteld)
• 404 → tool niet beschikbaar (niet gevonden of niet op allowlist)
• 405 → method not allowed
• 500 → { ok: false, error: { type, message } } (onverwachte fout bij tooluitvoering; opgeschoond bericht)

​

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