Skip to main content

Plugins

Plugins extend Agdi with new capabilities: channels, model providers, tools, skills, speech, image generation, and more. Some plugins are core (shipped with Agdi), others are external (published on npm by the community).

Quick start

1

See what is loaded

2

Install a plugin

3

Restart the Gateway

Then configure under plugins.entries.\<id\>.config in your config file.
If you prefer chat-native control, enable commands.plugins: true and use:
The install path uses the same resolver as the CLI: local path/archive, explicit clawhub:<pkg>, or bare package spec (ClawHub first, then npm fallback).

Plugin types

Agdi recognizes two plugin formats:
The native manifest filename and official npm package scope remain openclaw.plugin.json and @openclaw/* for compatibility. Use agdi for CLI commands and agdi/plugin-sdk/* for new plugin SDK imports.
Both show up under agdi plugins list. See Plugin Bundles for bundle details. If you are writing a native plugin, start with Building Plugins and the Plugin SDK Overview.

Official plugins

Installable (npm)

Core (shipped with Agdi)

anthropic, byteplus, cloudflare-ai-gateway, github-copilot, google, huggingface, kilocode, kimi-coding, minimax, mistral, modelstudio, moonshot, nvidia, openai, opencode, opencode-go, openrouter, qianfan, qwen-portal-auth, synthetic, together, venice, vercel-ai-gateway, volcengine, xiaomi, zai
  • memory-core — bundled memory search (default via plugins.slots.memory)
  • memory-lancedb — install-on-demand long-term memory with auto-recall/capture (set plugins.slots.memory = "memory-lancedb")
elevenlabs, microsoft
  • copilot-proxy — VS Code Copilot Proxy bridge (disabled by default)
Looking for third-party plugins? See Community Plugins.

Configuration

Config changes require a gateway restart. If the Gateway is running with config watch + in-process restart enabled (the default agdi gateway path), that restart is usually performed automatically a moment after the config write lands.
  • Disabled: plugin exists but enablement rules turned it off. Config is preserved.
  • Missing: config references a plugin id that discovery did not find.
  • Invalid: plugin exists but its config does not match the declared schema.

Discovery and precedence

Agdi scans for plugins in this order (first match wins):
1

Config paths

plugins.load.paths — explicit file or directory paths.
2

Workspace extensions

\<workspace\>/.agdi/extensions/*.ts and \<workspace\>/.agdi/extensions/*/index.ts.
3

Global extensions

~/.agdi/extensions/*.ts and ~/.agdi/extensions/*/index.ts.
4

Bundled plugins

Shipped with Agdi. Many are enabled by default (model providers, speech). Others require explicit enablement.

Enablement rules

  • plugins.enabled: false disables all plugins
  • plugins.deny always wins over allow
  • plugins.entries.\<id\>.enabled: false disables that plugin
  • Workspace-origin plugins are disabled by default (must be explicitly enabled)
  • Bundled plugins follow the built-in default-on set unless overridden
  • Exclusive slots can force-enable the selected plugin for that slot

Plugin slots (exclusive categories)

Some categories are exclusive (only one active at a time):

CLI reference

See agdi plugins CLI reference for full details.

Plugin API overview

Plugins export either a function or an object with register(api):
Common registration methods: Hook guard behavior for typed lifecycle hooks:
  • before_tool_call: { block: true } is terminal; lower-priority handlers are skipped.
  • before_tool_call: { block: false } is a no-op and does not clear an earlier block.
  • message_sending: { cancel: true } is terminal; lower-priority handlers are skipped.
  • message_sending: { cancel: false } is a no-op and does not clear an earlier cancel.
For full typed hook behavior, see SDK Overview.