SDK aplikacji OpenClaw

OpenClaw App SDK to publiczne API klienta dla aplikacji działających poza procesem OpenClaw. Użyj @openclaw/sdk, gdy skrypt, pulpit, zadanie CI, rozszerzenie IDE lub inna aplikacja zewnętrzna chce połączyć się z Gateway, uruchamiać przebiegi agentów, strumieniować zdarzenia, czekać na wyniki, anulować pracę albo sprawdzać zasoby Gateway.

Co jest dziś dostarczane

@openclaw/sdk zawiera:

SDK eksportuje także podstawowe typy używane przez te powierzchnie: 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 oraz powiązane typy wyników.

Połącz z Gateway

Utwórz klienta z jawnym adresem URL Gateway albo wstrzyknij niestandardowy transport dla testów i osadzonych środowisk wykonawczych aplikacji.

 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://..." }) jest równoważne z url. Opcja gateway: "auto" jest akceptowana przez konstruktor, ale automatyczne wykrywanie Gateway nie jest jeszcze osobną funkcją SDK; przekaż url, gdy aplikacja nie wie jeszcze, jak wykryć Gateway.

W testach przekaż obiekt implementujący OpenClawTransport:

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

Uruchom agenta

Użyj oc.agents.get(id), gdy aplikacja chce uzyskać uchwyt agenta, a następnie wywołaj 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);

Referencje modeli kwalifikowane dostawcą, takie jak openai/gpt-5.5, są dzielone na nadpisania Gateway provider i model. timeoutMs pozostaje w SDK w milisekundach i jest konwertowane na sekundy limitu czasu Gateway dla RPC agent.

run.wait() używa RPC Gateway agent.wait. Termin oczekiwania, który wygasa, gdy przebieg nadal jest aktywny, zwraca status: "accepted" zamiast udawać, że sam przebieg przekroczył limit czasu. Limity czasu środowiska wykonawczego, przerwane przebiegi i anulowane przebiegi są normalizowane do timed_out lub cancelled.

Twórz i ponownie używaj sesji

Użyj sesji, gdy aplikacja potrzebuje trwałego stanu transkrypcji.

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() wywołuje sessions.send i zwraca Run. Uchwyty sesji obsługują także:

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

Strumieniuj zdarzenia

SDK normalizuje surowe zdarzenia Gateway do stabilnej koperty OpenClawEvent:

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

Typowe typy zdarzeń obejmują:

Run.events() filtruje zdarzenia do jednego identyfikatora przebiegu i odtwarza już widziane zdarzenia dla szybkich przebiegów. Oznacza to, że udokumentowany przepływ jest bezpieczny:

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

Do strumieni obejmujących całą aplikację użyj oc.events(). Do surowych ramek Gateway użyj oc.rawEvents().

Modele, narzędzia, artefakty i zatwierdzenia

Pomocniki modeli mapują się na bieżące metody Gateway:

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

Pomocniki narzędzi udostępniają katalog Gateway, efektywny widok narzędzi i bezpośrednie wywoływanie narzędzi Gateway. oc.tools.invoke() zwraca typowaną kopertę zamiast zgłaszać wyjątek dla odmów polityki lub zatwierdzenia.

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

Pomocniki artefaktów udostępniają projekcję artefaktów Gateway dla kontekstu sesji, przebiegu lub zadania. Każde wywołanie wymaga jednego jawnego zakresu sessionKey, runId albo 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);}

Pomocniki zatwierdzeń używają RPC zatwierdzeń exec:

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

Pomocniki zadań używają trwałego rejestru zadań, który obsługuje także 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" });

Pomocniki środowisk udostępniają tylko do odczytu lokalne dla Gateway i węzłowe wykrywanie:

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

Jawnie nieobsługiwane dziś

SDK zawiera nazwy dla modelu produktu, którego chcemy, ale nie udaje po cichu, że RPC Gateway istnieją. Te wywołania obecnie zgłaszają jawne błędy braku obsługi:

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

Pola workspace, runtime, environment i approvals dla przebiegu są typowane jako przyszły kształt, ale obecny Gateway nie obsługuje tych nadpisań w RPC agent. Jeśli wywołujący je przekażą, SDK zgłasza wyjątek przed przesłaniem przebiegu, aby praca nie została przypadkowo wykonana z domyślnym obszarem roboczym, środowiskiem wykonawczym, środowiskiem lub zachowaniem zatwierdzeń.

App SDK kontra Plugin SDK

Użyj App SDK, gdy kod działa poza OpenClaw:

• skrypty Node, które uruchamiają lub obserwują przebiegi agentów
• zadania CI, które wywołują Gateway
• pulpity i panele administracyjne
• rozszerzenia IDE
• zewnętrzne mosty, które nie muszą stawać się Pluginami kanałów
• testy integracyjne z fałszywymi lub rzeczywistymi transportami Gateway

Użyj Plugin SDK, gdy kod działa wewnątrz OpenClaw:

• Pluginy dostawców
• Pluginy kanałów
• hooki narzędzi lub cyklu życia
• Pluginy uprzęży agentów
• zaufane pomocniki środowiska wykonawczego

Kod App SDK powinien importować z @openclaw/sdk. Kod Pluginów powinien importować z udokumentowanych ścieżek podrzędnych openclaw/plugin-sdk/*. Nie mieszaj tych dwóch kontraktów.

Powiązane

• Projekt API OpenClaw App SDK
• Dokumentacja referencyjna RPC Gateway
• Pętla agenta
• Środowiska uruchomieniowe agentów
• Sesje
• Zadania w tle
• Agenci ACP
• Przegląd SDK Plugin