> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat commands

> Register chat commands from a plugin that bypass the LLM and respond directly: api.registerCommand().

# Chat commands

Plugins can register chat commands that the gateway handles directly — without involving the LLM. When a user sends `/my-command arg1 arg2`, the gateway routes it to your handler and sends the reply immediately. Use this for fast utility responses, status lookups, or in-chat controls that don't need an AI agent.

Chat commands are distinct from agent tools: tools extend what the agent can call during a run; commands intercept messages before the agent runs.

## Registering a command

```typescript theme={"dark"}
import type { OpenClawPluginApi } from "openclaw/plugin-sdk";

export default function register(api: OpenClawPluginApi): void {
  api.registerCommand({
    name: "ping",
    description: "Check if the gateway is reachable",
    acceptsArgs: false,
    requireAuth: true,
    handler: async (ctx) => {
      return { text: "pong" };
    },
  });
}
```

The command is available in any channel the user has configured. No restart is needed when a plugin loads.

## `OpenClawPluginCommandDefinition` fields

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Command name without leading slash (e.g. `"ping"`, `"status"`). Lowercase, no spaces. |
| `description` | `string` | Yes | Shown in `/help` and native Telegram/Discord command menus |
| `acceptsArgs` | `boolean` | No | Whether the command accepts text after the name (default `false`) |
| `requireAuth` | `boolean` | No | Only authorized senders can invoke this command (default `true`) |
| `handler` | `PluginCommandHandler` | Yes | The function that runs when the command fires |

## The handler

The handler receives a `PluginCommandContext`:

| Field | Type | Description |
| - | - | - |
| `senderId` | `string \| undefined` | Sender identifier (channel-specific format) |
| `channel` | `string` | Channel surface — `"telegram"`, `"discord"`, `"whatsapp"`, etc. |
| `channelId` | `ChannelId \| undefined` | Provider channel id |
| `isAuthorizedSender` | `boolean` | Whether the sender is on the allowlist |
| `args` | `string \| undefined` | Raw text after the command name (present when `acceptsArgs: true`) |
| `commandBody` | `string` | Full normalized command body |
| `config` | `OpenClawConfig` | The resolved gateway config |
| `from` | — | Inbound context sender (channel-specific) |
| `accountId` | `string \| undefined` | The channel account id |
| `messageThreadId` | — | Thread id (Telegram forum topics, Discord threads) |

Return a `ReplyPayload` from the handler:

```typescript theme={"dark"}
// Minimal text reply
return { text: "Done." };

// Rich reply with media
return {
  text: "Here is your file:",
  mediaUrl: "https://example.com/file.pdf",
};

// Error reply
return { text: "Something went wrong.", isError: true };
```

## Using command arguments

```typescript theme={"dark"}
api.registerCommand({
  name: "echo",
  description: "Echo text back",
  acceptsArgs: true,
  handler: async (ctx) => {
    const input = ctx.args?.trim();
    if (!input) {
      return { text: "Usage: /echo <text>" };
    }
    return { text: input };
  },
});
```

## Access control

`requireAuth: true` (the default) means only senders on the channel's `allowFrom` list can invoke the command. Unauthorized senders receive no response and the invocation is silently dropped.

Set `requireAuth: false` for commands intended for all users (e.g. a public status command):

```typescript theme={"dark"}
api.registerCommand({
  name: "status",
  description: "Check gateway status (public)",
  requireAuth: false,
  handler: async (_ctx) => {
    return { text: "Gateway is running." };
  },
});
```

> [!WARNING]
>
> Commands with `requireAuth: false` respond to **any** sender regardless of
> channel policy. Do not return sensitive information from unauthenticated commands.

## Name collision

If two plugins register the same command name, both register but only one runs (last registration wins). Use namespaced names to avoid collisions: `my-plugin_status` rather than `status`.

## Async safety

Handlers are called in the gateway's event loop. Do not perform synchronous blocking I/O inside a handler.

```typescript theme={"dark"}
// ❌ Blocks the event loop
handler: (_ctx) => {
  const data = fs.readFileSync("./config.json", "utf8");
  return { text: data };
}

// ✅ Async I/O
handler: async (_ctx) => {
  const data = await fs.promises.readFile("./config.json", "utf8");
  return { text: data };
}
```

## What's next

* [Agent tools](https://docs.wednesdayai.dev/next/developers/agent-tools.md) — extend what the AI agent can call during a run
* [Hooks](https://docs.wednesdayai.dev/next/developers/hooks.md) — observe or modify the run lifecycle
* [Plugin SDK reference](https://docs.wednesdayai.dev/next/developers/sdk.md) — full exported surface


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