OpenClaw Webhooks einrichten: HTTP-Trigger in 5 Minuten

Kennst du das? Du hast einen externen Service oder ein Skript, das ein Ereignis registriert, aber dein Agent bekommt davon nichts mit. Ständiges Polling ist ineffizient und verbraucht unnötig Ressourcen. Webhooks lösen dieses Problem, indem sie dein Gateway für externe Trigger öffnen und so eine sofortige Reaktion ermöglichen.

Webhooks

Gateway kann einen kleinen HTTP-Webhook-Endpunkt für externe Trigger bereitstellen.

Aktivieren

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    // Optional: restrict explicit `agentId` routing to this allowlist.
    // Omit or include "*" to allow any agent.
    // Set [] to deny all explicit `agentId` routing.
    allowedAgentIds: ["hooks", "main"],
  },
}

Hinweise:

hooks.token ist erforderlich, wenn hooks.enabled=true gesetzt ist.
hooks.path hat den Standardwert /hooks.

Authentifizierung

Jeder Request muss den Hook-Token enthalten. Nutze am besten Header:

Authorization: Bearer <token> (empfohlen)
x-openclaw-token: <token>
Token in der Query-String werden abgelehnt (?token=... gibt einen 400 Fehler zurück).
Behandle Inhaber von hooks.token als vertrauenswürdige Aufrufer für die Hook-Ingress-Oberfläche dieses Gateways. Der Inhalt des Hook-Payloads gilt weiterhin als nicht vertrauenswürdig, aber dies ist keine separate Authentifizierungsgrenze für Nicht-Besitzer.

Endpunkte

`POST /hooks/wake`

Payload:

{ "text": "System line", "mode": "now" }

text erforderlich (String): Die Beschreibung des Ereignisses (z. B. “Neue E-Mail empfangen”).
mode optional (now | next-heartbeat): Legt fest, ob sofort ein Heartbeat ausgelöst wird (Standard now) oder ob bis zum nächsten periodischen Check gewartet wird.

Effekt:

Reiht ein System-Ereignis für die Main-Session ein.
Löst einen sofortigen Heartbeat aus, falls mode=now konfiguriert ist.

`POST /hooks/agent`

Payload:

{
  "message": "Run this",
  "name": "Email",
  "agentId": "hooks",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}

message erforderlich (String): Der Prompt oder die Nachricht, die der Agent verarbeiten soll.
name optional (String): Lesbarer Name für den Hook (z. B. “GitHub”), der als Präfix in Session-Zusammenfassungen erscheint.
agentId optional (String): Routet diesen Hook an einen spezifischen Agenten. Unbekannte IDs nutzen den Standard-Agenten. Wenn gesetzt, läuft der Hook im Workspace und mit der Konfiguration des jeweiligen Agenten.
sessionKey optional (String): Der Key zur Identifizierung der Agent-Session. Dieses Feld wird standardmäßig abgelehnt, außer hooks.allowRequestSessionKey=true ist aktiv.
wakeMode optional (now | next-heartbeat): Bestimmt, ob sofort ein Heartbeat ausgelöst wird (Standard now) oder erst beim nächsten Check.
deliver optional (Boolean): Bei true wird die Antwort des Agenten an den Messaging-Channel gesendet. Standard ist true. Antworten, die nur Heartbeat-Bestätigungen sind, werden automatisch übersprungen.
channel optional (String): Der Messaging-Channel für die Zustellung. Nutze last oder eine konfigurierte Channel- oder Plugin-ID wie discord, matrix, telegram oder whatsapp. Standard ist last.
to optional (String): Die Empfänger-ID für den Channel (z. B. Telefonnummer für WhatsApp/Signal, Chat-ID für Telegram, Channel-ID für Discord/Slack/Mattermost, Conversation-ID für Microsoft Teams). Standardmäßig wird der letzte Empfänger der Main-Session genutzt.
model optional (String): Überschreibt das Modell (z. B. anthropic/claude-sonnet-4-6 oder ein Alias). Muss bei Einschränkungen in der Liste der erlaubten Modelle stehen.
thinking optional (String): Überschreibt das Thinking-Level (z. B. low, medium, high).
timeoutSeconds optional (Number): Maximale Dauer für den Agent-Run in Sekunden.

Effekt:

Führt einen isolierten Agent-Turn aus (eigener Session-Key) und postet immer eine Zusammenfassung in die Main-Session.
Löst einen sofortigen Heartbeat aus, wenn wakeMode=now gesetzt ist.

Session-Key-Richtlinie (Breaking Change)

Überschreibungen des sessionKey im /hooks/agent Payload sind standardmäßig deaktiviert.

Empfehlung: Setze einen festen hooks.defaultSessionKey und erlaube keine Überschreibungen per Request.
Optional: Erlaube Überschreibungen nur bei Bedarf und schränke die Präfixe ein.

Empfohlene Konfiguration:

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
  },
}

Kompatibilitäts-Konfiguration (Legacy-Verhalten):

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:"], // strongly recommended
  },
}

`POST /hooks/<name>` (Mapped)

Eigene Hook-Namen werden über hooks.mappings aufgelöst. Ein Mapping kann beliebige Payloads in wake oder agent Aktionen umwandeln, optional mit Templates oder Code-Transformationen.

Mapping-Optionen (Zusammenfassung):

hooks.presets: ["gmail"] aktiviert das integrierte Gmail-Mapping.
hooks.mappings erlaubt die Definition von match, action und Templates in der Config.
hooks.transformsDir + transform.module lädt ein JS/TS-Modul für eigene Logik.
hooks.transformsDir muss (falls gesetzt) innerhalb des Transforms-Ordners unter deinem OpenClaw-Konfigurationsverzeichnis liegen (meist ~/.openclaw/hooks/transforms).
transform.module muss innerhalb des effektiven Transforms-Verzeichnisses aufgelöst werden (Traversal-Pfade werden abgelehnt).
Nutze match.source für einen generischen Ingest-Endpunkt (Payload-basiertes Routing).
TS-Transforms benötigen einen TS-Loader (z. B. bun oder tsx) oder vorkompilierte .js-Dateien zur Laufzeit.
Setze deliver: true + channel/to in Mappings, um Antworten an eine Chat-Oberfläche zu routen (channel nutzt standardmäßig last mit Fallback auf WhatsApp).
agentId routet den Hook an einen spezifischen Agenten; unbekannte IDs fallen auf den Standard-Agenten zurück.
hooks.allowedAgentIds schränkt das explizite agentId Routing ein. Lass es weg (oder nutze *), um jeden Agenten zu erlauben. Nutze [], um explizites Routing zu verbieten.
hooks.defaultSessionKey legt die Standard-Session für Hook-Agent-Runs fest, wenn kein Key angegeben wurde.
hooks.allowRequestSessionKey steuert, ob /hooks/agent Payloads den sessionKey setzen dürfen (Standard: false).
hooks.allowedSessionKeyPrefixes schränkt optional explizite sessionKey-Werte aus Requests und Mappings ein.
allowUnsafeExternalContent: true deaktiviert den Sicherheits-Wrapper für externen Content bei diesem Hook (gefährlich; nur für vertrauenswürdige interne Quellen).
openclaw webhooks gmail setup schreibt die hooks.gmail Konfiguration für openclaw webhooks gmail run. Details findest du unter Gmail Pub/Sub.

Antworten

200 für /hooks/wake
200 für /hooks/agent (Async-Run akzeptiert)
401 bei Authentifizierungsfehlern
429 nach wiederholten Fehlversuchen vom selben Client (prüfe Retry-After)
400 bei ungültigem Payload
413 bei zu großen Payloads

Beispiele

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

Ein anderes Modell nutzen

Füge model zum Agent-Payload (oder Mapping) hinzu, um das Modell für diesen Run zu überschreiben:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'

Falls du agents.defaults.models erzwingst, stelle sicher, dass das Modell dort gelistet ist.

curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'

Sicherheit

Betreibe Hook-Endpunkte hinter Loopback, Tailnet oder einem vertrauenswürdigen Reverse Proxy.
Nutze einen dedizierten Hook-Token; verwende keine Gateway-Auth-Token wieder.
Ich empfehle einen dedizierten Hook-Agenten mit striktem tools.profile und Sandboxing, um den Radius bei Problemen klein zu halten.
Wiederholte Authentifizierungsfehler werden pro Client-Adresse limitiert, um Brute-Force-Angriffe zu bremsen.
Nutze hooks.allowedAgentIds bei Multi-Agent-Routing, um die Auswahl der agentId zu begrenzen.
Belasse hooks.allowRequestSessionKey=false, außer du benötigst vom Aufrufer gewählte Sessions.
Falls du sessionKey in Requests erlaubst, schränke dies über hooks.allowedSessionKeyPrefixes ein (z. B. ["hook:"]).
Vermeide es, sensible Rohdaten in Webhook-Logs zu schreiben.
Hook-Payloads werden als nicht vertrauenswürdig behandelt und standardmäßig durch Sicherheitsgrenzen isoliert.
Deaktiviere dies nur im Ausnahmefall für spezifische Hooks mit allowUnsafeExternalContent: true im Mapping (gefährlich).

AI Setup Assistant

Nächste Schritte

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.