Tools rufen die API auf

• POST /tools/invoke
• Derselbe Port wie das Gateway (WS- und HTTP-Multiplexing): http://<gateway-host>:<port>/tools/invoke
• Standardmäßige maximale Größe des Anfragetexts: 2 MB

​

Authentifizierung

• Authentifizierung mit gemeinsamem Geheimnis (gateway.auth.mode="token" oder "password"): Authorization: Bearer <token-or-password>
• vertrauenswürdige identitätstragende HTTP-Authentifizierung (gateway.auth.mode="trusted-proxy"): Leiten Sie die Anfrage über den konfigurierten identitätsbewussten Proxy weiter und lassen Sie ihn die erforderlichen Identitätsheader einfügen
• offene Authentifizierung an einem privaten Ingress (gateway.auth.mode="none"): kein Authentifizierungsheader erforderlich

• mode="token" verwendet gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN).
• mode="password" verwendet gateway.auth.password (oder OPENCLAW_GATEWAY_PASSWORD).
• mode="trusted-proxy" setzt voraus, dass die HTTP-Anfrage von einer konfigurierten vertrauenswürdigen Proxy-Quelle stammt; Loopback-Proxys auf demselben Host erfordern ausdrücklich gateway.auth.trustedProxy.allowLoopback = true.
• Interne Aufrufer auf demselben Host, die den Proxy umgehen, können gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD als lokalen direkten Rückfallweg verwenden. Jegliche Hinweise durch die Header Forwarded, X-Forwarded-* oder X-Real-IP sorgen stattdessen dafür, dass die Anfrage auf dem Pfad für vertrauenswürdige Proxys bleibt.
• Wenn gateway.auth.rateLimit konfiguriert ist und zu viele Authentifizierungsfehler auftreten, gibt der Endpunkt 429 mit Retry-After zurück.

​

Sicherheitsgrenze (wichtig)

• Die HTTP-Bearer-Authentifizierung ist hier kein eng begrenztes benutzerspezifisches Berechtigungsmodell.
• Ein gültiges Gateway-Token/-Passwort für diesen Endpunkt sollte wie ein Zugangsmerkmal des Eigentümers/Operators behandelt werden.
• Bei Authentifizierungsmodi mit gemeinsamem Geheimnis (token und password) stellt der Endpunkt die normalen vollständigen Operator-Standardwerte wieder her, selbst wenn der Aufrufer einen enger gefassten x-openclaw-scopes-Header sendet.
• Bei der Authentifizierung mit gemeinsamem Geheimnis werden direkte Tool-Aufrufe an diesem Endpunkt außerdem als Durchläufe eines Eigentümer-Absenders behandelt.
• Vertrauenswürdige identitätstragende HTTP-Modi (Authentifizierung über einen vertrauenswürdigen Proxy oder gateway.auth.mode="none" an einem privaten Ingress) berücksichtigen x-openclaw-scopes, sofern vorhanden, und greifen andernfalls auf den normalen Satz standardmäßiger Operatorberechtigungen zurück.
• Beschränken Sie diesen Endpunkt auf Loopback, Tailnet oder einen privaten Ingress; stellen Sie ihn nicht direkt im öffentlichen Internet bereit.

​

Anfragetext

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

• tool / name (Zeichenfolge, erforderlich): Name des aufzurufenden Tools. name hat Vorrang, wenn beide gesendet werden.
• action (Zeichenfolge, optional): Wird mit args.action zusammengeführt, wenn das Tool-Schema eine action-Eigenschaft unterstützt und args noch keinen Wert dafür festgelegt hat.
• args (Objekt, optional): Tool-spezifische Argumente.
• sessionKey (Zeichenfolge, optional): Schlüssel der Zielsitzung. Wenn er weggelassen wird oder "main" lautet, verwendet das Gateway den konfigurierten Schlüssel der Hauptsitzung (berücksichtigt session.mainKey und den Standard-Agenten beziehungsweise global im globalen Sitzungsbereich).
• agentId (Zeichenfolge, optional): Löst den Sitzungsschlüssel für diesen Agenten auf. Führt zu einem 400-Fehler, wenn dies mit einem ausdrücklich angegebenen sessionKey kollidiert, der bereits einem anderen Agenten zugeordnet ist.
• idempotencyKey (Zeichenfolge, optional): Wird verwendet, um eine stabile Tool-Aufruf-ID für den Aufruf abzuleiten.
• dryRun (boolescher Wert, optional): Für die zukünftige Verwendung reserviert; wird derzeit ignoriert.

​

Richtlinien- und Routingverhalten

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

• Ausführungsgenehmigungen sind Schutzmechanismen für Operatoren und keine separate Autorisierungsgrenze für diesen HTTP-Endpunkt. Wenn ein Tool hier über Gateway-Authentifizierung und Tool-Richtlinie erreichbar ist, fügt /tools/invoke keine zusätzliche Genehmigungsabfrage pro Aufruf hinzu.
• Wenn exec hier erreichbar ist, behandeln Sie es als verändernde Shell-Oberfläche. Das Sperren von write, edit, apply_patch oder HTTP-Tools zum Schreiben in das Dateisystem macht die Shell-Ausführung nicht schreibgeschützt.
• Geben Sie Gateway-Bearer-Zugangsdaten nicht an nicht vertrauenswürdige Aufrufer weiter. Wenn Sie eine Trennung zwischen Vertrauensgrenzen benötigen, führen Sie separate Gateways aus (idealerweise unter separaten Betriebssystembenutzern oder auf separaten Hosts).

{
  gateway: {
    tools: {
      // Zusätzliche Tools, die über HTTP /tools/invoke gesperrt werden sollen
      deny: ["browser"],
      // Tools für Eigentümer-/Administratoraufrufer aus der standardmäßigen Sperrliste entfernen
      allow: ["gateway"],
    },
  },
}

• x-openclaw-message-channel: <channel> (Beispiel: slack, telegram)
• x-openclaw-account-id: <accountId> (wenn mehrere Konten vorhanden sind)
• x-openclaw-message-to: <target> (Zustellungsziel für die Richtlinie des Nachrichten-Tools)
• x-openclaw-thread-id: <threadId> (Thread-Kontext für die Richtlinie des Nachrichten-Tools)

​

Antworten

​

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

​

Verwandte Themen

• Gateway-Protokoll
• Tools und Plugins