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

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 і реєструють провайдерів, канали, інструменти, hooks або довірені середовища виконання.

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

@openclaw/sdk постачається з:
ІнтерфейсСтанЩо він робить
OpenClawГотовоОсновна точка входу клієнта. Керує транспортом, з’єднанням, запитами та подіями.
GatewayClientTransportГотовоWebSocket-транспорт на базі клієнта Gateway.
oc.agentsГотовоПерелічує, створює, оновлює, видаляє та отримує handles агентів.
Agent.run()ГотовоЗапускає виконання Gateway agent і повертає Run.
oc.runsГотовоСтворює, отримує, очікує, скасовує та транслює виконання.
Run.events()ГотовоТранслює нормалізовані події для окремого виконання з повтором для швидких виконань.
Run.wait()ГотовоВикликає agent.wait і повертає стабільний RunResult.
Run.cancel()ГотовоВикликає sessions.abort за id виконання, з ключем сесії, коли він доступний.
oc.sessionsГотовоСтворює, розв’язує, надсилає до, патчить, стискає та отримує handles сесій.
Session.send()ГотовоВикликає sessions.send і повертає Run.
oc.tasksГотовоПерелічує, читає та скасовує записи журналу завдань Gateway.
oc.modelsГотовоВикликає models.list і поточний статусний RPC models.authStatus.
oc.toolsГотовоПерелічує, задає scopes і викликає інструменти Gateway через конвеєр політик.
oc.artifactsГотовоПерелічує, отримує та завантажує артефакти транскриптів Gateway.
oc.approvalsГотовоПерелічує та розв’язує схвалення exec через RPC схвалень Gateway.
oc.environmentsЧастковоПерелічує локальні для Gateway та вузлові кандидати середовищ; create/delete ще не під’єднані.
oc.rawEvents()ГотовоНадає сирі події Gateway для просунутих споживачів.
normalizeGatewayEvent()ГотовоПеретворює сирі події Gateway на стабільну форму подій 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 або інжектуйте власний транспорт для тестів і вбудованих середовищ виконання застосунків.
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://..." }) еквівалентний 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;
};
Поширені типи подій включають:
Тип подіїВихідна подія Gateway
run.startedПочаток життєвого циклу agent
run.completedЗавершення життєвого циклу agent
run.failedПомилка життєвого циклу agent
run.cancelledЗавершення життєвого циклу після переривання/скасування
run.timed_outЗавершення життєвого циклу через тайм-аут
assistant.deltaStreaming delta асистента
assistant.messageПовідомлення асистента
thinking.deltaThinking або потік плану
tool.call.startedПочаток інструмента/елемента/команди
tool.call.deltaОновлення інструмента/елемента/команди
tool.call.completedЗавершення інструмента/елемента/команди
tool.call.failedЗбій інструмента/елемента/команди або заблокований статус
approval.requestedЗапит схвалення exec або plugin
approval.resolvedРозв’язання схвалення exec або plugin
session.createdСтворення sessions.changed
session.updatedОновлення sessions.changed
session.compactedCompaction sessions.changed
task.updatedПодії оновлення завдання
artifact.updatedПодії потоку patch
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, ефективний вигляд інструментів і прямий виклик інструмента 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/*. Не змішуйте ці два контракти.

Пов’язане