2026 OpenClaw Praxis: CircleCI Webhook auf Remote-Mac – Lockfile-Drift & Build-Zusammenfassung

Installieren Sie Node.js 22.16+ oder 24 LTS auf dem Mac, der als Gateway dient. OpenClaw wie in der offiziellen Dokumentation beschrieben einrichten (openclaw onboard), anschließend openclaw doctor ausführen, bis Pfad, TLS und Proxy stimmen. Derselbe PATH und dieselbe node-Binary müssen für Ihre Login-Shell und für den launchd-Dienst gelten, sonst schlagen nächtliche Webhooks fehl, während manuelle Tests funktionieren.

Das Dashboard und die Verwaltungs-APIs sollten nur an 127.0.0.1 lauschen; nach außen gehen Sie mit TLS-Terminierung (nginx, Caddy) oder einem kontrollierten Tunnel. Speichern Sie das Dashboard-Token und das CircleCI-Webhook-Secret ausschließlich im Secret Store oder in einer LaunchAgent-Plist mit restriktiven Dateirechten — nicht im Git-Repository.

Minimale CircleCI-Seite: Für das Anlegen und Ändern von Outbound-Webhooks sind typischerweise Organisationsadministratorrechte nötig. Auf dem Mac selbst reicht ein technischer Benutzer, der Repository lesend klonen darf (Deploy-Key oder PAT nur mit contents:read bzw. vergleichbar schmal), sofern Ihr Lockfile-Scan keinen Schreibzugriff braucht. Jede weitergehende Berechtigung sollte bewusst begründet sein.

Schnell-Checkliste vor dem ersten Live-Webhook:

• Node-Version und openclaw im Dienstkonto verifiziert (openclaw doctor).
• Gateway lauscht auf Loopback; öffentliche URL endet auf TLS mit gültigem Zertifikat.
• Webhook-Secret generiert, nur im Secret Store, Rotation dokumentiert.
• Git-Zugriff vom Mac zum VCS getestet (Clone/Fetch als Dienstbenutzer).
• Optional: Ziel-URL für Build-Zusammenfassung (Slack-kompatibler Webhook, internes API) und Rate-Limits geklärt.

Gehen Sie in CircleCI als berechtigte Person zu Projekteinstellungen → Webhooks. Tragen Sie die öffentliche HTTPS-URL ein, die auf Ihren Reverse-Proxy oder Tunnel zeigt und intern an den OpenClaw- bzw. Node-Handler auf 127.0.0.1 weiterleitet. Setzen Sie ein starkes Secret und wählen Sie ein schmales Ereignis, z. B. workflow completed oder job completed, je nachdem, ob Sie pro Workflow oder pro Job zusammenfassen möchten.

Schrittfolge (empfohlen):

1. Health-Route hinter dem Proxy mit curl prüfen (Status 2xx, gleicher Hostname wie später CircleCI).
2. Webhook in CircleCI speichern; Testlieferung auslösen und Roh-Header in den Gateway-Logs prüfen.
3. Header circleci-signature auswerten: Eintrag v1=<hex> extrahieren (kommaseparierte Liste).
4. HMAC-SHA256 über die unveränderten POST-Bytes mit dem Webhook-Secret berechnen und zeitkonstant mit v1 vergleichen — bei Abweichung 401, kein Repo-Zugriff.
5. Nur relevante Workflows filtern (Projekt, Branch, Status success/failed nach Policy), Payload-id für Idempotenz nutzen.

Der Reverse-Proxy darf den Body nicht neu serialisieren (kein Pretty-Print, kein erzwungener UTF-8-Normalisierungsschritt vor dem Handler). Viele Signaturfehler entstehen, weil Frameworks JSON.parse vor dem HMAC ausführen und den String danach erneut schreiben.

Der synchrone Teil des Handlers sollte nur aus Signaturprüfung, Validierung der Payload, optionalem shallow git fetch/git clone in ein eindeutiges Arbeitsverzeichnis pro Webhook-ID und einem begrenzten Lockfile-Diff bestehen. Liefern Sie innerhalb von etwa zehn Sekunden ein kurzes JSON mit Status und interner Job-ID zurück (HTTP 200), damit CircleCI die Lieferung nicht endlos wiederholt.

Die ausführliche Zusammenfassung (Markdown oder Slack-Blocks: Pipeline-Nummer, Branch, Commit, betroffene Lockdateien, Diff-Zeilenanzahl, Link zum Workflow) sollten Sie asynchron per setImmediate, Worker-Queue oder OpenClaw-Hintergrundskill senden, mit Retries z. B. nach 2 / 4 / 8 Sekunden und harter Obergrenze.

Beispielhafte Struktur eines Node-Handlers (vereinfacht, zum Anpassen unter Ihrem Gateway):

Unterstützen Sie mehrere Lockfile-Typen (package-lock.json, yarn.lock, pnpm-lock.yaml, Gemfile.lock, Cargo.lock) über eine kleine Konfigurationsliste, damit Teams nicht jedes Mal den Handler fork müssen. OpenClaw-Skills können die gleiche Logik kapseln und über stabile Umgebungsvariablen (CIRCLECI_WEBHOOK_SECRET, DEFAULT_BRANCH, SUMMARY_WEBHOOK_URL) parametrisieren.

• Keine gemeinsamen Workdirs: Parallele Lieferungen überschreiben sonst package-lock.json gegenseitig.
• Revision aus der Payload: Immer den Commit bzw. SHA aus dem Webhook auschecken, nicht den lokalen Cache von gestern.
• Truncation: Lange Diffs im Summary-Kanal kürzen und vollständige Logs nur auf dem Mac ablegen.

Der Webhook-Scan ist die leichte Vorstufe: Er erkennt Lockfile-Drift früh und feedet Zusammenfassungen in Chat oder Tickets. Die schwere Arbeit — npm ci, CocoaPods, Gradle, Docker-Layer — läuft weiterhin auf CircleCI-Runnern oder auf Ihrem Remote-Mac-Build-Pool. Verknüpfen Sie beide Welten, indem Sie dieselben Spiegel- und Proxy-Regeln verwenden: Was der Webhook auf dem Gateway als „Drift erkannt“ meldet, sollte der CI-Job mit konsistenten .npmrc-, bundle- oder goproxy-Einstellungen bestätigen.

Die in der Einleitung verlinkte Übersicht zu Mirror-Ketten und Parallelität hilft, Pull-Zeiten und Timeouts in der Pipeline zu reduzieren, sodass der Webhook nicht nur warnt, sondern der nachfolgende Job zuverlässig grün wird. Das Gateway bleibt dabei die stabile Schicht für eingehende Automatisierung — unabhängig davon, ob der nächste Schritt CircleCI bleibt oder ein selbst gehosteter macOS-Runner folgt.