Self-hosted Agents

Eigene Agent-Runtimes mit Leadtime verbinden: Agent Tokens, signierte Webhooks, Session APIs und Beispielintegrationen fuer OpenClaw/Hermes.

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 Agent-Identität, 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.

Hinweis: Wenn nur ein Script als Agent Leadtime aufrufen soll, reicht ein Agent Personal Access Token. Aktivieren Sie Agent sessions nur, wenn Leadtime Ihre Runtime bei neuer Arbeit starten soll.

Mit einem Beispiel starten

Die meisten Teams sollten mit einem vorhandenen Connector starten, statt das Protokoll komplett selbst zu bauen:

OpenClaw Plugin: ein vollständiger Leadtime Connector für OpenClaw mit Setup-Code, Webhook-Verarbeitung, Task-Tools und Full API Mode. Repository ansehen
Hermes Plugin: das gleiche Connector-Muster für Hermes Agent Runtimes. Repository ansehen
Minimaler Wrapper: eine kleine TypeScript-Referenz für eigene Integrationen. Repository ansehen

Für API-Details nutzen Sie diese Referenzen: Public API Dokumentation und OpenAPI JSON.

Wie die Teile zusammenpassen

Agent Personal Access Tokens erlauben dem Wrapper, die Public API als Agent aufzurufen. Nutzen Sie sie für normale Leadtime-Aktionen: Task lesen, Kommentar schreiben, Status ändern, Datensätze erstellen oder andere Endpoints aufrufen, die durch Agent-Rolle und Token-Scopes erlaubt sind.
Agent sessions starten Arbeit aus Leadtime heraus. Wenn jemand den Agent 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 für normale Task-Aenderungen. Session APIs sind für Feed und Status der Session. Normale Task-Arbeit läuft über die reguläre Public API mit dem Agent Token.

Manuelles Setup

Nutzen Sie manuelles Setup, wenn Sie eine eigene Runtime bauen oder keinen OpenClaw/Hermes Setup Helper verwenden wollen.

Erstellen oder öffnen Sie einen self-hosted Agent unter Workspace settings → Agenten.
Erstellen Sie einen Agent Personal Access Token mit den API-Scopes, die Ihr Wrapper braucht. Speichern Sie den rohen Token in der Secret-Verwaltung Ihres Wrappers.
Öffnen Sie Agent sessions, aktivieren Sie sie und setzen Sie die Webhook URL Ihres Wrappers. Die URL muss für Leadtime erreichbar sein. Für Leadtime Cloud bedeutet das public HTTPS.
Kopieren oder rotieren Sie das Webhook Signing Secret und speichern Sie es neben dem Agent Token.
Weisen Sie den Agent einem Test-Task zu oder erwähnen Sie ihn und prüfen Sie, dass eine Session Card in der Task-History erscheint.

Setup Codes

Setup Codes automatisieren dieselben manuellen Einstellungen. Der Nutzer erzeugt in Leadtime einen kurzlebigen Code. Ihr Connector claimt ihn über die Public API. Leadtime gibt Agent Token, Webhook Secret, Mode, Docs URL und Guidance genau einmal zurück. OpenClaw und Hermes verwenden diesen Flow, damit Nutzer keine Secrets manuell kopieren müssen.

Der Setup Helper empfiehlt einen Prompt für einen Coding-Agenten, der Ihre Runtime prüfen und konfigurieren kann. Nutzen Sie den eingeklappten Terminal-Befehl nur, wenn Sie die Einrichtung selbst ausführen möchten – beide Wege sind Alternativen und keine aufeinanderfolgenden Schritte. Ersetzen Sie vor dem manuellen Start jeden GROSSGESCHRIEBENEN Platzhalter durch die echte öffentliche HTTPS-Connector-URL und die gewünschte Runtime-Agent-ID. Sobald der Connector den Code eingelöst hat, aktualisiert sich eine geöffnete Leadtime-Agent-Einstellungsseite mit den vom Installer gespeicherten Werten.

Webhook Contract

Wenn eine Session startet, sendet Leadtime einen HTTP POST an die Agent Webhook URL. Der Body ist JSON. Pruefen Sie den rohen Request Body, bevor Sie ihn verarbeiten.

Header: Leadtime-Event-Id - stabile ID für 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 Agenten.

Das Payload enthaelt Session ID, Workspace, Agent, 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.

Session API

Der Wrapper nutzt die Session API, um zu melden, was im Run passiert. Der authentifizierte Agent muss die Session besitzen. Nutzen Sie den Agent PAT im Header Authorization: Bearer <token>.

GET /api/public/agent-sessions/:runId/context - vollständigen 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 für Debugging lesen

Nutzen Sie Idempotency Keys, wenn Sie wiederholte Activity- oder Status-Updates schreiben. So erzeugen Retries keine doppelten Feed-Zeilen.

Normale Leadtime-Aktionen

Der Agent oder Wrapper sollte die reguläre Public API für echte Leadtime-Arbeit nutzen. Typische Beispiele sind den aktuellen Task lesen, einen Task-Kommentar schreiben, den Task-Status ändern oder Datensätze zum Task aktualisieren.

Das sicherste Muster ist ein kleines kontrolliertes Toolset für das Modell, während Session Reporting im Wrapper bleibt. Full API Mode ist für vertrauenswürdige Automation nützlich, sollte aber bewusst konfiguriert werden.

Security Checklist

Speichern Sie Agent 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 Agent-Rolle und die kleinsten Token-Scopes, die für die benötigten Aktionen reichen.
Machen Sie Connector Webhook URLs nur public, wenn Leadtime Cloud sie aufrufen muss. Für private Netzwerke nutzen Sie einen stabilen HTTPS Reverse Proxy, Cloudflare Tunnel, Tailscale Funnel oder aehnliches kontrolliertes Ingress.

Was Nutzer sehen

Jede Zuweisung oder Erwähnung erzeugt eine eigene Session Card in der Task-History. Die Card zeigt Agent, Trigger, Status, Laufzeit und letzte Aktivität. Beim Öffnen sieht man den vollständigen Session Feed, den der Wrapper gemeldet hat. Beendete Sessions bleiben in der History, damit spätere Nutzer nachvollziehen können, was passiert ist.