API zum Aufrufen von Tools

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

​

Authentifizierung

• 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

• 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)

• 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.

• 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

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

• 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

• 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)

• 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).

• 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

{
  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"],
    },
  },
}

• 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

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

• Gateway-Protokoll
• Tools und Plugins