OpenACP/docs/gitbook/extending/plugin-system.md
0xmrpeter 3380faa4df docs: update plugin commands for consistency and clarity
- Changed 'plugins' to 'plugin' in installation, configuration, enabling, and disabling commands for uniformity.
- Updated Node.js version requirements in install script to reflect the minimum supported version.
2026-03-31 15:40:09 +07:00

2.7 KiB

Plugin System

Note: OpenACP has been refactored to a microkernel plugin architecture. This page provides a quick overview. For the full guide, see Architecture > Plugin System.


What Are Plugins?

Plugins are modules that extend OpenACP with new capabilities. Everything beyond the core kernel is a plugin: messaging adapters (Telegram, Discord, Slack), security, speech, tunnels, usage tracking, and more.

Plugins can:

  • Register services that other plugins consume
  • Register chat commands available on all platforms
  • Register middleware to intercept and modify message flows
  • Subscribe to events for cross-plugin communication
  • Use storage for persistent data

Installing a Plugin

openacp plugin install @community/my-plugin

If the plugin has essential: true, its interactive install() hook runs immediately. Otherwise, it's registered and available on next restart.

Listing Plugins

openacp plugins

Shows all installed plugins with their version, source (builtin/npm), and enabled state.

Configuring a Plugin

openacp plugin configure @community/my-plugin

Runs the plugin's interactive configure() hook.

Disabling / Enabling

openacp plugin disable @openacp/speech
openacp plugin enable @openacp/speech

Built-in plugins cannot be uninstalled, but they can be disabled.

Uninstalling

openacp plugin uninstall @community/my-plugin
openacp plugin uninstall @community/my-plugin --purge  # also delete settings

Plugin Interface (Quick Reference)

interface OpenACPPlugin {
  name: string
  version: string
  description?: string
  pluginDependencies?: Record<string, string>
  permissions?: PluginPermission[]
  settingsSchema?: ZodSchema
  essential?: boolean

  setup(ctx: PluginContext): Promise<void>
  teardown?(): Promise<void>
  install?(ctx: InstallContext): Promise<void>
  configure?(ctx: InstallContext): Promise<void>
  migrate?(ctx: MigrateContext, oldSettings: unknown, oldVersion: string): Promise<unknown>
  uninstall?(ctx: InstallContext, opts: { purge: boolean }): Promise<void>
}

Further Reading