​

Маніфест плагіна (openclaw.plugin.json)

• Пакет Codex: .codex-plugin/plugin.json
• Пакет Claude: .claude-plugin/plugin.json або стандартний макет компонента Claude без маніфесту
• Пакет Cursor: .cursor-plugin/plugin.json

​

Для чого потрібен цей файл

• ідентичності плагіна
• валідації конфігурації
• метаданих автентифікації та онбордингу, які мають бути доступні без запуску середовища виконання плагіна
• легких підказок активації, які поверхні control-plane можуть перевіряти до завантаження середовища виконання
• легких дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до завантаження середовища виконання
• метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження середовища виконання плагіна
• скорочених метаданих належності до сімейства моделей, які мають автоматично активувати плагін до завантаження середовища виконання
• статичних знімків належності можливостей, що використовуються для сумісної обв’язки bundled-плагінів і покриття контрактів
• метаданих конфігурації каналу, специфічних для каналу, які мають зливатися в поверхні каталогу та валідації без завантаження середовища виконання
• підказок UI для конфігурації

• реєстрації поведінки під час виконання
• оголошення кодових entrypoint
• метаданих встановлення npm

​

Мінімальний приклад

{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

​

Розширений приклад

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API key",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API key",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

​

Довідка щодо полів верхнього рівня

​

Довідка щодо providerAuthChoices

​

Довідка щодо commandAliases

{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}

​

Довідка щодо activation

{
  "activation": {
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onCapabilities": ["provider", "tool"]
  }
}

​

Довідка щодо setup

{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}

​

Довідка щодо setup.providers

​

Поля setup

​

Довідка щодо uiHints

{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

​

Довідка щодо contracts

{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

​

Довідка щодо channelConfigs

{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Підключення до homeserver Matrix",
      "preferOver": ["matrix-legacy"]
    }
  }
}

​

Довідка щодо modelSupport

{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}

• явні посилання provider/model використовують метадані маніфесту власника providers
• modelPatterns мають пріоритет над modelPrefixes
• якщо збігаються один не-bundled плагін і один bundled-плагін, перемагає не-bundled плагін
• решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть провайдера

​

Маніфест і package.json

• якщо OpenClaw повинен знати це до завантаження коду плагіна, помістіть це в openclaw.plugin.json
• якщо це стосується пакування, entry-файлів або поведінки встановлення npm, помістіть це в package.json

​

Поля package.json, які впливають на виявлення

{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}

{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}

​

Вимоги до JSON Schema

• Кожен плагін повинен постачатися з JSON Schema, навіть якщо він не приймає конфігурацію.
• Порожня схема допустима (наприклад, { "type": "object", "additionalProperties": false }).
• Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime.

​

Поведінка валідації

• Невідомі ключі channels.* є помилками, якщо тільки id каналу не оголошено маніфестом плагіна.
• plugins.entries.<id>, plugins.allow, plugins.deny і plugins.slots.* повинні посилатися на виявлювані id плагінів. Невідомі id є помилками.
• Якщо плагін встановлено, але він має зламаний або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку плагіна.
• Якщо конфігурація плагіна існує, але сам плагін вимкнений, конфігурація зберігається, і у Doctor + журналах відображається попередження.

​

Примітки

• Маніфест обов’язковий для власних плагінів OpenClaw, включно із завантаженням із локальної файлової системи.
• Runtime і далі завантажує модуль плагіна окремо; маніфест використовується лише для виявлення + валідації.
• Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо кінцеве значення все одно є об’єктом.
• Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання тут власних ключів верхнього рівня.
• providerAuthEnvVars — це шлях дешевих метаданих для перевірок автентифікації, валідації env-маркерів та подібних поверхонь автентифікації провайдера, які не повинні запускати runtime плагіна лише для перевірки назв env.
• providerAuthAliases дозволяє варіантам провайдерів повторно використовувати vars env автентифікації, профілі автентифікації, автентифікацію на основі конфігурації та варіант онбордингу з API key іншого провайдера без жорсткого кодування цього зв’язку в core.
• channelEnvVars — це шлях дешевих метаданих для fallback через shell-env, підказок налаштування та подібних поверхонь каналів, які не повинні запускати runtime плагіна лише для перевірки назв env.
• providerAuthChoices — це шлях дешевих метаданих для picker варіантів автентифікації, визначення --auth-choice, мапінгу бажаного провайдера та простої реєстрації прапорців CLI для онбордингу до завантаження runtime провайдера. Для метаданих wizard runtime, які потребують коду провайдера, див. Хуки runtime провайдера.
• Виняткові види плагінів вибираються через plugins.slots.*.
  • kind: "memory" вибирається через plugins.slots.memory.
  • kind: "context-engine" вибирається через plugins.slots.contextEngine (типово: вбудований legacy).
• channels, providers, cliBackends і skills можна не вказувати, якщо плагіну вони не потрібні.
• Якщо ваш плагін залежить від native-модулів, задокументуйте кроки збирання та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Пов’язане

• Створення плагінів — початок роботи з плагінами
• Архітектура плагінів — внутрішня архітектура
• Огляд SDK — довідник Plugin SDK