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

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

Правило:

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

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

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

Створюйте нову можливість, коли всі ці умови істинні:

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

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

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

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

Що куди належить

Ядро:

• Типи запиту/відповіді.
• Реєстр постачальників + розв’язання.
• Резервна поведінка.
• Схема конфігурації з поширеними метаданими документації title / description на вкладених об’єктах, wildcard, елементах масиву та вузлах композиції.
• Поверхня допоміжних засобів середовища виконання.

Vendor plugin:

• Виклики API постачальника.
• Обробка автентифікації постачальника.
• Нормалізація запитів, специфічна для постачальника.
• Реєстрація реалізації можливості.

Feature/channel plugin:

• Викликає api.runtime.* або відповідний допоміжний засіб plugin-sdk/*-runtime.
• Ніколи не викликає реалізацію постачальника напряму.

Межі постачальників і harness

Використовуйте provider hooks, коли поведінка належить до контракту постачальника моделі, а не до загального циклу агента. Приклади включають параметри запиту, специфічні для постачальника, після вибору транспорту, пріоритет auth-profile, накладки prompt і резервну маршрутизацію подальших запитів після failover моделі/профілю.

Використовуйте agent harness hooks, коли поведінка належить до середовища виконання, яке виконує turn. Harnesses можуть класифікувати явні результати протоколу, як-от порожній вивід, reasoning без видимого виводу або структурований план без фінальної відповіді, щоб зовнішня політика резервного використання моделі могла ухвалити рішення про повторну спробу.

Тримайте обидві межі вузькими:

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

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

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

• 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
• Один або кілька bundled plugin packages.
• Конфігурація, документація, тести.

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

Генерація зображень має стандартну форму:

1. Ядро визначає ImageGenerationProvider.
2. Ядро надає registerImageGenerationProvider(...).
3. Ядро надає runtime.imageGeneration.generate(...).
4. Plugins openai, google, fal і minimax реєструють реалізації, підтримувані постачальниками.
5. Майбутні постачальники реєструють той самий контракт без змін у каналах/інструментах.

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

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

Тримайте їх окремо, щоб резервна логіка й політика залишалися явними.

Постачальники embedding

Використовуйте embeddingProviders для reusable vector embedding providers. Цей контракт навмисно ширший за пам’ять: інструменти, пошук, retrieval, імпортери або майбутні feature plugins можуть споживати embeddings, не залежачи від рушія пам’яті.

Пошук у пам’яті може споживати загальні embeddingProviders. Старіший контракт memoryEmbeddingProviders є застарілою сумісністю, доки наявні постачальники, специфічні для пам’яті, мігрують; нові reusable embedding providers мають використовувати embeddingProviders.

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

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

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

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

Пов’язане

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