Skip to main content

​
Plugin manifest (clawdbot.plugin.json)

Every plugin must ship a clawdbot.plugin.json file in the plugin root. Clawdbot uses this manifest to validate configuration without executing plugin code. Missing or invalid manifests are treated as plugin errors and block config validation. See the full plugin system guide: Plugins.

​
Required fields

{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}
Required keys:
  • id (string): canonical plugin id.
  • configSchema (object): JSON Schema for plugin config (inline).
Optional keys:
  • kind (string): plugin kind (example: "memory").
  • channels (array): channel ids registered by this plugin (example: ["matrix"]).
  • providers (array): provider ids registered by this plugin.
  • skills (array): skill directories to load (relative to the plugin root).
  • name (string): display name for the plugin.
  • description (string): short plugin summary.
  • uiHints (object): config field labels/placeholders/sensitive flags for UI rendering.
  • version (string): plugin version (informational).

​
JSON Schema requirements

  • Every plugin must ship a JSON Schema, even if it accepts no config.
  • An empty schema is acceptable (for example, { "type": "object", "additionalProperties": false }).
  • Schemas are validated at config read/write time, not at runtime.

​
Validation behavior

  • Unknown channels.* keys are errors, unless the channel id is declared by a plugin manifest.
  • plugins.entries.<id>, plugins.allow, plugins.deny, and plugins.slots.* must reference discoverable plugin ids. Unknown ids are errors.
  • If a plugin is installed but has a broken or missing manifest or schema, validation fails and Doctor reports the plugin error.
  • If plugin config exists but the plugin is disabled, the config is kept and a warning is surfaced in Doctor + logs.

​
Notes

  • The manifest is required for all plugins, including local filesystem loads.
  • Runtime still loads the plugin module separately; the manifest is only for discovery + validation.
  • If your plugin depends on native modules, document the build steps and any package-manager allowlist requirements (for example, pnpm allow-build-scripts
    • pnpm rebuild <package>).