Перейти до основного вмісту

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.

OpenClaw App SDK — це публічний клієнтський API для застосунків поза процесом OpenClaw. Використовуйте @openclaw/sdk, коли скрипт, панель керування, завдання CI, розширення IDE або інший зовнішній застосунок має підключатися до Gateway, запускати виконання агентів, транслювати події, чекати на результати, скасовувати роботу або перевіряти ресурси Gateway.
App SDK відрізняється від Plugin SDK. @openclaw/sdk взаємодіє з Gateway ззовні OpenClaw. openclaw/plugin-sdk/* призначений лише для plugins, які працюють усередині OpenClaw і реєструють провайдерів, канали, інструменти, хуки або довірені runtime-середовища.

Що постачається сьогодні

@openclaw/sdk постачається з:
ІнтерфейсСтанЩо він робить
OpenClawГотовоОсновна точка входу клієнта. Керує транспортом, підключенням, запитами та подіями.
GatewayClientTransportГотовоWebSocket-транспорт на основі клієнта Gateway.
oc.agentsГотовоПерелічує, створює, оновлює, видаляє та отримує дескриптори агентів.
Agent.run()ГотовоЗапускає виконання Gateway agent і повертає Run.
oc.runsГотовоСтворює, отримує, очікує, скасовує та транслює виконання.
Run.events()ГотовоТранслює нормалізовані події для окремого виконання з повторним відтворенням для швидких виконань.
Run.wait()ГотовоВикликає agent.wait і повертає стабільний RunResult.
Run.cancel()ГотовоВикликає sessions.abort за id виконання, із ключем сесії, коли він доступний.
oc.sessionsГотовоСтворює, вирішує, надсилає до, виправляє, ущільнює та отримує дескриптори сесій.
Session.send()ГотовоВикликає sessions.send і повертає Run.
oc.modelsГотовоВикликає models.list і поточний статусний RPC models.authStatus.
oc.toolsЧастковоПерелічує каталог інструментів і ефективні інструменти; прямий виклик інструментів не підключено.
oc.approvalsГотовоПерелічує та вирішує схвалення виконання через RPC схвалень Gateway.
oc.rawEvents()ГотовоНадає необроблені події Gateway для просунутих споживачів.
normalizeGatewayEvent()ГотовоПеретворює необроблені події Gateway у стабільну форму подій SDK.
SDK також експортує основні типи, які використовують ці інтерфейси: AgentRunParams, RunResult, RunStatus, OpenClawEvent, OpenClawEventType, GatewayEvent, OpenClawTransport, GatewayRequestOptions, SessionCreateParams, SessionSendParams, RuntimeSelection, EnvironmentSelection, WorkspaceSelection, ApprovalMode і пов’язані типи результатів.

Підключення до Gateway

Створіть клієнт із явною URL-адресою Gateway або інжектуйте власний транспорт для тестів і runtime-середовищ вбудованих застосунків.
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://..." }) еквівалентний url. Параметр gateway: "auto" приймається конструктором, але автоматичне виявлення Gateway ще не є окремою функцією SDK; передавайте url, коли застосунок ще не знає, як виявити Gateway. Для тестів передайте об’єкт, який реалізує OpenClawTransport:
const oc = new OpenClaw({
  transport: {
    async request(method, params) {
      return { method, params };
    },
    async *events() {},
  },
});

Запуск агента

Використовуйте oc.agents.get(id), коли застосунку потрібен дескриптор агента, а потім викликайте 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);
Посилання на моделі з указанням провайдера, як-от openai/gpt-5.5, розділяються на перевизначення Gateway provider і model. timeoutMs залишається в мілісекундах у SDK і перетворюється на секунди тайм-ауту Gateway для RPC agent. run.wait() використовує RPC Gateway agent.wait. Якщо дедлайн очікування спливає, поки виконання все ще активне, повертається status: "accepted" замість удавання, що саме виконання вичерпало час. Тайм-аути runtime-середовища, перервані виконання та скасовані виконання нормалізуються в timed_out або cancelled.

Створення та повторне використання сесій

Використовуйте сесії, коли застосунку потрібен сталий стан транскрипту.
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() викликає sessions.send і повертає Run. Дескриптори сесій також підтримують:
await session.abort(run.id);
await session.patch({ label: "renamed-session" });
await session.compact({ maxLines: 200 });

Трансляція подій

SDK нормалізує необроблені події Gateway у стабільну оболонку 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;
};
Поширені типи подій:
Тип подіїВихідна подія Gateway
run.startedПочаток життєвого циклу agent
run.completedЗавершення життєвого циклу agent
run.failedПомилка життєвого циклу agent
run.cancelledЗавершення життєвого циклу після переривання/скасування
run.timed_outЗавершення життєвого циклу через тайм-аут
assistant.deltaПотокова дельта асистента
assistant.messageПовідомлення асистента
thinking.deltaПотік міркування або плану
tool.call.startedПочаток інструмента/елемента/команди
tool.call.deltaОновлення інструмента/елемента/команди
tool.call.completedЗавершення інструмента/елемента/команди
tool.call.failedЗбій інструмента/елемента/команди або заблокований статус
approval.requestedЗапит на схвалення виконання або Plugin
approval.resolvedРішення щодо схвалення виконання або Plugin
session.createdСтворення sessions.changed
session.updatedОновлення sessions.changed
session.compactedУщільнення sessions.changed
task.updatedПодії оновлення завдань
artifact.updatedПодії потоку патчів
rawБудь-яка подія, що ще не має стабільного зіставлення SDK
Run.events() фільтрує події до одного id виконання та повторно відтворює вже побачені події для швидких виконань. Це означає, що задокументований потік безпечний:
const run = await agent.run("Summarize the latest session.");

for await (const event of run.events()) {
  if (event.type === "run.completed") {
    break;
  }
}
Для потоків на рівні всього застосунку використовуйте oc.events(). Для необроблених кадрів Gateway використовуйте oc.rawEvents().

Моделі, інструменти та схвалення

Допоміжні методи моделей зіставляються з поточними методами Gateway:
await oc.models.list();
await oc.models.status({ probe: false }); // calls models.authStatus
Допоміжні методи інструментів надають каталог Gateway і представлення ефективних інструментів:
await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });
Допоміжні методи схвалень використовують RPC схвалень виконання:
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });

Явно не підтримується сьогодні

SDK містить назви для моделі продукту, яку ми хочемо, але не вдає непомітно, що RPC Gateway існують. Наразі ці виклики викидають явні помилки непідтримуваності:
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");
Поля workspace, runtime, environment і approvals для окремого виконання типізовані як майбутня форма, але поточний Gateway не підтримує ці перевизначення в RPC agent. Якщо викликачі передають їх, SDK викидає помилку до надсилання виконання, щоб робота випадково не виконалася зі стандартною поведінкою workspace, runtime-середовища, environment або схвалень.

App SDK і Plugin SDK

Використовуйте App SDK, коли код працює поза OpenClaw:
  • Node-скрипти, які запускають або спостерігають за виконаннями агентів
  • завдання CI, які викликають Gateway
  • панелі керування та адміністративні панелі
  • розширення IDE
  • зовнішні мости, яким не потрібно ставати канальними plugins
  • інтеграційні тести з фіктивними або реальними транспортами Gateway
Використовуйте Plugin SDK, коли код працює всередині OpenClaw:
  • plugins провайдерів
  • канальні plugins
  • інструментальні або життєво-циклові хуки
  • plugins обв’язки агентів
  • довірені допоміжні засоби runtime-середовища
Код App SDK має імпортувати з @openclaw/sdk. Код Plugin має імпортувати з задокументованих підшляхів openclaw/plugin-sdk/*. Не змішуйте ці два контракти.

Пов’язані документи