SDK застосунку OpenClaw

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

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

@openclaw/sdk постачається з:

SDK також експортує основні типи, які використовують ці інтерфейси: 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 і пов’язані типи результатів.

Під’єднання до Gateway

Створіть клієнт із явною URL-адресою Gateway або інжектуйте власний транспорт для тестів і вбудованих середовищ виконання застосунків.

 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://..." }) еквівалентний 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), коли застосунку потрібен handle агента, а потім викличте 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 override-и provider і model. timeoutMs у SDK залишається в мілісекундах і перетворюється на секунди тайм-ауту Gateway для RPC agent.

run.wait() використовує RPC Gateway agent.wait. Дедлайн очікування, який спливає, поки виконання ще активне, повертає status: "accepted", а не вдає, що саме виконання вичерпало час. Тайм-аути середовища виконання, перервані виконання та скасовані виконання нормалізуються до 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. Handles сесій також підтримують:

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;};

Поширені типи подій включають:

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, ефективний вигляд інструментів і прямий виклик інструмента Gateway. oc.tools.invoke() повертає типізовану оболонку замість викидання винятку для відмов політики або схвалення.

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

Помічники артефактів відкривають проєкцію артефактів Gateway для контексту сесії, виконання або завдання. Кожен виклик потребує одного явного scope sessionKey, runId або 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);}

Помічники схвалень використовують RPC схвалень exec:

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

Помічники завдань використовують довговічний журнал завдань, який також лежить в основі 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" });

Помічники середовищ надають доступ до read-only виявлення локальних для Gateway та вузлових середовищ:

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

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

SDK містить назви для моделі продукту, якої ми прагнемо, але не мовчки вдає, що RPC Gateway існують. Ці виклики зараз викидають явні помилки про непідтримуваність:

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

Поля для окремого виконання workspace, runtime, environment і approvals типізовані як майбутня форма, але поточний Gateway не підтримує ці override-и в RPC agent. Якщо викликачі передають їх, SDK викидає помилку до надсилання виконання, щоб робота випадково не виконалася з типовою поведінкою workspace, runtime, environment або approval.

App SDK проти Plugin SDK

Використовуйте App SDK, коли код живе поза OpenClaw:

• сценарії Node, які запускають або спостерігають виконання агентів
• завдання CI, які викликають Gateway
• панелі керування та адміністративні панелі
• розширення IDE
• зовнішні мости, яким не потрібно ставати channel plugins
• інтеграційні тести з фейковими або справжніми транспортами Gateway

Використовуйте Plugin SDK, коли код працює всередині OpenClaw:

• provider plugins
• channel plugins
• hooks інструментів або життєвого циклу
• plugins агентного harness
• довірені runtime-помічники

Код App SDK має імпортувати з @openclaw/sdk. Код Plugin має імпортувати з документованих підшляхів openclaw/plugin-sdk/*. Не змішуйте ці два контракти.

Пов’язане

• Проєктування API OpenClaw App SDK
• Довідник RPC Gateway
• Цикл агента
• Середовища виконання агентів
• Сеанси
• Фонові завдання
• Агенти ACP
• Огляд Plugin SDK