Tools Invoke (HTTP)

Das OpenClaw-Gateway stellt einen einfachen HTTP-Endpunkt zum direkten Aufrufen eines einzelnen Tools bereit. Er ist immer aktiviert, 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

Maximale Standard-Payload-Größe ist 2 MB.

Authentifizierung

Verwendet die Gateway-Auth-Konfiguration. Sende ein Bearer-Token:

Authorization: Bearer <token>

Hinweise:

Bei gateway.auth.mode="token" verwende gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN).
Bei gateway.auth.mode="password" verwende gateway.auth.password (oder OPENCLAW_GATEWAY_PASSWORD).
Wenn gateway.auth.rateLimit konfiguriert ist und zu viele Auth-Fehler auftreten, gibt der Endpunkt 429 mit Retry-After zurück.

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 die Args gemappt, wenn das Tool-Schema action unterstützt und der Args-Payload es ausgelassen hat.
args (Objekt, optional): Tool-spezifische Argumente.
sessionKey (String, optional): Ziel-Session-Key. Wenn weggelassen oder "main", verwendet das Gateway den konfigurierten Main-Session-Key (berücksichtigt session.mainKey und Default-Agent, oder global im globalen Scope).
dryRun (Boolean, optional): Für zukünftige Verwendung reserviert; wird aktuell ignoriert.

Policy- + Routing-Verhalten

Die Tool-Verfügbarkeit wird durch dieselbe Policy-Kette gefiltert, die auch von Gateway-Agents verwendet wird:

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

Wenn ein Tool von der Policy nicht erlaubt wird, gibt der Endpunkt 404 zurück.

Gateway-HTTP wendet standardmäßig auch eine Hard-Deny-Liste an (selbst wenn die Session-Policy das Tool erlaubt):

sessions_spawn
sessions_send
gateway
whatsapp_login

Du kannst diese Deny-Liste über gateway.tools anpassen:

{
  gateway: {
    tools: {
      // Zusätzliche Tools über HTTP /tools/invoke blockieren
      deny: ["browser"],
      // Tools von der Standard-Deny-Liste entfernen
      allow: ["gateway"],
    },
  },
}

Um Gruppen-Policies bei der Kontext-Auflösung zu helfen, kannst du optional setzen:

x-openclaw-message-channel: <channel> (Beispiel: 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-Input-Fehler)
401 -> nicht autorisiert
429 -> Auth-Rate-Limit erreicht (Retry-After gesetzt)
404 -> Tool nicht verfügbar (nicht gefunden oder nicht in der Allowlist)
405 -> Methode nicht erlaubt
500 -> { ok: false, error: { type, message } } (unerwarteter Tool-Ausführungsfehler; bereinigte Nachricht)

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