OpenACP/docs/gitbook/extending/plugin-system.md
0xmrpeter add905a40c docs: clean up and simplify gitbook documentation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 22:28:37 +07:00

2.7 KiB

Plugin System Overview

Note: This page provides a quick overview of plugin management from a user's perspective. For the full technical deep dive into the plugin infrastructure, 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