Tools Invoke (HTTP)

Das Gateway von OpenClaw bietet einen einfachen HTTP-Endpoint, um ein einzelnes Tool direkt aufzurufen. Der Endpoint ist immer aktiv, aber durch Gateway-Auth und Tool-Policy geschützt.

  • POST /tools/invoke
  • Gleicher Port wie das Gateway (WS + HTTP Multiplex): http://<gateway-host>:<port>/tools/invoke

Die maximale Payload-Groesse ist standardmaessig 2 MB.

Authentifizierung

Nutzt die Gateway-Auth-Konfiguration. Sende einen Bearer Token:

  • Authorization: Bearer <token>

Hinweise:

  • Bei gateway.auth.mode="token" verwendest du gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN).
  • Bei gateway.auth.mode="password" verwendest du gateway.auth.password (oder OPENCLAW_GATEWAY_PASSWORD).

Request Body

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

Felder:

  • tool (string, erforderlich): Name des Tools, das aufgerufen werden soll.
  • action (string, optional): Wird in args gemappt, wenn das Tool-Schema action unterstuetzt und es in der args-Payload fehlt.
  • args (object, optional): Tool-spezifische Argumente.
  • sessionKey (string, optional): Ziel-Session-Key. Wenn weggelassen oder "main", verwendet das Gateway den konfigurierten Main-Session-Key (beruecksichtigt session.mainKey und den Default-Agent, oder global im globalen Scope).
  • dryRun (boolean, optional): Fuer zukuenftige Nutzung reserviert; wird aktuell ignoriert.

Policy- und Routing-Verhalten

Die Tool-Verfuegbarkeit wird durch dieselbe Policy-Chain gefiltert, die auch Gateway-Agents nutzen:

  • tools.profile / tools.byProvider.profile
  • tools.allow / tools.byProvider.allow
  • agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
  • Group-Policies (wenn der Session-Key auf eine Gruppe oder einen Channel verweist)
  • Subagent-Policy (beim Aufruf mit einem Subagent-Session-Key)

Wenn ein Tool durch die Policy nicht erlaubt ist, gibt der Endpoint 404 zurueck.

Um Group-Policies bei der Kontext-Aufloesung zu helfen, kannst du optional setzen:

  • x-openclaw-message-channel: <channel> (Beispiel: slack, telegram)
  • x-openclaw-account-id: <accountId> (wenn mehrere Accounts existieren)

Responses

  • 200 → { ok: true, result }
  • 400 → { ok: false, error: { type, message } } (ungueltiger Request oder Tool-Fehler)
  • 401 → nicht autorisiert
  • 404 → Tool nicht verfuegbar (nicht gefunden oder nicht in der Allowlist)
  • 405 → Methode nicht erlaubt

Beispiel

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