OpenClaw Tools per HTTP aufrufen: Schnelle API-Anbindung

Kennst du das? Du hast ein nützliches Tool in deinem Gateway registriert, willst es aber einfach nur schnell per Skript oder Webhook triggern, ohne direkt eine komplexe Agenten-Logik oder eine WebSocket-Verbindung aufzubauen. Manchmal ist ein simpler HTTP-Call genau das, was man braucht, um eine Aufgabe effizient zu erledigen.

Das OpenClaw Gateway bietet dafür einen direkten HTTP-Endpoint an, um ein einzelnes Tool aufzurufen. Er ist standardmäßig aktiviert und nutzt die Gateway-Authentifizierung sowie die Tool-Policies. Genau wie die OpenAI-kompatible /v1/* Oberfläche wird der Shared-Secret Bearer-Auth hier als vertrauenswürdiger Operator-Zugriff für das gesamte Gateway behandelt.

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

Die standardmäßige maximale Payload-Größe beträgt 2 MB.

Authentifizierung

Der Endpoint nutzt die Gateway-Auth-Konfiguration. Sende einen Bearer-Token im Header:

• Authorization: Bearer <token>

Hinweise:

• Wenn gateway.auth.mode="token" aktiv ist, verwende gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN).
• Wenn gateway.auth.mode="password" aktiv ist, verwende gateway.auth.password (oder OPENCLAW_GATEWAY_PASSWORD).
• Falls gateway.auth.rateLimit konfiguriert ist und zu viele Fehlversuche auftreten, gibt der Endpoint 429 mit einem Retry-After Header zurück.

Sicherheitsgrenzen (Wichtig)

Betrachte diesen Endpoint als Schnittstelle für den vollen Operator-Zugriff auf die Gateway-Instanz.

• HTTP Bearer-Auth ist hier kein feingranulares Modell pro User.
• Ein gültiger Gateway-Token oder ein Passwort für diesen Endpoint sollte wie ein Owner/Operator-Credential behandelt werden.
• Bei Shared-Secret-Modi (token und password) stellt der Endpoint die normalen Operator-Standardeinstellungen wieder her, selbst wenn der Aufrufer einen eingeschränkten x-openclaw-scopes Header mitsendet.
• Shared-Secret-Auth behandelt direkte Tool-Aufrufe an diesem Endpoint als Aktionen des Owners.
• Vertrauenswürdige identitätsbasierte HTTP-Modi (zum Beispiel Trusted Proxy Auth oder gateway.auth.mode="none" in einem privaten Ingress) berücksichtigen weiterhin die deklarierten Operator-Scopes im Request.
• Behalte diesen Endpoint nur im Loopback, Tailnet oder privaten Ingress; gib ihn nicht direkt im öffentlichen Internet frei.

Auth-Matrix:

• gateway.auth.mode="token" oder "password" + Authorization: Bearer ...
  • Bestätigt den Besitz des Shared Gateway Operator Secrets.
  • Ignoriert eingeschränkte x-openclaw-scopes.
  • Stellt das volle Standard-Operator-Scope-Set wieder her.
  • Behandelt direkte Tool-Aufrufe als Aktionen des Owners.
• Vertrauenswürdige identitätsbasierte HTTP-Modi (z. B. Trusted Proxy Auth oder gateway.auth.mode="none" im privaten Ingress)
  • Authentifizieren eine externe vertrauenswürdige Identität oder Deployment-Grenze.
  • Berücksichtigen den deklarierten x-openclaw-scopes Header.
  • Erhalten Owner-Semantik nur, wenn operator.admin tatsächlich in den deklarierten Scopes enthalten ist.

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, falls das Tool-Schema action unterstützt und die Payload es weggelassen hat.
• args (Object, optional): Tool-spezifische Argumente.
• sessionKey (String, optional): Ziel-Session-Key. Wenn weggelassen oder auf "main" gesetzt, nutzt das Gateway den konfigurierten Main-Session-Key (berücksichtigt session.mainKey und den Standard-Agenten, oder global im globalen Scope).
• dryRun (Boolean, optional): Reserviert für zukünftige Nutzung; wird derzeit ignoriert.

Policy- und Routing-Verhalten

Die Tool-Verfügbarkeit wird durch dieselbe Policy-Chain gefiltert, die auch Gateway-Agenten nutzen:

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

Falls ein Tool durch eine Policy nicht erlaubt ist, gibt der Endpoint 404 zurück.

Wichtige Hinweise zu den Grenzen:

• Exec-Approvals sind Operator-Guardrails und keine separate Autorisierungsgrenze für diesen HTTP-Endpoint. Wenn ein Tool hier über Gateway-Auth + Tool-Policy erreichbar ist, fügt /tools/invoke keine zusätzliche Bestätigung pro Aufruf hinzu.
• Teile Gateway-Bearer-Credentials nicht mit nicht vertrauenswürdigen Aufrufern. Wenn du eine Trennung zwischen Vertrauensbereichen benötigst, lass separate Gateways laufen (idealerweise unter verschiedenen OS-Usern oder Hosts).

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

• exec — Direkte Befehlsausführung (RCE-Risiko)
• spawn — Erstellung beliebiger Child-Prozesse (RCE-Risiko)
• shell — Shell-Befehlsausführung (RCE-Risiko)
• fs_write — Beliebige Dateimanipulation auf dem Host
• fs_delete — Beliebiges Löschen von Dateien auf dem Host
• fs_move — Beliebiges Verschieben/Umbenennen von Dateien auf dem Host
• apply_patch — Patches können beliebige Dateien überschreiben
• sessions_spawn — Session-Orchestrierung; das Remote-Spawning von Agenten ist RCE
• sessions_send — Nachrichten-Injektion über Sessions hinweg
• cron — Persistente Automatisierungs-Control-Plane
• gateway — Gateway-Control-Plane; verhindert Rekonfiguration via HTTP
• nodes — Node-Command-Relay kann system.run auf gekoppelten Hosts erreichen
• whatsapp_login — Interaktives Setup, das einen QR-Scan im Terminal erfordert; bleibt bei HTTP hängen

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

{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list
      allow: ["gateway"],
    },
  },
}

Um Group Policies bei der Kontextauflösung zu helfen, kannst du optional folgende Header setzen:

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

Antworten

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (Ungültiger Request oder Tool-Input-Fehler)
• 401 → Nicht autorisiert
• 429 → Auth Rate-Limited (Retry-After ist gesetzt)
• 404 → Tool nicht verfügbar (nicht gefunden oder nicht auf der Allowlist)
• 405 → Methode nicht erlaubt
• 500 → { ok: false, error: { type, message } } (Unerwarteter Fehler bei der Tool-Ausführung; bereinigte Nachricht)

Beispiel

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

Nächste Schritte

• Schau dir die Gateway-Konfiguration an, um die Authentifizierung anzupassen.
• Erfahre mehr über Tool-Policies, um den Zugriff feiner zu steuern.

AI Setup Assistant