API-Design des OpenClaw App SDK

Diese Seite ist der detaillierte API-Referenzentwurf für das öffentliche OpenClaw App SDK. Sie ist absichtlich getrennt vom Plugin SDK.

Das öffentliche App SDK sollte in zwei Schichten aufgebaut sein:

1. Ein Low-Level-generierter Gateway-Client.
2. Ein ergonomischer High-Level-Wrapper mit OpenClaw-, Agent-, Session-, Run-, Task-, Artifact-, Approval- und Environment-Objekten.

Namespace-Design

Die Low-Level-Namespaces sollten Gateway-Ressourcen eng folgen:

oc.agents.list();oc.agents.get("main");oc.agents.create(...);oc.agents.update(...); oc.sessions.list();oc.sessions.create(...);oc.sessions.resolve(...);oc.sessions.send(...);oc.sessions.messages(...);oc.sessions.fork(...);oc.sessions.compact(...);oc.sessions.abort(...); oc.runs.create(...);oc.runs.get(runId);oc.runs.events(runId, { after });oc.runs.wait(runId);oc.runs.cancel(runId); oc.tasks.list({ status: "running" });oc.tasks.get(taskId);oc.tasks.cancel(taskId, { reason });oc.tasks.events(taskId, { after }); // future API oc.models.list();oc.models.status(); // Gateway models.authStatus oc.tools.list();oc.tools.invoke("tool-name", { sessionKey, idempotencyKey }); oc.artifacts.list({ runId });oc.artifacts.get(artifactId, { runId });oc.artifacts.download(artifactId, { runId }); oc.approvals.list();oc.approvals.respond(approvalId, ...); oc.environments.list();oc.environments.create(...); // future API: current SDK throws unsupportedoc.environments.status(environmentId);oc.environments.delete(environmentId); // future API: current SDK throws unsupported

High-Level-Wrapper sollten Objekte zurückgeben, die häufige Abläufe angenehm machen:

const run = await agent.run(inputOrParams);await run.cancel();await run.wait(); for await (const event of run.events()) {  // normalized event stream} const artifacts = await run.artifacts.list();const session = await run.session();

Event-Vertrag

Das öffentliche SDK sollte versionierte, replayfähige, normalisierte Events bereitstellen.

type OpenClawEvent = {  version: 1;  id: string;  ts: number;  type: OpenClawEventType;  runId?: string;  sessionId?: string;  sessionKey?: string;  taskId?: string;  agentId?: string;  data: unknown;  raw?: unknown;};

id ist ein Replay-Cursor. Consumer sollten sich mit events({ after: id }) erneut verbinden und verpasste Events empfangen können, sofern die Aufbewahrung dies erlaubt.

Empfohlene normalisierte Event-Familien:

Runtime-native Payloads sollten über raw verfügbar sein, aber Apps sollten raw für normale Benutzeroberflächen nicht parsen müssen.

Ergebnisvertrag

Run.wait() sollte eine stabile Ergebnis-Hülle zurückgeben:

type RunResult = {  runId: string;  status: "accepted" | "completed" | "failed" | "cancelled" | "timed_out";  sessionId?: string;  sessionKey?: string;  taskId?: string;  startedAt?: string | number;  endedAt?: string | number;  output?: {    text?: string;    messages?: SDKMessage[];  };  usage?: {    inputTokens?: number;    outputTokens?: number;    totalTokens?: number;    costUsd?: number;  };  artifacts?: ArtifactSummary[];  error?: SDKError;};

Das Ergebnis sollte schlicht und stabil sein. Zeitstempelwerte bewahren die Gateway- Form, sodass aktuelle lifecycle-gestützte Runs normalerweise Epochen-Millisekunden melden, während Adapter weiterhin ISO-Strings ausgeben können. Umfangreiche Benutzeroberflächen, Tool-Traces und runtime-native Details gehören in Events und Artefakte.

accepted ist ein nicht-terminales Warteergebnis: Es bedeutet, dass die Gateway-Wartefrist abgelaufen ist, bevor der Run ein Lifecycle-Ende oder einen Fehler erzeugt hat. Es darf nicht als timed_out behandelt werden; timed_out ist für einen Run reserviert, der sein eigenes Runtime- Timeout überschritten hat.

Genehmigungen und Fragen

Genehmigungen müssen erstklassig sein, weil Coding-Agents ständig Sicherheitsgrenzen überschreiten.

run.onApproval(async (request) => {  if (request.kind === "tool" && request.toolName === "exec") {    return request.approveOnce({ reason: "CI command allowed by policy" });  }   return request.askUser();});

Genehmigungs-Events sollten Folgendes enthalten:

• Genehmigungs-ID
• Run-ID und Sitzungs-ID
• Anfragetyp
• Zusammenfassung der angeforderten Aktion
• Tool-Name oder Umgebungsaktion
• Risikostufe
• verfügbare Entscheidungen
• Ablaufzeit
• ob die Entscheidung wiederverwendet werden kann

Fragen sind von Genehmigungen getrennt. Eine Frage bittet den Benutzer oder die Host-App um Informationen. Eine Genehmigung bittet um Erlaubnis, eine Aktion auszuführen.

ToolSpace-Modell

Apps müssen die Tool-Oberfläche verstehen, ohne Plugin-Interna zu importieren.

const tools = await run.toolSpace(); for (const tool of tools.list()) {  console.log(tool.name, tool.source, tool.requiresApproval);}

Das SDK sollte Folgendes bereitstellen:

• normalisierte Tool-Metadaten
• Quelle: OpenClaw, MCP, Plugin, Kanal, Runtime oder App
• Schema-Zusammenfassung
• Genehmigungsrichtlinie
• Runtime-Kompatibilität
• ob ein Tool verborgen, schreibgeschützt, schreibfähig oder hostfähig ist

Tool-Aufrufe über das SDK sollten explizit und begrenzt sein. Die meisten Apps sollten Agents ausführen und nicht beliebige Tools direkt aufrufen.

Artefaktmodell

Artefakte sollten mehr als Dateien abdecken.

type ArtifactSummary = {  id: string;  runId?: string;  sessionId?: string;  type:    | "file"    | "patch"    | "diff"    | "log"    | "media"    | "screenshot"    | "trajectory"    | "pull_request"    | "workspace";  title?: string;  mimeType?: string;  sizeBytes?: number;  createdAt: string;  expiresAt?: string;};

Gängige Beispiele:

• Dateiänderungen und generierte Dateien
• Patch-Bundles
• VCS-Diffs
• Screenshots und Medienausgaben
• Logs und Trace-Bundles
• Pull-Request-Links
• Runtime-Trajektorien
• Snapshots verwalteter Umgebungs-Workspaces

Artefaktzugriff sollte Schwärzung, Aufbewahrung und Download-URLs unterstützen, ohne anzunehmen, dass jedes Artefakt eine normale lokale Datei ist.

Sicherheitsmodell

Das App SDK muss Autorität explizit machen.

Empfohlene Token-Scopes:

Standardeinstellungen:

• keine Secret-Weiterleitung standardmäßig
• keine uneingeschränkte Weitergabe von Umgebungsvariablen
• Secret-Referenzen statt Secret-Werten
• explizite Sandbox- und Netzwerkrichtlinie
• explizite Aufbewahrung entfernter Umgebungen
• Genehmigungen für Host-Ausführung, sofern die Richtlinie nichts anderes beweist
• rohe Runtime-Events werden geschwärzt, bevor sie das Gateway verlassen, sofern der Aufrufer keinen stärkeren Diagnose-Scope besitzt

Provider für verwaltete Umgebungen

Verwaltete Agents sollten als Environment-Provider implementiert werden.

type EnvironmentProvider = {  id: string;  capabilities: {    checkout?: boolean;    sandbox?: boolean;    networkPolicy?: boolean;    secrets?: boolean;    artifacts?: boolean;    logs?: boolean;    pullRequests?: boolean;    longRunning?: boolean;  };};

Die erste Implementierung muss kein gehostetes SaaS-Angebot sein. Sie kann auf vorhandene Node-Hosts, kurzlebige Workspaces, CI-ähnliche Runner oder Testbox-artige Umgebungen abzielen. Der wichtige Vertrag lautet:

1. Workspace vorbereiten
2. sichere Umgebung und Secrets binden
3. Run starten
4. Events streamen
5. Artefakte sammeln
6. gemäß Richtlinie bereinigen oder aufbewahren

Sobald dies stabil ist, kann ein gehosteter Cloud-Service denselben Provider-Vertrag implementieren.

Paketstruktur

Empfohlene Pakete:

Das Repo enthält bereits openclaw/plugin-sdk/* für Plugins. Halten Sie diesen Namespace getrennt, um Plugin-Autoren nicht mit App-Entwicklern zu verwechseln.

Strategie für generierte Clients

Der Low-Level-Client sollte aus versionierten Gateway-Protokollschemas generiert und anschließend durch handgeschriebene ergonomische Klassen umschlossen werden.

Schichtung:

1. Gateway-Schema als maßgebliche Quelle.
2. Generierter Low-Level-TypeScript-Client.
3. Runtime-Validatoren für externe Eingaben und Event-Payloads.
4. High-Level-Wrapper für OpenClaw, Agent, Session, Run, Task und Artifact.
5. Cookbook-Beispiele und Integrationstests.

Vorteile:

• Protokollabweichungen werden sichtbar
• Tests können generierte Methoden mit Gateway-Exporten vergleichen
• Das App-SDK bleibt unabhängig von Interna des Plugin SDK
• Low-Level-Consumer haben weiterhin vollständigen Protokollzugriff
• High-Level-Consumer erhalten die kleine Produkt-API

Verwandte Themen

• OpenClaw App SDK
• Gateway-RPC-Referenz
• Agentenschleife
• Agent-Runtimes
• Hintergrundaufgaben
• ACP-Agenten
• Plugin-SDK-Übersicht