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

# autClaw Python plugin reference

> Use autClaw middleware.py for Python plugins, including the entry point, Sender, storage, routes, proactive push, Cron, and type signatures.

`plugin/scripts/middleware.py` is the SDK for regular Python plugins. Use it to create `Sender`, read the current context, reply to messages, store data, wait for input, handle payments, download user-uploaded files, handle HTTP routes, push proactively, and manage runtime scheduled tasks.

<Note>
  New plugins should prefer `from middleware import Sender, getSenderID`. Do not hard-code credentials, ports, or autClaw internal service addresses.
</Note>

## Quick start

```python theme={null}
#[author: your-name]
#[runtime: python@3.12]
#[title: Echo]
#[rule: echo (.+)]
from middleware import Sender, getSenderID

sender = Sender(getSenderID())
text = sender.param(1)
sender.reply(text or "Please enter text")
```

Python SDK methods are synchronous. Failures raise `Exception`; catch exceptions in flows that send network requests, media, or files, and reply with an actionable message.

## Browse by task

<CardGroup cols={2}>
  <Card title="Context and base types" icon="circle-dot" href="/en/plugin-sdk/python/context">
    Import style, `senderID`, response wrappers, `SendReceipt`, `MediaItem`, and download return bodies.
  </Card>

  <Card title="Sender message capabilities" icon="message-circle" href="/en/plugin-sdk/python/sender-messages">
    Read users and chats, match parameters, reply with text/media, recall, and use `replyMixed(...)`.
  </Card>

  <Card title="Wait for input and payment" icon="hourglass" href="/en/plugin-sdk/python/wait-and-payment">
    `listen(...)`, `input(...)`, `waitPay(exitcode, timeout, amount=None)`, and amount-matching details.
  </Card>

  <Card title="Events, media, and files" icon="file-down" href="/en/plugin-sdk/python/media-files">
    `getMediaItems()`, `fileDownload(...)`, `downloadAdapterFile(...)`, and `getGroupMemberList(...)`.
  </Card>

  <Card title="Storage and routes" icon="database" href="/en/plugin-sdk/python/storage-and-routes">
    Default storage, named buckets, and HTTP router request and response aliases.
  </Card>

  <Card title="Proactive push" icon="send" href="/en/plugin-sdk/python/push">
    Targets, account selection, and return values for `push(...)` / `pushImage(...)` / `pushMixed(...)`.
  </Card>

  <Card title="Tools, Cron, and group management" icon="wrench" href="/en/plugin-sdk/python/tools-cron-group">
    `import_module(...)`, system utilities, `Cron`, group invite/mute/announcement.
  </Card>

  <Card title="Python signatures" icon="file-code" href="/en/plugin-sdk/python/signatures">
    Navigation-indexed `.pyi`-style signatures for IDEs and AI retrieval through MCP.
  </Card>
</CardGroup>

## Common imports

```python theme={null}
from middleware import (
    Sender,
    Cron,
    getSenderID,
    bucketGet,
    bucketSet,
    fileDownload,
    downloadAdapterFile,
    getGroupMemberList,
    import_module,
    push,
    pushImage,
    pushMixed,
)

sender = Sender(getSenderID())
```

Common rules:

* Use `Sender` to handle the current message, route request, or event.
* Use top-level functions for global operations, such as `bucketGet(...)`, `pushImage(...)`, and `fileDownload(...)`.
* Business timeout parameters for `listen(...)`, `input(...)`, and `waitPay(...)` use milliseconds.
* Serialize objects with `json.dumps(...)` before saving them with `set(...)` / `bucketSet(...)`.

## Recommended template

```python theme={null}
#[author: your-name]
#[runtime: python@3.12]
#[title: Safe template]
#[rule: demo (.+)]
from middleware import Sender, getSenderID

sender = Sender(getSenderID())

try:
    value = sender.param(1)
    if not value:
        sender.reply("Please enter text, for example: demo hello")
    else:
        sender.reply(f"Received: {value}")
except Exception as error:
    print(error)
    sender.reply("Processing failed. Try again later or contact an administrator.")
```

## Actual differences from JavaScript middleware

This table is checked against the current `plugin/scripts/middleware.py` and `plugin/scripts/middleware.js`:

| Difference             | JavaScript                                                              | Python                                                                                                            |
| ---------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Call style             | Most methods return `Promise` and need `await`.                         | Methods return synchronously and raise `Exception` on failure.                                                    |
| Import style           | `const { Sender } = require('./middleware.js')`                         | `from middleware import Sender`                                                                                   |
| Default storage delete | `del(key)`                                                              | `delete(key)`; `del_` is also available. Avoid the Python keyword `del`.                                          |
| Dependency ensure      | `importModule(module, versionOrOptions?, manager?)`                     | `import_module(module, package="", version="", manager="")`; the current SDK also keeps `importModule`.           |
| Router aliases         | `sender.getRouter()` / `getMethod()` / `getRouterData()` are available. | The same aliases are available; prefer `getRouterPath()`, `getRouterMethod()`, and `getRouterBody()` in new docs. |
| `getRouterData()`      | Returns a JSON string.                                                  | Returns a JSON string; use `getRouterBody()` when you need an object.                                             |
| `Cron` constructor     | `new Cron()`                                                            | `Cron()` or the legacy-compatible `Cron(cronID=None)`.                                                            |
| Cron methods           | `getCron(...)`, `delCron(...)`.                                         | Also supports `getCronByID(...)` and `deleteCron(...)`.                                                           |
| Python-only aliases    | None.                                                                   | `download_adapter_file(...)`, `get_group_member_list(...)`.                                                       |

<Tip>
  All Python child pages are included in `docs.json` navigation. Mintlify indexes navigation pages for MCP search by default, so AI tools can retrieve these split reference pages.
</Tip>