Tools Invoke (HTTP)

Der OpenClaw-Gateway stellt einen einfachen HTTP-Endpunkt zum direkten Aufruf eines einzelnen Tools bereit. Er ist immer aktiv, unterliegt aber der Gateway-Auth und der Tool-Policy.

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

Standard-Maximum für die Payload-Größe ist 2 MB.

Authentifizierung

Nutzt die Gateway-Auth-Konfiguration. Bearer-Token mitsenden:

Authorization: Bearer <token>

Hinweise:

Bei gateway.auth.mode="token": gateway.auth.token (oder CLAWDBOT_GATEWAY_TOKEN) verwenden.
Bei gateway.auth.mode="password": gateway.auth.password (oder CLAWDBOT_GATEWAY_PASSWORD) verwenden.

Request-Body


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

Felder:

tool (string, erforderlich): Name des aufzurufenden Tools.
action (string, optional): wird in args übernommen, wenn das Tool-Schema action unterstützt und die Args-Payload es weglässt.
args (Objekt, optional): toolspezifische Argumente.
sessionKey (string, optional): Ziel-Sitzungsschlüssel. Wenn weggelassen oder "main", nutzt der Gateway den konfigurierten Hauptsitzungs-Key (beachtet session.mainKey und Standard-Agent oder global bei globalem Scope).
dryRun (boolean, optional): für künftige Nutzung reserviert; derzeit ignoriert.

Policy + Routing-Verhalten

Die Tool-Verfügbarkeit wird über dieselbe Policy-Kette gefiltert wie bei Gateway-Agenten:

tools.profile / tools.byProvider.profile
tools.allow / tools.byProvider.allow
agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
Gruppen-Policies (wenn der Sitzungsschlüssel auf eine Gruppe oder einen Kanal abbildet)
Subagent-Policy (bei Aufruf mit Subagent-Sitzungsschlüssel)

Ist ein Tool durch die Policy nicht erlaubt, antwortet der Endpunkt mit 404. Für die Auflösung von Gruppen-Policies können Sie optional setzen:

x-openclaw-message-channel: <channel> (z. B. slack, telegram)
x-openclaw-account-id: <accountId> (bei mehreren Accounts)

Antworten

200 → { ok: true, result }
400 → { ok: false, error: { type, message } } (ungültige Anfrage oder Tool-Fehler)
401 → nicht autorisiert
404 → Tool nicht verfügbar (nicht gefunden oder nicht in 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": {}
  }'