OpenClaw SDK-ontwerp

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.

​

Status

​

Doelen

• Appontwikkelaars een kleine API op hoog niveau geven voor het uitvoeren van OpenClaw-agents.
• OpenClaw met lokale uitvoering als uitgangspunt de standaardruntime laten blijven.
• Cloud- of beheerde omgevingen een aanvullende omgevingsprovider maken, geen andere agent-API.
• Bestaande OpenClaw-grenzen behouden: Gateway bezit het publieke protocol, de Plugin-SDK bezit in-process extensies, ACP bezit interoperabiliteit met externe harnassen.
• stream, wait, cancel, resume, fork, artefacten, goedkeuringen en achtergrondtaken ondersteunen als eersteklas operaties.
• Stabiele genormaliseerde events blootstellen en runtime-native raw events behouden voor geavanceerde consumenten.
• SDK-toestemmingen, doorgeven van secrets, goedkeuringen, sandboxing en externe omgevingen expliciet maken.
• Het publieke contract klein genoeg houden om te documenteren, testen, versioneren en genereren.

​

Niet-doelen

• openclaw/plugin-sdk/* niet blootstellen als de app-SDK.
• ACP niet het enige runtimemodel maken.
• Geen cloudservice vereisen voordat de SDK nuttig is.
• Cursor-, Claude-, OpenAI-, ADK-, OpenCode-, Codex- of ACP-API’s niet exact klonen.
• Geen onbegrensde any-eventpayloads blootstellen als het enige publieke contract.
• Geen sandbox- of netwerkisolatie beloven voor een extern harnas tenzij de geselecteerde omgeving dit daadwerkelijk kan afdwingen.
• Plugin-auteurs niet afhankelijk maken van app-SDK-objecten binnen runtimecode van Plugins.

​

Huidige OpenClaw-inpassing

​

Kernmodel

​

Productvorm

import { OpenClaw } from "@openclaw/sdk";

const oc = new OpenClaw({ gateway: "auto" });
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",
});

for await (const event of run.events()) {
  if (event.type === "assistant.delta") {
    process.stdout.write(event.text);
  }
}

const result = await run.wait();
console.log(result.status);

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

const run = await oc.runs.create({
  input: "Deep review this repository and return only high-risk findings.",
  workspace: { cwd: process.cwd() },
  runtime: { type: "acp", harness: "claude" },
  mode: "task",
});

const run = await agent.run({
  input: "Run the full changed gate and summarize failures.",
  workspace: { repo: "openclaw/openclaw", ref: "main" },
  runtime: {
    type: "managed",
    provider: "testbox",
    timeoutMinutes: 90,
  },
});

​

Runtime-selectie

type RuntimeSelection =
  | "auto"
  | { type: "embedded"; id: "pi" | "codex" | string }
  | { type: "cli"; id: "claude-cli" | string }
  | { type: "acp"; harness: "claude" | "cursor" | "gemini" | "opencode" | string }
  | { type: "managed"; provider: "local" | "node" | "testbox" | "cloud" | string };

• auto volgt de runtime-selectieregels van OpenClaw.
• embedded richt zich op vertrouwde in-process harnesses die via de Plugin SDK zijn geregistreerd, zoals pi of codex.
• cli richt zich op door OpenClaw beheerde CLI-backenduitvoering waar beschikbaar.
• acp richt zich via ACP/acpx op externe harnesses.
• managed richt zich op een environment-provider en kan nog steeds een embedded, CLI- of ACP-runtime binnen die environment uitvoeren.

​

Environment-model

type EnvironmentSelection =
  | { type: "local"; cwd?: string }
  | { type: "gateway"; url?: string; cwd?: string }
  | { type: "node"; nodeId: string; cwd?: string }
  | { type: "managed"; provider: string; repo?: string; ref?: string }
  | { type: "ephemeral"; provider: string; repo?: string; ref?: string };

• checkout- of workspacevoorbereiding
• proces- en bestandstoegang
• sandbox- en netwerkhandhaving
• omgevingsvariabelen en geheime referenties
• logs, traces en artifacts
• opschoning en retentie
• runtime-beschikbaarheid

​

Cookbook-plan

​

Gefaseerde implementatie

​

Fase 0: RFC en vocabulaire

• Spreek publieke zelfstandige naamwoorden en namen af.
• Beslis over pakketnamen.
• Definieer de eerste eventtaxonomie.
• Markeer de huidige Plugin SDK in de docs als bewust apart.

​

Fase 1: Low-level gegenereerde client

• Genereer een TypeScript-client uit Gateway-protocolschema’s.
• Dek eerst agent, agent.wait, sessies, abonnementen, afbreken en taken af.
• Voeg smoketests toe die controleren dat gegenereerde methoden overeenkomen met Gateway-methodenamen en schema- vormen.
• Publiceer als experimenteel of intern pakket.

​

Fase 2: High-level run-API

• Voeg OpenClaw, Agent, Session en Run toe.
• Ondersteun run.events(), run.wait() en run.cancel().
• Ondersteun lokale Gateway-detectie en expliciete Gateway-URL’s.
• Ondersteun duurzame sessies en sessieverzending.

​

Fase 3: Genormaliseerde eventprojectie

• Voeg Gateway-side genormaliseerde eventprojectie toe naast bestaande ruwe gebeurtenissen.
• Behoud ruwe runtimegebeurtenissen waar beleid dit toestaat.
• Voeg replaycursors en reconnectgedrag toe.
• Map PI-, Codex-, ACP- en taakgebeurtenissen naar de stabiele taxonomie.

​

Fase 4: Artefacten en goedkeuringen

• Voeg artefactlijst en download toe.
• Voeg helpers voor goedkeuringsabonnementen en antwoorden toe.
• Voeg helpers voor vraagabonnementen en antwoorden toe.
• Voeg een cookbook-goedkeuringsconsole toe.

​

Fase 5: Omgevingsproviders

• Introduceer contracten voor lokale, node- en beheerde omgevingsproviders.
• Begin met een omgeving die operationeel al bestaat.
• Voeg werkruimtevoorbereiding, logs, artefacten, time-out, opruiming en retentie toe.

​

Fase 6: Cloudstijlworkflows

• Voeg repository- en branch-georiënteerde runs toe.
• Voeg pull-requestartefacten toe.
• Voeg runborden toe, gegroepeerd op repo, branch, status en toegewezene.
• Voeg langlopende beheerde sessies en retentiebeleid toe.

​

Ontwerpkeuzes om over te nemen

• Van Cursor: Agent plus Run, lokale en cloudsymmetrie, modeldetectie, artefacten en cookbook-gestuurde onboarding.
• Van Claude Agent SDK: bidirectionele clients, interrupt, machtigingen, hooks, aangepaste tools, sessiestores en hervattingssemantiek.
• Van OpenAI Agents: handoffs, guardrails, hervatting na menselijke goedkeuring, tracing en gestructureerde gestreamde resultaatobjecten.
• Van Google ADK: services achter runner, eventacties, geheugen, artefacten, credentialservices en Plugin-interceptie rond de run-lifecycle.
• Van OpenCode: gegenereerde protocolclient, REST plus SSE, sessies, werkruimten, vragen, machtigingen, bestanden, VCS, PTY, MCP, agents en Skills.
• Van Codex: expliciete sandbox, goedkeuring, netwerk, lokale en remote exec, en threadgrenzen voor appserver.
• Van ACP en acpx: adaptergebaseerde interoperabiliteit met externe harnesses en benoemde promptwachtrijen.

​

Ontwerpkeuzes om te vermijden

• Een publieke SDK die slechts een dunne dump van Gateway-internals is.
• Een publieke SDK die Plugin SDK-subpaden importeert.
• Een publieke SDK waarin gebeurtenissen alleen stream plus data zijn.
• Een cloud-first API die lokale OpenClaw als een legacy-modus laat aanvoelen.
• Runtimekeuze verborgen in model-id-prefixen.
• Secret-forwarding verborgen in omgevingsmaps.
• ACP-specifieke opties op het topniveau van elke run.
• Sandboxvlaggen die niet kunnen worden afgedwongen door de gekozen runtime.
• Een SDK-object dat tegelijk provider-Plugin, kanaal-Plugin, appclient en beheerde runner probeert te zijn.

​

Open vragen

• Moet het initiële pakket in deze repo staan of in een aparte SDK-repo?
• Moet de gegenereerde low-level client publiek worden gepubliceerd voordat de high-level wrapper stabiliseert?
• Wat is het eerste ondersteunde app-authmechanisme: lokale token, admintoken, OAuth-deviceflow of ondertekende appregistratie?
• Hoeveel sessieberichtgeschiedenis moet de SDK standaard blootstellen?
• Moeten beheerde omgevingen alleen in Gateway-configuratie worden geconfigureerd, of kunnen SDK- aanroepers ze direct aanvragen met scoped tokens?
• Welke retentieregels gelden voor artefacten die door lokale runs worden gegenereerd?
• Welke eventpayloads vereisen redactie vóór applevering?
• Moet Run normale chatbeurten en losgekoppelde taken dekken, of moet losgekoppeld achtergrondwerk altijd een Task-wrapper met een geneste Run teruggeven?

​

Gerelateerde docs

• Agentloop
• Agentruntimes
• Sessie
• Subagents
• Achtergrondtaken
• ACP-agents
• Agentharness-Plugins
• Plugin SDK-overzicht