Naar hoofdinhoud gaan

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.

Deze pagina is het gedetailleerde API-referentieontwerp voor de voorgestelde openbare OpenClaw 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.

​
Namespace-ontwerp

De namespaces op laag niveau moeten nauw aansluiten bij Gateway-resources: 
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(); // future API: current SDK throws unsupported
oc.tasks.get(taskId); // future API: current SDK throws unsupported
oc.tasks.cancel(taskId); // future API: current SDK throws unsupported
oc.tasks.events(taskId, { after }); // future API

oc.models.list();
oc.models.status(); // Gateway models.authStatus

oc.tools.list();
oc.tools.invoke(...); // future API: current SDK throws unsupported

oc.artifacts.list({ runId }); // future API: current SDK throws unsupported
oc.artifacts.get(artifactId); // future API: current SDK throws unsupported
oc.artifacts.download(artifactId); // future API: current SDK throws unsupported

oc.approvals.list();
oc.approvals.respond(approvalId, ...);

oc.environments.list(); // future API: current SDK throws unsupported
oc.environments.create(...); // future API: current SDK throws unsupported
oc.environments.status(environmentId); // future API: current SDK throws unsupported
oc.environments.delete(environmentId); // future API: current SDK throws unsupported
Wrappers op hoog niveau moeten objecten teruggeven die veelvoorkomende 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();

​
Eventcontract

De openbare SDK moet geversioneerde, opnieuw afspeelbare, genormaliseerde events 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 replaycursor. Consumers moeten opnieuw verbinding kunnen maken met events({ after: id }) en gemiste events ontvangen wanneer de retentie dat toestaat. Aanbevolen genormaliseerde eventfamilies:
EventBetekenis
run.createdRun geaccepteerd.
run.queuedRun wacht op een sessielane, runtime of omgeving.
run.startedRuntime is begonnen met uitvoeren.
run.completedRun is succesvol voltooid.
run.failedRun is geëindigd met een fout.
run.cancelledRun is geannuleerd.
run.timed_outRun heeft de time-out overschreden.
assistant.deltaTekstdelta van de assistant.
assistant.messageVolledig assistant-bericht of vervanging.
thinking.deltaRedeneer- of plandelta, wanneer beleid blootstelling toestaat.
tool.call.startedToolaanroep is begonnen.
tool.call.deltaToolaanroep heeft voortgang of gedeeltelijke uitvoer gestreamd.
tool.call.completedToolaanroep is succesvol teruggekeerd.
tool.call.failedToolaanroep is mislukt.
approval.requestedEen run of tool heeft goedkeuring nodig.
approval.resolvedGoedkeuring is verleend, geweigerd, verlopen of geannuleerd.
question.requestedRuntime vraagt de gebruiker of host-app om invoer.
question.answeredHost-app heeft een antwoord geleverd.
artifact.createdNieuw artifact beschikbaar.
artifact.updatedBestaand artifact gewijzigd.
session.createdSessie aangemaakt.
session.updatedSessiemetadata gewijzigd.
session.compactedSessiecCompaction heeft plaatsgevonden.
task.updatedStatus van achtergrondtaak gewijzigd.
git.branchRuntime heeft branchstatus waargenomen of gewijzigd.
git.diffRuntime heeft een diff geproduceerd of gewijzigd.
git.prRuntime heeft een pull request geopend, bijgewerkt of gekoppeld.
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 teruggeven: 
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 eenvoudig en stabiel zijn. Timestampwaarden behouden de Gateway-vorm, zodat huidige lifecycle-ondersteunde runs meestal milliseconden sinds epoch rapporteren, terwijl adapters nog steeds ISO-strings kunnen tonen. Rijke UI, tooltraces en runtime-native details horen thuis in events en artifacts. accepted is een niet-terminaal wachtresultaat: het betekent dat de Gateway-wachtdeadline verliep voordat de run een lifecycle-einde of -fout produceerde. Dit 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 code-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();
});
Goedkeuringsevents moeten bevatten:
  • goedkeurings-id
  • run-id en sessie-id
  • aanvraagsoort
  • samenvatting van gevraagde actie
  • toolnaam of omgevingsactie
  • risiconiveau
  • beschikbare beslissingen
  • vervaldatum
  • of de beslissing opnieuw kan worden gebruikt
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 kunnen 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 afgebakend zijn. De meeste apps moeten agents uitvoeren, niet willekeurige tools rechtstreeks 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
  • runtimetrajecten
  • snapshots van werkruimten in beheerde omgevingen
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 tokenbereiken:
BereikStaat toe
agent.readAgents weergeven en inspecteren.
agent.runRuns starten.
session.readSessiemetadata en berichten lezen.
session.writeSessies aanmaken, verzenden naar, forken, compacten en afbreken.
task.readStatus van achtergrondtaken lezen.
task.writeTaakmeldingsbeleid annuleren of wijzigen.
approval.respondAanvragen goedkeuren of weigeren.
tools.invokeBlootgestelde tools rechtstreeks aanroepen.
artifacts.readArtifacts weergeven en downloaden.
environment.writeBeheerde omgevingen aanmaken of vernietigen.
adminBeheerdersbewerkingen.
Standaarden:
  • standaard geen doorsturen van geheimen
  • geen onbeperkte doorgifte van omgevingsvariabelen
  • geheimverwijzingen in plaats van geheimwaarden
  • expliciet sandbox- en netwerkbeleid
  • expliciete retentie voor externe omgevingen
  • goedkeuringen voor hostuitvoering tenzij beleid anders bewijst
  • onbewerkte runtime-events geredigeerd voordat ze de Gateway verlaten, tenzij de aanroeper een sterker diagnostisch bereik heeft

​
Provider voor beheerde omgevingen

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 gericht zijn op bestaande node-hosts, tijdelijke werkruimten, CI-achtige runners of Testbox-achtige omgevingen. Het belangrijke contract is:
  1. werkruimte voorbereiden
  2. veilige omgeving en geheimen binden
  3. run starten
  4. events streamen
  5. artifacts verzamelen
  6. opruimen of behouden volgens beleid
Zodra dit stabiel is, kan een gehoste clouddienst hetzelfde providercontract implementeren.

​
Pakketstructuur

Aanbevolen pakketten:
PakketDoel
@openclaw/sdkOpenbare SDK op hoog niveau en gegenereerde Gateway-client op laag niveau.
@openclaw/sdk-reactOptionele React-hooks voor dashboards en appbouwers.
@openclaw/sdk-testingTesthelpers en nep-Gateway-server voor appintegraties.
De repo heeft al openclaw/plugin-sdk/* voor plugins. Houd die namespace gescheiden om verwarring tussen Plugin-auteurs en appontwikkelaars te voorkomen.

​
Gegenereerde-clientstrategie

De client op laag niveau moet worden gegenereerd uit geversioneerde Gateway-protocolschema’s en daarna worden omwikkeld met handgeschreven ergonomische classes. Lagen:
  1. Gateway-schema als bron van waarheid.
  2. Gegenereerde low-level TypeScript-client.
  3. Runtime-validators voor externe invoer en eventpayloads.
  4. High-level OpenClaw, Agent, Session, Run, Task en Artifact wrappers.
  5. Cookbookvoorbeelden en integratietests.
Voordelen:
  • protocolafwijking is zichtbaar
  • tests kunnen gegenereerde methoden vergelijken met Gateway-exports
  • app-SDK blijft onafhankelijk van interne onderdelen van de plugin-SDK
  • low-level gebruikers behouden volledige protocoltoegang
  • high-level gebruikers krijgen de kleine product-API

​
Gerelateerde docs