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

# Building Plugins

# Building Plugins

Plugins extend Agdi with new capabilities: channels, model providers, speech,
image generation, web search, agent tools, or any combination.

You do not need to add your plugin to the Agdi repository. Publish to
[ClawHub](https://agdiai-597e782f.mintlify.site/tools/clawhub.md) or npm and users install with
`agdi plugins install <package-name>`. Agdi tries ClawHub first and
falls back to npm automatically.

## Prerequisites

* Node >= 22 and a package manager (npm or pnpm)
* Familiarity with TypeScript (ESM)
* For in-repo plugins: repository cloned and `pnpm install` done

## What kind of plugin?

> [card] [Channel plugin](https://agdiai-597e782f.mintlify.site/plugins/sdk-channel-plugins.md)
>
> Connect Agdi to a messaging platform (Discord, IRC, etc.)

> [card] [Provider plugin](https://agdiai-597e782f.mintlify.site/plugins/sdk-provider-plugins.md)
>
> Add a model provider (LLM, proxy, or custom endpoint)

> [card] Tool / hook plugin
>
> Register agent tools, event hooks, or services — continue below

## Quick start: tool plugin

This walkthrough creates a minimal plugin that registers an agent tool. Channel
and provider plugins have dedicated guides linked above.

**1. Create the package and manifest**

```json package.json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "name": "@myorg/agdi-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "agdi": {
    "extensions": ["./index.ts"]
  }
}
```

```json openclaw.plugin.json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "Adds a custom tool to Agdi",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}
```

Every plugin needs a manifest, even with no config. See
[Manifest](https://agdiai-597e782f.mintlify.site/plugins/manifest.md) for the full schema.

**2. Write the entry point**

```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}}
// index.ts
import { definePluginEntry } from "agdi/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to Agdi",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});
```

`definePluginEntry` is for non-channel plugins. For channels, use
`defineChannelPluginEntry` — see [Channel Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-channel-plugins.md).
For full entry point options, see [Entry Points](https://agdiai-597e782f.mintlify.site/plugins/sdk-entrypoints.md).

**3. Test and publish**

**External plugins:** publish to [ClawHub](https://agdiai-597e782f.mintlify.site/tools/clawhub.md) or npm, then install:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi plugins install @myorg/agdi-my-plugin
```

Agdi checks ClawHub first, then falls back to npm.

**In-repo plugins:** place under `extensions/` — automatically discovered.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm test -- extensions/my-plugin/
```

## Plugin capabilities

A single plugin can register any number of capabilities via the `api` object:

| Capability | Registration method | Detailed guide |
| - | - | - |
| Text inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-provider-plugins.md) |
| Channel / messaging | `api.registerChannel(...)` | [Channel Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-channel-plugins.md) |
| Speech (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-provider-plugins.md#step-5-add-extra-capabilities) |
| Media understanding | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-provider-plugins.md#step-5-add-extra-capabilities) |
| Image generation | `api.registerImageGenerationProvider(...)` | [Provider Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-provider-plugins.md#step-5-add-extra-capabilities) |
| Web search | `api.registerWebSearchProvider(...)` | [Provider Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-provider-plugins.md#step-5-add-extra-capabilities) |
| Agent tools | `api.registerTool(...)` | Below |
| Custom commands | `api.registerCommand(...)` | [Entry Points](https://agdiai-597e782f.mintlify.site/plugins/sdk-entrypoints.md) |
| Event hooks | `api.registerHook(...)` | [Entry Points](https://agdiai-597e782f.mintlify.site/plugins/sdk-entrypoints.md) |
| HTTP routes | `api.registerHttpRoute(...)` | [Internals](https://agdiai-597e782f.mintlify.site/plugins/architecture.md#gateway-http-routes) |
| CLI subcommands | `api.registerCli(...)` | [Entry Points](https://agdiai-597e782f.mintlify.site/plugins/sdk-entrypoints.md) |

For the full registration API, see [SDK Overview](https://agdiai-597e782f.mintlify.site/plugins/sdk-overview.md#registration-api).

Hook guard semantics to keep in mind:

* `before_tool_call`: `{ block: true }` is terminal and stops lower-priority handlers.
* `before_tool_call`: `{ block: false }` is treated as no decision.
* `message_sending`: `{ cancel: true }` is terminal and stops lower-priority handlers.
* `message_sending`: `{ cancel: false }` is treated as no decision.

See [SDK Overview hook decision semantics](https://agdiai-597e782f.mintlify.site/plugins/sdk-overview.md#hook-decision-semantics) for details.

## Registering agent tools

Tools are typed functions the LLM can call. They can be required (always
available) or optional (user opt-in):

```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}}
register(api) {
  // Required tool — always available
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Optional tool — user must add to allowlist
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}
```

Users enable optional tools in config:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: { allow: ["workflow_tool"] },
}
```

* Tool names must not clash with core tools (conflicts are skipped)
* Use `optional: true` for tools with side effects or extra binary requirements
* Users can enable all tools from a plugin by adding the plugin id to `tools.allow`

## Import conventions

Always import from focused `agdi/plugin-sdk/<subpath>` paths:

```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}}
import { definePluginEntry } from "agdi/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "agdi/plugin-sdk/runtime-store";

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "agdi/plugin-sdk";
```

For the full subpath reference, see [SDK Overview](https://agdiai-597e782f.mintlify.site/plugins/sdk-overview.md).

Within your plugin, use local barrel files (`api.ts`, `runtime-api.ts`) for
internal imports — never import your own plugin through its SDK path.

## Pre-submission checklist

> [!TIP]
>
> **package.json** has correct `agdi` metadata

> [!TIP]
>
> **openclaw\.plugin.json** manifest is present and valid

> [!TIP]
>
> Entry point uses `defineChannelPluginEntry` or `definePluginEntry`

> [!TIP]
>
> All imports use focused `plugin-sdk/<subpath>` paths

> [!TIP]
>
> Internal imports use local modules, not SDK self-imports

> [!TIP]
>
> Tests pass (`pnpm test -- extensions/my-plugin/`)

> [!TIP]
>
> `pnpm check` passes (in-repo plugins)

## Next steps

> [card] [Channel Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-channel-plugins.md)
>
> Build a messaging channel plugin

> [card] [Provider Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-provider-plugins.md)
>
> Build a model provider plugin

> [card] [SDK Overview](https://agdiai-597e782f.mintlify.site/plugins/sdk-overview.md)
>
> Import map and registration API reference

> [card] [Runtime Helpers](https://agdiai-597e782f.mintlify.site/plugins/sdk-runtime.md)
>
> TTS, search, subagent via api.runtime

> [card] [Testing](https://agdiai-597e782f.mintlify.site/plugins/sdk-testing.md)
>
> Test utilities and patterns

> [card] [Plugin Manifest](https://agdiai-597e782f.mintlify.site/plugins/manifest.md)
>
> Full manifest schema reference


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