Naar hoofdinhoud gaan

​
Tools Aanroepen (HTTP)

De Gateway van OpenClaw stelt een eenvoudig HTTP-eindpunt beschikbaar om één enkele tool rechtstreeks aan te roepen. Het is altijd ingeschakeld, maar afgeschermd door Gateway-authenticatie en toolbeleid.
  • POST /tools/invoke
  • Zelfde poort als de Gateway (WS + HTTP-multiplex): http://<gateway-host>:<port>/tools/invoke
De standaard maximale payloadgrootte is 2 MB.

​
Authenticatie

Gebruikt de Gateway-authenticatieconfiguratie. Stuur een bearer-token:
  • Authorization: Bearer <token>
Notities:
  • 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).
  • Als gateway.auth.rateLimit is geconfigureerd en er te veel authenticatiefouten optreden, retourneert het endpoint 429 met Retry-After.

​
Request body

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}
Velden
  • tool (string, vereist): naam van de tool die moet worden aangeroepen.
  • action (string, optioneel): wordt gemapt naar args als het toolschema action ondersteunt en de args-payload dit heeft weggelaten.
  • args (object, optioneel): tool-specifieke argumenten.
  • sessionKey (string, optioneel): doelsessiesleutel. Indien weggelaten of "main", gebruikt de Gateway de geconfigureerde hoofdsessiesleutel (respecteert session.mainKey en de standaardagent, of global in globale scope).
  • dryRun (boolean, optioneel): gereserveerd voor toekomstig gebruik; momenteel genegeerd.

​
Beleid + routeringsgedrag

Toolbeschikbaarheid wordt gefilterd via dezelfde beleidsketen die door Gateway-agents wordt gebruikt:
  • 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 wijst)
  • subagentbeleid (bij aanroepen met een subagentsessiesleutel)
Als een tool niet is toegestaan door het beleid, retourneert het eindpunt 404. Gateway HTTP past standaard ook een harde denylist toe (zelfs als het sessiebeleid de tool toestaat):
  • sessions_spawn
  • sessions_send
  • gateway
  • whatsapp_login
Je kunt deze denylist aanpassen via gateway.tools: 
{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list
      allow: ["gateway"],
    },
  },
}
Om groepsbeleid te helpen context op te lossen, kun je optioneel instellen:
  • 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 } } (ongeldige aanvraag of toolfout)
  • 401 → unauthorized
  • 429 → authenticatie rate-limited (Retry-After ingesteld)
  • 404 → tool niet beschikbaar (niet gevonden of niet op de toegestane lijst)
  • 405 → methode niet toegestaan
  • Velden

​
Voorbeeld

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'