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

Используйте этот подход, когда 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 — сопутствующий интерфейс для участников разработки.