Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Das OpenClaw App SDK ist die öffentliche Client-API für Apps außerhalb des OpenClaw-Prozesses. Verwenden Sie @openclaw/sdk, wenn ein Skript, Dashboard, CI-Job, eine IDE-Erweiterung oder eine andere externe App eine Verbindung zum Gateway herstellen, Agent-Ausführungen starten, Events streamen, auf Ergebnisse warten, Arbeit abbrechen oder Gateway-Ressourcen prüfen soll.
Das App SDK unterscheidet sich vom Plugin SDK. @openclaw/sdk spricht von außerhalb von OpenClaw mit dem Gateway. openclaw/plugin-sdk/* ist nur für Plugins gedacht, die innerhalb von OpenClaw laufen und Provider, Kanäle, Tools, Hooks oder vertrauenswürdige Runtimes registrieren.

​
Was heute ausgeliefert wird

@openclaw/sdk wird mit Folgendem ausgeliefert:
OberflächeStatusWas sie macht
OpenClawBereitHaupteinstiegspunkt für Clients. Besitzt Transport, Verbindung, Anfragen und Events.
GatewayClientTransportBereitWebSocket-Transport auf Basis des Gateway-Clients.
oc.agentsBereitListet, erstellt, aktualisiert, löscht und ruft Agent-Handles ab.
Agent.run()BereitStartet eine Gateway-agent-Ausführung und gibt einen Run zurück.
oc.runsBereitErstellt, ruft ab, wartet auf, bricht ab und streamt Ausführungen.
Run.events()BereitStreamt normalisierte Events pro Ausführung mit Replay für schnelle Ausführungen.
Run.wait()BereitRuft agent.wait auf und gibt ein stabiles RunResult zurück.
Run.cancel()BereitRuft sessions.abort nach Ausführungs-ID auf, mit Sitzungsschlüssel, sofern verfügbar.
oc.sessionsBereitErstellt, löst auf, sendet an, patcht, kompaktiert und ruft Sitzungs-Handles ab.
Session.send()BereitRuft sessions.send auf und gibt einen Run zurück.
oc.tasksBereitListet, liest und bricht Gateway-Task-Ledger-Einträge ab.
oc.modelsBereitRuft models.list und den aktuellen Status-RPC models.authStatus auf.
oc.toolsBereitListet, scoped und ruft Gateway-Tools über die Policy-Pipeline auf.
oc.artifactsBereitListet, ruft ab und lädt Gateway-Transkript-Artefakte herunter.
oc.approvalsBereitListet und löst Exec-Freigaben über Gateway-Freigabe-RPCs auf.
oc.environmentsTeilweiseListet Gateway-lokale und Node-Umgebungskandidaten; Erstellen/Löschen ist nicht verdrahtet.
oc.rawEvents()BereitStellt rohe Gateway-Events für fortgeschrittene Consumer bereit.
normalizeGatewayEvent()BereitWandelt rohe Gateway-Events in die stabile SDK-Event-Form um.
Das SDK exportiert außerdem die Kerntypen, die von diesen Oberflächen verwendet werden: AgentRunParams, RunResult, RunStatus, OpenClawEvent, OpenClawEventType, GatewayEvent, OpenClawTransport, GatewayRequestOptions, SessionCreateParams, SessionSendParams, ArtifactSummary, ArtifactQuery, ArtifactsListResult, ArtifactsGetResult, ArtifactsDownloadResult, TaskSummary, TaskStatus, TasksListParams, TasksListResult, TasksGetResult, TasksCancelResult, RuntimeSelection, EnvironmentSelection, WorkspaceSelection, ApprovalMode und verwandte Ergebnistypen.

​
Verbindung zu einem Gateway herstellen

Erstellen Sie einen Client mit einer expliziten Gateway-URL, oder injizieren Sie einen benutzerdefinierten Transport für Tests und eingebettete App-Runtimes. 
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();
new OpenClaw({ gateway: "ws://..." }) ist gleichwertig mit url. Die Option gateway: "auto" wird vom Konstruktor akzeptiert, aber automatische Gateway-Erkennung ist noch kein separates SDK-Feature; übergeben Sie url, wenn die App nicht bereits weiß, wie sie das Gateway erkennen soll. Übergeben Sie für Tests ein Objekt, das OpenClawTransport implementiert: 
const oc = new OpenClaw({
  transport: {
    async request(method, params) {
      return { method, params };
    },
    async *events() {},
  },
});

​
Einen Agent ausführen

Verwenden Sie oc.agents.get(id), wenn die App ein Agent-Handle benötigt, und rufen Sie dann agent.run() auf. 
const agent = await oc.agents.get("main");

const run = await agent.run({
  input: "Review this pull request and suggest the smallest safe fix.",
  model: "openai/gpt-5.5",
  sessionKey: "main",
  timeoutMs: 30_000,
});

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

const result = await run.wait({ timeoutMs: 120_000 });
console.log(result.status);
Provider-qualifizierte Modellreferenzen wie openai/gpt-5.5 werden in Gateway-Overrides für provider und model aufgeteilt. timeoutMs bleibt im SDK in Millisekunden und wird für den agent-RPC in Gateway-Timeout-Sekunden umgewandelt. run.wait() verwendet den Gateway-RPC agent.wait. Eine Wait-Deadline, die abläuft, während die Ausführung noch aktiv ist, gibt status: "accepted" zurück, anstatt vorzutäuschen, dass die Ausführung selbst einen Timeout hatte. Runtime-Timeouts, abgebrochene Ausführungen und stornierte Ausführungen werden zu timed_out oder cancelled normalisiert.

​
Sitzungen erstellen und wiederverwenden

Verwenden Sie Sitzungen, wenn die App dauerhaften Transkriptzustand benötigt. 
const session = await oc.sessions.create({
  agentId: "main",
  label: "release-review",
});

const run = await session.send("Prepare release notes from the current diff.");
await run.wait();
Session.send() ruft sessions.send auf und gibt einen Run zurück. Sitzungs-Handles unterstützen außerdem: 
await session.abort(run.id);
await session.patch({ label: "renamed-session" });
await session.compact({ maxLines: 200 });

​
Events streamen

Das SDK normalisiert rohe Gateway-Events in einen stabilen OpenClawEvent-Umschlag: 
type OpenClawEvent = {
  version: 1;
  id: string;
  ts: number;
  type: OpenClawEventType;
  runId?: string;
  sessionId?: string;
  sessionKey?: string;
  taskId?: string;
  agentId?: string;
  data: unknown;
  raw?: GatewayEvent;
};
Häufige Event-Typen sind:
Event-TypGateway-Quell-Event
run.startedStart des agent-Lebenszyklus
run.completedEnde des agent-Lebenszyklus
run.failedFehler im agent-Lebenszyklus
run.cancelledEnde eines abgebrochenen/stornierten Lebenszyklus
run.timed_outEnde eines Timeout-Lebenszyklus
assistant.deltaStreaming-Delta des Assistenten
assistant.messageAssistentennachricht
thinking.deltaDenk- oder Plan-Stream
tool.call.startedStart von Tool/Item/Befehl
tool.call.deltaAktualisierung von Tool/Item/Befehl
tool.call.completedAbschluss von Tool/Item/Befehl
tool.call.failedFehler oder blockierter Status von Tool/Item/Befehl
approval.requestedExec- oder Plugin-Freigabeanforderung
approval.resolvedExec- oder Plugin-Freigabeauflösung
session.createdsessions.changed-Erstellung
session.updatedsessions.changed-Aktualisierung
session.compactedsessions.changed-Compaction
task.updatedTask-Aktualisierungs-Events
artifact.updatedPatch-Stream-Events
rawJedes Event ohne bisher stabiles SDK-Mapping
Run.events() filtert Events auf eine Ausführungs-ID und spielt bereits gesehene Events für schnelle Ausführungen erneut ab. Das bedeutet, dass der dokumentierte Ablauf sicher ist: 
const run = await agent.run("Summarize the latest session.");

for await (const event of run.events()) {
  if (event.type === "run.completed") {
    break;
  }
}
Verwenden Sie für appweite Streams oc.events(). Verwenden Sie für rohe Gateway-Frames oc.rawEvents().

​
Modelle, Tools, Artefakte und Freigaben

Modell-Helfer ordnen aktuellen Gateway-Methoden zu: 
await oc.models.list();
await oc.models.status({ probe: false }); // calls models.authStatus
Tool-Helfer stellen den Gateway-Katalog, die effektive Tool-Ansicht und den direkten Gateway-Tool-Aufruf bereit. oc.tools.invoke() gibt einen typisierten Umschlag zurück, anstatt bei Policy- oder Freigabeverweigerungen eine Exception auszulösen. 
await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });
await oc.tools.invoke("tool-name", {
  args: { input: "value" },
  sessionKey: "main",
  confirm: false,
  idempotencyKey: "tool-call-1",
});
Artefakt-Helfer stellen die Gateway-Artefaktprojektion für Sitzungs-, Ausführungs- oder Task-Kontext bereit. Jeder Aufruf erfordert genau einen expliziten Scope sessionKey, runId oder taskId: 
const { artifacts } = await oc.artifacts.list({ sessionKey: "main" });
const first = artifacts[0];

if (first) {
  const { artifact } = await oc.artifacts.get(first.id, { sessionKey: "main" });
  const download = await oc.artifacts.download(artifact.id, { sessionKey: "main" });
  console.log(download.encoding, download.url);
}
Freigabe-Helfer verwenden die Exec-Freigabe-RPCs: 
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });
Task-Helfer verwenden das dauerhafte Task-Ledger, das auch openclaw tasks unterstützt: 
const tasks = await oc.tasks.list({ status: "running", sessionKey: "agent:main:main" });
const task = await oc.tasks.get(tasks.tasks[0].id);
await oc.tasks.cancel(task.task.id, { reason: "user stopped task" });
Umgebungs-Helfer stellen schreibgeschützte Gateway-lokale und Node-Erkennung bereit: 
const { environments } = await oc.environments.list();
await oc.environments.status(environments[0].id);

​
Heute ausdrücklich nicht unterstützt

Das SDK enthält Namen für das Produktmodell, das wir anstreben, tut aber nicht stillschweigend so, als ob Gateway-RPCs existierten. Diese Aufrufe lösen derzeit explizite Nicht-unterstützt-Fehler aus: 
await oc.environments.create({});
await oc.environments.delete("environment-id");
Die Felder workspace, runtime, environment und approvals pro Ausführung sind als zukünftige Form typisiert, aber das aktuelle Gateway unterstützt diese Overrides im agent-RPC nicht. Wenn Aufrufer sie übergeben, löst das SDK vor dem Absenden der Ausführung eine Exception aus, damit Arbeit nicht versehentlich mit Standardverhalten für Workspace, Runtime, Umgebung oder Freigaben ausgeführt wird.

​
App SDK vs. Plugin SDK

Verwenden Sie das App SDK, wenn Code außerhalb von OpenClaw lebt:
  • Node-Skripte, die Agent-Ausführungen starten oder beobachten
  • CI-Jobs, die ein Gateway aufrufen
  • Dashboards und Admin-Panels
  • IDE-Erweiterungen
  • externe Bridges, die nicht zu Kanal-Plugins werden müssen
  • Integrationstests mit gefälschten oder echten Gateway-Transporten
Verwenden Sie das Plugin SDK, wenn Code innerhalb von OpenClaw läuft:
  • Provider-Plugins
  • Kanal-Plugins
  • Tool- oder Lebenszyklus-Hooks
  • Agent-Harness-Plugins
  • vertrauenswürdige Runtime-Helfer
App-SDK-Code sollte aus @openclaw/sdk importieren. Plugin-Code sollte aus dokumentierten openclaw/plugin-sdk/*-Unterpfaden importieren. Mischen Sie die beiden Verträge nicht.

​
Verwandte Themen