autClaw Python plugin reference

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.

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

Quick start

#[author: your-name]
#[runtime: [email protected]]
#[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

Context and base types

Import style, senderID, response wrappers, SendReceipt, MediaItem, and download return bodies.

Sender message capabilities

Read users and chats, match parameters, reply with text/media, recall, and use replyMixed(...).

Wait for input and payment

listen(...), input(...), waitPay(exitcode, timeout, amount=None), and amount-matching details.

Events, media, and files

getMediaItems(), fileDownload(...), downloadAdapterFile(...), and getGroupMemberList(...).

Storage and routes

Default storage, named buckets, and HTTP router request and response aliases.

Proactive push

Targets, account selection, and return values for push(...) / pushImage(...) / pushMixed(...).

Tools, Cron, and group management

import_module(...), system utilities, Cron, group invite/mute/announcement.

Python signatures

Navigation-indexed .pyi-style signatures for IDEs and AI retrieval through MCP.

Common imports

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

#[author: your-name]
#[runtime: [email protected]]
#[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(...)`.

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.

Plugin SDK

autClaw Python plugin reference

Quick start

Browse by task

Context and base types

Sender message capabilities

Wait for input and payment

Events, media, and files

Storage and routes

Proactive push

Tools, Cron, and group management

Python signatures

Common imports

Recommended template

Actual differences from JavaScript middleware

Python plugin context and base types

Python Sender message capabilities

Python wait for input and payment

Python events, media, and files

Python plugin storage and routes

Python plugin proactive push

Python tools, Cron, and groups

Python middleware.py signatures

​Quick start

​Browse by task

Context and base types

Sender message capabilities

Wait for input and payment

Events, media, and files

Storage and routes

Proactive push

Tools, Cron, and group management

Python signatures

​Common imports

​Recommended template

​Actual differences from JavaScript middleware

Python plugin context and base types

Python Sender message capabilities

Python wait for input and payment

Python events, media, and files

Python plugin storage and routes

Python plugin proactive push

Python tools, Cron, and groups

Python middleware.py signatures

Quick start

Browse by task

Common imports

Recommended template

Actual differences from JavaScript middleware