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

# Plugin Entry Points

# Plugin Entry Points

Every plugin exports a default entry object. The SDK provides three helpers for
creating them.

> [!TIP]
>
> **Looking for a walkthrough?** See [Channel Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-channel-plugins.md)
> or [Provider Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-provider-plugins.md) for step-by-step guides.

## `definePluginEntry`

**Import:** `agdi/plugin-sdk/plugin-entry`

For provider plugins, tool plugins, hook plugins, and anything that is **not**
a messaging channel.

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

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});
```

| Field | Type | Required | Default |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `name` | `string` | Yes | — |
| `description` | `string` | Yes | — |
| `kind` | `string` | No | — |
| `configSchema` | `AgdiPluginConfigSchema \| () => AgdiPluginConfigSchema` | No | Empty object schema |
| `register` | `(api: AgdiPluginApi) => void` | Yes | — |

* `id` must match your `openclaw.plugin.json` manifest.
* `kind` is for exclusive slots: `"memory"` or `"context-engine"`.
* `configSchema` can be a function for lazy evaluation.

## `defineChannelPluginEntry`

**Import:** `agdi/plugin-sdk/core`

Wraps `definePluginEntry` with channel-specific wiring. Automatically calls
`api.registerChannel({ plugin })` and gates `registerFull` on registration mode.

```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}}
import { defineChannelPluginEntry } from "agdi/plugin-sdk/core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerFull(api) {
    api.registerCli(/* ... */);
    api.registerGatewayMethod(/* ... */);
  },
});
```

| Field | Type | Required | Default |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `name` | `string` | Yes | — |
| `description` | `string` | Yes | — |
| `plugin` | `ChannelPlugin` | Yes | — |
| `configSchema` | `AgdiPluginConfigSchema \| () => AgdiPluginConfigSchema` | No | Empty object schema |
| `setRuntime` | `(runtime: PluginRuntime) => void` | No | — |
| `registerFull` | `(api: AgdiPluginApi) => void` | No | — |

* `setRuntime` is called during registration so you can store the runtime reference
  (typically via `createPluginRuntimeStore`).
* `registerFull` only runs when `api.registrationMode === "full"`. It is skipped
  during setup-only loading.

## `defineSetupPluginEntry`

**Import:** `agdi/plugin-sdk/core`

For the lightweight `setup-entry.ts` file. Returns just `{ plugin }` with no
runtime or CLI wiring.

```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}}
import { defineSetupPluginEntry } from "agdi/plugin-sdk/core";

export default defineSetupPluginEntry(myChannelPlugin);
```

Agdi loads this instead of the full entry when a channel is disabled,
unconfigured, or when deferred loading is enabled. See
[Setup and Config](https://agdiai-597e782f.mintlify.site/plugins/sdk-setup.md#setup-entry) for when this matters.

## Registration mode

`api.registrationMode` tells your plugin how it was loaded:

| Mode | When | What to register |
| - | - | - |
| `"full"` | Normal gateway startup | Everything |
| `"setup-only"` | Disabled/unconfigured channel | Channel registration only |
| `"setup-runtime"` | Setup flow with runtime available | Channel + lightweight runtime |

`defineChannelPluginEntry` handles this split automatically. If you use
`definePluginEntry` directly for a channel, check mode yourself:

```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}}
register(api) {
  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerCli(/* ... */);
  api.registerService(/* ... */);
}
```

## Plugin shapes

Agdi classifies loaded plugins by their registration behavior:

| Shape | Description |
| - | - |
| **plain-capability** | One capability type (e.g. provider-only) |
| **hybrid-capability** | Multiple capability types (e.g. provider + speech) |
| **hook-only** | Only hooks, no capabilities |
| **non-capability** | Tools/commands/services but no capabilities |

Use `agdi plugins inspect <id>` to see a plugin's shape.

## Related

* [SDK Overview](https://agdiai-597e782f.mintlify.site/plugins/sdk-overview.md) — registration API and subpath reference
* [Runtime Helpers](https://agdiai-597e782f.mintlify.site/plugins/sdk-runtime.md) — `api.runtime` and `createPluginRuntimeStore`
* [Setup and Config](https://agdiai-597e782f.mintlify.site/plugins/sdk-setup.md) — manifest, setup entry, deferred loading
* [Channel Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-channel-plugins.md) — building the `ChannelPlugin` object
* [Provider Plugins](https://agdiai-597e782f.mintlify.site/plugins/sdk-provider-plugins.md) — provider registration and hooks


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