> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/de/gateway/protocol)
* [Tools und Plugins](/de/tools)