<AccordionGroup>

<Accordion title="Implementation notes">

- Button callbacks use HMAC-SHA256 verification (automatic, no config needed).

- Mattermost strips callback data from its API responses (security feature), so all buttons are removed on click — partial removal is not possible.

- Mattermost strips callback data from its API responses (security feature), so all buttons are removed on click - partial removal is not possible.

- Action IDs containing hyphens or underscores are sanitized automatically (Mattermost routing limitation).

</Accordion>

{

actions: [

{

id: "mybutton01", // alphanumeric only — see below

id: "mybutton01", // alphanumeric only - see below

type: "button", // required, or clicks are silently ignored

name: "Approve", // display label

style: "primary", // optional: "default", "primary", "danger"

**Critical rules**

1. Attachments go in `props.attachments`, not top-level `attachments` (silently ignored).

2. Every action needs `type: "button"` — without it, clicks are swallowed silently.

3. Every action needs an `id` field — Mattermost ignores actions without IDs.

2. Every action needs `type: "button"` - without it, clicks are swallowed silently.

3. Every action needs an `id` field - Mattermost ignores actions without IDs.

4. Action `id` must be **alphanumeric only** (`[a-zA-Z0-9]`). Hyphens and underscores break Mattermost's server-side action routing (returns 404). Strip them before use.

5. `context.action_id` must match the button's `id` so the confirmation message shows the button name (e.g., "Approve") instead of a raw ID.

6. `context.action_id` is required — the interaction handler returns 400 without it.

6. `context.action_id` is required - the interaction handler returns 400 without it.

</Warning>

<Accordion title="Common HMAC pitfalls">

- Python's `json.dumps` adds spaces by default (`{"key": "val"}`). Use `separators=(",", ":")` to match JavaScript's compact output (`{"key":"val"}`).

- Always sign **all** context fields (minus `_token`). The gateway strips `_token` then signs everything remaining. Signing a subset causes silent verification failure.

- Use `sort_keys=True` — the gateway sorts keys before signing, and Mattermost may reorder context fields when storing the payload.

- Use `sort_keys=True` - the gateway sorts keys before signing, and Mattermost may reorder context fields when storing the payload.

- Derive the secret from the bot token (deterministic), not random bytes. The secret must be the same across the process that creates buttons and the gateway that verifies.

</Accordion>

The Mattermost plugin includes a directory adapter that resolves channel and user names via the Mattermost API. This enables `#channel-name` and `@username` targets in `openclaw message send` and cron/webhook deliveries.

No configuration is needed — the adapter uses the bot token from the account config.

No configuration is needed - the adapter uses the bot token from the account config.

## Multi-account

## Related

- [Channel Routing](/channels/channel-routing) — session routing for messages

- [Channels Overview](/channels) — all supported channels

- [Groups](/channels/groups) — group chat behavior and mention gating

- [Pairing](/channels/pairing) — DM authentication and pairing flow

- [Security](/gateway/security) — access model and hardening

- [Channel Routing](/channels/channel-routing) - session routing for messages

- [Channels Overview](/channels) - all supported channels

- [Groups](/channels/groups) - group chat behavior and mention gating

- [Pairing](/channels/pairing) - DM authentication and pairing flow

- [Security](/gateway/security) - access model and hardening

## Built-in providers (pi-ai catalog)

OpenClaw ships with the pi‑ai catalog. These providers require **no** `models.providers` config; just set auth + pick a model.

OpenClaw ships with the pi-ai catalog. These providers require **no** `models.providers` config; just set auth + pick a model.

### OpenAI

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

| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |

| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |

| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |

| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | - |

| DeepInfra | `deepinfra` | `DEEPINFRA_API_KEY` | `deepinfra/deepseek-ai/DeepSeek-V3.2` |

| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` |

| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — |

| Groq | `groq` | `GROQ_API_KEY` | — |

| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | - |

| Groq | `groq` | `GROQ_API_KEY` | - |

| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |

| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |

| Kimi Coding | `kimi` | `KIMI_API_KEY` or `KIMICODE_API_KEY` | `kimi/kimi-code` |

| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` |

| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` |

| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` |

| Venice | `venice` | `VENICE_API_KEY` | — |

| Venice | `venice` | `VENICE_API_KEY` | - |

| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |

| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |

| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4.3` |

## Providers via `models.providers` (custom/base URL)

Use `models.providers` (or `models.json`) to add **custom** providers or OpenAI/Anthropic‑compatible proxies.

Use `models.providers` (or `models.json`) to add **custom** providers or OpenAI/Anthropic-compatible proxies.

Many of the bundled provider plugins below already publish a default catalog. Use explicit `models.providers.<id>` entries only when you want to override the default base URL, headers, or model list.

### Local proxies (LM Studio, vLLM, LiteLLM, etc.)

Example (OpenAI‑compatible):

Example (OpenAI-compatible):

```json5

{

## Related

- [Configuration reference](/gateway/config-agents#agent-defaults) — model config keys

- [Model failover](/concepts/model-failover) — fallback chains and retry behavior

- [Models](/concepts/models) — model configuration and aliases

- [Providers](/providers) — per-provider setup guides

- [Configuration reference](/gateway/config-agents#agent-defaults) - model config keys

- [Model failover](/concepts/model-failover) - fallback chains and retry behavior

- [Models](/concepts/models) - model configuration and aliases

- [Providers](/providers) - per-provider setup guides

Block chunking is implemented by `EmbeddedBlockChunker`:

- **Low bound:** don’t emit until buffer >= `minChars` (unless forced).

- **Low bound:** don't emit until buffer >= `minChars` (unless forced).

- **High bound:** prefer splits before `maxChars`; if forced, split at `maxChars`.

- **Break preference:** `paragraph` → `newline` → `sentence` → `whitespace` → hard break.

- **Code fences:** never split inside fences; when forced at `maxChars`, close + reopen the fence to keep Markdown valid.

`maxChars` is clamped to the channel `textChunkLimit`, so you can’t exceed per-channel caps.

`maxChars` is clamped to the channel `textChunkLimit`, so you can't exceed per-channel caps.

## Coalescing (merge streamed blocks)

When block streaming is enabled, OpenClaw can **merge consecutive block chunks**

before sending them out. This reduces “single-line spam” while still providing

before sending them out. This reduces "single-line spam" while still providing

progressive output.

- Coalescing waits for **idle gaps** (`idleMs`) before flushing.

more natural.

- Config: `agents.defaults.humanDelay` (override per agent via `agents.list[].humanDelay`).

- Modes: `off` (default), `natural` (800–2500ms), `custom` (`minMs`/`maxMs`).

- Modes: `off` (default), `natural` (800-2500ms), `custom` (`minMs`/`maxMs`).

- Applies only to **block replies**, not final replies or tool summaries.

## "Stream chunks or everything"

### Tool-progress preview updates

Preview streaming can also include **tool-progress** updates — short status lines like "searching the web", "reading file", or "calling tool" — that appear in the same preview message while tools are running, ahead of the final reply. This keeps multi-step tool turns visually alive rather than silent between the first thinking preview and the final answer.

Preview streaming can also include **tool-progress** updates - short status lines like "searching the web", "reading file", or "calling tool" - that appear in the same preview message while tools are running, ahead of the final reply. This keeps multi-step tool turns visually alive rather than silent between the first thinking preview and the final answer.

Supported surfaces:

## Related

- [Message lifecycle refactor](/concepts/message-lifecycle-refactor) - target shared preview, edit, stream, and finalization design

- [Progress drafts](/concepts/progress-drafts) — visible work-in-progress messages that update during long turns

- [Messages](/concepts/messages) — message lifecycle and delivery

- [Retry](/concepts/retry) — retry behavior on delivery failure

- [Channels](/channels) — per-channel streaming support

- [Progress drafts](/concepts/progress-drafts) - visible work-in-progress messages that update during long turns

- [Messages](/concepts/messages) - message lifecycle and delivery

- [Retry](/concepts/retry) - retry behavior on delivery failure

- [Channels](/channels) - per-channel streaming support

Add a model provider (LLM, proxy, or custom endpoint)

</Card>

<Card title="Tool / hook plugin" icon="wrench" href="/plugins/hooks">

Register agent tools, event hooks, or services — continue below

Register agent tools, event hooks, or services - continue below

</Card>

</CardGroup>

```

`definePluginEntry` is for non-channel plugins. For channels, use

`defineChannelPluginEntry` — see [Channel Plugins](/plugins/sdk-channel-plugins).

`defineChannelPluginEntry` - see [Channel Plugins](/plugins/sdk-channel-plugins).

For full entry point options, see [Entry Points](/plugins/sdk-entrypoints).

</Step>

Bare package specs like `@myorg/openclaw-my-plugin` install from npm during

the launch cutover. Use `clawhub:` when you want ClawHub resolution.

**In-repo plugins:** place under the bundled plugin workspace tree — automatically discovered.

**In-repo plugins:** place under the bundled plugin workspace tree - automatically discovered.

```bash

pnpm test -- <bundled-plugin-root>/my-plugin/

```typescript

register(api) {

// Required tool — always available

// Required tool - always available

api.registerTool({

name: "my_tool",

description: "Do a thing",

},

});

// Optional tool — user must add to allowlist

// Optional tool - user must add to allowlist

api.registerTool(

{

name: "workflow_tool",

For the full subpath reference, see [SDK Overview](/plugins/sdk-overview).

Within your plugin, use local barrel files (`api.ts`, `runtime-api.ts`) for

internal imports — never import your own plugin through its SDK path.

internal imports - never import your own plugin through its SDK path.

For provider plugins, keep provider-specific helpers in those package-root

barrels unless the seam is truly generic. Current bundled examples:

## Related

- [Plugin Architecture](/plugins/architecture) — internal architecture deep dive

- [SDK Overview](/plugins/sdk-overview) — Plugin SDK reference

- [Manifest](/plugins/manifest) — plugin manifest format

- [Channel Plugins](/plugins/sdk-channel-plugins) — building channel plugins

- [Provider Plugins](/plugins/sdk-provider-plugins) — building provider plugins

- [Plugin Architecture](/plugins/architecture) - internal architecture deep dive

- [SDK Overview](/plugins/sdk-overview) - Plugin SDK reference

- [Manifest](/plugins/manifest) - plugin manifest format

- [Channel Plugins](/plugins/sdk-channel-plugins) - building channel plugins

- [Provider Plugins](/plugins/sdk-provider-plugins) - building provider plugins