> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins

# 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**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi plugins list
```

**2. Install a plugin**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# From npm
agdi plugins install @openclaw/voice-call

# From a local directory or archive
agdi plugins install ./my-plugin
agdi plugins install ./my-plugin.tgz
```

**3. Restart the Gateway**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi gateway restart
```

Then configure under `plugins.entries.\<id\>.config` in your config file.

If you prefer chat-native control, enable `commands.plugins: true` and use:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/plugin install clawhub:@openclaw/voice-call
/plugin show voice-call
/plugin enable voice-call
```

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:

| Format | How it works | Examples |
| - | - | - |
| **Native** | `openclaw.plugin.json` + runtime module; executes in-process | Official plugins, community npm packages |
| **Bundle** | Codex/Claude/Cursor-compatible layout; mapped to Agdi features | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |

> [!NOTE]
>
> 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](https://agdiai-597e782f.mintlify.site/plugins/bundles.md) for bundle details.

If you are writing a native plugin, start with [Building Plugins](https://agdiai-597e782f.mintlify.site/plugins/building-plugins.md)
and the [Plugin SDK Overview](https://agdiai-597e782f.mintlify.site/plugins/sdk-overview.md).

## Official plugins

### Installable (npm)

| Plugin | Package | Docs |
| - | - | - |
| Matrix | `@openclaw/matrix` | [Matrix](https://agdiai-597e782f.mintlify.site/channels/matrix.md) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](https://agdiai-597e782f.mintlify.site/channels/msteams.md) |
| Nostr | `@openclaw/nostr` | [Nostr](https://agdiai-597e782f.mintlify.site/channels/nostr.md) |
| Voice Call | `@openclaw/voice-call` | [Voice Call](https://agdiai-597e782f.mintlify.site/plugins/voice-call.md) |
| Zalo | `@openclaw/zalo` | [Zalo](https://agdiai-597e782f.mintlify.site/channels/zalo.md) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](https://agdiai-597e782f.mintlify.site/plugins/zalouser) |

### Core (shipped with Agdi)

> [accordion] Model providers (enabled by default)
>
> `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`

> [accordion] Memory plugins
>
> * `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"`)

> [accordion] Speech providers (enabled by default)
>
> `elevenlabs`, `microsoft`

> [accordion] Other
>
> * `copilot-proxy` — VS Code Copilot Proxy bridge (disabled by default)

Looking for third-party plugins? See [Community Plugins](https://agdiai-597e782f.mintlify.site/plugins/community.md).

## Configuration

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}
```

| Field | Description |
| - | - |
| `enabled` | Master toggle (default: `true`) |
| `allow` | Plugin allowlist (optional) |
| `deny` | Plugin denylist (optional; deny wins) |
| `load.paths` | Extra plugin files/directories |
| `slots` | Exclusive slot selectors (e.g. `memory`, `contextEngine`) |
| `entries.\<id\>` | Per-plugin toggles + config |

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.

> [accordion] Plugin states: disabled vs missing vs invalid
>
> * **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):

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable
      contextEngine: "legacy", // or a plugin id
    },
  },
}
```

| Slot | What it controls | Default |
| - | - | - |
| `memory` | Active memory plugin | `memory-core` |
| `contextEngine` | Active context engine | `legacy` (built-in) |

## CLI reference

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi plugins list                    # compact inventory
agdi plugins inspect <id>            # deep detail
agdi plugins inspect <id> --json     # machine-readable
agdi plugins status                  # operational summary
agdi plugins doctor                  # diagnostics

agdi plugins install <package>        # install (ClawHub first, then npm)
agdi plugins install clawhub:<pkg>   # install from ClawHub only
agdi plugins install <path>          # install from local path
agdi plugins install -l <path>       # link (no copy) for dev
agdi plugins update <id>             # update one plugin
agdi plugins update --all            # update all

agdi plugins enable <id>
agdi plugins disable <id>
```

See [`agdi plugins` CLI reference](https://agdiai-597e782f.mintlify.site/cli/plugins) for full details.

## Plugin API overview

Plugins export either a function or an object with `register(api)`:

```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}}
export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
    api.registerChannel({
      /* ... */
    });
  },
});
```

Common registration methods:

| Method | What it registers |
| - | - |
| `registerProvider` | Model provider (LLM) |
| `registerChannel` | Chat channel |
| `registerTool` | Agent tool |
| `registerHook` / `on(...)` | Lifecycle hooks |
| `registerSpeechProvider` | Text-to-speech / STT |
| `registerMediaUnderstandingProvider` | Image/audio analysis |
| `registerImageGenerationProvider` | Image generation |
| `registerWebSearchProvider` | Web search |
| `registerHttpRoute` | HTTP endpoint |
| `registerCommand` / `registerCli` | CLI commands |
| `registerContextEngine` | Context engine |
| `registerService` | Background service |

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](https://agdiai-597e782f.mintlify.site/plugins/sdk-overview.md#hook-decision-semantics).

## Related

* [Building Plugins](https://agdiai-597e782f.mintlify.site/plugins/building-plugins.md) — create your own plugin
* [Plugin Bundles](https://agdiai-597e782f.mintlify.site/plugins/bundles.md) — Codex/Claude/Cursor bundle compatibility
* [Plugin Manifest](https://agdiai-597e782f.mintlify.site/plugins/manifest.md) — manifest schema
* [Registering Tools](https://agdiai-597e782f.mintlify.site/plugins/building-plugins.md#registering-agent-tools) — add agent tools in a plugin
* [Plugin Internals](https://agdiai-597e782f.mintlify.site/plugins/architecture.md) — capability model and load pipeline
* [Community Plugins](https://agdiai-597e782f.mintlify.site/plugins/community.md) — third-party listings


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.