SDK dell'app OpenClaw

L'OpenClaw App SDK è l'API client pubblica per app esterne al processo OpenClaw. Usa @openclaw/sdk quando uno script, una dashboard, un job CI, un'estensione IDE o un'altra app esterna vuole connettersi al Gateway, avviare esecuzioni di agenti, trasmettere eventi in streaming, attendere i risultati, annullare il lavoro o ispezionare le risorse del Gateway.

Cosa è incluso oggi

@openclaw/sdk include:

L'SDK esporta anche i tipi core usati da queste superfici: 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 e tipi di risultato correlati.

Connettersi a un Gateway

Crea un client con un URL Gateway esplicito, oppure inietta un trasporto personalizzato per test e runtime di app incorporati.

 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://..." }) è equivalente a url. L'opzione gateway: "auto" è accettata dal costruttore, ma la discovery automatica del Gateway non è ancora una funzionalità separata dell'SDK; passa url quando l'app non sa già come individuare il Gateway.

Per i test, passa un oggetto che implementa OpenClawTransport:

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

Eseguire un agente

Usa oc.agents.get(id) quando l'app vuole un handle agente, quindi chiama 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);

I riferimenti ai modelli qualificati dal provider, come openai/gpt-5.5, vengono suddivisi in override provider e model del Gateway. timeoutMs rimane in millisecondi nell'SDK e viene convertito in secondi di timeout del Gateway per l'RPC agent.

run.wait() usa l'RPC agent.wait del Gateway. Una scadenza di attesa che scade mentre la run è ancora attiva restituisce status: "accepted" invece di far sembrare che la run stessa sia andata in timeout. Timeout di runtime, run interrotte e run annullate vengono normalizzati in timed_out o cancelled.

Creare e riutilizzare sessioni

Usa le sessioni quando l'app vuole uno stato di trascrizione durevole.

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() chiama sessions.send e restituisce una Run. Gli handle di sessione supportano anche:

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

Trasmettere eventi in streaming

L'SDK normalizza gli eventi Gateway grezzi in un envelope OpenClawEvent stabile:

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

I tipi di evento comuni includono:

Run.events() filtra gli eventi per un solo ID run e riproduce gli eventi già visti per run rapide. Questo significa che il flusso documentato è sicuro:

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

Per stream a livello di app, usa oc.events(). Per frame Gateway grezzi, usa oc.rawEvents().

Modelli, strumenti, artifact e approvazioni

Gli helper dei modelli si mappano ai metodi Gateway attuali:

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

Gli helper degli strumenti espongono il catalogo Gateway, la vista effettiva degli strumenti e l'invocazione diretta degli strumenti Gateway. oc.tools.invoke() restituisce un envelope tipizzato invece di generare un'eccezione per rifiuti di policy o approvazione.

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

Gli helper degli artifact espongono la proiezione artifact del Gateway per il contesto di sessione, run o task. Ogni chiamata richiede un solo ambito esplicito tra sessionKey, runId o 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);}

Gli helper di approvazione usano le RPC di approvazione exec:

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

Gli helper dei task usano il registro task durevole che supporta anche 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" });

Gli helper di ambiente espongono la discovery di sola lettura locale al Gateway e del nodo:

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

Esplicitamente non supportato oggi

L'SDK include nomi per il modello di prodotto che vogliamo, ma non finge silenziosamente che esistano RPC Gateway. Queste chiamate attualmente generano errori espliciti di non supportato:

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

I campi per run workspace, runtime, environment e approvals sono tipizzati come forma futura, ma il Gateway attuale non supporta questi override sull'RPC agent. Se i chiamanti li passano, l'SDK genera un errore prima di sottomettere la run, così il lavoro non viene eseguito accidentalmente con comportamento predefinito di workspace, runtime, ambiente o approvazione.

App SDK e Plugin SDK

Usa l'App SDK quando il codice vive fuori da OpenClaw:

• script Node che avviano o osservano run di agenti
• job CI che chiamano un Gateway
• dashboard e pannelli di amministrazione
• estensioni IDE
• bridge esterni che non devono diventare Plugin di canale
• test di integrazione con trasporti Gateway finti o reali

Usa il Plugin SDK quando il codice viene eseguito dentro OpenClaw:

• Plugin provider
• Plugin di canale
• hook di strumenti o ciclo di vita
• Plugin harness agente
• helper runtime attendibili

Il codice App SDK deve importare da @openclaw/sdk. Il codice Plugin deve importare dai sottopercorsi documentati openclaw/plugin-sdk/*. Non mescolare i due contratti.

Correlati

• Progettazione dell'API dell'SDK dell'app OpenClaw
• Riferimento RPC del Gateway
• Ciclo dell'agente
• Runtime degli agenti
• Sessioni
• Attività in secondo piano
• Agenti ACP
• Panoramica dell'SDK Plugin