Додавання можливостей (посібник для учасників проєкту)

Використовуйте цей підхід, коли OpenClaw потребує нової спільної предметної області, як-от векторні представлення, генерація зображень, генерація відео або певна майбутня функціональна область, реалізована постачальниками.

Правило:

• плагін = межа володіння
• можливість = спільний контракт ядра

Не підключайте постачальника безпосередньо до каналу або інструмента. Спочатку визначте можливість.

Коли створювати можливість

Створюйте нову можливість, лише якщо виконуються всі наведені умови:

1. Її потенційно може реалізувати більш ніж один постачальник.
2. Канали, інструменти або функціональні плагіни мають використовувати її незалежно від постачальника.
3. Ядро має керувати резервуванням, політикою, конфігурацією або доставленням.

Якщо робота стосується лише одного постачальника, а спільного контракту ще немає, спочатку визначте контракт.

Стандартна послідовність

1. Визначте типізований контракт ядра.
2. Додайте реєстрацію плагіна для цього контракту.
3. Додайте спільний допоміжний засіб середовища виконання.
4. Підключіть один реальний плагін постачальника як підтвердження працездатності.
5. Переведіть споживачів функцій і каналів на допоміжний засіб середовища виконання.
6. Додайте тести контракту.
7. Задокументуйте доступну оператору конфігурацію та модель володіння.

Розподіл відповідальності

Точки розширення провайдера та середовища агента

Використовуйте хуки провайдера, коли поведінка належить до контракту провайдера моделі, а не до загального циклу агента. Прикладами є специфічні для провайдера параметри запиту після вибору транспорту, пріоритет профілю автентифікації, доповнення промпту та подальша резервна маршрутизація після перемикання моделі або профілю через збій.

Використовуйте хуки середовища агента, коли поведінка належить до середовища виконання, яке виконує хід. Середовища можуть класифікувати явні результати протоколу, як-от порожній вивід, міркування без видимого виводу або структурований план без остаточної відповіді, щоб зовнішня політика резервування моделей могла вирішити, чи повторювати спробу.

Зберігайте обидві точки розширення вузькими:

• Ядро керує політикою повторних спроб і резервування.
• Плагіни провайдерів керують специфічними для провайдера підказками щодо запитів, автентифікації та маршрутизації.
• Плагіни середовищ керують специфічною для середовища виконання класифікацією спроб.
• Сторонні плагіни повертають підказки, а не безпосередньо змінюють стан ядра.

Контрольний список файлів

Для нової можливості зазвичай потрібно змінити такі області:

• src/<capability>/types.ts
• src/<capability>/...registry/runtime.ts
• src/plugins/types.ts
• src/plugins/registry.ts
• src/plugins/captured-registration.ts
• src/plugins/contracts/registry.ts
• src/plugins/runtime/types-core.ts
• src/plugins/runtime/index.ts
• src/plugin-sdk/<capability>.ts
• src/plugin-sdk/<capability>-runtime.ts
• Один або кілька пакетів вбудованих плагінів.
• Конфігурацію, документацію та тести.

Практичний приклад: генерація зображень

Генерація зображень відповідає стандартній структурі:

1. Ядро визначає ImageGenerationProvider.
2. Ядро надає registerImageGenerationProvider(...).
3. Ядро надає api.runtime.imageGeneration.generate(...) і .listProviders(...).
4. Плагіни постачальників (comfy, deepinfra, fal, google, litellm, microsoft-foundry, minimax, openai, openrouter, vydra, xai) реєструють реалізації відповідних постачальників.
5. Майбутні постачальники реєструють той самий контракт без змін у каналах або інструментах.

Ключ конфігурації навмисно відокремлено від маршрутизації аналізу зображень:

• agents.defaults.imageModel аналізує зображення.
• agents.defaults.imageGenerationModel генерує зображення.

Не об’єднуйте їх, щоб резервування та політика залишалися явними.

Провайдери векторних представлень

Використовуйте registerEmbeddingProvider(...) / контракт embeddingProviders для багаторазово використовуваних провайдерів векторних представлень. Цей контракт навмисно має ширшу сферу застосування, ніж пам’ять: інструменти, пошук, отримання даних, засоби імпорту або майбутні функціональні плагіни можуть використовувати векторні представлення без залежності від рушія пам’яті. Пошук у пам’яті також використовує універсальні embeddingProviders.

Старі API реєстрації та контракт memoryEmbeddingProviders, призначені лише для пам’яті, застаріли. Для всіх нових провайдерів векторних представлень використовуйте registerEmbeddingProvider і embeddingProviders.

Контрольний список перевірки

Перед випуском нової можливості перевірте:

• Жоден канал або інструмент не імпортує код постачальника безпосередньо.
• Допоміжний засіб середовища виконання є спільним шляхом.
• Принаймні один тест контракту перевіряє володіння вбудованим компонентом.
• Документація конфігурації зазначає нову модель або ключ конфігурації.
• Документація плагіна пояснює межу володіння.

Якщо PR оминає рівень можливостей і жорстко вбудовує поведінку постачальника в канал або інструмент, поверніть його на доопрацювання та спочатку визначте контракт.

Пов’язані матеріали

• Внутрішня архітектура плагінів — модель можливостей, володіння, конвеєр завантаження та допоміжні засоби середовища виконання.
• Створення плагінів — посібник зі створення першого плагіна.
• Огляд SDK — довідник із карти імпортів та API реєстрації.
• Створення Skills — пов’язаний інтерфейс для учасників розробки.