Gateway

API zum Aufrufen von Tools

OpenClaw-Gateway stellt einen einfachen HTTP-Endpunkt bereit, um ein einzelnes Tool direkt aufzurufen. Er ist immer aktiviert und verwendet Gateway-Authentifizierung plus Tool-Richtlinie. Wie bei der OpenAI-kompatiblen /v1/*-Oberfläche wird Shared-Secret-Bearer-Authentifizierung als vertrauenswürdiger Operator-Zugriff für den gesamten Gateway behandelt.

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

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

Authentifizierung

Verwendet die Gateway-Authentifizierungskonfiguration.

Gängige HTTP-Authentifizierungspfade:

Shared-Secret-Authentifizierung (gateway.auth.mode="token" oder "password"): Authorization: Bearer <token-or-password>
vertrauenswürdige identitätstragende HTTP-Authentifizierung (gateway.auth.mode="trusted-proxy"): Leiten Sie über den konfigurierten identitätsbewussten Proxy weiter und lassen Sie ihn die erforderlichen Identitäts-Header injizieren
offene Authentifizierung für privaten Ingress (gateway.auth.mode="none"): kein Authentifizierungs-Header erforderlich

Hinweise:

Wenn gateway.auth.mode="token" gilt, verwenden Sie gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN).
Wenn gateway.auth.mode="password" gilt, verwenden Sie gateway.auth.password (oder OPENCLAW_GATEWAY_PASSWORD).
Wenn gateway.auth.mode="trusted-proxy" gilt, muss die HTTP-Anfrage von einer konfigurierten vertrauenswürdigen Proxy-Quelle stammen; Same-Host-loopback-Proxys erfordern explizit gateway.auth.trustedProxy.allowLoopback = true.
Interne Same-Host-Aufrufer, die den Proxy umgehen, können gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD als lokale direkte Rückfalloption verwenden. Hinweise in Forwarded-, X-Forwarded-*- oder X-Real-IP-Headern halten die Anfrage stattdessen auf dem Trusted-Proxy-Pfad.
Wenn gateway.auth.rateLimit konfiguriert ist und zu viele Authentifizierungsfehler auftreten, gibt der Endpunkt 429 mit Retry-After zurück.

Sicherheitsgrenze (wichtig)

Behandeln Sie diesen Endpunkt als Oberfläche mit vollständigem Operator-Zugriff für die Gateway-Instanz.

HTTP-Bearer-Authentifizierung ist hier kein eng gefasstes Pro-Benutzer-Scope-Modell.
Ein gültiges Gateway-Token/-Passwort für diesen Endpunkt sollte wie ein Owner-/Operator-Anmeldedatum behandelt werden.
Für Shared-Secret-Authentifizierungsmodi (token und password) stellt der Endpunkt die normalen vollständigen Operator-Standards wieder her, selbst wenn der Aufrufer einen engeren x-openclaw-scopes-Header sendet.
Shared-Secret-Authentifizierung behandelt direkte Tool-Aufrufe an diesem Endpunkt außerdem als Owner-Sender-Turns.
Vertrauenswürdige identitätstragende HTTP-Modi (zum Beispiel Trusted-Proxy-Authentifizierung oder gateway.auth.mode="none" auf einem privaten Ingress) berücksichtigen x-openclaw-scopes, wenn vorhanden, und fallen andernfalls auf den normalen Standard-Scope-Satz für Operatoren zurück.
Beschränken Sie diesen Endpunkt auf loopback/tailnet/privaten Ingress; stellen Sie ihn nicht direkt im öffentlichen Internet bereit.

Authentifizierungsmatrix:

gateway.auth.mode="token" oder "password" + Authorization: Bearer ...
- weist den Besitz des gemeinsamen Gateway-Operator-Geheimnisses nach
- ignoriert engere x-openclaw-scopes
- stellt den vollständigen Standard-Scope-Satz für Operatoren wieder her: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
- behandelt direkte Tool-Aufrufe an diesem Endpunkt als Owner-Sender-Turns
vertrauenswürdige identitätstragende HTTP-Modi (zum Beispiel Trusted-Proxy-Authentifizierung oder gateway.auth.mode="none" auf privatem Ingress)
- authentifizieren eine äußere vertrauenswürdige Identität oder Deployment-Grenze
- berücksichtigen x-openclaw-scopes, wenn der Header vorhanden ist
- fallen auf den normalen Standard-Scope-Satz für Operatoren zurück, wenn der Header fehlt
- verlieren Owner-Semantik nur, wenn der Aufrufer Scopes explizit einschränkt und operator.admin weglässt

Anfrage-Body

json

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

Felder:

tool (String, erforderlich): Name des aufzurufenden Tools.
action (String, optional): wird in Argumente abgebildet, wenn das Tool-Schema action unterstützt und die Argument-Payload es ausgelassen hat.
args (Objekt, optional): Tool-spezifische Argumente.
sessionKey (String, optional): Ziel-Session-Schlüssel. Wenn ausgelassen oder "main", verwendet der Gateway den konfigurierten Haupt-Session-Schlüssel (berücksichtigt session.mainKey und den Standard-Agent oder global im globalen Scope).
dryRun (Boolean, optional): für künftige Verwendung reserviert; derzeit ignoriert.

Richtlinien- und Routing-Verhalten

Die Tool-Verfügbarkeit wird über dieselbe Richtlinienkette gefiltert, die Gateway-Agenten verwenden:

tools.profile / tools.byProvider.profile
tools.allow / tools.byProvider.allow
agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
Gruppenrichtlinien (wenn der Session-Schlüssel einer Gruppe oder einem Kanal zugeordnet ist)
Subagent-Richtlinie (beim Aufruf mit einem Subagent-Session-Schlüssel)

Wenn ein Tool durch die Richtlinie nicht erlaubt ist, gibt der Endpunkt 404 zurück.

Wichtige Grenzhinweise:

Exec-Genehmigungen sind Operator-Leitplanken, keine separate Autorisierungsgrenze für diesen HTTP-Endpunkt. Wenn ein Tool hier über Gateway-Authentifizierung + Tool-Richtlinie erreichbar ist, fügt /tools/invoke keine zusätzliche Pro-Aufruf-Genehmigungsabfrage hinzu.
Wenn exec hier erreichbar ist, behandeln Sie es als verändernde Shell-Oberfläche. Das Verweigern von write, edit, apply_patch oder HTTP-Tools für Dateisystem-Schreibvorgänge macht Shell-Ausführung nicht schreibgeschützt.
Geben Sie Gateway-Bearer-Anmeldedaten nicht an nicht vertrauenswürdige Aufrufer weiter. Wenn Sie Trennung über Vertrauensgrenzen hinweg benötigen, betreiben Sie separate Gateways (und idealerweise separate Betriebssystembenutzer/-Hosts).

Gateway-HTTP wendet standardmäßig außerdem eine harte Sperrliste an (auch wenn die Session-Richtlinie das Tool erlaubt):

exec - direkte Befehlsausführung (RCE-Oberfläche)
spawn - beliebige Erstellung von Kindprozessen (RCE-Oberfläche)
shell - Shell-Befehlsausführung (RCE-Oberfläche)
fs_write - beliebige Dateiänderung 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 - Patch-Anwendung kann beliebige Dateien umschreiben
sessions_spawn - Session-Orchestrierung; das entfernte Starten von Agenten ist RCE
sessions_send - sitzungsübergreifende Nachrichteneinspeisung
cron - persistente Automatisierungs-Steuerungsebene
gateway - Gateway-Steuerungsebene; verhindert Neukonfiguration über HTTP
nodes - Node-Befehlsweiterleitung kann system.run auf gekoppelten Hosts erreichen
whatsapp_login - interaktive Einrichtung, die einen QR-Scan im Terminal erfordert; hängt bei HTTP

Sie können diese Sperrliste über gateway.tools anpassen:

json5

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

gateway.tools.allow ist eine Expositions-Überschreibung, keine Scope-Erweiterung. In identitätstragenden HTTP-Modi bleiben cron, gateway und nodes für Aufrufer ohne Owner-/Admin-Identität (operator.admin) nicht verfügbar, selbst wenn sie in gateway.tools.allow aufgeführt sind. Shared-Secret-Bearer-Authentifizierung folgt weiterhin der oben genannten Regel für vollständig vertrauenswürdige Operatoren.

Um Gruppenrichtlinien beim Auflösen des Kontexts zu unterstützen, können Sie optional Folgendes setzen:

x-openclaw-message-channel: <channel> (Beispiel: slack, telegram)
x-openclaw-account-id: <accountId> (wenn mehrere Konten vorhanden sind)

Antworten

200 → { ok: true, result }
400 → { ok: false, error: { type, message } } (ungültige Anfrage oder Tool-Eingabefehler)
401 → nicht autorisiert
429 → Authentifizierung durch Ratenbegrenzung begrenzt (Retry-After gesetzt)
404 → Tool nicht verfügbar (nicht gefunden oder nicht auf der Allowlist)
405 → Methode nicht erlaubt
500 → { ok: false, error: { type, message } } (unerwarteter Tool-Ausführungsfehler; bereinigte Meldung)

Beispiel

bash

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

Verwandt

Was this useful?