Passer au contenu principal

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.

Le SDK d’applications OpenClaw est l’API client 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 d’IDE ou une autre application externe veut se connecter au Gateway, démarrer des exécutions d’agents, diffuser des événements, attendre des résultats, annuler du travail ou inspecter les ressources du Gateway.
Le SDK d’applications est différent du Plugin SDK. @openclaw/sdk communique avec le Gateway depuis l’extérieur d’OpenClaw. openclaw/plugin-sdk/* est réservé aux plugins qui s’exécutent dans OpenClaw et enregistrent des fournisseurs, des canaux, des outils, des hooks ou des environnements d’exécution de confiance.

​
Ce qui est livré aujourd’hui

@openclaw/sdk est livré avec :
SurfaceÉtatCe qu’elle fait
OpenClawPrêtPoint d’entrée principal du client. Possède le transport, la connexion, les requêtes et les événements.
GatewayClientTransportPrêtTransport WebSocket adossé au client Gateway.
oc.agentsPrêtListe, crée, met à jour, supprime et obtient des handles d’agent.
Agent.run()PrêtDémarre une exécution Gateway agent et renvoie un Run.
oc.runsPrêtCrée, obtient, attend, annule et diffuse des exécutions.
Run.events()PrêtDiffuse des événements normalisés par exécution avec relecture pour les exécutions rapides.
Run.wait()PrêtAppelle agent.wait et renvoie un RunResult stable.
Run.cancel()PrêtAppelle sessions.abort par identifiant d’exécution, avec la clé de session lorsqu’elle est disponible.
oc.sessionsPrêtCrée, résout, envoie vers, corrige, compacte et obtient des handles de session.
Session.send()PrêtAppelle sessions.send et renvoie un Run.
oc.modelsPrêtAppelle models.list et le RPC d’état models.authStatus actuel.
oc.toolsPartielListe le catalogue d’outils et les outils effectifs ; l’invocation directe d’outils n’est pas câblée.
oc.approvalsPrêtListe et résout les approbations d’exécution via les RPC d’approbation du Gateway.
oc.rawEvents()PrêtExpose les événements Gateway bruts pour les consommateurs avancés.
normalizeGatewayEvent()PrêtConvertit les événements Gateway bruts dans la forme d’événement stable du SDK.
Le SDK exporte aussi les types de base utilisés par ces surfaces : AgentRunParams, RunResult, RunStatus, OpenClawEvent, OpenClawEventType, GatewayEvent, OpenClawTransport, GatewayRequestOptions, SessionCreateParams, SessionSendParams, RuntimeSelection, EnvironmentSelection, WorkspaceSelection, ApprovalMode et les types de résultats 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 intégrées. 
import { OpenClaw } from "@openclaw/sdk";

const oc = new OpenClaw({
  url: "ws://127.0.0.1:14565",
  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é distincte du SDK ; passez url lorsque l’application ne sait pas déjà comment découvrir le Gateway. Pour les tests, passez 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èles 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 Gateway pour le RPC agent. run.wait() utilise le RPC Gateway agent.wait. Une échéance d’attente qui expire pendant que l’exécution est encore active renvoie status: "accepted" au lieu de faire comme si l’exécution elle-même avait expiré. Les délais d’exécution, les exécutions interrompues et les exécutions annulées sont normalisés en timed_out ou cancelled.

​
Créer et réutiliser des sessions

Utilisez des 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

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 :
Type d’événementÉvénement Gateway source
run.startedDébut du cycle de vie agent
run.completedFin du cycle de vie agent
run.failedErreur du cycle de vie agent
run.cancelledFin de cycle de vie interrompue/annulée
run.timed_outFin de cycle de vie par délai expiré
assistant.deltaDelta de diffusion de l’assistant
assistant.messageMessage de l’assistant
thinking.deltaFlux de réflexion ou de plan
tool.call.startedDébut d’outil/d’élément/de commande
tool.call.deltaMise à jour d’outil/d’élément/de commande
tool.call.completedAchèvement d’outil/d’élément/de commande
tool.call.failedÉchec ou état bloqué d’outil/d’élément/de commande
approval.requestedDemande d’approbation d’exécution ou de Plugin
approval.resolvedRésolution d’approbation d’exécution ou de Plugin
session.createdCréation sessions.changed
session.updatedMise à jour sessions.changed
session.compactedCompaction sessions.changed
task.updatedÉvénements de mise à jour de tâche
artifact.updatedÉvénements de flux de patch
rawTout événement sans mappage SDK stable pour l’instant
Run.events() filtre les événements sur un seul 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 et approbations

Les assistants de modèles correspondent aux méthodes Gateway actuelles : 
await oc.models.list();
await oc.models.status({ probe: false }); // calls models.authStatus
Les assistants d’outils exposent le catalogue Gateway et la vue des outils effectifs : 
await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });
Les assistants d’approbation utilisent les RPC d’approbation d’exécution : 
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });

​
Explicitement non pris en charge aujourd’hui

Le SDK inclut des noms pour le modèle produit que nous voulons, mais il ne fait pas semblant silencieusement que des RPC Gateway existent. Ces appels lèvent actuellement des erreurs explicites de non-prise en charge : 
await oc.tasks.list();
await oc.tasks.get("task-id");
await oc.tasks.cancel("task-id");

await oc.tools.invoke("tool-name", {});

await oc.artifacts.list();
await oc.artifacts.get("artifact-id");
await oc.artifacts.download("artifact-id");

await oc.environments.list();
await oc.environments.create({});
await oc.environments.status("environment-id");
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 passent, le SDK lève une erreur avant de soumettre l’exécution afin que le travail ne s’exécute pas accidentellement avec le comportement par défaut de l’espace de travail, de l’environnement d’exécution, de l’environnement ou de l’approbation.

​
SDK d’applications ou Plugin SDK

Utilisez le SDK d’applications lorsque le code vit en dehors d’OpenClaw :
  • scripts Node qui démarrent ou observent des exécutions d’agents
  • tâches CI qui appellent un Gateway
  • tableaux de bord et panneaux d’administration
  • extensions d’IDE
  • ponts externes qui n’ont pas besoin de devenir des Plugins de canaux
  • tests d’intégration avec des transports Gateway factices ou réels
Utilisez le Plugin SDK lorsque le code s’exécute dans OpenClaw :
  • Plugins de fournisseurs
  • Plugins de canaux
  • hooks d’outils ou de cycle de vie
  • Plugins de harnais d’agent
  • assistants d’environnement d’exécution de confiance
Le code du SDK d’applications 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.

​
Documentation associée