跳转到主要内容
autClaw 插件可以读取消息、回复文本或媒体、保存配置、等待用户输入、处理 HTTP 路由和定时任务。新插件建议放在 plugin/scripts/，并使用内置 middleware.js 或 middleware.py。
本页面面向插件作者。你只需要编写脚本和顶部声明，不需要绕过 SDK 直接请求 autClaw 服务。

​
你可以做什么

回复消息

读取用户消息、匹配规则参数，并回复文本、Markdown 或媒体。

发送媒体

发送图片、语音、视频、文件和 mixed 消息。

保存状态

使用默认存储或命名 bucket 保存用户进度、配置和缓存。

开放路由

声明 router 和 method，把插件变成一个 HTTP 处理函数。

​
选择语言

语言适合场景典型入口
JavaScriptnpm 生态、异步 I/O、前端或 Node.js 经验middleware.js
Python数据处理、脚本自动化、AI 调用middleware.py
两种语言都能读取消息、发送回复和保存状态。区别主要在你现有的生态和依赖。
适合需要 npm 生态、异步 I/O 和前端/Node.js 经验的插件作者。
//[author: your-name]
//[runtime: [email protected]]
//[title: Echo]
//[description: 回复用户输入]
//[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 || '请输入内容')
}

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

​
创建一个插件

1

新建脚本

在 plugin/scripts/ 下创建文件，例如 plugin/scripts/echo.js 或 plugin/scripts/echo.py。
2

写 manifest headers

在文件顶部声明 author、runtime、title 和触发方式。消息插件通常使用 rule。
3

导入 middleware

JavaScript 使用 require('./middleware.js')；Python 使用 from middleware import ...。
4

创建 Sender 并回复

用 new Sender(getSenderID()) 或 Sender(getSenderID()) 读取上下文和发送回复。

​
常用文档

Manifest headers

声明插件名称、作者、触发规则、参数、依赖、路由和定时任务。

JavaScript middleware

查看 Sender、存储、文件、路由、等待输入和 cron 的 JavaScript 用法。

Python middleware

查看 Sender、存储、文件、路由、等待输入和 cron 的 Python 用法。

Media sending

发送图片、语音、视频、文件，或处理用户上传文件。

​
插件文件和声明

位置说明
plugin/scripts/*.js普通 JavaScript 插件。
plugin/scripts/*.py普通 Python 插件。
plugin/replies/*.js旧版回复脚本。维护旧插件时可继续使用。
最小声明： 
//[author: your-name]
//[runtime: [email protected]]
//[rule: hello]

#[author: your-name]
#[runtime: [email protected]]
#[rule: hello]
author 必填。rule 用来匹配消息。更多字段见 Plugin manifest headers。

​
推荐写法

  • 使用 Sender 读取上下文和回复消息。
  • 媒体发送使用 replyImage、replyVoice、replyVideo、replyFile 或 replyMixed。
  • 用户上传文件使用 sender.getMediaItems() + downloadAdapterFile(...)。
  • 配置项写在 param 里，运行状态写入 bucketSet(...)；bucket 名称可用 . 表示子级，推荐最多 3 级。
  • 依赖优先写在 dependency 里；临时依赖可用 importModule(...) 或 import_module(...)。

​
避免这些做法

  • 不要硬编码运行时凭据、端口或服务地址。
  • 不要绕过 SDK 直接请求 autClaw 服务。
  • 不要手动解析平台原始文件字段；使用 SDK 的文件下载方法。
  • 不要把大量数据塞进一个 bucket key；拆成多个 key 更容易维护。
Last modified on June 3, 2026