Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.
L’App SDK è diverso dal Plugin SDK. @openclaw/sdk comunica con il Gateway dall’esterno di OpenClaw. openclaw/plugin-sdk/* è solo per Plugin eseguiti dentro OpenClaw e che registrano provider, canali, strumenti, hook o runtime attendibili.

​
Cosa è incluso oggi

@openclaw/sdk include:
AreaStatoCosa fa
OpenClawProntoPunto di ingresso principale del client. Gestisce trasporto, connessione, richieste ed eventi.
GatewayClientTransportProntoTrasporto WebSocket basato sul client Gateway.
oc.agentsProntoElenca, crea, aggiorna, elimina e ottiene handle degli agenti.
Agent.run()ProntoAvvia una run agent del Gateway e restituisce una Run.
oc.runsProntoCrea, ottiene, attende, annulla e trasmette run in streaming.
Run.events()ProntoTrasmette eventi normalizzati per run con replay per run rapide.
Run.wait()ProntoChiama agent.wait e restituisce un RunResult stabile.
Run.cancel()ProntoChiama sessions.abort per ID run, con la chiave di sessione quando disponibile.
oc.sessionsProntoCrea, risolve, invia a, applica patch, compatta e ottiene handle di sessione.
Session.send()ProntoChiama sessions.send e restituisce una Run.
oc.tasksProntoElenca, legge e annulla voci del registro task del Gateway.
oc.modelsProntoChiama models.list e l’attuale RPC di stato models.authStatus.
oc.toolsProntoElenca, definisce ambiti e invoca strumenti del Gateway tramite la pipeline di policy.
oc.artifactsProntoElenca, ottiene e scarica artifact di trascrizione del Gateway.
oc.approvalsProntoElenca e risolve approvazioni exec tramite RPC di approvazione del Gateway.
oc.environmentsParzialeElenca candidati di ambiente locali al Gateway e del nodo; creazione/eliminazione non sono collegate.
oc.rawEvents()ProntoEspone eventi Gateway grezzi per consumer avanzati.
normalizeGatewayEvent()ProntoConverte eventi Gateway grezzi nella forma evento stabile dell’SDK.
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. 
import { OpenClaw } from "@openclaw/sdk";

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:
Tipo di eventoEvento Gateway di origine
run.startedAvvio del ciclo di vita agent
run.completedFine del ciclo di vita agent
run.failedErrore del ciclo di vita agent
run.cancelledFine del ciclo di vita interrotto/annullato
run.timed_outFine del ciclo di vita per timeout
assistant.deltaDelta di streaming dell’assistente
assistant.messageMessaggio dell’assistente
thinking.deltaStream di pensiero o piano
tool.call.startedAvvio di strumento/elemento/comando
tool.call.deltaAggiornamento di strumento/elemento/comando
tool.call.completedCompletamento di strumento/elemento/comando
tool.call.failedErrore o stato bloccato di strumento/elemento/comando
approval.requestedRichiesta di approvazione exec o Plugin
approval.resolvedRisoluzione di approvazione exec o Plugin
session.createdCreazione sessions.changed
session.updatedAggiornamento sessions.changed
session.compactedCompaction sessions.changed
task.updatedEventi di aggiornamento task
artifact.updatedEventi di stream patch
rawQualsiasi evento senza ancora una mappatura SDK stabile
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