​

Manifest Pluginu (openclaw.plugin.json)

• Bundle Codex: .codex-plugin/plugin.json
• Bundle Claude: .claude-plugin/plugin.json lub domyślny układ komponentów Claude bez manifestu
• Bundle Cursor: .cursor-plugin/plugin.json

​

Do czego służy ten plik

• tożsamości Pluginu
• walidacji konfiguracji
• metadanych uwierzytelniania i onboardingu, które powinny być dostępne bez uruchamiania runtime Pluginu
• tanich wskazówek aktywacji, które powierzchnie control-plane mogą sprawdzać przed załadowaniem runtime
• tanich deskryptorów konfiguracji, które powierzchnie konfiguracji/onboardingu mogą sprawdzać przed załadowaniem runtime
• metadanych aliasów i automatycznego włączania, które powinny być rozwiązywane przed załadowaniem runtime Pluginu
• skróconych metadanych własności rodziny modeli, które powinny automatycznie aktywować Plugin przed załadowaniem runtime
• statycznych snapshotów własności capabilities używanych do wbudowanego okablowania zgodności i pokrycia kontraktów
• tanich metadanych runnera QA, które współdzielony host openclaw qa może sprawdzać przed załadowaniem runtime Pluginu
• metadanych konfiguracji specyficznych dla kanału, które powinny być scalane z powierzchniami katalogu i walidacji bez ładowania runtime
• wskazówek dla UI konfiguracji

• rejestrowania zachowania runtime
• deklarowania entrypointów kodu
• metadanych instalacji npm

​

Minimalny przykład

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

​

Rozbudowany przykład

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "Plugin providera OpenRouter",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "providerEndpoints": [
    {
      "endpointClass": "xai-native",
      "hosts": ["api.x.ai"]
    }
  ],
  "cliBackends": ["openrouter-cli"],
  "syntheticAuthRefs": ["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": "Klucz API OpenRouter",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "Klucz API OpenRouter",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "Klucz API",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

​

Opis pól najwyższego poziomu

​

Opis providerAuthChoices

​

Opis commandAliases

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

​

Opis activation

​

Opis qaRunners

{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Uruchom opartą na Dockerze aktywną ścieżkę QA Matrix przeciwko tymczasowemu homeserverowi"
    }
  ]
}

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

• planowanie CLI wyzwalane poleceniami wraca do starszych commandAliases[].cliCommand lub commandAliases[].name
• planowanie konfiguracji/kanału wyzwalane kanałem wraca do starszej własności channels[], gdy brakuje jawnych metadanych aktywacji kanału
• planowanie konfiguracji/runtime wyzwalane providerem wraca do starszej własności providers[] i najwyższego poziomu cliBackends[], gdy brakuje jawnych metadanych aktywacji providera

​

Opis setup

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

​

Opis setup.providers

​

Pola setup

​

Opis uiHints

{
  "uiHints": {
    "apiKey": {
      "label": "Klucz API",
      "help": "Używany do żądań OpenRouter",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

​

Opis 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"]
  }
}

​

Opis channelConfigs

{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "URL homeservera",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Połączenie z homeserverem Matrix",
      "preferOver": ["matrix-legacy"]
    }
  }
}

​

Opis modelSupport

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

• jawne odwołania provider/model używają metadanych manifestu providers należących do właściciela
• modelPatterns mają pierwszeństwo przed modelPrefixes
• jeśli pasują jednocześnie jeden Plugin niewbudowany i jeden wbudowany, wygrywa Plugin niewbudowany
• pozostała niejednoznaczność jest ignorowana, dopóki użytkownik lub konfiguracja nie określi providera

​

Manifest a package.json

• jeśli OpenClaw musi znać go przed załadowaniem kodu Pluginu, umieść go w openclaw.plugin.json
• jeśli dotyczy pakowania, plików entry lub zachowania instalacji npm, umieść go w package.json

​

Pola package.json, które wpływają na wykrywanie

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

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

​

Wymagania JSON Schema

• Każdy Plugin musi dostarczać JSON Schema, nawet jeśli nie przyjmuje żadnej konfiguracji.
• Pusty schemat jest akceptowalny (na przykład { "type": "object", "additionalProperties": false }).
• Schematy są walidowane podczas odczytu/zapisu konfiguracji, a nie w runtime.

​

Zachowanie walidacji

• Nieznane klucze channels.* są błędami, chyba że identyfikator kanału jest zadeklarowany przez manifest Pluginu.
• plugins.entries.<id>, plugins.allow, plugins.deny i plugins.slots.* muszą odwoływać się do wykrywalnych identyfikatorów Pluginów. Nieznane identyfikatory są błędami.
• Jeśli Plugin jest zainstalowany, ale ma uszkodzony lub brakujący manifest albo schemat, walidacja kończy się niepowodzeniem, a Doctor zgłasza błąd Pluginu.
• Jeśli konfiguracja Pluginu istnieje, ale Plugin jest wyłączony, konfiguracja zostaje zachowana, a w Doctor + logach pojawia się ostrzeżenie.

​

Uwagi

• Manifest jest wymagany dla natywnych Pluginów OpenClaw, w tym dla ładowania z lokalnego systemu plików.
• Runtime nadal ładuje moduł Pluginu osobno; manifest służy wyłącznie do wykrywania + walidacji.
• Natywne manifesty są parsowane przy użyciu JSON5, więc komentarze, końcowe przecinki i klucze bez cudzysłowów są akceptowane, o ile wartość końcowa nadal jest obiektem.
• Loader manifestu odczytuje wyłącznie udokumentowane pola manifestu. Unikaj dodawania tutaj własnych kluczy najwyższego poziomu.
• providerAuthEnvVars to lekka ścieżka metadanych dla sprawdzeń auth, walidacji znaczników env i podobnych powierzchni auth providera, które nie powinny uruchamiać runtime Pluginu tylko po to, aby sprawdzić nazwy env.
• providerAuthAliases pozwala wariantom providera ponownie używać zmiennych env auth, profili auth, auth opartego na konfiguracji i wyboru onboardingu klucza API innego providera bez hardcodowania tej relacji w rdzeniu.
• providerEndpoints pozwala Pluginom providera zarządzać prostymi metadanymi dopasowywania hosta/baseUrl endpointu. Używaj tego tylko dla klas endpointów, które rdzeń już obsługuje; zachowanie runtime nadal należy do Pluginu.
• syntheticAuthRefs to lekka ścieżka metadanych dla należących do providera hooków synthetic auth, które muszą być widoczne dla zimnego wykrywania modeli, zanim rejestr runtime zacznie istnieć. Wypisuj tylko odwołania, których runtime provider lub backend CLI rzeczywiście implementuje resolveSyntheticAuth.
• nonSecretAuthMarkers to lekka ścieżka metadanych dla należących do wbudowanego Pluginu zastępczych kluczy API, takich jak znaczniki lokalne, OAuth lub ambient credential. Rdzeń traktuje je jako niesekretne na potrzeby wyświetlania auth i audytów sekretów bez hardcodowania właściciela providera.
• channelEnvVars to lekka ścieżka metadanych dla fallbacku shell-env, promptów konfiguracji i podobnych powierzchni kanału, które nie powinny uruchamiać runtime Pluginu tylko po to, aby sprawdzić nazwy env.
• providerAuthChoices to lekka ścieżka metadanych dla selektorów wyboru auth, rozwiązywania --auth-choice, mapowania preferowanego providera i prostej rejestracji flag CLI onboardingu przed załadowaniem runtime providera. Metadane kreatora runtime, które wymagają kodu providera, opisano tutaj: Hooki runtime providera.
• Wyłączne typy Pluginów są wybierane przez plugins.slots.*.
  • kind: "memory" jest wybierane przez plugins.slots.memory.
  • kind: "context-engine" jest wybierane przez plugins.slots.contextEngine (domyślnie: wbudowane legacy).
• channels, providers, cliBackends i skills można pominąć, jeśli Plugin ich nie potrzebuje.
• Jeśli Twój Plugin zależy od modułów natywnych, opisz kroki budowania oraz wszelkie wymagania dotyczące allowlist menedżera pakietów (na przykład pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Powiązane

• Tworzenie Pluginów — pierwsze kroki z Pluginami
• Architektura Pluginów — architektura wewnętrzna
• Przegląd SDK — opis Plugin SDK