Self-hosted Agents verbinden eine eigene Runtime mit Leadtime. Das kann ein OpenClaw Gateway, Hermes, ein Wrapper um Claude Code, ein eigener Worker oder jeder Prozess sein, der HTTPS-Webhooks empfangen und die Leadtime Public API aufrufen kann.
Leadtime verwaltet Bot-Identitaet, Task-Trigger, Session-Datensatz, signierten Webhook und die Task-History UI. Ihr Wrapper verwaltet die Runtime: Er empfaengt den Webhook, startet den Agent, meldet Fortschritt und entscheidet, welche Tools oder API-Aufrufe das Modell nutzen darf.
Die meisten Teams sollten mit einem vorhandenen Connector starten, statt das Protokoll komplett selbst zu bauen:
OpenClaw Plugin: ein vollstaendiger Leadtime Connector fuer OpenClaw mit Setup-Code, Webhook-Verarbeitung, Task-Tools und Full API Mode. Repository ansehen
Hermes Plugin: das gleiche Connector-Muster fuer Hermes Agent Runtimes. Repository ansehen
Minimaler Wrapper: eine kleine TypeScript-Referenz fuer eigene Integrationen. Repository ansehen
Fuer API-Details nutzen Sie diese Referenzen: Public API Dokumentation und OpenAPI JSON.
Bot Personal Access Tokens erlauben dem Wrapper, die Public API als Bot aufzurufen. Nutzen Sie sie fuer normale Leadtime-Aktionen: Task lesen, Kommentar schreiben, Status aendern, Datensaetze erstellen oder andere Endpoints aufrufen, die durch Bot-Rolle und Token-Scopes erlaubt sind.
Agent sessions starten Arbeit aus Leadtime heraus. Wenn jemand den Bot auf einem Task zuweist oder erwaehnt, erstellt Leadtime eine Session, zeigt sie in der Task-History und sendet einen signierten Webhook an Ihren Wrapper.
Der Wrapper prueft den Webhook, dedupliziert Retries, startet die Runtime, schreibt Session-Aktivitaeten, aktualisiert den Session-Status und haelt rohe Zugangsdaten von untrusted Model-Logik fern, ausser Sie entscheiden sich bewusst dafuer.
Nutzen Sie Session APIs nicht fuer normale Task-Aenderungen. Session APIs sind fuer Feed und Status der Session. Normale Task-Arbeit laeuft ueber die regulaere Public API mit dem Bot Token.
Nutzen Sie manuelles Setup, wenn Sie eine eigene Runtime bauen oder keinen OpenClaw/Hermes Setup Helper verwenden wollen.
Erstellen oder oeffnen Sie einen self-hosted Bot unter Workspace settings -> Bots.
Erstellen Sie einen Bot Personal Access Token mit den API-Scopes, die Ihr Wrapper braucht. Speichern Sie den rohen Token in der Secret-Verwaltung Ihres Wrappers.
Oeffnen Sie Agent sessions, aktivieren Sie sie und setzen Sie die Webhook URL Ihres Wrappers. Die URL muss fuer Leadtime erreichbar sein. Fuer Leadtime Cloud bedeutet das public HTTPS.
Kopieren oder rotieren Sie das Webhook Signing Secret und speichern Sie es neben dem Bot Token.
Weisen Sie den Bot einem Test-Task zu oder erwaehnen Sie ihn und pruefen Sie, dass eine Session Card in der Task-History erscheint.
Setup Codes automatisieren dieselben manuellen Einstellungen. Der Nutzer erzeugt in Leadtime einen kurzlebigen Code. Ihr Connector claimt ihn ueber die Public API. Leadtime gibt Bot Token, Webhook Secret, Mode, Docs URL und Guidance genau einmal zurueck. OpenClaw und Hermes verwenden diesen Flow, damit Nutzer keine Secrets manuell kopieren muessen.
Wenn eine Session startet, sendet Leadtime einen HTTP POST an die Bot Webhook URL. Der Body ist JSON. Pruefen Sie den rohen Request Body, bevor Sie ihn verarbeiten.
Header: Leadtime-Event-Id - stabile ID fuer Deduplizierung.
Header: Leadtime-Event-Type - aktuell meistens session.created.
Header: Leadtime-Timestamp - Zeitpunkt der Webhook-Erstellung. Lehnen Sie alte Timestamps ab, um Replay-Risiken zu reduzieren.
Header: Leadtime-Signature - HMAC-SHA256 Signatur des rohen Bodys mit dem Webhook Signing Secret des Bots.
Das Payload enthaelt Session ID, Workspace, Bot, Trigger Source, Task Context, Guidance, API Base URL, Docs URL und Session API Pfade. Behandeln Sie agentRunId als kanonische Session ID.
Bei Task Mentions ist der ausloesende Kommentar die aktuelle Anfrage. Aeltere Task-Kommentare, Beschreibung und fruehere Sessions sind nur Kontext.
Der Wrapper nutzt die Session API, um zu melden, was im Run passiert. Der authentifizierte Bot muss die Session besitzen. Nutzen Sie den Bot PAT im Header Authorization: Bearer <token>.
GET /api/public/agent-sessions/:runId/context - vollstaendigen Session Context lesen
POST /api/public/agent-sessions/:runId/activities - Fortschritt, Tool Events, Logs, finale Antwort oder Fehler schreiben
PATCH /api/public/agent-sessions/:runId/status - Status auf running, done, failed oder canceled setzen
GET /api/public/tasks/:identifier/agent-sessions - Sessions eines Tasks auflisten
GET /api/public/agent-sessions/:runId/activities - Session Feed fuer Debugging lesen
Nutzen Sie Idempotency Keys, wenn Sie wiederholte Activity- oder Status-Updates schreiben. So erzeugen Retries keine doppelten Feed-Zeilen.
Der Agent oder Wrapper sollte die regulaere Public API fuer echte Leadtime-Arbeit nutzen. Typische Beispiele sind den aktuellen Task lesen, einen Task-Kommentar schreiben, den Task-Status aendern oder Datensaetze zum Task aktualisieren.
Das sicherste Muster ist ein kleines kontrolliertes Toolset fuer das Modell, waehrend Session Reporting im Wrapper bleibt. Full API Mode ist fuer vertrauenswuerdige Automation nuetzlich, sollte aber bewusst konfiguriert werden.
Speichern Sie Bot PAT und Webhook Signing Secret serverseitig. Schreiben Sie sie nicht in Task-Kommentare oder model-sichtbare Prompts, ausser Sie vertrauen dieser Runtime bewusst.
Pruefen Sie Webhook Signaturen gegen den rohen Body, bevor Arbeit startet.
Deduplizieren Sie anhand von Leadtime-Event-Id, bevor Sie einen Run starten.
Nutzen Sie die engste Bot-Rolle und die kleinsten Token-Scopes, die fuer die benoetigten Aktionen reichen.
Machen Sie Connector Webhook URLs nur public, wenn Leadtime Cloud sie aufrufen muss. Fuer private Netzwerke nutzen Sie einen stabilen HTTPS Reverse Proxy, Cloudflare Tunnel, Tailscale Funnel oder aehnliches kontrolliertes Ingress.
Jede Zuweisung oder Erwaehnung erzeugt eine eigene Session Card in der Task-History. Die Card zeigt Bot, Trigger, Status, Laufzeit und letzte Aktivitaet. Beim Oeffnen sieht man den vollstaendigen Session Feed, den der Wrapper gemeldet hat. Beendete Sessions bleiben in der History, damit spaetere Nutzer nachvollziehen koennen, was passiert ist.
