Use the narrowest import that matches the job. If you cannot find an export,

check the source at `src/plugin-sdk/` or ask in Discord.

## Active deprecations

Narrower deprecations that apply across the plugin SDK, provider contract,

runtime surface, and manifest. Each one still works today but will be removed

in a future major release. The entry below every item maps the old API to its

canonical replacement.

<AccordionGroup>

<Accordion title="command-auth help builders → command-status">

**Old (`openclaw/plugin-sdk/command-auth`)**: `buildCommandsMessage`,

`buildCommandsMessagePaginated`, `buildHelpMessage`.

**New (`openclaw/plugin-sdk/command-status`)**: same signatures, same

exports — just imported from the narrower subpath. `command-auth`

re-exports them as compat stubs.

```typescript

// Before

import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After

import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

```

</Accordion>

<Accordion title="Mention gating helpers → resolveInboundMentionDecision">

**Old**: `resolveInboundMentionRequirement({ facts, policy })` and

`shouldDropInboundForMention(...)` from

`openclaw/plugin-sdk/channel-inbound` or

`openclaw/plugin-sdk/channel-mention-gating`.

**New**: `resolveInboundMentionDecision({ facts, policy })` — returns a

single decision object instead of two split calls.

Downstream channel plugins (Slack, Discord, Matrix, MS Teams) have already

switched.

</Accordion>

<Accordion title="Channel runtime shim and channel actions helpers">

`openclaw/plugin-sdk/channel-runtime` is a compatibility shim for older

channel plugins. Do not import it from new code; use

`openclaw/plugin-sdk/channel-runtime-context` for registering runtime

objects.

`channelActions*` helpers in `openclaw/plugin-sdk/channel-actions` are

deprecated alongside raw "actions" channel exports. Expose capabilities

through the semantic `presentation` surface instead — channel plugins

declare what they render (cards, buttons, selects) rather than which raw

action names they accept.

</Accordion>

<Accordion title="Web search provider tool() helper → createTool() on the plugin">

**Old**: `tool()` factory from `openclaw/plugin-sdk/provider-web-search`.

**New**: implement `createTool(...)` directly on the provider plugin.

OpenClaw no longer needs the SDK helper to register the tool wrapper.

</Accordion>

<Accordion title="Plaintext channel envelopes → BodyForAgent">

**Old**: `formatInboundEnvelope(...)` (and

`ChannelMessageForAgent.channelEnvelope`) to build a flat plaintext prompt

envelope from inbound channel messages.

**New**: `BodyForAgent` plus structured user-context blocks. Channel

plugins attach routing metadata (thread, topic, reply-to, reactions) as

typed fields instead of concatenating them into a prompt string. The

`formatAgentEnvelope(...)` helper is still supported for synthesized

assistant-facing envelopes, but inbound plaintext envelopes are on the

way out.

Affected areas: `inbound_claim`, `message_received`, and any custom

channel plugin that post-processed `channelEnvelope` text.

</Accordion>

<Accordion title="Provider discovery types → provider catalog types">

Four discovery type aliases are now thin wrappers over the

catalog-era types:

| Old alias | New type |

| ------------------------- | ------------------------- |

| `ProviderDiscoveryOrder` | `ProviderCatalogOrder` |

| `ProviderDiscoveryContext`| `ProviderCatalogContext` |

| `ProviderDiscoveryResult` | `ProviderCatalogResult` |

| `ProviderPluginDiscovery` | `ProviderPluginCatalog` |

Plus the legacy `ProviderCapabilities` static bag — provider plugins

should attach capability facts through the provider runtime contract

rather than a static object.

</Accordion>

<Accordion title="Thinking policy hooks → resolveThinkingProfile">

**Old** (three separate hooks on `ProviderThinkingPolicy`):

`isBinaryThinking(ctx)`, `supportsXHighThinking(ctx)`, and

`resolveDefaultThinkingLevel(ctx)`.

**New**: a single `resolveThinkingProfile(ctx)` that returns a

`ProviderThinkingProfile` with the canonical `id`, optional `label`, and

ranked level list. OpenClaw downgrades stale stored values by profile

rank automatically.

Implement one hook instead of three. The legacy hooks keep working during

the deprecation window but are not composed with the profile result.

</Accordion>

<Accordion title="External OAuth provider fallback → contracts.externalAuthProviders">

**Old**: implementing `resolveExternalOAuthProfiles(...)` without

declaring the provider in the plugin manifest.

**New**: declare `contracts.externalAuthProviders` in the plugin manifest

**and** implement `resolveExternalAuthProfiles(...)`. The old "auth

fallback" path emits a warning at runtime and will be removed.

```json

{

"contracts": {

"externalAuthProviders": ["anthropic", "openai"]

}

}

```

</Accordion>

<Accordion title="Provider env-var lookup → setup.providers[].envVars">

**Old** manifest field: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`.

**New**: mirror the same env-var lookup into `setup.providers[].envVars`

on the manifest. This consolidates setup/status env metadata in one

place and avoids booting the plugin runtime just to answer env-var

lookups.

`providerAuthEnvVars` remains supported through a compatibility adapter

until the deprecation window closes.

</Accordion>

<Accordion title="Memory plugin registration → registerMemoryCapability">

**Old**: three separate calls —

`api.registerMemoryPromptSection(...)`,

`api.registerMemoryFlushPlan(...)`,

`api.registerMemoryRuntime(...)`.

**New**: one call on the memory-state API —

`registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`.

Same slots, single registration call. Additive memory helpers

(`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`,

`registerMemoryEmbeddingProvider`) are not affected.

</Accordion>

<Accordion title="Subagent session messages types renamed">

Two legacy type aliases still exported from `src/plugins/runtime/types.ts`:

| Old | New |

| ----------------------------- | ------------------------------- |

| `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` |

| `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` |

The runtime method `readSession` is deprecated in favor of

`getSessionMessages`. Same signature; the old method calls through to the

new one.

</Accordion>

<Accordion title="runtime.tasks.flow → runtime.tasks.flows">

**Old**: `runtime.tasks.flow` (singular) returned a live task-flow accessor.

**New**: `runtime.tasks.flows` (plural) returns DTO-based TaskFlow access,

which is import-safe and does not require the full task runtime to be

loaded.

```typescript

// Before

const flow = api.runtime.tasks.flow(ctx);

// After

const flows = api.runtime.tasks.flows(ctx);

```

</Accordion>

<Accordion title="Embedded extension factories → agent tool-result middleware">

Covered in "How to migrate → Migrate Pi tool-result extensions to

middleware" above. Included here for completeness: the Pi-only

`api.registerEmbeddedExtensionFactory(...)` path is deprecated in favor of

`api.registerAgentToolResultMiddleware(...)` with an explicit harness

list in `contracts.agentToolResultMiddleware`.

</Accordion>

<Accordion title="OpenClawSchemaType alias → OpenClawConfig">

`OpenClawSchemaType` re-exported from `openclaw/plugin-sdk` is now a

one-line alias for `OpenClawConfig`. Prefer the canonical name.

```typescript

// Before

import type { OpenClawSchemaType } from "openclaw/plugin-sdk";

// After

import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

```

</Accordion>

</AccordionGroup>

<Note>

Extension-level deprecations (inside bundled channel/provider plugins under

`extensions/`) are tracked inside their own `api.ts` and `runtime-api.ts`

barrels. They do not affect third-party plugin contracts and are not listed

here. If you consume a bundled plugin's local barrel directly, read the

deprecation comments in that barrel before upgrading.

</Note>

## Removal timeline

| When | What happens |