Manifest headers are comment declarations at the top of a plugin file. autClaw reads them to show plugin metadata, match messages, generate configuration forms, install dependencies, and register routes.
Regular plugin authors only need the fields on this page. IM platform adapter fields are not covered here.
Basic syntax
//[author: your-name]
//[runtime: [email protected]]
//[title: Hello]
//[description: Reply hello]
//[rule: hello]
const { Sender, getSenderID } = require('./middleware.js')
const sender = new Sender(getSenderID())
await sender.reply('hello')
#[author: your-name]
#[runtime: [email protected]]
#[title: Hello]
#[description: Reply hello]
#[rule: hello]
from middleware import Sender, getSenderID
sender = Sender(getSenderID())
sender.reply("hello")
Parsing rules
- JavaScript uses
//[key: value].
- Python uses
#[key: value].
- Declarations must be in the continuous comment block at the top of the file. Declarations after the first non-comment code line are ignored as headers.
key is case-insensitive. Use lowercase for consistency.author is required. Without author, the plugin is marked as invalid.- For most duplicate fields, the last value wins.
rule, event, method, param, dependency, and selector fields can repeat.
- Boolean values support
true/false, 1/0, and yes/no.
Common fields
| Header | Required | Example | Purpose |
|---|
author | Yes | your-name | Plugin author. Use a stable English or pinyin identifier. |
title | No | Order lookup | Display name. |
description | No | Look up status by order ID | Short description that tells users what the plugin does. |
version | No | 1.0.0 | Plugin version. |
runtime | No | [email protected], [email protected] | Runtime environment. |
language | No | javascript, python | Usually inferred from the file extension. |
class | No | Tools | Category or display group. |
icon | No | bot | Display icon. |
disable | No | true | Disable the plugin. |
admin | No | true | Only administrators can trigger the plugin. |
priority | No | 10 | Trigger priority. Higher numbers run first. |
Message trigger: rule
rule matches user messages. You can write multiple rule headers.
//[rule: hello]
//[rule: query (.+)]
sender.param(1).
//[rule: query (.+)]
const { Sender, getSenderID } = require('./middleware.js')
const sender = new Sender(getSenderID())
const keyword = await sender.param(1)
await sender.reply(`You want to query: ${keyword}`)
Events and scheduled triggers
| Header | Example | Purpose |
|---|
event | qq-notice-group_decrease-kick | Listen for an event. Use getEventType() / getEventData() in the plugin. |
cron | 0 9 * * * | Trigger the plugin on a schedule. |
cron only once. It supports common 5-field expressions, expressions with seconds, and cron descriptors.
// Trigger every day at 09:00
//[cron: 0 9 * * *]
Trigger scope
Use selectors to limit which IM channels, users, or groups can trigger a plugin.
//[imtype+: qq,wx]
//[groupid+: 123456]
//[userid-: 10001,10002]
| Header | Mode | Description |
|---|
imtype / imtype+ | Allowlist | Only allow specific IM channels. |
imtype- | Blocklist | Exclude specific IM channels. |
userid / userid+ | Allowlist | Only allow specific users. |
userid- | Blocklist | Exclude specific users. |
groupid / groupid+ | Allowlist | Only allow specific groups or chats. |
groupid- | Blocklist | Exclude specific groups or chats. |
Configuration parameters: param
Use JSON in param headers to declare configuration fields. Declare one field per line.
//[param: {"key":"api_key","name":"API Key","type":"secret","required":true,"placeholder":"sk-..."}]
//[param: {"key":"enabled","name":"Enabled","type":"boolean","default":true}]
//[param: {"key":"mode","name":"Mode","type":"select","options":["fast","safe"],"default":"safe"}]
//[param: {"spliter":true,"name":"Advanced settings"}]
| Field | Required | Description |
|---|
key | Yes | Config key. Separator items with spliter: true do not need it. |
name | No | Display name. Defaults to key. |
desc | No | Config description. |
placeholder | No | Input placeholder. |
required | No | Whether the field is required. |
type | No | string, boolean, number, secret, or select. Defaults to string. |
secret | No | Treat the field as a secret when true. |
default | No | Default value. |
options | No | Options for select. |
scope | No | global or account. Defaults to global. |
bind | No | Currently supports ingress_token. |
spliter | No | Separator title for organizing the configuration form. |
Dependencies: dependency
Use dependency to declare packages that the plugin needs. Each line is a JSON object.
//[dependency: {"name":"axios","manager":"npm","version":"1.7.9"}]
#[dependency: {"name":"httpx","manager":"pip","version":"0.27.2"}]
| Field | Required | Description |
|---|
name | Yes | Package name. |
manager | No | Package manager, such as npm, pip, or go. |
version | No | Version. |
importModule(...); Python uses import_module(...).
HTTP route plugins
Declare router to let a plugin handle HTTP requests.
//[author: your-name]
//[runtime: [email protected]]
//[title: Demo API]
//[router: /demo/{id}]
//[method: post]
const { Sender, getSenderID } = require('./middleware.js')
const sender = new Sender(getSenderID())
const params = await sender.getRouterParams()
const body = await sender.getRouterBody()
await sender.response({ ok: true, id: params.id, body })
| Header | Example | Description |
|---|
router | /demo/{id} | Public route path. It must start with /. |
method | get, post | HTTP method. Can repeat or use commas. Supports get, post, put, and delete. |
server | demo | Optional service group name. |
/api, /open, or /healthz as route prefixes.
Marketplace fields
If you want to publish a plugin publicly, add these fields.
//[public: true]
//[open_source: false]
//[price: 9.90]
//[billing_mode: monthly]
//[monthly_price: 3.00]
//[auto_renew_default: true]
| Header | Example | Description |
|---|
public | true | Whether to show the plugin publicly. |
open_source | false | Whether to expose the source code. |
pin | true | Whether to pin the plugin. |
price | 9.90 | One-time price. Non-negative with up to two decimals. |
billing_mode | one_time / monthly | Billing mode. |
monthly_price | 3.00 | Monthly price. Non-negative with up to two decimals. |
auto_renew_default | true | Whether auto-renew is enabled by default. |
Complete example
//[author: demo]
//[runtime: [email protected]]
//[title: Claim card]
//[description: Let a user send claim-card to claim one card code]
//[version: 1.0.0]
//[rule: claim-card]
//[admin: false]
//[priority: 10]
//[param: {"key":"period_limit","name":"Period limit","type":"number","default":1}]
//[dependency: {"name":"dayjs","manager":"npm"}]
const { Sender, getSenderID, bucketGet, bucketSet } = require('./middleware.js')
const sender = new Sender(getSenderID())
const user = await sender.getUserID()
const claimed = await bucketGet('card_claims', user)
if (claimed) {
await sender.reply('You have already claimed a card')
return
}
await bucketSet('card_claims', user, String(Date.now()))
await sender.reply('Claimed successfully')
Machine-readable files
