Skip to main content
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

LanguageBest forTypical entry
JavaScriptnpm ecosystem, async I/O, and frontend or Node.js experiencemiddleware.js
PythonData processing, script automation, and AI callsmiddleware.py
Both languages can read messages, send replies, and save state. The main difference is your existing ecosystem and dependencies.
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))

​
Create a plugin

1

Create a script

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

Write manifest headers

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

Import middleware

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

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

LocationDescription
plugin/scripts/*.jsRegular JavaScript plugins.
plugin/scripts/*.pyRegular Python plugins.
plugin/replies/*.jsLegacy 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.
  • 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.
Last modified on June 3, 2026