API-ontwerp van de OpenClaw App SDK

Deze pagina is het gedetailleerde API-referentieontwerp voor de openbare OpenClaw App SDK. Deze staat bewust los van de Plugin SDK.

De openbare app-SDK moet in twee lagen worden gebouwd:

1. Een gegenereerde Gateway-client op laag niveau.
2. Een ergonomische wrapper op hoog niveau met OpenClaw-, Agent-, Session-, Run-, Task-, Artifact-, Approval- en Environment-objecten.

Ontwerp van naamruimten

De naamruimten op laag niveau moeten Gateway-resources nauw volgen:

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

Wrappers op hoog niveau moeten objecten retourneren die gangbare flows prettig maken:

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();

Gebeurteniscontract

De openbare SDK moet geversioneerde, opnieuw afspeelbare, genormaliseerde gebeurtenissen beschikbaar maken.

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 is een afspeelcursor. Consumenten moeten opnieuw verbinding kunnen maken met events({ after: id }) en gemiste gebeurtenissen ontvangen wanneer de retentie dat toestaat.

Aanbevolen genormaliseerde gebeurtenisfamilies:

Runtime-native payloads moeten beschikbaar zijn via raw, maar apps zouden raw niet hoeven te parsen voor normale UI.

Resultaatcontract

Run.wait() moet een stabiele resultatenvelop retourneren:

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

Het resultaat moet saai en stabiel zijn. Tijdstempelwaarden behouden de Gateway-vorm, zodat huidige lifecycle-ondersteunde runs meestal epoch-milliseconden rapporteren, terwijl adapters nog steeds ISO-strings kunnen tonen. Rijke UI, tooltraces en runtime-native details horen thuis in gebeurtenissen en artifacts.

accepted is een niet-terminaal wachtresultaat: het betekent dat de Gateway-wachtdeadline verliep voordat de run een lifecycle-einde of -fout produceerde. Het mag niet worden behandeld als timed_out; timed_out is gereserveerd voor een run die zijn eigen runtime-time-out heeft overschreden.

Goedkeuringen en vragen

Goedkeuringen moeten eersteklas zijn, omdat coding agents voortdurend veiligheidsgrenzen overschrijden.

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

Goedkeuringsgebeurtenissen moeten bevatten:

• goedkeurings-id
• run-id en sessie-id
• verzoeksoort
• samenvatting van de gevraagde actie
• toolnaam of omgevingsactie
• risiconiveau
• beschikbare beslissingen
• vervaldatum
• of de beslissing kan worden hergebruikt

Vragen staan los van goedkeuringen. Een vraag vraagt de gebruiker of host-app om informatie. Een goedkeuring vraagt toestemming om een actie uit te voeren.

ToolSpace-model

Apps moeten het tooloppervlak begrijpen zonder Plugin-internals te importeren.

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

De SDK moet beschikbaar maken:

• genormaliseerde toolmetadata
• bron: OpenClaw, MCP, plugin, kanaal, runtime of app
• schemasamenvatting
• goedkeuringsbeleid
• runtimecompatibiliteit
• of een tool verborgen, alleen-lezen, schrijfcapabel of hostcapabel is

Toolaanroep via de SDK moet expliciet en gescoped zijn. De meeste apps moeten agents uitvoeren, niet rechtstreeks willekeurige tools aanroepen.

Artifact-model

Artifacts moeten meer omvatten dan bestanden.

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

Veelvoorkomende voorbeelden:

• bestandsbewerkingen en gegenereerde bestanden
• patchbundels
• VCS-diffs
• screenshots en media-uitvoer
• logs en tracebundels
• pull request-links
• runtime-trajecten
• snapshots van beheerde omgevingswerkspaces

Artifact-toegang moet redactie, retentie en download-URL's ondersteunen zonder aan te nemen dat elk artifact een normaal lokaal bestand is.

Beveiligingsmodel

De app-SDK moet expliciet zijn over bevoegdheid.

Aanbevolen token-scopes:

Standaardwaarden:

• standaard geen doorsturen van geheimen
• geen onbeperkte doorvoer van omgevingsvariabelen
• geheime verwijzingen in plaats van geheime waarden
• expliciet sandbox- en netwerkbeleid
• expliciete retentie van remote omgevingen
• goedkeuringen voor hostuitvoering tenzij beleid anders bewijst
• ruwe runtime-gebeurtenissen worden geredigeerd voordat ze de Gateway verlaten, tenzij de aanroeper een sterkere diagnostische scope heeft

Provider voor beheerde omgeving

Beheerde agents moeten worden geïmplementeerd als omgevingsproviders.

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

De eerste implementatie hoeft geen gehoste SaaS te zijn. Deze kan zich richten op bestaande nodehosts, vluchtige workspaces, CI-achtige runners of Testbox-achtige omgevingen. Het belangrijke contract is:

1. workspace voorbereiden
2. veilige omgeving en geheimen binden
3. run starten
4. gebeurtenissen streamen
5. artifacts verzamelen
6. opschonen of behouden volgens beleid

Zodra dit stabiel is, kan een gehoste cloudservice hetzelfde providercontract implementeren.

Pakketstructuur

Aanbevolen pakketten:

De repo heeft al openclaw/plugin-sdk/* voor plugins. Houd die naamruimte gescheiden om verwarring tussen Plugin-auteurs en appontwikkelaars te voorkomen.

Strategie voor gegenereerde client

De client op laag niveau moet worden gegenereerd uit geversioneerde Gateway-protocolschema's en daarna worden omwikkeld door handgeschreven ergonomische klassen.

Gelaagdheid:

1. Gateway-schema als bron van waarheid.
2. Gegenereerde TypeScript-client op laag niveau.
3. Runtimevalidators voor externe invoer en eventpayloads.
4. Hoogwaardige wrappers voor OpenClaw, Agent, Session, Run, Task en Artifact.
5. Cookbook-voorbeelden en integratietests.

Voordelen:

• protocoldrift is zichtbaar
• tests kunnen gegenereerde methoden vergelijken met Gateway-exports
• App-SDK blijft onafhankelijk van interne onderdelen van de Plugin-SDK
• consumenten op laag niveau behouden volledige protocoltoegang
• consumenten op hoog niveau krijgen de kleine product-API

Gerelateerd

• OpenClaw App-SDK
• Gateway-RPC-referentie
• Agentlus
• Agentruntimes
• Achtergrondtaken
• ACP-agents
• Plugin-SDK-overzicht