OpenClaw App SDK verstehen

Die meisten Einsteiger landen irgendwann an derselben Weggabelung. Sie wollen etwas Neues mit OpenClaw verbinden, und plötzlich klingt alles ähnlich: App SDK, Plugin SDK, MCP, CLI, rohe Gateway-Calls. Genau dort gehen gern unnötige Wochenenden verloren.

Die Kurzfassung ist simpel. Nutze das OpenClaw App SDK, wenn dein Code außerhalb von OpenClaw läuft und einen sauberen, typisierten Weg zum Gateway braucht. Denk an Dashboards, CI-Jobs, IDE-Helfer, Review-Bots und interne Tools. Wenn dein Code in OpenClaw selbst leben und neue native Fähigkeiten registrieren soll, bist du im Plugin SDK richtig.

Wofür das App SDK wirklich da ist

Die offizielle OpenClaw App SDK Doku beschreibt @openclaw/sdk als öffentliche Client-API für Apps außerhalb des OpenClaw-Prozesses. Es ist für Software gedacht, die sich mit dem Gateway verbindet, Runs startet, Events streamt, auf Ergebnisse wartet, Arbeit abbricht, Ressourcen prüft und Freigaben behandelt, ohne so zu tun, als wäre sie ein Plugin.

Ein hilfreiches Bild: Das App SDK ist eine Fernbedienung, kein Schraubendreher. Du bedienst das System von außen. Du schraubst den Kasten nicht auf und legst keine neuen Leitungen hinein.

App SDK vs. Plugin SDK

Das Plugin SDK Overview macht die Trennung ausdrücklich klar: Plugin-Subpaths sind für In-Process-Erweiterungen, externe Apps sollen das App SDK nutzen. Genau das ist gesund. So übernimmst du als App-Builder nicht versehentlich Runtime-Interna, die du nie besitzen wolltest.

Was heute schon da ist

Das ist der Teil, der für echte Entscheidungen zählt. Das App SDK ist kein leeres Platzhalter-Paket. Die offizielle Doku listet bereits eine solide nutzbare Fläche.

• Client-Verbindung: OpenClaw plus Gateway-Transport
• Agent-Runs: Runs starten, darauf warten, sie abbrechen und Events streamen
• Sessions: dauerhafte Gespräche anlegen, auflösen, senden, patchen und kompaktieren
• Tools: effektive Tools auflisten und über Policy-Gates aufrufen
• Tasks und Artefakte: Hintergrundarbeit einsehen und Outputs herunterladen
• Freigaben: Exec-Freigaben auflisten und beantworten
• Modelle: Modell-Inventar und Auth-Status prüfen
• Environment-Helfer: teilweise vorhanden, aber noch nicht die fertige Geschichte

Anders gesagt: Das nützliche Mittelstück des Produkts ist schon da. Du kannst heute echte Bedienoberflächen bauen, ohne gleich in rohe WebSocket-Klempnerei abzurutschen.

Wie eine einfache externe App aussieht

Eine minimale App macht meist vier Dinge: verbinden, Agent oder Session holen, Arbeit starten und das Ergebnis streamen oder abwarten. Erfreulich langweilig. Genau so sollte Integrationscode sein.

import { OpenClaw } from "@openclaw/sdk";

const oc = new OpenClaw({
  url: "ws://127.0.0.1:18789",
  token: process.env.OPENCLAW_GATEWAY_TOKEN,
  requestTimeoutMs: 30_000,
});

await oc.connect();

const agent = await oc.agents.get("main");
const run = await agent.run({
  input: "Prüfe diesen Deploy-Plan und markiere den riskanten Schritt.",
  sessionKey: "main",
  timeoutMs: 30_000,
});

for await (const event of run.events()) {
  if (event.type === "assistant.delta") {
    const data = event.data as { delta?: unknown };
    if (typeof data.delta === "string") process.stdout.write(data.delta);
  }
}

const result = await run.wait({ timeoutMs: 120_000 });
console.log(result.status);

Das reicht schon für erstaunlich viele Werkzeuge. Wenn du Runs starten, Sessions wiederverwenden und auf normalisierte Events reagieren kannst, baust du mehr als nur ein Spielzeug.

Gute echte App-Ideen

Genau hier wird das App SDK greifbar. Du brauchst keine große Plattform-Strategie. Du brauchst eine nützliche äußere Oberfläche.

• Review-Dashboard: Runs gegen ausgewählte Sessions starten und Artefakte plus Freigabestatus in einer UI anzeigen.
• CI Release Assistant: Release-Diffs an einen Agenten senden, auf das Ergebnis warten und die Pipeline stoppen, wenn eine Pflicht-Checkliste fehlt.
• IDE-Seitenleiste: Entwicklern erlauben, fokussierte Prompts in eine benannte Session zu schicken, statt alles in Wegwerf-Chats zu verlieren.
• Ops-Konsole: laufende Tasks prüfen, hängende Freigaben sehen und Arbeit abbrechen, ohne dich auf dem Host einzuloggen.
• Internes Anfrageformular: strukturierte Business-Eingaben von Kollegen sammeln und an eine dauerhafte Session übergeben.

Das Muster ist klar. Diese Apps ersetzen OpenClaw nicht. Sie bauen für eine bestimmte Nutzergruppe nur einen schmaleren, saubereren Eingang hinein.

Warum das Event-Modell wichtiger ist, als viele denken

Viele selbstgebaute Integrationen enden bei Anfrage rein, Text raus. Das hält, bis du Fortschritt, Freigaben, Abbruch oder Artefakte brauchst. Dann läuft alles plötzlich mit verbundenen Augen.

Das App SDK fängt genau das mit normalisierten Events ab, etwa Run-Start, Assistant-Deltas, Tool-Updates, Freigabeanfragen und Task-Änderungen. Das ist wichtig, weil externe Apps meist nicht an der Verbindung scheitern, sondern an mangelnder Sichtbarkeit. Ein Dashboard, das erklären kann, was der Agent gerade tut, ist deutlich mehr wert als eins, das nach zwei Minuten Schweigen nur einen Absatz ausspuckt.

Wann das App SDK besser ist als rohe Gateway-Calls

Könntest du direkt mit dem Gateway sprechen? Klar. Aber das ist wie rohes SQL für jede winzige Listenansicht zu wählen. Manchmal richtig. Oft einfach selbst verursachte Reibung.

• Nutze das App SDK, wenn du typisierte Objekte, stabile Flows, normalisierte Events und weniger Klebecode willst.
• Nutze rohe Gateway-Calls, wenn du Protokolldetails debuggen musst oder etwas baust, das der High-Level-Wrapper noch nicht sauber anbietet.
• Nutze das Plugin SDK, wenn du neue Runtime-Fähigkeiten registrieren willst, statt bestehende Fähigkeiten zu konsumieren.

Wo Menschen das falsche Werkzeug wählen

Sie greifen zu früh zum Plugin

Wenn dein eigentliches Ziel lautet „Ich will eine Web-App, die Runs starten und Status anzeigen kann“, ist ein Plugin oft zu viel. Du musst nicht in den Maschinenraum ziehen, nur um den Startknopf zu drücken.

Sie bauen einen Haufen Scripts ohne Session-Modell

Die Doku macht Sessions aus gutem Grund erstklassig. Wenn deine externe App Kontinuität braucht, nutze Sessions statt jeden Call als Wegwerf-Einzelschuss zu behandeln. Sonst baust du im Grunde eine hübsch verkleidete Amnesie.

Sie ignorieren Freigaben und Artefakte

Coding- und Ops-Flows überschreiten regelmäßig Sicherheitsgrenzen. Das App SDK hat bereits Flächen für Freigaben und Artefakte. So zu tun, als gäbe es sie nicht, bedeutet nur, dass du später schlechtere Versionen davon nachbaust.

Praktische Entscheidungsregel

Stell dir eine direkte Frage: Muss dieser Code OpenClaw erweitern oder OpenClaw steuern?

• Erweitern → Plugin SDK
• Steuern → App SDK

Diese einfache Trennung spart erstaunlich viel Architektur-Theater.