autClaw plugin SDK overview

autClaw plugins can read messages, reply with text or media, save configuration, wait for user input, handle HTTP routes, and run scheduled tasks. Put new plugins in plugin/scripts/ and use the built-in middleware.js or middleware.py.

This page is for plugin authors. Write scripts and manifest headers. Do not bypass the SDK to call autClaw services directly.

What you can build

Reply to messages

Read user messages, match rule captures, and reply with text, Markdown, or media.

Send media

Send images, voice, video, files, and mixed messages.

Save state

Use default storage or named buckets to save user progress, configuration, and cache data.

Expose routes

Declare router and method to turn a plugin into an HTTP handler.

Choose a language

Language	Best for	Typical entry
JavaScript	npm ecosystem, async I/O, and frontend or Node.js experience	`middleware.js`
Python	Data processing, script automation, and AI calls	`middleware.py`

Both languages can read messages, send replies, and save state. The main difference is your existing ecosystem and dependencies.

JavaScript
Python

Use JavaScript when you want npm packages, async I/O, or Node.js experience.

//[author: your-name]
//[runtime: [email protected]]
//[title: Echo]
//[description: Reply with user input]
//[rule: echo (.+)]
const { Sender, getSenderID } = require('./middleware.js')

async function main() {
  const sender = new Sender(getSenderID())
  const text = await sender.param(1)
  await sender.reply(text || 'Please enter text')
}

main().catch((error) => console.error(error))

Use Python for data processing, scripting, AI calls, or Python ecosystem packages.

#[author: your-name]
#[runtime: [email protected]]
#[title: Echo]
#[description: Reply with user input]
#[rule: echo (.+)]
from middleware import Sender, getSenderID

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

Create a plugin

Create a script

Create a file under plugin/scripts/, such as plugin/scripts/echo.js or plugin/scripts/echo.py.

Write manifest headers

Declare author, runtime, title, and the trigger. Message plugins usually use rule.

Import middleware

Use require('./middleware.js') in JavaScript or from middleware import ... in Python.

Create Sender and reply

Use new Sender(getSenderID()) or Sender(getSenderID()) to read context and send replies.

Common docs

Manifest headers

Declare the plugin name, author, trigger rules, parameters, dependencies, routes, and scheduled tasks.

JavaScript middleware

Learn JavaScript usage for Sender, storage, files, routes, input waiting, and cron.

Python middleware

Learn Python usage for Sender, storage, files, routes, input waiting, and cron.

Media sending

Send images, voice, video, and files, or handle user-uploaded files.

Plugin files and declarations

Location	Description
`plugin/scripts/*.js`	Regular JavaScript plugins.
`plugin/scripts/*.py`	Regular Python plugins.
`plugin/replies/*.js`	Legacy reply scripts. Keep using them only when maintaining existing plugins.

Minimum declarations:

//[author: your-name]
//[runtime: [email protected]]
//[rule: hello]

#[author: your-name]
#[runtime: [email protected]]
#[rule: hello]

author is required. rule matches messages. See Plugin manifest headers for more fields.

Recommended patterns

Use Sender to read context and reply to messages.
Use replyImage, replyVoice, replyVideo, replyFile, or replyMixed for media.
Use sender.getMediaItems() + downloadAdapterFile(...) for user-uploaded files.
Put configuration fields in param; put runtime state in bucketSet(...). Bucket names can use . for child levels; prefer at most 3 levels.
Prefer declaring dependencies with dependency; use importModule(...) or import_module(...) for temporary dependencies.

Avoid these patterns

Do not hard-code runtime credentials, ports, or service addresses.
Do not bypass the SDK to call autClaw services directly.
Do not manually parse platform-specific raw file fields. Use SDK download helpers.
Do not put large datasets into one bucket key. Split data across keys for easier maintenance.

​What you can build

Reply to messages

Send media

Save state

Expose routes

​Choose a language

​Create a plugin

​Common docs

Manifest headers

JavaScript middleware

Python middleware

Media sending

​Plugin files and declarations

​Recommended patterns

​Avoid these patterns

What you can build

Choose a language

Create a plugin

Common docs

Plugin files and declarations

Recommended patterns

Avoid these patterns