diff --git a/docs/uk/concepts/openclaw-sdk.md b/docs/uk/concepts/openclaw-sdk.md
index eb2157127..c5d01f350 100644
--- a/docs/uk/concepts/openclaw-sdk.md
+++ b/docs/uk/concepts/openclaw-sdk.md
@@ -1,119 +1,126 @@
---
read_when:
- - Ви проєктуєте або реалізуєте публічний SDK для застосунків OpenClaw
- - Ви порівнюєте API агентів OpenClaw з Cursor, Claude Agent SDK, OpenAI Agents, Google ADK, OpenCode, Codex або ACP
- - Потрібно визначити, чи належить можливість до публічного SDK застосунку, Plugin SDK, протоколу Gateway, бекенду ACP або шару керованого середовища
-summary: Проєктна пропозиція щодо публічного SDK застосунків OpenClaw для запусків агентів, сеансів, завдань, артефактів і керованих середовищ
-title: Дизайн SDK OpenClaw
+ - Ви проєктуєте або реалізуєте публічний SDK застосунку OpenClaw
+ - Ви порівнюєте API агентів OpenClaw із Cursor, Claude Agent SDK, OpenAI Agents, Google ADK, OpenCode, Codex або ACP
+ - Потрібно вирішити, чи належить можливість до публічного App SDK, Plugin SDK, протоколу Gateway, бекенду ACP або шару керованого середовища
+sidebarTitle: App SDK
+summary: Дизайн публічного SDK застосунків OpenClaw для зовнішніх застосунків, скриптів, панелей моніторингу, завдань CI та розширень IDE
+title: SDK застосунків OpenClaw
x-i18n:
- generated_at: "2026-04-29T23:55:40Z"
+ generated_at: "2026-04-30T00:49:49Z"
model: gpt-5.5
provider: openai
- source_hash: ffd4380e556e0e2e1218acaa9e5934e8b308b3420aa25a6d2598d35c7f9a7ab2
+ source_hash: 227d3baf3aaf54bf35288214b051e2e284280165e1283d476594feda26d56bb9
source_path: concepts/openclaw-sdk.md
workflow: 16
---
-Ця сторінка є проєктною пропозицією для майбутнього публічного **SDK застосунків OpenClaw**. Вона
-окрема від наявного [Plugin SDK](/uk/plugins/sdk-overview).
+Ця сторінка є проєктною пропозицією для публічного **OpenClaw App SDK**. Вона
+відокремлена від наявного [Plugin SDK](/uk/plugins/sdk-overview).
-Plugin SDK призначений для коду, який виконується всередині OpenClaw і розширює провайдерів,
-канали, інструменти, хуки та довірені середовища виконання. SDK застосунків має бути призначений для
-зовнішніх застосунків, скриптів, інформаційних панелей, завдань CI, розширень IDE та
-систем автоматизації, які хочуть запускати й спостерігати за агентами OpenClaw через стабільний
+
+ Використовуйте `@openclaw/sdk`, коли зовнішній застосунок, скрипт, dashboard, CI job або IDE
+ extension хоче запускати агентів OpenClaw і спостерігати за ними через Gateway. Використовуйте
+ `openclaw/plugin-sdk/*` лише під час написання Plugin, який працює всередині OpenClaw.
+
+
+Plugin SDK призначений для коду, який працює всередині OpenClaw і розширює providers,
+channels, tools, hooks і trusted runtimes. App SDK має бути призначений для
+зовнішніх застосунків, скриптів, dashboards, CI jobs, IDE extensions і
+систем автоматизації, які хочуть запускати агентів OpenClaw і спостерігати за ними через стабільний
публічний API.
## Статус
Чернетка архітектури.
-Цей документ фіксує напрям дизайну з порівняльного огляду цих
-SDK агентів і поверхонь середовища виконання:
+Цей документ фіксує напрям дизайну на основі порівняльного огляду цих
+agent SDK і runtime surfaces:
| Проєкт | Корисний висновок |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Cursor SDK cookbook | Найкращий високорівневий продуктовий API: `Agent`, `Run`, локальні та хмарні середовища виконання, потокова передача, скасування, виявлення моделей, репозиторії, артефакти та хмарні потоки pull request. |
-| Claude Agent SDK | Сильний двонапрямний клієнт сесії, підтримка переривання й керування, режими дозволів, хуки, користувацькі інструменти, сховища сесій і відновлювані транскрипти. |
-| OpenAI Agents SDK | Сильні концепції робочих процесів: передавання керування, запобіжники, людські схвалення, трасування, стан запуску, об’єкти результатів потокової передачі та відновлення після переривань. |
-| Google ADK | Сильна внутрішня архітектура: runner, сервіс сесій, сервіс пам’яті, сервіс артефактів, сервіс облікових даних, Plugins, дії подій і підтвердження довготривалих інструментів. |
-| OpenCode | Сильна форма клієнт/сервер: згенерований API-клієнт, REST плюс SSE, сесії, робочі простори, worktrees, дозволи, запитання, файли, VCS, PTY, інструменти, агенти, Skills і MCP. |
-| Codex | Сильна межа локального середовища виконання: схвалення, ізоляція sandbox, мережева політика, локальні та віддалені сервери exec, структуровані події протоколу та сесії app-server з урахуванням тредів. |
-| ACP and acpx | Сильний шар взаємодії для зовнішніх coding harnesses з іменованими сесіями, чергами підказок, кооперативним скасуванням і адаптерами середовища виконання. |
+| Cursor SDK cookbook | Найкращий високорівневий продуктовий API: `Agent`, `Run`, локальні та хмарні runtimes, streaming, cancellation, model discovery, repositories, artifacts і cloud pull request flows. |
+| Claude Agent SDK | Потужний двоспрямований session client, підтримка interrupt і steer, permission modes, hooks, custom tools, session stores і resumable transcripts. |
+| OpenAI Agents SDK | Сильні концепції workflow: handoffs, guardrails, human approvals, tracing, run state, streaming result objects і resume after interruptions. |
+| Google ADK | Потужна внутрішня архітектура: runner, session service, memory service, artifact service, credential service, plugins, event actions і long running tool confirmations. |
+| OpenCode | Сильна форма client/server: generated API client, REST plus SSE, sessions, workspaces, worktrees, permissions, questions, files, VCS, PTY, tools, agents, skills і MCP. |
+| Codex | Сильна межа локального runtime: approvals, sandboxing, network policy, локальні та віддалені exec servers, structured protocol events і thread aware app-server sessions. |
+| ACP і acpx | Сильний шар сумісності для зовнішніх coding harnesses із named sessions, prompt queues, cooperative cancellation і runtime adapters. |
-Рекомендація полягає в тому, щоб побудувати простий, як у Cursor, публічний фасад поверх
-згенерованого клієнта Gateway у стилі OpenCode, зберігаючи концепції Claude, OpenAI Agents,
-ADK, Codex і ACP як внутрішні проєктні орієнтири там, де вони доречні.
+Рекомендація полягає в тому, щоб побудувати публічний facade у стилі Cursor-simple поверх
+згенерованого Gateway client у стилі OpenCode, зберігаючи концепції Claude, OpenAI Agents,
+ADK, Codex і ACP як внутрішні дизайнерські орієнтири там, де вони доречні.
## Цілі
-- Надати розробникам застосунків мінімальний високорівневий API для запуску агентів OpenClaw.
-- Зберегти локальний за замовчуванням OpenClaw як стандартне середовище виконання.
-- Зробити хмарні або керовані середовища додатковим провайдером середовища, а не
- іншим API агента.
-- Зберегти наявні межі OpenClaw: Gateway володіє публічним протоколом, Plugin
- SDK володіє внутрішньопроцесними розширеннями, ACP володіє взаємодією із зовнішніми harnesses.
-- Підтримувати `stream`, `wait`, `cancel`, `resume`, `fork`, артефакти, схвалення
- та фонові завдання як першокласні операції.
-- Надавати стабільні нормалізовані події, зберігаючи водночас сирі події, нативні для середовища виконання, для
+- Дати розробникам застосунків мінімальний високорівневий API для запуску агентів OpenClaw.
+- Зберегти local-first OpenClaw як runtime за замовчуванням.
+- Зробити хмарні або managed environments додатковим environment provider, а не
+ іншим agent API.
+- Зберегти наявні межі OpenClaw: Gateway володіє публічним protocol, plugin
+ SDK володіє in-process extensions, ACP володіє interop із external harness.
+- Підтримувати `stream`, `wait`, `cancel`, `resume`, `fork`, artifacts, approvals,
+ і background tasks як першокласні операції.
+- Надавати стабільні нормалізовані events, зберігаючи runtime-native raw events для
просунутих споживачів.
-- Зробити дозволи SDK, передавання секретів, схвалення, sandboxing і віддалені
- середовища явними.
+- Зробити SDK permissions, secret forwarding, approvals, sandboxing і remote
+ environments явними.
- Зберегти публічний контракт достатньо малим, щоб його можна було документувати, тестувати, версіонувати та
генерувати.
## Нецілі
-- Не відкривати `openclaw/plugin-sdk/*` як SDK застосунків.
-- Не робити ACP єдиною моделлю середовища виконання.
-- Не вимагати хмарного сервісу до того, як SDK стане корисним.
+- Не відкривати `openclaw/plugin-sdk/*` як app SDK.
+- Не робити ACP єдиною runtime model.
+- Не вимагати cloud service до того, як SDK стане корисним.
- Не клонувати API Cursor, Claude, OpenAI, ADK, OpenCode, Codex або ACP
- буквально.
-- Не відкривати необмежені payloads подій `any` як єдиний публічний контракт.
-- Не обіцяти ізоляцію sandbox або мережеву ізоляцію для зовнішнього harness, якщо
- вибране середовище не може фактично її забезпечити.
-- Не змушувати авторів Plugin залежати від об’єктів SDK застосунків усередині коду
- середовища виконання Plugin.
+ дослівно.
+- Не виставляти необмежені payloads подій `any` як єдиний публічний контракт.
+- Не обіцяти sandbox або network isolation для external harness, якщо
+ вибране середовище не може реально це забезпечити.
+- Не змушувати авторів plugin залежати від об’єктів app SDK всередині runtime
+ code plugin.
## Поточна відповідність OpenClaw
-OpenClaw уже має більшу частину основи:
+OpenClaw уже має більшість основи:
-| Наявна поверхня | Що вона дає |
+| Наявна surface | Що вона дає |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| [Цикл агента](/uk/concepts/agent-loop) | Життєвий цикл запуску `agent` і `agent.wait`, потокова передача, тайм-аут і серіалізація сесії. |
-| [Середовища виконання агентів](/uk/concepts/agent-runtimes) | Розділення провайдера, моделі, середовища виконання та каналу. |
-| [Агенти ACP](/uk/tools/acp-agents) | Сесії зовнішніх harnesses для Claude Code, Cursor, Gemini CLI, OpenCode, явного Codex ACP та подібних інструментів. |
-| [Фонові завдання](/uk/automation/tasks) | Відокремлений журнал активності для ACP, субагентів, Cron, операцій CLI та асинхронних медіазавдань. |
-| [Субагенти](/uk/tools/subagents) | Ізольовані фонові запуски агентів, необов’язковий forked context, доставлення назад у сесії запитувача. |
-| [Plugins harness агентів](/uk/plugins/sdk-agent-harness) | Реєстрація довіреного нативного середовища виконання для вбудованих harnesses, таких як Codex. |
-| Схеми протоколу Gateway | Поточні типізовані визначення методів і подій для параметрів агентів, сесій, підписок, переривань, Compaction і контрольних точок. |
+| [Agent loop](/uk/concepts/agent-loop) | Життєвий цикл запуску `agent` і `agent.wait`, streaming, timeout і session serialization. |
+| [Agent runtimes](/uk/concepts/agent-runtimes) | Розділення provider, model, runtime і channel. |
+| [ACP agents](/uk/tools/acp-agents) | Sessions зовнішнього harness для Claude Code, Cursor, Gemini CLI, OpenCode, explicit Codex ACP і подібних інструментів. |
+| [Background tasks](/uk/automation/tasks) | Відокремлений ledger активності для ACP, subagents, Cron, CLI operations і async media jobs. |
+| [Sub-agents](/uk/tools/subagents) | Ізольовані фонові agent runs, optional forked context, доставка назад у requester sessions. |
+| [Agent harness plugins](/uk/plugins/sdk-agent-harness) | Реєстрація trusted native runtime для embedded harnesses, таких як Codex. |
+| Gateway protocol schemas | Поточні типізовані визначення method і event для agent params, sessions, subscriptions, aborts, Compaction і checkpoints. |
-Прогалина не в запуску агентів. Прогалина в стабільному, зручному публічному фасаді поверх
-цих частин.
+Прогалина не в agent execution. Прогалина — у стабільному, зручному публічному facade над
+цими компонентами.
-## Базова модель
+## Основна модель
-SDK застосунків має використовувати невеликий набір стійких іменників.
+App SDK має використовувати невеликий набір стійких іменників.
| Іменник | Значення |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `OpenClaw` | Точка входу клієнта. Володіє виявленням Gateway, автентифікацією, низькорівневим доступом клієнта та фабриками просторів імен. |
-| `Agent` | Налаштований актор. Містить id агента, модель за замовчуванням, середовище виконання за замовчуванням, політику інструментів за замовчуванням і помічники для застосунків. |
-| `Session` | Стійкий транскрипт, маршрутизація, робочий простір, контекст і прив’язка середовища виконання. |
-| `Run` | Один надісланий хід або завдання. Потоково передає події, очікує на результат, скасовує та відкриває артефакти. |
-| `Task` | Запис у журналі відокремленої або фонової активності. Охоплює субагентів, породження ACP, завдання Cron, запуски CLI та асинхронні завдання. |
-| `Artifact` | Файли, патчі, diff-и, медіа, журнали, траєкторії, pull requests, знімки екрана та згенеровані bundles. |
-| `Environment` | Де виконується запуск: локальний Gateway, локальний робочий простір, хост node, ACP harness, керований runner або майбутній хмарний робочий простір. |
-| `ToolSpace` | Ефективна поверхня інструментів: інструменти OpenClaw, сервери MCP, інструменти каналів, інструменти застосунків, правила схвалення та метадані інструментів. |
-| `Approval` | Рішення людини або політики, запитане запуском, інструментом, середовищем або harness. |
+| `OpenClaw` | Точка входу клієнта. Володіє Gateway discovery, auth, low-level client access і namespace factories. |
+| `Agent` | Налаштований actor. Містить agent id, default model, default runtime, default tool policy і app-facing helpers. |
+| `Session` | Стійкий transcript, routing, workspace, context і runtime binding. |
+| `Run` | Один надісланий turn або task. Streams events, waits for result, cancels і exposes artifacts. |
+| `Task` | Detached або background activity ledger entry. Охоплює subagents, ACP spawns, Cron jobs, CLI runs і async jobs. |
+| `Artifact` | Files, patches, diffs, media, logs, trajectories, pull requests, screenshots і generated bundles. |
+| `Environment` | Де виконується run: local Gateway, local workspace, node host, ACP harness, managed runner або майбутній cloud workspace. |
+| `ToolSpace` | Ефективна tool surface: OpenClaw tools, MCP servers, channel tools, app tools, approval rules і tool metadata. |
+| `Approval` | Рішення людини або політики, запитане run, tool, environment або harness. |
-Ці іменники чисто відображаються на наявні концепції OpenClaw, але не розкривають
-назви, специфічні для реалізації, такі як внутрішні деталі PI runner, реєстрація Plugin harness
-або деталі адаптера ACP.
+Ці іменники добре мапляться на наявні концепції OpenClaw, але не розкривають
+implementation-specific names, такі як внутрішні механізми PI runner, реєстрація plugin harness
+або деталі ACP adapter.
## Форма продукту
-Високорівневий SDK має виглядати так:
+Високорівневий SDK має відчуватися так:
```typescript
import { OpenClaw } from "@openclaw/sdk";
@@ -136,7 +143,7 @@ const result = await run.wait();
console.log(result.status);
```
-Той самий застосунок має вміти використовувати стійкий сеанс:
+Той самий застосунок має мати змогу використовувати durable session:
```typescript
const session = await oc.sessions.create({
@@ -148,9 +155,16 @@ const run = await session.send("Prepare release notes from the current diff.");
await run.wait();
```
-Примітка щодо поточної реалізації: `@openclaw/sdk` починає з поверхні, підтримуваної Gateway, яка існує сьогодні. Посилання на моделі з уточненням провайдера, як-от `openai/gpt-5.5`, розділяються на перевизначення Gateway `provider` і `model`. Вибір `workspace`, `runtime`, `environment` і `approvals` для окремого запуску все ще є цільовим дизайном; клієнт викидає помилку, коли викликачі задають їх, щоб запити не виконувалися мовчки зі значеннями за замовчуванням. Допоміжні засоби для завдань, артефактів, середовищ і загального виклику інструментів також заготовлені як майбутня форма API та викидають явні помилки про непідтримуваність, доки для них не з’являться Gateway RPC.
+Поточна примітка щодо реалізації: `@openclaw/sdk` починається з Gateway-backed
+surface, яка існує сьогодні. Provider-qualified model refs, такі як
+`openai/gpt-5.5`, розділяються на Gateway `provider` і `model` overrides.
+Per-run вибори `workspace`, `runtime`, `environment` і `approvals` усе ще є
+дизайнерськими цілями; клієнт кидає помилку, коли callers задають їх, щоб requests не
+виконувалися мовчки з defaults. Task, artifact, environment і generic tool
+invocation helpers також scaffolded як майбутня форма API і кидають явні
+unsupported errors, доки для них не існує Gateway RPCs.
-І той самий API має вміти використовувати зовнішній ACP harness:
+І той самий API має мати змогу використовувати зовнішній ACP harness:
```typescript
const run = await oc.runs.create({
@@ -161,7 +175,7 @@ const run = await oc.runs.create({
});
```
-Керовані середовища не мають змінювати API верхнього рівня:
+Managed environments не мають змінювати top-level API:
```typescript
const run = await agent.run({
@@ -175,9 +189,9 @@ const run = await agent.run({
});
```
-## Вибір середовища виконання
+## Вибір runtime
-SDK застосунку має надавати вибір середовища виконання як нормалізоване об’єднання:
+App SDK має надавати вибір runtime як normalized union:
```typescript
type RuntimeSelection =
@@ -190,17 +204,22 @@ type RuntimeSelection =
Правила:
-- `auto` дотримується правил вибору середовища виконання OpenClaw.
-- `embedded` націлюється на довірені внутрішньопроцесні harnesses, зареєстровані через plugin SDK, як-от `pi` або `codex`.
-- `cli` націлюється на виконання через CLI backend, що належить OpenClaw, де це доступно.
+- `auto` дотримується правил вибору runtime OpenClaw.
+- `embedded` націлюється на trusted in-process harnesses, зареєстровані через plugin
+ SDK, такі як `pi` або `codex`.
+- `cli` націлюється на OpenClaw-owned CLI backend execution там, де вона доступна.
- `acp` націлюється на зовнішні harnesses через ACP/acpx.
-- `managed` націлюється на провайдера середовища й усе ще може запускати embedded, CLI або ACP runtime всередині цього середовища.
+- `managed` націлюється на environment provider і все ще може запускати embedded,
+ CLI або ACP runtime всередині цього environment.
-Об’єкт вибору середовища виконання має бути описовим. Це не має бути місцем, де приховуються обробка секретів, політика пісочниці або підготовка робочого простору.
+Об’єкт вибору runtime має бути описовим. Він не має бути місцем,
+де ховаються secret handling, sandbox policy або workspace provisioning.
-## Модель середовища
+## Модель environment
-Середовище є субстратом виконання. Воно має бути явним, оскільки локальні CLI-запуски, зовнішні harnesses, хости node і хмарні робочі простори мають різні властивості безпеки та життєвого циклу.
+Environment — це execution substrate. Він має бути явним, оскільки локальні
+CLI runs, external harnesses, node hosts і cloud workspaces мають різні
+властивості безпеки та життєвого циклу.
```typescript
type EnvironmentSelection =
@@ -211,40 +230,43 @@ type EnvironmentSelection =
| { type: "ephemeral"; provider: string; repo?: string; ref?: string };
```
-Середовище відповідає за:
+Environment володіє:
-- підготовку checkout або робочого простору
-- доступ до процесів і файлів
-- застосування пісочниці та мережевих обмежень
-- змінні середовища та посилання на секрети
-- журнали, трасування й артефакти
-- очищення та зберігання
-- доступність середовища виконання
+- підготовкою checkout або workspace
+- доступом до процесів і файлів
+- забезпеченням sandbox і network
+- environment variables і secret references
+- logs, traces і artifacts
+- cleanup і retention
+- availability runtime
-Такий поділ робить керованих агентів природним розширенням SDK. Керований агент — це звичайний запуск у керованому середовищі, а не спеціальне відгалуження продукту.
+Це розділення робить managed agents природним розширенням SDK. Managed
+agent — це звичайний run у managed environment, а не окреме продуктове відгалуження.
-Докладні контракти простору імен, подій, результатів, схвалень, артефактів, безпеки, пакетів і провайдерів середовищ містяться в [дизайні OpenClaw SDK API](/uk/reference/openclaw-sdk-api-design).
+Детальні контракти namespace, event, result, approval, artifact, security, package,
+і environment provider містяться в
+[OpenClaw App SDK API design](/uk/reference/openclaw-sdk-api-design).
-## План збірника рецептів
+## План cookbook
-SDK має постачатися зі збірником рецептів, а не лише з довідковою документацією.
+SDK має постачатися з кулінарною книгою, а не лише з довідковою документацією.
Рекомендовані приклади:
| Приклад | Показує |
| ---------------------------- | -------------------------------------------------------------------------------------------- |
| Швидкий старт | Створення клієнта, запуск агента, потокове виведення, очікування результату. |
-| CLI кодингового агента | Локальний робочий простір, вибір моделі, скасування, затвердження, JSON-вивід. |
-| Панель агента | Сесії, запуски, фонові завдання, артефакти, повторне відтворення подій, фільтри статусу. |
+| CLI кодувального агента | Локальний робочий простір, вибір моделі, скасування, схвалення, JSON-вивід. |
+| Панель агента | Сесії, запуски, фонові завдання, артефакти, відтворення подій, фільтри статусу. |
| Конструктор застосунків | Агент редагує робочий простір, поки поруч працює сервер попереднього перегляду. |
-| Рецензент pull request | Запуск для посилання на репозиторій, збирання коментарів до diff і артефактів. |
-| Консоль затверджень | Підписка на затвердження й відповіді на них з UI. |
-| Запускач ACP harness | Запуск Claude Code, Cursor, Gemini CLI або OpenCode через ACP з використанням того самого API `Run`. |
-| Провайдер керованого середовища | Мінімальний провайдер, який готує робочий простір, транслює події, зберігає артефакти та очищає ресурси. |
-| Міст Slack або Discord | Зовнішній застосунок отримує події та публікує підсумки прогресу, не стаючи Plugin каналу. |
+| Рецензент pull request | Запуск для посилання репозиторію, збирання коментарів до diff і артефактів. |
+| Консоль схвалень | Підписка на схвалення та відповіді на них з UI. |
+| Запускач ACP harness | Запуск Claude Code, Cursor, Gemini CLI або OpenCode через ACP за допомогою того самого API `Run`. |
+| Постачальник керованого середовища | Мінімальний постачальник, який готує робочий простір, транслює події, зберігає артефакти та очищує ресурси. |
+| Міст Slack або Discord | Зовнішній застосунок отримує події та публікує зведення прогресу, не стаючи Plugin каналу. |
| Багатоагентне дослідження | Породження паралельних запусків, збирання артефактів і синтез фінального звіту. |
-Приклади cookbook мають спершу використовувати високорівневий API. Приклади низькорівневого згенерованого
+Приклади кулінарної книги мають спершу використовувати високорівневий API. Приклади низькорівневого згенерованого
клієнта належать до розширеного розділу.
## Поетапна реалізація
@@ -254,105 +276,106 @@ SDK має постачатися зі збірником рецептів, а
- Узгодити публічні іменники та назви.
- Визначити назви пакетів.
- Визначити першу таксономію подій.
-- Позначити в документації поточний Plugin SDK як навмисно окремий.
+- Позначити поточний Plugin SDK у документації як навмисно окремий.
### Фаза 1: Низькорівневий згенерований клієнт
- Згенерувати TypeScript-клієнт зі схем протоколу Gateway.
-- Спершу охопити `agent`, `agent.wait`, сесії, підписки, переривання та завдання.
-- Додати smoke-тести, які перевіряють, що згенеровані методи відповідають назвам методів Gateway і формам схем.
+- Спершу покрити `agent`, `agent.wait`, сесії, підписки, переривання та завдання.
+- Додати smoke-тести, які перевіряють, що згенеровані методи відповідають назвам методів Gateway і
+ формам схем.
- Опублікувати як експериментальний або внутрішній пакет.
### Фаза 2: Високорівневий API запуску
- Додати `OpenClaw`, `Agent`, `Session` і `Run`.
- Підтримати `run.events()`, `run.wait()` і `run.cancel()`.
-- Підтримати локальне виявлення Gateway та явні URL Gateway.
+- Підтримати виявлення локального Gateway і явні URL Gateway.
- Підтримати довговічні сесії та надсилання в сесію.
### Фаза 3: Нормалізована проєкція подій
- Додати на боці Gateway нормалізовану проєкцію подій поруч з наявними сирими подіями.
-- Зберігати сирі події середовища виконання там, де це дозволяє політика.
-- Додати курсори повторного відтворення та поведінку повторного підключення.
+- Зберегти сирі події середовища виконання там, де це дозволяє політика.
+- Додати курсори відтворення та поведінку повторного підключення.
- Відобразити події PI, Codex, ACP і завдань у стабільну таксономію.
-### Фаза 4: Артефакти та затвердження
+### Фаза 4: Артефакти та схвалення
- Додати перелік і завантаження артефактів.
-- Додати підписку на затвердження та помічники для відповідей.
-- Додати підписку на запитання та помічники для відповідей.
-- Додати cookbook-консоль затверджень.
+- Додати помічники підписки на схвалення та відповіді.
+- Додати помічники підписки на запитання та відповіді.
+- Додати консоль схвалень до кулінарної книги.
-### Фаза 5: Провайдери середовищ
+### Фаза 5: Постачальники середовищ
-- Запровадити контракти локального, node- і керованого провайдерів середовищ.
-- Почати із середовища, яке вже існує операційно.
-- Додати підготовку робочого простору, журнали, артефакти, timeout, очищення та утримання.
+- Запровадити контракти постачальників локального, вузлового та керованого середовища.
+- Почати з середовища, яке вже існує операційно.
+- Додати підготовку робочого простору, журнали, артефакти, тайм-аут, очищення та зберігання.
-### Фаза 6: Робочі процеси у хмарному стилі
+### Фаза 6: Робочі процеси в хмарному стилі
- Додати запуски, орієнтовані на репозиторій і гілку.
- Додати артефакти pull request.
- Додати дошки запусків, згруповані за репозиторієм, гілкою, статусом і виконавцем.
-- Додати довготривалі керовані сесії та політику утримання.
+- Додати довготривалі керовані сесії та політику зберігання.
-## Проєктні рішення для наслідування
+## Дизайн-рішення для наслідування
Скопіювати ці ідеї:
-- З Cursor: `Agent` плюс `Run`, симетрія локального й хмарного режимів, виявлення моделей,
- артефакти та онбординг на основі cookbook.
-- З Claude Agent SDK: двонапрямні клієнти, interrupt, permissions, hooks,
- custom tools, сховища сесій і семантика resume.
-- З OpenAI Agents: handoffs, guardrails, відновлення після затвердження людиною, трасування та
+- З Cursor: `Agent` плюс `Run`, симетрія локального та хмарного режимів, виявлення моделей,
+ артефакти й onboarding через кулінарну книгу.
+- З Claude Agent SDK: двонапрямні клієнти, переривання, дозволи, hooks,
+ користувацькі інструменти, сховища сесій і семантика відновлення.
+- З OpenAI Agents: передавання керування, захисні обмеження, відновлення після людського схвалення, трасування та
структуровані об’єкти потокового результату.
- З Google ADK: сервіси за runner, дії подій, пам’ять, артефакти,
- сервіси облікових даних і Plugin-перехоплення навколо життєвого циклу запуску.
+ сервіси облікових даних і перехоплення Plugin навколо життєвого циклу запуску.
- З OpenCode: згенерований клієнт протоколу, REST плюс SSE, сесії,
- робочі простори, запитання, дозволи, файли, VCS, PTY, MCP, агенти та skills.
-- З Codex: явні sandbox, approval, network, локальне й віддалене виконання, а також
+ робочі простори, запитання, дозволи, файли, VCS, PTY, MCP, агенти та Skills.
+- З Codex: явні пісочниця, схвалення, мережа, локальне та віддалене виконання, а також
межі потоків app-server.
- З ACP і acpx: сумісність зовнішніх harness на основі адаптерів і іменовані
черги prompt.
-## Проєктні рішення, яких слід уникати
+## Дизайн-рішення, яких слід уникати
Уникайте цих пасток:
- Публічний SDK, який є лише тонким вивантаженням внутрішніх деталей Gateway.
- Публічний SDK, який імпортує підшляхи Plugin SDK.
-- Публічний SDK, де події є лише `stream` плюс `data`.
-- API, орієнтований насамперед на хмару, через який локальний OpenClaw відчувається як застарілий режим.
-- Вибір середовища виконання, прихований у префіксах id моделей.
+- Публічний SDK, де події — це лише `stream` плюс `data`.
+- API з пріоритетом хмари, через який локальний OpenClaw відчувається як застарілий режим.
+- Вибір середовища виконання, прихований у префіксах ідентифікаторів моделей.
- Передавання секретів, приховане в мапах середовища.
- ACP-специфічні параметри на верхньому рівні кожного запуску.
-- Прапорці sandbox, які неможливо забезпечити вибраним середовищем виконання.
-- Один об’єкт SDK, який одночасно намагається бути Plugin провайдера, Plugin каналу, клієнтом застосунку
+- Прапорці пісочниці, які неможливо забезпечити вибраним середовищем виконання.
+- Один об’єкт SDK, який одночасно намагається бути provider Plugin, channel Plugin, клієнтом застосунку
і керованим runner.
## Відкриті питання
-- Початковий пакет має жити в цьому репозиторії чи в окремому SDK-репозиторії?
-- Чи слід публічно опублікувати згенерований низькорівневий клієнт до того, як
- стабілізується високорівнева обгортка?
-- Який перший підтримуваний механізм автентифікації застосунку: локальний токен, адмін-токен,
+- Чи має початковий пакет жити в цьому репозиторії чи в окремому репозиторії SDK?
+- Чи слід публікувати згенерований низькорівневий клієнт публічно до стабілізації
+ високорівневої обгортки?
+- Який перший підтримуваний механізм автентифікації застосунку: локальний токен, admin-токен,
OAuth device flow чи підписана реєстрація застосунку?
- Скільки історії повідомлень сесії SDK має відкривати за замовчуванням?
-- Чи керовані середовища мають налаштовуватися лише в конфігурації Gateway, чи виклики SDK
+- Чи мають керовані середовища налаштовуватися лише в конфігурації Gateway, чи виклики SDK
можуть запитувати їх напряму зі scoped tokens?
-- Які правила утримання застосовуються до артефактів, згенерованих локальними запусками?
+- Які правила зберігання застосовуються до артефактів, згенерованих локальними запусками?
- Які payload подій потребують редагування перед доставленням у застосунок?
-- Чи має `Run` охоплювати звичайні чат-ходи й відокремлені завдання, чи відокремлена
+- Чи має `Run` покривати звичайні ходи чату й відокремлені завдання, чи відокремлена
фонова робота завжди має повертати обгортку `Task` з вкладеним `Run`?
## Пов’язані документи
- [Цикл агента](/uk/concepts/agent-loop)
-- [Середовища виконання агентів](/uk/concepts/agent-runtimes)
+- [Середовища виконання агента](/uk/concepts/agent-runtimes)
- [Сесія](/uk/concepts/session)
- [Субагенти](/uk/tools/subagents)
- [Фонові завдання](/uk/automation/tasks)
-- [ACP-агенти](/uk/tools/acp-agents)
-- [Plugins agent harness](/uk/plugins/sdk-agent-harness)
+- [Агенти ACP](/uk/tools/acp-agents)
+- [Agent harness plugins](/uk/plugins/sdk-agent-harness)
- [Огляд Plugin SDK](/uk/plugins/sdk-overview)
diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md
index a4cd41530..fcbb9ecb4 100644
--- a/docs/uk/plugins/sdk-overview.md
+++ b/docs/uk/plugins/sdk-overview.md
@@ -1,27 +1,35 @@
---
read_when:
- - Потрібно знати, з якого підшляху SDK виконувати імпорт
+ - Потрібно знати, з якого підшляху SDK імпортувати
- Вам потрібна довідка щодо всіх методів реєстрації в OpenClawPluginApi
- Ви шукаєте конкретний експорт SDK
-sidebarTitle: SDK overview
-summary: Карта імпортів, довідник API реєстрації та архітектура SDK
+sidebarTitle: Plugin SDK overview
+summary: Мапа імпортів, довідник API реєстрації та архітектура SDK
title: Огляд Plugin SDK
x-i18n:
- generated_at: "2026-04-29T04:42:21Z"
+ generated_at: "2026-04-30T00:49:45Z"
model: gpt-5.5
provider: openai
- source_hash: 7652c2be756dad14792f59f36fa2fc2becd1681454005cf391e401b89999b857
+ source_hash: 1749ad99c55ffd14624b817aba963bd93ebe7976937138693177523bbe3aa88c
source_path: plugins/sdk-overview.md
workflow: 16
---
-SDK Plugin є типізованим контрактом між плагінами та ядром. Ця сторінка є довідником щодо того, **що імпортувати** і **що можна реєструвати**.
+Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є
+довідником щодо **того, що імпортувати** і **що можна реєструвати**.
+
+
+ Ця сторінка призначена для авторів plugins, які використовують `openclaw/plugin-sdk/*` всередині
+ OpenClaw. Для зовнішніх застосунків, скриптів, панелей керування, завдань CI та розширень IDE,
+ які хочуть запускати агентів через Gateway, натомість використовуйте
+ [OpenClaw App SDK](/uk/concepts/openclaw-sdk) і пакет `@openclaw/sdk`.
+
-Шукаєте натомість практичний посібник? Почніть із [Створення плагінів](/uk/plugins/building-plugins), використовуйте [Плагіни каналів](/uk/plugins/sdk-channel-plugins) для плагінів каналів, [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) для плагінів провайдерів і [Хуки Plugin](/uk/plugins/hooks) для плагінів інструментів або хуків життєвого циклу.
+Шукаєте натомість практичний посібник? Почніть із [Створення plugins](/uk/plugins/building-plugins), використовуйте [Channel plugins](/uk/plugins/sdk-channel-plugins) для channel plugins, [Provider plugins](/uk/plugins/sdk-provider-plugins) для provider plugins і [Plugin hooks](/uk/plugins/hooks) для plugins інструментів або хуків життєвого циклу.
-## Угода про імпорт
+## Угода щодо імпорту
Завжди імпортуйте з конкретного підшляху:
@@ -30,163 +38,166 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
-Кожен підшлях є невеликим самодостатнім модулем. Це забезпечує швидкий запуск і
-запобігає проблемам із циклічними залежностями. Для допоміжних засобів входу/збірки,
-специфічних для каналів, віддавайте перевагу `openclaw/plugin-sdk/channel-core`; залиште `openclaw/plugin-sdk/core` для
-ширшої узагальнювальної поверхні та спільних допоміжних засобів, таких як
+Кожен підшлях — це невеликий самодостатній модуль. Це пришвидшує запуск і
+запобігає проблемам із циклічними залежностями. Для специфічних для каналів помічників entry/build
+надавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для
+ширшої парасолькової поверхні та спільних помічників, як-от
`buildChannelConfigSchema`.
Для конфігурації каналу публікуйте JSON Schema, що належить каналу, через
`openclaw.plugin.json#channelConfigs`. Підшлях `plugin-sdk/channel-config-schema`
-призначений для спільних примітивів схем і загального конструктора. Вбудовані
-плагіни OpenClaw використовують `plugin-sdk/bundled-channel-config-schema` для збережених
+призначений для спільних примітивів схем і універсального збирача. Вбудовані
+plugins OpenClaw використовують `plugin-sdk/bundled-channel-config-schema` для збережених
схем вбудованих каналів. Застарілі експорти сумісності залишаються в
-`plugin-sdk/channel-config-schema-legacy`; жоден із підшляхів вбудованих схем не є
-шаблоном для нових плагінів.
+`plugin-sdk/channel-config-schema-legacy`; жоден із підшляхів схем вбудованих каналів не є
+шаблоном для нових plugins.
- Не імпортуйте зручні seams із брендингом провайдера або каналу (наприклад,
+ Не імпортуйте provider- або channel-брендовані допоміжні межі (наприклад
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
- Вбудовані плагіни компонують загальні підшляхи SDK у власних barrel-файлах `api.ts` /
- `runtime-api.ts`; споживачі ядра мають або використовувати ці локальні для плагіна
- barrel-файли, або додати вузький загальний контракт SDK, коли потреба справді є
+ Вбудовані plugins компонують універсальні підшляхи SDK всередині власних barrel-файлів `api.ts` /
+ `runtime-api.ts`; споживачі ядра мають або використовувати ці локальні для plugin
+ barrel-файли, або додавати вузький універсальний контракт SDK, коли потреба справді є
міжканальною.
-Невеликий набір допоміжних seams вбудованих плагінів досі з'являється у згенерованій мапі експортів,
-коли для них відстежується використання власником. Вони існують лише для
-супроводу вбудованих плагінів і не рекомендовані як шляхи імпорту для нових сторонніх
-плагінів.
+Невеликий набір допоміжних меж для вбудованих plugins усе ще з’являється у згенерованій мапі експортів,
+коли вони мають відстежене використання власником. Вони існують лише для супроводу вбудованих plugins
+і не рекомендовані як шляхи імпорту для нових сторонніх
+plugins.
`openclaw/plugin-sdk/discord` і `openclaw/plugin-sdk/telegram-account` також
-збережені як застарілі фасади сумісності для відстежуваного використання власником. Не
-копіюйте ці шляхи імпорту в нові плагіни; натомість використовуйте ін'єктовані runtime-допоміжні засоби та
-загальні підшляхи SDK каналів.
+збережені як застарілі фасади сумісності для відстеженого використання власником. Не
+копіюйте ці шляхи імпорту в нові plugins; натомість використовуйте ін’єктовані runtime-помічники та
+універсальні підшляхи channel SDK.
## Довідник підшляхів
-SDK Plugin надається як набір вузьких підшляхів, згрупованих за областями (вхід
-плагіна, канал, провайдер, автентифікація, runtime, capability, пам'ять і зарезервовані
-допоміжні засоби вбудованих плагінів). Повний каталог — згрупований і з посиланнями — див.
-[Підшляхи SDK Plugin](/uk/plugins/sdk-subpaths).
+Plugin SDK надається як набір вузьких підшляхів, згрупованих за областями (entry plugin,
+канал, provider, автентифікація, runtime, capability, пам’ять і зарезервовані
+помічники вбудованих plugins). Повний каталог — згрупований і з посиланнями — див.
+[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths).
-Згенерований список із понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`.
+Згенерований список із понад 200 підшляхів розміщений у `scripts/lib/plugin-sdk-entrypoints.json`.
## API реєстрації
-Callback `register(api)` отримує об'єкт `OpenClawPluginApi` з такими
+Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
методами:
-### Реєстрація capability
+### Реєстрація capabilities
-| Метод | Що він реєструє |
-| ------------------------------------------------ | -------------------------------------- |
-| `api.registerProvider(...)` | Текстове виведення (LLM) |
-| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента |
-| `api.registerCliBackend(...)` | Локальний backend виведення CLI |
-| `api.registerChannel(...)` | Канал обміну повідомленнями |
-| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT |
+| Метод | Що реєструє |
+| ------------------------------------------------ | ------------------------------------- |
+| `api.registerProvider(...)` | Текстовий inference (LLM) |
+| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агентів |
+| `api.registerCliBackend(...)` | Локальний backend inference для CLI |
+| `api.registerChannel(...)` | Канал повідомлень |
+| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі |
-| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі |
-| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
-| `api.registerImageGenerationProvider(...)` | Генерація зображень |
-| `api.registerMusicGenerationProvider(...)` | Генерація музики |
-| `api.registerVideoGenerationProvider(...)` | Генерація відео |
-| `api.registerWebFetchProvider(...)` | Провайдер веботримання / скрейпінгу |
-| `api.registerWebSearchProvider(...)` | Вебпошук |
+| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сеанси в реальному часі |
+| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
+| `api.registerImageGenerationProvider(...)` | Генерація зображень |
+| `api.registerMusicGenerationProvider(...)` | Генерація музики |
+| `api.registerVideoGenerationProvider(...)` | Генерація відео |
+| `api.registerWebFetchProvider(...)` | Provider web fetch / scrape |
+| `api.registerWebSearchProvider(...)` | Вебпошук |
-### Інструменти та команди
+### Інструменти й команди
-| Метод | Що він реєструє |
-| ------------------------------- | ------------------------------------------------ |
-| `api.registerTool(tool, opts?)` | Інструмент агента (обов'язковий або `{ optional: true }`) |
-| `api.registerCommand(def)` | Користувацька команда (оминає LLM) |
+| Метод | Що реєструє |
+| ------------------------------- | -------------------------------------------- |
+| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) |
+| `api.registerCommand(def)` | Користувацька команда (оминає LLM) |
Команди Plugin можуть задавати `agentPromptGuidance`, коли агенту потрібна коротка,
-належна команді підказка маршрутизації. Тримайте цей текст про саму команду; не додавайте
-політику, специфічну для провайдера або плагіна, до конструкторів core prompt.
+належна команді підказка для маршрутизації. Тримайте цей текст про саму команду; не додавайте
+provider- або plugin-специфічну політику до збирачів prompt ядра.
### Інфраструктура
-| Метод | Що він реєструє |
-| ---------------------------------------------- | --------------------------------------- |
-| `api.registerHook(events, handler, opts?)` | Хук події |
-| `api.registerHttpRoute(params)` | HTTP endpoint Gateway |
-| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway |
-| `api.registerGatewayDiscoveryService(service)` | Оголошувач локального виявлення Gateway |
-| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
-| `api.registerService(service)` | Фоновий сервіс |
-| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
-| `api.registerAgentToolResultMiddleware(...)` | Runtime middleware результатів інструментів |
-| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ prompt поруч із пам'яттю |
-| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам'яті |
+| Метод | Що реєструє |
+| ---------------------------------------------- | -------------------------------------- |
+| `api.registerHook(events, handler, opts?)` | Хук події |
+| `api.registerHttpRoute(params)` | HTTP endpoint Gateway |
+| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway |
+| `api.registerGatewayDiscoveryService(service)` | Рекламодавець виявлення локального Gateway |
+| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
+| `api.registerService(service)` | Фоновий сервіс |
+| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
+| `api.registerAgentToolResultMiddleware(...)` | Runtime middleware для результатів інструментів |
+| `api.registerMemoryPromptSupplement(builder)` | Адитивна секція prompt поруч із пам’яттю |
+| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті |
-### Хост-хуки для плагінів workflow
+### Host hooks для workflow plugins
-Хост-хуки — це seams SDK для плагінів, яким потрібно брати участь у життєвому циклі хоста,
-а не лише додавати провайдера, канал або інструмент. Вони є
-загальними контрактами; Plan Mode може їх використовувати, але так само можуть workflow затверджень,
-гейти політик робочого простору, фонові монітори, майстри налаштування та супровідні UI
-плагіни.
+Host hooks — це межі SDK для plugins, яким потрібно брати участь у життєвому циклі хоста,
+а не лише додавати provider, канал або інструмент. Це
+універсальні контракти; Plan Mode може їх використовувати, але так само можуть workflow-и погодження,
+шлюзи політик робочого простору, фонові монітори, майстри налаштування та UI companion
+plugins.
-| Метод | Контракт, яким він володіє |
-| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
-| `api.registerSessionExtension(...)` | Належний Plugin JSON-сумісний стан сесії, проєктований через сесії Gateway |
-| `api.enqueueNextTurnInjection(...)` | Стійкий контекст exactly-once, ін'єктований у наступний хід агента для однієї сесії |
-| `api.registerTrustedToolPolicy(...)` | Політика інструментів до Plugin для вбудованих/довірених інструментів, що може блокувати або переписувати параметри інструмента |
-| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента |
-| `api.registerCommand(...)` | Обмежені за scope команди Plugin; результати команд можуть задавати `continueAgent: true` |
-| `api.registerControlUiDescriptor(...)` | Дескриптори внеску Control UI для поверхонь сесії, інструмента, запуску або налаштувань |
-| `api.registerRuntimeLifecycle(...)` | Callback-и очищення для належних Plugin runtime-ресурсів на шляхах reset/delete/reload |
-| `api.registerAgentEventSubscription(...)` | Санітизовані підписки на події для стану workflow та моніторів |
-| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Належний Plugin scratch-стан для кожного запуску, очищений у термінальному життєвому циклі запуску |
-| `api.registerSessionSchedulerJob(...)` | Належні Plugin записи завдань планувальника сесій із детермінованим очищенням |
+| Метод | Контракт, яким він володіє |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| `api.registerSessionExtension(...)` | Належний plugin JSON-сумісний стан сеансу, спроєктований через сеанси Gateway |
+| `api.enqueueNextTurnInjection(...)` | Надійний exactly-once контекст, ін’єктований у наступний хід агента для одного сеансу |
+| `api.registerTrustedToolPolicy(...)` | Політика інструментів перед bundled/trusted pre-plugin, яка може блокувати або переписувати параметри інструментів |
+| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента |
+| `api.registerCommand(...)` | Scoped команди plugin; результати команд можуть задавати `continueAgent: true` |
+| `api.registerControlUiDescriptor(...)` | Дескриптори внеску Control UI для поверхонь сеансу, інструмента, запуску або налаштувань |
+| `api.registerRuntimeLifecycle(...)` | Зворотні виклики очищення для runtime-ресурсів, що належать plugin, на шляхах reset/delete/reload |
+| `api.registerAgentEventSubscription(...)` | Санітизовані підписки на події для стану workflow і моніторів |
+| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Scratch-стан plugin для кожного запуску, очищений на термінальному життєвому циклі запуску |
+| `api.registerSessionSchedulerJob(...)` | Належні plugin записи завдань планувальника сеансів із детермінованим очищенням |
Контракти навмисно розділяють повноваження:
-- Зовнішні плагіни можуть володіти розширеннями сесій, UI-дескрипторами, командами, метаданими інструментів, ін'єкціями наступного ходу та звичайними хуками.
-- Довірені політики інструментів виконуються перед звичайними хуками `before_tool_call` і доступні лише для вбудованих компонентів, бо беруть участь у політиці безпеки хоста.
-- Зарезервоване володіння командами доступне лише для вбудованих компонентів. Зовнішні плагіни мають використовувати власні назви команд або псевдоніми.
-- `allowPromptInjection=false` вимикає хуки, що змінюють prompt, включно з
+- Зовнішні plugins можуть володіти session extensions, UI descriptors, commands, tool
+ metadata, next-turn injections і звичайними hooks.
+- Trusted tool policies виконуються перед звичайними hooks `before_tool_call` і є
+ лише вбудованими, бо вони беруть участь у політиці безпеки хоста.
+- Зарезервоване володіння командами доступне лише вбудованим plugins. Зовнішні plugins мають використовувати
+ власні імена команд або псевдоніми.
+- `allowPromptInjection=false` вимикає hooks, що змінюють prompt, зокрема
`agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`,
- полями prompt із застарілого `before_agent_start` і
+ поля prompt із legacy `before_agent_start` і
`enqueueNextTurnInjection`.
Приклади споживачів, що не належать до Plan:
-| Архетип Plugin | Використані хуки |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| Workflow затвердження | Розширення сесії, продовження команди, ін'єкція наступного ходу, UI-дескриптор |
-| Гейт політики бюджету/робочого простору | Довірена політика інструментів, метадані інструментів, проєкція сесії |
-| Фоновий монітор життєвого циклу | Очищення runtime-життєвого циклу, підписка на події агента, володіння/очищення планувальника сесій, внесок Heartbeat prompt, UI-дескриптор |
-| Майстер налаштування або onboarding | Розширення сесії, обмежені за scope команди, дескриптор Control UI |
+| Архетип plugin | Використані hooks |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Workflow погодження | Session extension, command continuation, next-turn injection, UI descriptor |
+| Шлюз політик бюджету/робочого простору | Trusted tool policy, tool metadata, session projection |
+| Фоновий монітор життєвого циклу | Runtime lifecycle cleanup, agent event subscription, session scheduler ownership/cleanup, heartbeat prompt contribution, UI descriptor |
+| Майстер налаштування або onboarding | Session extension, scoped commands, Control UI descriptor |
Зарезервовані core admin namespaces (`config.*`, `exec.approvals.*`, `wizard.*`,
- `update.*`) завжди залишаються `operator.admin`, навіть якщо Plugin намагається призначити
- вужчий scope методу gateway. Віддавайте перевагу префіксам, специфічним для Plugin, для
- методів, якими володіє Plugin.
+ `update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити
+ вужчу область gateway method. Надавайте перевагу plugin-specific prefixes для
+ методів, що належать plugin.
- Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли
+ Вбудовані plugins можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли
їм потрібно переписати результат інструмента після виконання і до того, як runtime
- передасть цей результат назад у модель. Це довірений runtime-нейтральний
- seam для асинхронних редукторів виводу, таких як tokenjuice.
+ передасть цей результат назад у модель. Це trusted runtime-neutral
+ межа для async output reducers, таких як tokenjuice.
-Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для кожного
-цільового runtime, наприклад `["pi", "codex"]`. Зовнішні плагіни
-не можуть реєструвати це middleware; залишайте звичайні хуки Plugin OpenClaw для роботи,
-яка не потребує timing результату інструмента до моделі. Старий вбудований
-шлях реєстрації фабрики розширення лише для Pi було видалено.
+Вбудовані plugins мають оголошувати `contracts.agentToolResultMiddleware` для кожного
+цільового runtime, наприклад `["pi", "codex"]`. Зовнішні plugins
+не можуть реєструвати це middleware; залишайте звичайні hooks OpenClaw plugin для роботи,
+якій не потрібен таймінг результату інструмента перед моделлю. Старий Pi-only embedded
+шлях реєстрації extension factory було вилучено.
### Реєстрація виявлення Gateway
-`api.registerGatewayDiscoveryService(...)` дає Plugin змогу оголошувати активний
-Gateway на локальному транспорті виявлення, наприклад mDNS/Bonjour. OpenClaw викликає
-сервіс під час запуску Gateway, коли локальне виявлення увімкнене, передає
-поточні порти Gateway і несекретні TXT hint-дані, а також викликає повернений
+`api.registerGatewayDiscoveryService(...)` дає plugin змогу рекламувати активний
+Gateway у локальному транспорті виявлення, як-от mDNS/Bonjour. OpenClaw викликає
+сервіс під час запуску Gateway, коли локальне виявлення ввімкнено, передає
+поточні порти Gateway і несекретні TXT hint-дані та викликає повернений
обробник `stop` під час завершення роботи Gateway.
```typescript
@@ -203,19 +214,19 @@ api.registerGatewayDiscoveryService({
});
```
-Плагіни виявлення Gateway не повинні трактувати оголошені TXT-значення як секрети або
-автентифікацію. Виявлення є routing hint; автентифікація Gateway і TLS pinning і далі
+Плагіни виявлення Gateway не повинні розглядати оголошені значення TXT як секрети або
+автентифікацію. Виявлення є підказкою для маршрутизації; автентифікація Gateway і прив’язка TLS і далі
відповідають за довіру.
### Метадані реєстрації CLI
-`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня:
+`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня:
- `commands`: явні корені команд, якими володіє реєстратор
-- `descriptors`: дескриптори команд часу розбору, які використовуються для довідки кореневого CLI,
- маршрутизації та лінивої реєстрації CLI Plugin
+- `descriptors`: дескриптори команд часу розбору, що використовуються для довідки кореневого CLI,
+ маршрутизації та лінивої реєстрації CLI плагіна
-Якщо ви хочете, щоб команда Plugin залишалася ліниво завантажуваною у звичайному кореневому шляху CLI,
+Якщо ви хочете, щоб команда плагіна залишалася ліниво завантажуваною у звичайному шляху кореневого CLI,
надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, відкритий цим
реєстратором.
@@ -229,7 +240,7 @@ api.registerCli(
descriptors: [
{
name: "matrix",
- description: "Manage Matrix accounts, verification, devices, and profile state",
+ description: "Керування обліковими записами Matrix, перевіркою, пристроями та станом профілю",
hasSubcommands: true,
},
],
@@ -237,53 +248,53 @@ api.registerCli(
);
```
-Використовуйте `commands` окремо лише тоді, коли вам не потрібна лінива реєстрація кореневого CLI.
-Цей енергійний шлях сумісності й надалі підтримується, але він не встановлює
+Використовуйте лише `commands`, тільки коли вам не потрібна лінива реєстрація кореневого CLI.
+Цей шлях енергійної сумісності й надалі підтримується, але він не встановлює
заповнювачі на основі дескрипторів для лінивого завантаження під час розбору.
### Реєстрація бекенду CLI
-`api.registerCliBackend(...)` дає Plugin змогу володіти типовою конфігурацією для локального
-бекенду AI CLI, такого як `codex-cli`.
+`api.registerCliBackend(...)` дає плагіну змогу володіти типовою конфігурацією для локального
+бекенду AI CLI, як-от `codex-cli`.
-- `id` бекенду стає префіксом провайдера в посиланнях на моделі на кшталт `codex-cli/gpt-5`.
+- `id` бекенду стає префіксом провайдера в посиланнях на моделі, як-от `codex-cli/gpt-5`.
- `config` бекенду використовує ту саму форму, що й `agents.defaults.cliBackends.`.
- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх
- типових налаштувань Plugin перед запуском CLI.
+ типових значень плагіна перед запуском CLI.
- Використовуйте `normalizeConfig`, коли бекенду потрібні переписування для сумісності після об’єднання
(наприклад, нормалізація старих форм прапорців).
### Ексклюзивні слоти
-| Метод | Що він реєструє |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `api.registerContextEngine(id, factory)` | Контекстний рушій (одночасно активний лише один). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати доповнення до промпта. |
-| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті |
-| `api.registerMemoryPromptSection(builder)` | Побудовник секції промпта пам’яті |
-| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті |
-| `api.registerMemoryRuntime(runtime)` | Адаптер середовища виконання пам’яті |
+| Метод | Що він реєструє |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `api.registerContextEngine(id, factory)` | Рушій контексту (один активний одночасно). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг налаштувати додавання до промпта. |
+| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті |
+| `api.registerMemoryPromptSection(builder)` | Побудовник секції промпта пам’яті |
+| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті |
+| `api.registerMemoryRuntime(runtime)` | Адаптер середовища виконання пам’яті |
### Адаптери ембедингів пам’яті
-| Метод | Що він реєструє |
-| ---------------------------------------------- | ---------------------------------------------- |
-| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер ембедингів пам’яті для активного Plugin |
+| Метод | Що він реєструє |
+| ---------------------------------------------- | ---------------------------------------------------- |
+| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер ембедингів пам’яті для активного плагіна |
-- `registerMemoryCapability` — рекомендований ексклюзивний API Plugin пам’яті.
-- `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`,
- щоб супровідні Plugins могли споживати експортовані артефакти пам’яті через
- `openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної структури
- конкретного Plugin пам’яті.
+- `registerMemoryCapability` є бажаним ексклюзивним API плагіна пам’яті.
+- `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`,
+ щоб супутні плагіни могли споживати експортовані артефакти пам’яті через
+ `openclaw/plugin-sdk/memory-host-core` замість доступу до приватної структури
+ конкретного плагіна пам’яті.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` і
- `registerMemoryRuntime` — це сумісні зі спадщиною ексклюзивні API Plugin пам’яті.
-- `MemoryFlushPlan.model` може прив’язати хід скидання до точного посилання
- `provider/model`, такого як `ollama/qwen3:8b`, без успадкування активного
- ланцюжка резервних варіантів.
-- `registerMemoryEmbeddingProvider` дає активному Plugin пам’яті змогу зареєструвати один
- або кілька ідентифікаторів адаптерів ембедингів (наприклад, `openai`, `gemini` або власний
- ідентифікатор, визначений Plugin).
-- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і
- `agents.defaults.memorySearch.fallback`, розв’язується відносно цих зареєстрованих
+ `registerMemoryRuntime` є ексклюзивними API плагіна пам’яті зі збереженням сумісності зі спадщиною.
+- `MemoryFlushPlan.model` може закріпити хід скидання за точним посиланням
+ `provider/model`, як-от `ollama/qwen3:8b`, без успадкування активного ланцюга
+ резервних варіантів.
+- `registerMemoryEmbeddingProvider` дає активному плагіну пам’яті змогу зареєструвати один
+ або кілька ідентифікаторів адаптерів ембедингів (наприклад `openai`, `gemini` або власний
+ ідентифікатор, визначений плагіном).
+- Користувацька конфігурація, як-от `agents.defaults.memorySearch.provider` і
+ `agents.defaults.memorySearch.fallback`, резолвиться відносно цих зареєстрованих
ідентифікаторів адаптерів.
### Події та життєвий цикл
@@ -293,7 +304,8 @@ api.registerCli(
| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу |
| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови |
-Див. [хуки Plugin](/uk/plugins/hooks) для прикладів, поширених назв хуків і семантики захисту.
+Див. [хуки плагінів](/uk/plugins/hooks) для прикладів, поширених назв хуків і семантики
+запобіжників.
### Семантика рішень хуків
@@ -301,94 +313,94 @@ api.registerCli(
- `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення.
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
- `before_install`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення.
-- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере dispatch на себе, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються.
+- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере на себе доставлення, обробники з нижчим пріоритетом і типовий шлях доставлення моделі пропускаються.
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
- `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як пропуск `cancel`), а не як перевизначення.
- `message_received`: використовуйте типізоване поле `threadId`, коли потрібна маршрутизація вхідної гілки/теми. Залишайте `metadata` для специфічних для каналу додаткових даних.
-- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічного для каналу `metadata`.
+- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічних для каналу `metadata`.
- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, яким володіє Gateway, замість покладання на внутрішні хуки `gateway:startup`.
-- `cron_changed`: спостерігайте за змінами життєвого циклу Cron, яким володіє Gateway. Використовуйте `event.job?.state?.nextRunAtMs` і `ctx.getCron?.()` під час синхронізації зовнішніх планувальників пробудження, а OpenClaw залишайте джерелом істини для перевірок строків виконання та виконання.
+- `cron_changed`: спостерігайте за змінами життєвого циклу cron, яким володіє gateway. Використовуйте `event.job?.state?.nextRunAtMs` і `ctx.getCron?.()`, коли синхронізуєте зовнішні планувальники пробудження, і залишайте OpenClaw джерелом істини для перевірок настання часу та виконання.
### Поля об’єкта API
-| Поле | Тип | Опис |
-| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- |
-| `api.id` | `string` | Ідентифікатор Plugin |
-| `api.name` | `string` | Відображувана назва |
-| `api.version` | `string?` | Версія Plugin (необов’язково) |
-| `api.description` | `string?` | Опис Plugin (необов’язково) |
-| `api.source` | `string` | Шлях до джерела Plugin |
-| `api.rootDir` | `string?` | Кореневий каталог Plugin (необов’язково) |
-| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, коли доступний) |
-| `api.pluginConfig` | `Record` | Специфічна для Plugin конфігурація з `plugins.entries..config` |
-| `api.runtime` | `PluginRuntime` | [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) |
-| `api.logger` | `PluginLogger` | Обмежений логер (`debug`, `info`, `warn`, `error`) |
-| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним входом |
-| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня Plugin |
+| Поле | Тип | Опис |
+| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `api.id` | `string` | Ідентифікатор плагіна |
+| `api.name` | `string` | Відображувана назва |
+| `api.version` | `string?` | Версія плагіна (необов’язково) |
+| `api.description` | `string?` | Опис плагіна (необов’язково) |
+| `api.source` | `string` | Шлях до джерела плагіна |
+| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) |
+| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, коли доступний) |
+| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, з `plugins.entries..config` |
+| `api.runtime` | `PluginRuntime` | [Помічники середовища виконання](/uk/plugins/sdk-runtime) |
+| `api.logger` | `PluginLogger` | Логер з областю дії (`debug`, `info`, `warn`, `error`) |
+| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — полегшене вікно запуску/налаштування до повного входу |
+| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня плагіна |
-## Конвенція внутрішніх модулів
+## Внутрішня домовленість щодо модулів
-У межах вашого Plugin використовуйте локальні barrel-файли для внутрішніх імпортів:
+У своєму плагіні використовуйте локальні barrel-файли для внутрішніх імпортів:
```
my-plugin/
- api.ts # Public exports for external consumers
- runtime-api.ts # Internal-only runtime exports
- index.ts # Plugin entry point
- setup-entry.ts # Lightweight setup-only entry (optional)
+ api.ts # Публічні експорти для зовнішніх споживачів
+ runtime-api.ts # Внутрішні експорти середовища виконання
+ index.ts # Точка входу плагіна
+ setup-entry.ts # Полегшений вхід лише для налаштування (необов’язково)
```
- Ніколи не імпортуйте власний Plugin через `openclaw/plugin-sdk/`
- з виробничого коду. Спрямовуйте внутрішні імпорти через `./api.ts` або
- `./runtime-api.ts`. Шлях SDK — лише зовнішній контракт.
+ Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/`
+ з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або
+ `./runtime-api.ts`. Шлях SDK є лише зовнішнім контрактом.
-Публічні поверхні вбудованих Plugin, завантажені через фасад (`api.ts`, `runtime-api.ts`,
+Публічні поверхні вбудованого плагіна, завантажені через фасад (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` і подібні публічні вхідні файли), віддають перевагу
-активному знімку конфігурації середовища виконання, коли OpenClaw уже запущено. Якщо знімка середовища
-виконання ще немає, вони повертаються до розв’язаної конфігурації на диску.
-Фасади упакованих вбудованих Plugin слід завантажувати через фасадні завантажувачі OpenClaw SDK;
-прямі імпорти з `dist/extensions/...` оминають поетапні дзеркала залежностей середовища виконання,
-які упаковані встановлення використовують для залежностей, якими володіє Plugin.
+активному знімку конфігурації середовища виконання, коли OpenClaw уже працює. Якщо знімка середовища виконання
+ще немає, вони повертаються до розв’язаної конфігурації на диску.
+Запаковані фасади вбудованих плагінів слід завантажувати через завантажувачі фасадів плагінів
+OpenClaw; прямі імпорти з `dist/extensions/...` оминають staged-дзеркала залежностей середовища виконання,
+які запаковані встановлення використовують для залежностей, що належать плагіну.
-Plugin провайдерів можуть надавати вузький локальний для Plugin contract barrel, коли
-допоміжний засіб навмисно специфічний для провайдера і ще не належить до загального підшляху SDK.
+Плагіни провайдерів можуть відкривати вузький локальний для плагіна barrel контракту, коли
+помічник навмисно специфічний для провайдера й поки що не належить до загального підшляху SDK.
Вбудовані приклади:
-- **Anthropic**: публічний шов `api.ts` / `contract-api.ts` для beta-header Claude
- і допоміжних засобів потоків `service_tier`.
-- **`@openclaw/openai-provider`**: `api.ts` експортує побудовники провайдера,
- допоміжні засоби типових моделей і побудовники realtime-провайдера.
-- **`@openclaw/openrouter-provider`**: `api.ts` експортує побудовник провайдера,
- а також допоміжні засоби onboarding/конфігурації.
+- **Anthropic**: публічний шов `api.ts` / `contract-api.ts` для Claude
+ beta-header і помічників потоку `service_tier`.
+- **`@openclaw/openai-provider`**: `api.ts` експортує побудовники провайдерів,
+ помічники типових моделей і побудовники провайдерів realtime.
+- **`@openclaw/openrouter-provider`**: `api.ts` експортує побудовник провайдера
+ плюс помічники онбордингу/конфігурації.
- Виробничому коду розширення також слід уникати імпортів `openclaw/plugin-sdk/`.
- Якщо допоміжний засіб справді спільний, піднесіть його до нейтрального підшляху SDK,
- такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або інша
- поверхня, орієнтована на можливість, замість того щоб зв’язувати два Plugins між собою.
+ Production-коду розширень також слід уникати імпортів `openclaw/plugin-sdk/`.
+ Якщо помічник справді спільний, підніміть його до нейтрального підшляху SDK,
+ як-от `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
+ поверхні, орієнтованої на можливість, замість зв’язування двох плагінів між собою.
## Пов’язане
-
+
Параметри `definePluginEntry` і `defineChannelPluginEntry`.
-
+
Повна довідка простору імен `api.runtime`.
-
+
Пакування, маніфести та схеми конфігурації.
-
- Утиліти тестування та правила lint.
+
+ Тестові утиліти та правила lint.
-
+
Міграція із застарілих поверхонь.
-
+
Глибока архітектура та модель можливостей.
diff --git a/docs/uk/reference/openclaw-sdk-api-design.md b/docs/uk/reference/openclaw-sdk-api-design.md
index 649b50a96..848848aac 100644
--- a/docs/uk/reference/openclaw-sdk-api-design.md
+++ b/docs/uk/reference/openclaw-sdk-api-design.md
@@ -1,30 +1,37 @@
---
read_when:
- - Ви реалізуєте запропонований публічний SDK застосунку OpenClaw
- - Вам потрібен чернетковий простір імен, подія, результат, артефакт, затвердження або контракт безпеки для SDK застосунку
- - Ви порівнюєте ресурси протоколу Gateway з високорівневою обгорткою OpenClaw SDK
-summary: Еталонний дизайн запропонованого публічного API SDK застосунку OpenClaw, таксономії подій, артефактів, схвалень і структури пакета
-title: Дизайн API OpenClaw SDK
+ - Ви впроваджуєте запропонований публічний SDK застосунку OpenClaw
+ - Вам потрібен чернетковий контракт простору імен, події, результату, артефакту, затвердження або безпеки для SDK застосунку
+ - Ви порівнюєте ресурси протоколу Gateway з високорівневою обгорткою OpenClaw App SDK
+sidebarTitle: App SDK API design
+summary: Еталонний дизайн для публічного OpenClaw App SDK API, таксономії подій, артефактів, затверджень і структури пакета
+title: Проєктування API SDK застосунків OpenClaw
x-i18n:
- generated_at: "2026-04-29T23:55:35Z"
+ generated_at: "2026-04-30T00:49:55Z"
model: gpt-5.5
provider: openai
- source_hash: c4dd0123581f4ba8332b6af9c673467092082a16488a61b5cbeac1b33e9a5dd1
+ source_hash: cacc5329942798b6876dba6ab8d6a9193291ddda81db5cb2ed492cc42a810099
source_path: reference/openclaw-sdk-api-design.md
workflow: 16
---
-Ця сторінка є докладним проєктом довідника API для запропонованого публічного
-[OpenClaw SDK](/uk/concepts/openclaw-sdk). Вона навмисно відокремлена від
-[plugin SDK](/uk/plugins/sdk-overview).
+Ця сторінка є докладним проєктом довідника API для публічного
+[OpenClaw App SDK](/uk/concepts/openclaw-sdk). Вона навмисно відокремлена від
+[Plugin SDK](/uk/plugins/sdk-overview).
-Публічний SDK застосунку має бути побудований у двох шарах:
+
+ `@openclaw/sdk` — це зовнішній пакет застосунку/клієнта для взаємодії з
+ Gateway. `openclaw/plugin-sdk/*` — це внутрішньопроцесний контракт для створення Plugin.
+ Не імпортуйте підшляхи Plugin SDK із застосунків, яким потрібно лише запускати агентів.
+
+
+Публічний SDK застосунку має бути побудований у два шари:
1. Низькорівневий згенерований клієнт Gateway.
-2. Високорівнева ергономічна обгортка з обʼєктами `OpenClaw`, `Agent`, `Session`, `Run`,
- `Task`, `Artifact`, `Approval` та `Environment`.
+2. Високорівнева ергономічна обгортка з об’єктами `OpenClaw`, `Agent`, `Session`, `Run`,
+ `Task`, `Artifact`, `Approval` і `Environment`.
-## Проєктування простору імен
+## Проєкт простору імен
Низькорівневі простори імен мають точно відповідати ресурсам Gateway:
@@ -73,7 +80,7 @@ oc.environments.status(environmentId); // future API: current SDK throws unsuppo
oc.environments.delete(environmentId); // future API: current SDK throws unsupported
```
-Високорівневі обгортки мають повертати обʼєкти, які роблять типові потоки зручними:
+Високорівневі обгортки мають повертати об’єкти, які роблять поширені потоки зручними:
```typescript
const run = await agent.run(inputOrParams);
@@ -108,43 +115,43 @@ type OpenClawEvent = {
};
```
-`id` є курсором відтворення. Споживачі мають мати змогу повторно підключитися через
-`events({ after: id })` і отримати пропущені події, якщо це дозволяє термін зберігання.
+`id` — це курсор відтворення. Споживачі мають мати змогу повторно підключитися з
+`events({ after: id })` і отримати пропущені події, якщо це дозволяє утримання.
-Рекомендовані нормалізовані сімейства подій:
+Рекомендовані сімейства нормалізованих подій:
-| Подія | Значення |
-| --------------------- | ---------------------------------------------------------- |
-| `run.created` | Запуск прийнято. |
-| `run.queued` | Запуск очікує на лінію сесії, runtime або середовище. |
-| `run.started` | Runtime почав виконання. |
-| `run.completed` | Запуск успішно завершився. |
-| `run.failed` | Запуск завершився з помилкою. |
-| `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` | Запуск або інструмент потребує схвалення. |
-| `approval.resolved` | Схвалення надано, відхилено, прострочено або скасовано. |
-| `question.requested` | Runtime просить користувача або застосунок-хост надати дані. |
-| `question.answered` | Застосунок-хост надав відповідь. |
-| `artifact.created` | Доступний новий артефакт. |
-| `artifact.updated` | Наявний артефакт змінено. |
-| `session.created` | Сесію створено. |
-| `session.updated` | Метадані сесії змінено. |
-| `session.compacted` | Відбулася Compaction сесії. |
-| `task.updated` | Стан фонової задачі змінено. |
-| `git.branch` | Runtime спостеріг або змінив стан гілки. |
-| `git.diff` | Runtime створив або змінив diff. |
-| `git.pr` | Runtime відкрив, оновив або повʼязав pull request. |
+| Подія | Значення |
+| --------------------- | ----------------------------------------------------------- |
+| `run.created` | Запуск прийнято. |
+| `run.queued` | Запуск очікує смуги сеансу, середовища виконання або оточення. |
+| `run.started` | Середовище виконання почало виконання. |
+| `run.completed` | Запуск успішно завершено. |
+| `run.failed` | Запуск завершився з помилкою. |
+| `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` | Запуск або інструмент потребує схвалення. |
+| `approval.resolved` | Схвалення надано, відхилено, прострочено або скасовано. |
+| `question.requested` | Середовище виконання запитує ввід у користувача або хост-застосунку. |
+| `question.answered` | Хост-застосунок надав відповідь. |
+| `artifact.created` | Доступний новий артефакт. |
+| `artifact.updated` | Наявний артефакт змінено. |
+| `session.created` | Сеанс створено. |
+| `session.updated` | Метадані сеансу змінено. |
+| `session.compacted` | Відбулася Compaction сеансу. |
+| `task.updated` | Стан фонового завдання змінено. |
+| `git.branch` | Середовище виконання виявило або змінило стан гілки. |
+| `git.diff` | Середовище виконання створило або змінило diff. |
+| `git.pr` | Середовище виконання відкрило, оновило або пов’язало pull request. |
-Нативні для runtime корисні навантаження мають бути доступні через `raw`, але застосунки не повинні
-розбирати `raw` для звичайного UI.
+Власні корисні навантаження середовища виконання мають бути доступні через `raw`, але застосунки не повинні
+парсити `raw` для звичайного UI.
## Контракт результату
@@ -176,16 +183,17 @@ type RunResult = {
Результат має бути простим і стабільним. Значення часових міток зберігають форму Gateway,
тому поточні запуски на основі життєвого циклу зазвичай повідомляють числа мілісекунд епохи,
-тоді як адаптери все ще можуть повертати ISO-рядки. Багатий UI, трасування інструментів і
-нативні для runtime деталі належать до подій та артефактів.
+тоді як адаптери все ще можуть показувати рядки ISO. Багатий UI, траси інструментів і
+власні деталі середовища виконання належать до подій та артефактів.
-`accepted` є нетермінальним результатом очікування: це означає, що дедлайн очікування Gateway
+`accepted` — це нетермінальний результат очікування: він означає, що крайній термін очікування Gateway
минув до того, як запуск створив завершення життєвого циклу або помилку. Його не можна трактувати як
-`timed_out`; `timed_out` зарезервовано для запуску, який перевищив власний тайм-аут runtime.
+`timed_out`; `timed_out` зарезервовано для запуску, який перевищив власний тайм-аут
+середовища виконання.
## Схвалення та запитання
-Схвалення мають бути сутностями першого класу, тому що агенти кодування постійно перетинають межі безпеки.
+Схвалення мають бути першокласними, оскільки агенти коду постійно перетинають межі безпеки.
```typescript
run.onApproval(async (request) => {
@@ -199,17 +207,18 @@ run.onApproval(async (request) => {
Події схвалення мають містити:
-- id схвалення
-- id запуску та id сесії
+- ідентифікатор схвалення
+- ідентифікатор запуску та ідентифікатор сеансу
- тип запиту
-- підсумок запитуваної дії
+- зведення запитаної дії
- назву інструмента або дію середовища
- рівень ризику
- доступні рішення
- строк дії
- чи можна повторно використати рішення
-Запитання відокремлені від схвалень. Запитання просить у користувача або застосунку-хоста інформацію. Схвалення просить дозволу виконати дію.
+Запитання відокремлені від схвалень. Запитання просить у користувача або хост-застосунку
+інформацію. Схвалення просить дозвіл виконати дію.
## Модель ToolSpace
@@ -225,14 +234,15 @@ for (const tool of tools.list()) {
SDK має надавати:
-- нормалізовані метадані інструментів
-- джерело: OpenClaw, MCP, Plugin, канал, runtime або застосунок
-- підсумок схеми
+- нормалізовані метадані інструмента
+- джерело: OpenClaw, MCP, Plugin, канал, середовище виконання або застосунок
+- зведення схеми
- політику схвалення
-- сумісність із runtime
-- чи інструмент прихований, readonly, здатний до запису або здатний до хост-дій
+- сумісність із середовищем виконання
+- чи є інструмент прихованим, лише для читання, здатним до запису або здатним працювати з хостом
-Виклик інструментів через SDK має бути явним і обмеженим за областю. Більшість застосунків мають запускати агентів, а не викликати довільні інструменти напряму.
+Виклик інструмента через SDK має бути явним і обмеженим за областю. Більшість застосунків мають
+запускати агентів, а не напряму викликати довільні інструменти.
## Модель артефактів
@@ -261,54 +271,54 @@ type ArtifactSummary = {
};
```
-Типові приклади:
+Поширені приклади:
- редагування файлів і згенеровані файли
-- пакети patch
+- пакети патчів
- diff VCS
- знімки екрана та медіавиводи
-- журнали та пакети трасування
+- журнали та пакети трас
- посилання на pull request
-- траєкторії runtime
-- знімки робочих просторів керованих середовищ
+- траєкторії середовища виконання
+- знімки робочого простору керованого середовища
-Доступ до артефактів має підтримувати редагування чутливих даних, зберігання та URL для завантаження без
+Доступ до артефактів має підтримувати редагування чутливих даних, утримання та URL-адреси для завантаження без
припущення, що кожен артефакт є звичайним локальним файлом.
## Модель безпеки
-SDK застосунку має явно визначати повноваження.
+SDK застосунку має явно описувати повноваження.
-Рекомендовані області токена:
+Рекомендовані області токенів:
| Область | Дозволяє |
| ------------------- | ---------------------------------------------------- |
-| `agent.read` | Перелічувати й переглядати агентів. |
-| `agent.run` | Запускати запуски. |
-| `session.read` | Читати метадані та повідомлення сесій. |
-| `session.write` | Створювати, надсилати до, форкати, compact і переривати сесії. |
-| `task.read` | Читати стан фонових задач. |
-| `task.write` | Скасовувати або змінювати політику сповіщень задач. |
+| `agent.read` | Перелічувати та переглядати агентів. |
+| `agent.run` | Запускати виконання. |
+| `session.read` | Читати метадані та повідомлення сеансу. |
+| `session.write` | Створювати, надсилати до, форкати, compact і переривати сеанси. |
+| `task.read` | Читати стан фонового завдання. |
+| `task.write` | Скасовувати або змінювати політику сповіщень завдань. |
| `approval.respond` | Схвалювати або відхиляти запити. |
-| `tools.invoke` | Викликати відкриті інструменти напряму. |
-| `artifacts.read` | Перелічувати й завантажувати артефакти. |
+| `tools.invoke` | Напряму викликати відкриті інструменти. |
+| `artifacts.read` | Перелічувати та завантажувати артефакти. |
| `environment.write` | Створювати або знищувати керовані середовища. |
| `admin` | Адміністративні операції. |
Типові значення:
- без пересилання секретів за замовчуванням
-- без необмеженого пропускання змінних середовища
+- без необмеженого наскрізного передавання змінних середовища
- посилання на секрети замість значень секретів
-- явна політика sandbox і мережі
-- явне зберігання віддаленого середовища
-- схвалення для виконання на хості, якщо політика не доводить інше
-- необроблені події runtime редагуються для вилучення чутливих даних перед виходом із Gateway, якщо викликач не має
+- явна політика пісочниці та мережі
+- явне утримання віддаленого середовища
+- схвалення для виконання на хості, якщо політика не доводить протилежне
+- сирі події середовища виконання редагуються до того, як залишають Gateway, якщо викликач не має
сильнішої діагностичної області
-## Провайдер керованого середовища
+## Постачальник керованого середовища
-Керовані агенти мають реалізовуватися як провайдери середовищ.
+Керовані агенти мають бути реалізовані як постачальники середовищ.
```typescript
type EnvironmentProvider = {
@@ -326,60 +336,59 @@ type EnvironmentProvider = {
};
```
-Перша реалізація не обовʼязково має бути hosted SaaS. Вона може націлюватися на
-наявні хости node, ефемерні робочі простори, runners у стилі CI або середовища
-у стилі Testbox. Важливий контракт такий:
+Перша реалізація не обов’язково має бути розміщеним SaaS. Вона може бути націлена на
+наявні хости Node, ефемерні робочі простори, runner-и у стилі CI або середовища у стилі Testbox.
+Важливий контракт такий:
1. підготувати робочий простір
-2. привʼязати безпечне середовище й секрети
-3. запустити запуск
+2. прив’язати безпечне середовище та секрети
+3. запустити виконання
4. транслювати події
5. зібрати артефакти
-6. очистити або зберегти згідно з політикою
+6. очистити або утримати відповідно до політики
-Коли це стабілізується, hosted cloud service зможе реалізувати той самий контракт провайдера.
+Коли це стане стабільним, розміщений хмарний сервіс зможе реалізувати той самий контракт
+постачальника.
-## Структура пакунків
+## Структура пакетів
-Рекомендовані пакунки:
+Рекомендовані пакети:
-| Пакунок | Призначення |
-| ----------------------- | ------------------------------------------------------------- |
+| Пакет | Призначення |
+| ----------------------- | ------------------------------------------------------------ |
| `@openclaw/sdk` | Публічний високорівневий SDK і згенерований низькорівневий клієнт Gateway. |
-| `@openclaw/sdk-react` | Опціональні хуки React для dashboards і розробників застосунків. |
+| `@openclaw/sdk-react` | Необов’язкові React-хуки для панелей керування та розробників застосунків. |
| `@openclaw/sdk-testing` | Тестові помічники та фальшивий сервер Gateway для інтеграцій застосунків. |
-У репозиторії вже є `openclaw/plugin-sdk/*` для plugins. Тримайте цей простір імен
+У репозиторії вже є `openclaw/plugin-sdk/*` для Plugin. Тримайте цей простір імен
окремо, щоб не плутати авторів Plugin із розробниками застосунків.
## Стратегія згенерованого клієнта
-Низькорівневий клієнт має генеруватися з версійованих схем протоколу Gateway,
-а потім обгортатися рукописними ергономічними класами.
+Низькорівневий клієнт має генеруватися з версійованих схем протоколу Gateway, а потім обгортатися написаними вручну зручними класами.
-Шарування:
+Шари:
-1. Джерело істини для схеми Gateway.
-2. Згенерований низькорівневий клієнт TypeScript.
-3. Валідатори часу виконання для зовнішніх вхідних даних і даних подій.
-4. Високорівневі обгортки `OpenClaw`, `Agent`, `Session`, `Run`, `Task` і `Artifact`
- .
-5. Практичні приклади та інтеграційні тести.
+1. Схеми Gateway як джерело істини.
+2. Згенерований низькорівневий TypeScript-клієнт.
+3. Валідатори часу виконання для зовнішніх вхідних даних і корисного навантаження подій.
+4. Високорівневі обгортки `OpenClaw`, `Agent`, `Session`, `Run`, `Task` і `Artifact`.
+5. Приклади рецептів і інтеграційні тести.
Переваги:
-- дрейф протоколу помітний
+- розбіжність протоколу помітна
- тести можуть порівнювати згенеровані методи з експортами Gateway
-- SDK застосунку залишається незалежним від внутрішніх компонентів SDK Plugin
+- SDK застосунку залишається незалежним від внутрішніх деталей Plugin SDK
- низькорівневі споживачі все ще мають повний доступ до протоколу
- високорівневі споживачі отримують невеликий продуктовий API
-## Пов’язані документи
+## Пов’язана документація
-- [Дизайн SDK OpenClaw](/uk/concepts/openclaw-sdk)
+- [SDK застосунку OpenClaw](/uk/concepts/openclaw-sdk)
- [Довідник RPC Gateway](/uk/reference/rpc)
- [Цикл агента](/uk/concepts/agent-loop)
- [Середовища виконання агентів](/uk/concepts/agent-runtimes)
- [Фонові завдання](/uk/automation/tasks)
- [Агенти ACP](/uk/tools/acp-agents)
-- [Огляд SDK Plugin](/uk/plugins/sdk-overview)
+- [Огляд Plugin SDK](/uk/plugins/sdk-overview)