SDK d’application OpenClaw

Le SDK d’application OpenClaw est l’API cliente publique pour les applications en dehors du processus OpenClaw. Utilisez @openclaw/sdk lorsqu’un script, un tableau de bord, une tâche CI, une extension IDE ou une autre application externe veut se connecter au Gateway, démarrer des exécutions d’agent, diffuser des événements en continu, attendre des résultats, annuler du travail ou inspecter les ressources du Gateway.

Ce qui est livré aujourd’hui

@openclaw/sdk est livré avec :

Le SDK exporte aussi les types principaux utilisés par ces surfaces : 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, ainsi que les types de résultat associés.

Se connecter à un Gateway

Créez un client avec une URL Gateway explicite, ou injectez un transport personnalisé pour les tests et les environnements d’exécution d’applications embarquées.

 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://..." }) est équivalent à url. L’option gateway: "auto" est acceptée par le constructeur, mais la découverte automatique du Gateway n’est pas encore une fonctionnalité SDK distincte ; transmettez url lorsque l’application ne sait pas déjà comment découvrir le Gateway.

Pour les tests, transmettez un objet qui implémente OpenClawTransport :

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

Exécuter un agent

Utilisez oc.agents.get(id) lorsque l’application veut un handle d’agent, puis appelez agent.run().

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

Les références de modèle qualifiées par fournisseur, comme openai/gpt-5.5, sont séparées en remplacements Gateway provider et model. timeoutMs reste en millisecondes dans le SDK et est converti en secondes de délai d’expiration Gateway pour le RPC agent.

run.wait() utilise le RPC Gateway agent.wait. Une échéance d’attente qui expire alors que l’exécution est toujours active renvoie status: "accepted" au lieu de prétendre que l’exécution elle-même a expiré. Les expirations d’environnement d’exécution, les exécutions abandonnées et les exécutions annulées sont normalisées en timed_out ou cancelled.

Créer et réutiliser des sessions

Utilisez les sessions lorsque l’application veut un état de transcription durable.

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() appelle sessions.send et renvoie un Run. Les handles de session prennent aussi en charge :

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

Diffuser des événements en continu

Le SDK normalise les événements Gateway bruts dans une enveloppe OpenClawEvent stable :

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

Les types d’événements courants incluent :

Run.events() filtre les événements vers un identifiant d’exécution et relit les événements déjà vus pour les exécutions rapides. Cela signifie que le flux documenté est sûr :

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

Pour les flux à l’échelle de l’application, utilisez oc.events(). Pour les trames Gateway brutes, utilisez oc.rawEvents().

Modèles, outils, artefacts et approbations

Les helpers de modèle correspondent aux méthodes Gateway actuelles :

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

Les helpers d’outil exposent le catalogue Gateway, la vue effective des outils et l’invocation directe d’outil Gateway. oc.tools.invoke() renvoie une enveloppe typée au lieu de lever une exception en cas de refus par politique ou approbation.

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

Les helpers d’artefact exposent la projection d’artefact Gateway pour un contexte de session, d’exécution ou de tâche. Chaque appel nécessite une portée explicite sessionKey, runId ou 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);}

Les helpers d’approbation utilisent les RPC d’approbation d’exécution :

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

Les helpers de tâche utilisent le registre durable des tâches qui alimente aussi openclaw tasks :

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

Les helpers d’environnement exposent la découverte locale au Gateway et de nœud en lecture seule :

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

Explicitement non pris en charge aujourd’hui

Le SDK inclut des noms pour le modèle de produit que nous voulons, mais il ne fait pas semblant silencieusement que les RPC Gateway existent. Ces appels lèvent actuellement des erreurs explicites de non-prise en charge :

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

Les champs par exécution workspace, runtime, environment et approvals sont typés comme forme future, mais le Gateway actuel ne prend pas en charge ces remplacements sur le RPC agent. Si les appelants les transmettent, le SDK lève une exception avant de soumettre l’exécution afin que le travail ne s’exécute pas accidentellement avec le comportement par défaut d’espace de travail, d’environnement d’exécution, d’environnement ou d’approbation.

SDK d’application vs SDK Plugin

Utilisez le SDK d’application lorsque le code vit en dehors d’OpenClaw :

• scripts Node qui démarrent ou observent des exécutions d’agent
• tâches CI qui appellent un Gateway
• tableaux de bord et panneaux d’administration
• extensions IDE
• ponts externes qui n’ont pas besoin de devenir des plugins de canal
• tests d’intégration avec de faux ou vrais transports Gateway

Utilisez le SDK Plugin lorsque le code s’exécute dans OpenClaw :

• plugins de fournisseur
• plugins de canal
• hooks d’outil ou de cycle de vie
• plugins de harnais d’agent
• helpers d’environnement d’exécution de confiance

Le code du SDK d’application doit importer depuis @openclaw/sdk. Le code de Plugin doit importer depuis les sous-chemins documentés openclaw/plugin-sdk/*. Ne mélangez pas les deux contrats.

Associé

• Conception de l’API du SDK d’application OpenClaw
• Référence RPC du Gateway
• Boucle d’agent
• Environnements d’exécution des agents
• Sessions
• Tâches en arrière-plan
• Agents ACP
• Vue d’ensemble du SDK de Plugin