Przejdź do głównej treści

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.

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.
App SDK różni się od Plugin SDK. @openclaw/sdk komunikuje się z Gateway spoza OpenClaw. openclaw/plugin-sdk/* jest przeznaczone tylko dla pluginów uruchamianych wewnątrz OpenClaw, które rejestrują dostawców, kanały, narzędzia, hooki lub zaufane środowiska wykonawcze.

Co jest dziś dostarczane

@openclaw/sdk zawiera:
PowierzchniaStatusCo robi
OpenClawGotoweGłówny punkt wejścia klienta. Odpowiada za transport, połączenie, żądania i zdarzenia.
GatewayClientTransportGotoweTransport WebSocket oparty na kliencie Gateway.
oc.agentsGotoweWyświetla, tworzy, aktualizuje, usuwa i pobiera uchwyty agentów.
Agent.run()GotoweUruchamia przebieg Gateway agent i zwraca Run.
oc.runsGotoweTworzy, pobiera, oczekuje na, anuluje i strumieniuje przebiegi.
Run.events()GotoweStrumieniuje znormalizowane zdarzenia dla przebiegu z odtworzeniem dla szybkich przebiegów.
Run.wait()GotoweWywołuje agent.wait i zwraca stabilny RunResult.
Run.cancel()GotoweWywołuje sessions.abort według identyfikatora przebiegu, z kluczem sesji, gdy jest dostępny.
oc.sessionsGotoweTworzy, rozwiązuje, wysyła do, łata, kompaktuje i pobiera uchwyty sesji.
Session.send()GotoweWywołuje sessions.send i zwraca Run.
oc.tasksGotoweWyświetla, odczytuje i anuluje wpisy rejestru zadań Gateway.
oc.modelsGotoweWywołuje models.list oraz bieżące RPC statusu models.authStatus.
oc.toolsGotoweWyświetla, zakresuje i wywołuje narzędzia Gateway przez potok polityk.
oc.artifactsGotoweWyświetla, pobiera i pobiera do pliku artefakty transkrypcji Gateway.
oc.approvalsGotoweWyświetla i rozwiązuje zatwierdzenia exec przez RPC zatwierdzeń Gateway.
oc.environmentsCzęścioweWyświetla lokalne dla Gateway i węzłowe kandydaty środowisk; tworzenie/usuwanie nie są podłączone.
oc.rawEvents()GotoweUdostępnia surowe zdarzenia Gateway dla zaawansowanych odbiorców.
normalizeGatewayEvent()GotoweKonwertuje surowe zdarzenia Gateway na stabilny kształt zdarzeń SDK.
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.
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://..." }) 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ą:
Typ zdarzeniaZdarzenie źródłowe Gateway
run.startedstart cyklu życia agent
run.completedkoniec cyklu życia agent
run.failedbłąd cyklu życia agent
run.cancelledkoniec cyklu życia po przerwaniu/anulowaniu
run.timed_outkoniec cyklu życia po limicie czasu
assistant.deltadelta strumieniowania asystenta
assistant.messagewiadomość asystenta
thinking.deltastrumień myślenia lub planu
tool.call.startedstart narzędzia/elementu/polecenia
tool.call.deltaaktualizacja narzędzia/elementu/polecenia
tool.call.completedukończenie narzędzia/elementu/polecenia
tool.call.failedniepowodzenie narzędzia/elementu/polecenia albo status zablokowany
approval.requestedżądanie zatwierdzenia exec lub pluginu
approval.resolvedrozwiązanie zatwierdzenia exec lub pluginu
session.createdutworzenie sessions.changed
session.updatedaktualizacja sessions.changed
session.compactedCompaction sessions.changed
task.updatedzdarzenia aktualizacji zadania
artifact.updatedzdarzenia strumienia łat
rawdowolne zdarzenie bez stabilnego mapowania SDK
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