Webhooks

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

Aktivieren

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

Hinweise:

  • hooks.token ist erforderlich, wenn hooks.enabled=true gesetzt ist.
  • hooks.path hat standardmäßig den Wert /hooks.

Authentifizierung

Jede Anfrage muss das Hook-Token enthalten. Bevorzuge Header:

  • Authorization: Bearer <token> (empfohlen)
  • x-openclaw-token: <token>
  • ?token=<token> (veraltet; gibt eine Warnung aus und wird in einem zukünftigen Major-Release entfernt)

Endpunkte

POST /hooks/wake

Payload:

{ "text": "System line", "mode": "now" }
  • text erforderlich (string): Die Beschreibung des Events (z. B. “New email received”).
  • mode optional (now | next-heartbeat): Ob ein sofortiger Heartbeat ausgelöst werden soll (Standard: now) oder auf den nächsten periodischen Check gewartet wird.

Effekt:

  • Reiht ein System-Event für die main Session ein
  • Bei mode=now wird ein sofortiger Heartbeat ausgelöst

POST /hooks/agent

Payload:

{
  "message": "Run this",
  "name": "Email",
  "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”), wird als Präfix in Session-Zusammenfassungen verwendet.
  • sessionKey optional (string): Der Schlüssel zur Identifikation der Agent-Session. Standard ist ein zufälliger hook:<uuid>. Mit einem konsistenten Schlüssel kannst du eine mehrstufige Konversation im Hook-Kontext führen.
  • wakeMode optional (now | next-heartbeat): Ob ein sofortiger Heartbeat ausgelöst werden soll (Standard: now) oder auf den nächsten periodischen Check gewartet wird.
  • deliver optional (boolean): Bei true wird die Antwort des Agents 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. Einer von: last, whatsapp, telegram, discord, slack, mattermost (Plugin), signal, imessage, msteams. 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 (Plugin), Conversation-ID für MS Teams). Standard ist der letzte Empfänger in der main Session.
  • model optional (string): Modell-Override (z. B. anthropic/claude-3-5-sonnet oder ein Alias). Muss in der erlaubten Modellliste enthalten sein, falls eingeschränkt.
  • thinking optional (string): Thinking-Level-Override (z. B. low, medium, high).
  • timeoutSeconds optional (number): Maximale Dauer für den Agent-Lauf in Sekunden.

Effekt:

  • Führt einen isolierten Agent-Turn aus (eigener Session-Key)
  • Postet immer eine Zusammenfassung in die main Session
  • Bei wakeMode=now wird ein sofortiger Heartbeat ausgelöst

POST /hooks/<name> (gemappt)

Benutzerdefinierte Hook-Namen werden über hooks.mappings aufgelöst (siehe Konfiguration). Ein Mapping kann beliebige Payloads in wake- oder agent-Aktionen umwandeln, mit optionalen Templates oder Code-Transformationen.

Mapping-Optionen (Zusammenfassung):

  • hooks.presets: ["gmail"] aktiviert das eingebaute Gmail-Mapping.
  • hooks.mappings ermöglicht dir, match, action und Templates in der Config zu definieren.
  • hooks.transformsDir + transform.module lädt ein JS/TS-Modul für benutzerdefinierte Logik.
  • Nutze match.source, um einen generischen Ingest-Endpunkt zu behalten (Payload-gesteuertes Routing).
  • TS-Transformationen benötigen einen TS-Loader (z. B. bun oder tsx) oder vorkompiliertes .js zur Laufzeit.
  • Setze deliver: true + channel/to in Mappings, um Antworten an eine Chat-Oberfläche zu routen (channel hat standardmäßig den Wert last und fällt auf WhatsApp zurück).
  • allowUnsafeExternalContent: true deaktiviert den External-Content-Safety-Wrapper für diesen Hook (gefährlich; nur für vertrauenswürdige interne Quellen).
  • openclaw webhooks gmail setup schreibt die hooks.gmail-Config für openclaw webhooks gmail run. Siehe Gmail Pub/Sub für den vollständigen Gmail-Watch-Flow.

Antworten

  • 200 für /hooks/wake
  • 202 für /hooks/agent (asynchroner Lauf gestartet)
  • 401 bei Authentifizierungsfehler
  • 400 bei ungültiger 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 verwenden

Füge model zur Agent-Payload (oder zum Mapping) hinzu, um das Modell für diesen Lauf 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 Override-Modell dort enthalten 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

  • Halte Hook-Endpunkte hinter Loopback, Tailnet oder einem vertrauenswürdigen Reverse Proxy.
  • Verwende ein dediziertes Hook-Token; nutze keine Gateway-Auth-Tokens wieder.
  • Vermeide es, sensible Raw-Payloads in Webhook-Logs aufzunehmen.
  • Hook-Payloads werden standardmäßig als nicht vertrauenswürdig behandelt und mit Sicherheitsgrenzen umschlossen. Falls du dies für einen bestimmten Hook deaktivieren musst, setze allowUnsafeExternalContent: true im Mapping dieses Hooks (gefährlich).