OpenClaw-app-SDK

De OpenClaw App SDK is de openbare client-API voor apps buiten het OpenClaw-proces. Gebruik @openclaw/sdk wanneer een script, dashboard, CI-taak, IDE-extensie of andere externe app verbinding wil maken met de Gateway, agent-uitvoeringen wil starten, events wil streamen, op resultaten wil wachten, werk wil annuleren of Gateway-resources wil inspecteren.

Wat vandaag wordt meegeleverd

@openclaw/sdk wordt geleverd met:

De SDK exporteert ook de kerntypen die door deze oppervlakken worden gebruikt: 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 en gerelateerde resultaattypen.

Verbinden met een Gateway

Maak een client met een expliciete Gateway-URL, of injecteer een aangepast transport voor tests en ingebedde app-runtimes.

 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://..." }) is gelijkwaardig aan url. De optie gateway: "auto" wordt door de constructor geaccepteerd, maar automatische Gateway-detectie is nog geen afzonderlijke SDK-functie; geef url door wanneer de app nog niet weet hoe de Gateway moet worden ontdekt.

Geef voor tests een object door dat OpenClawTransport implementeert:

const oc = new OpenClaw({  transport: {    async request(method, params) {      return { method, params };    },    async *events() {},  },});

Een agent uitvoeren

Gebruik oc.agents.get(id) wanneer de app een agent-handle wil, en roep daarna agent.run() aan.

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-gekwalificeerde modelreferenties zoals openai/gpt-5.5 worden gesplitst in Gateway-overschrijvingen voor provider en model. timeoutMs blijft in de SDK milliseconden en wordt voor de agent-RPC geconverteerd naar Gateway-timeoutseconden.

run.wait() gebruikt de Gateway-agent.wait-RPC. Een wachtdeadline die verloopt terwijl de uitvoering nog actief is, retourneert status: "accepted" in plaats van te doen alsof de uitvoering zelf een timeout had. Runtime-timeouts, afgebroken uitvoeringen en geannuleerde uitvoeringen worden genormaliseerd naar timed_out of cancelled.

Sessies maken en hergebruiken

Gebruik sessies wanneer de app duurzame transcriptstatus wil.

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() roept sessions.send aan en retourneert een Run. Sessie-handles ondersteunen ook:

await session.abort(run.id);await session.patch({ label: "renamed-session" });await session.compact({ maxLines: 200 });

Events streamen

De SDK normaliseert ruwe Gateway-events naar een stabiele OpenClawEvent-envelop:

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

Veelvoorkomende eventtypen zijn:

Run.events() filtert events op één run-id en speelt al geziene events opnieuw af voor snelle uitvoeringen. Dat betekent dat de gedocumenteerde flow veilig is:

const run = await agent.run("Summarize the latest session."); for await (const event of run.events()) {  if (event.type === "run.completed") {    break;  }}

Gebruik oc.events() voor app-brede streams. Gebruik oc.rawEvents() voor ruwe Gateway-frames.

Modellen, tools, artefacten en goedkeuringen

Modelhelpers mappen naar huidige Gateway-methoden:

await oc.models.list();await oc.models.status({ probe: false }); // calls models.authStatus

Toolhelpers bieden toegang tot de Gateway-catalogus, effectieve toolweergave en directe Gateway-toolaanroep. oc.tools.invoke() retourneert een getypte envelop in plaats van te throwen bij policy- of goedkeuringsweigeringen.

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",});

Artefacthelpers bieden toegang tot de Gateway-artefactprojectie voor sessie-, run- of taakcontext. Elke aanroep vereist één expliciete scope: sessionKey, runId of 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);}

Goedkeuringshelpers gebruiken de exec-goedkeurings-RPC's:

const approvals = await oc.approvals.list();await oc.approvals.respond("approval-id", { decision: "approve" });

Taakhelpers gebruiken de duurzame taakledger die ook openclaw tasks ondersteunt:

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" });

Omgevingshelpers bieden alleen-lezen Gateway-lokale en node-detectie:

const { environments } = await oc.environments.list();await oc.environments.status(environments[0].id);

Vandaag expliciet niet ondersteund

De SDK bevat namen voor het productmodel dat we willen, maar doet niet stilzwijgend alsof Gateway-RPC's bestaan. Deze aanroepen throwen momenteel expliciete niet-ondersteund-fouten:

await oc.environments.create({});await oc.environments.delete("environment-id");

De velden workspace, runtime, environment en approvals per uitvoering zijn getypt als toekomstige vorm, maar de huidige Gateway ondersteunt deze overschrijvingen niet op de agent-RPC. Als aanroepers ze doorgeven, throwt de SDK voordat de uitvoering wordt ingediend, zodat werk niet per ongeluk wordt uitgevoerd met standaardgedrag voor workspace, runtime, omgeving of goedkeuringen.

App SDK versus Plugin SDK

Gebruik de App SDK wanneer code buiten OpenClaw leeft:

• Node-scripts die agent-uitvoeringen starten of observeren
• CI-taken die een Gateway aanroepen
• dashboards en beheerderspanelen
• IDE-extensies
• externe bridges die geen kanaalplugins hoeven te worden
• integratietests met neppe of echte Gateway-transporten

Gebruik de Plugin SDK wanneer code binnen OpenClaw draait:

• providerplugins
• kanaalplugins
• tool- of levenscyclus-hooks
• agent-harnessplugins
• vertrouwde runtimehelpers

App SDK-code moet importeren uit @openclaw/sdk. Plugincode moet importeren uit gedocumenteerde openclaw/plugin-sdk/*-subpaden. Meng de twee contracten niet.

Gerelateerd

• OpenClaw App SDK API-ontwerp
• Gateway RPC-referentie
• Agentloop
• Agent-runtimes
• Sessies
• Achtergrondtaken
• ACP-agenten
• Plugin SDK-overzicht