بناء Plugins

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

المتطلبات الأساسية

• Node >= 22 ومدير حزم (npm أو pnpm)
• الإلمام بـ TypeScript (ESM)
• بالنسبة إلى Plugins داخل المستودع: يجب أن يكون المستودع مستنسخًا وأن يكون pnpm install قد نُفّذ. تطوير Plugin من نسخة مصدر checkout مخصص لـ pnpm فقط لأن OpenClaw يحمّل Plugins المضمّنة من حزم مساحة العمل extensions/*.

​

ما نوع Plugin؟

​

البدء السريع: Plugin أداة

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

pnpm test -- <bundled-plugin-root>/my-plugin/

​

إمكانات Plugin

• before_tool_call: يكون { block: true } نهائيًا ويوقف المعالجات ذات الأولوية الأدنى.
• before_tool_call: يُعامَل { block: false } على أنه لا قرار.
• before_tool_call: يوقف { requireApproval: true } تنفيذ الوكيل مؤقتًا ويطلب موافقة المستخدم عبر طبقة موافقات التنفيذ، أو أزرار Telegram، أو تفاعلات Discord، أو أمر /approve على أي قناة.
• before_install: يكون { block: true } نهائيًا ويوقف المعالجات ذات الأولوية الأدنى.
• before_install: يُعامَل { block: false } على أنه لا قرار.
• message_sending: يكون { cancel: true } نهائيًا ويوقف المعالجات ذات الأولوية الأدنى.
• message_sending: يُعامَل { cancel: false } على أنه لا قرار.
• message_received: فضّل حقل threadId المطبوع عندما تحتاج إلى توجيه سلسلة/موضوع وارد. احتفظ بـ metadata للإضافات الخاصة بالقناة.
• message_sending: فضّل حقول التوجيه المطبوعة replyToId / threadId على مفاتيح metadata الخاصة بالقناة.

​

تسجيل أدوات الوكيل

register(api) {
  // Required tool - always available
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Optional tool - user must add to allowlist
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

{
  "contracts": {
    "tools": ["my_tool", "workflow_tool"]
  },
  "toolMetadata": {
    "workflow_tool": {
      "optional": true
    }
  }
}

{
  tools: { allow: ["workflow_tool"] },
}

• يجب ألا تتعارض أسماء الأدوات مع أدوات النواة (يتم تخطي التعارضات)
• يتم تخطي الأدوات ذات كائنات التسجيل غير السليمة، بما في ذلك غياب parameters، والإبلاغ عنها في تشخيصات Plugin بدلا من كسر تشغيلات الوكيل
• استخدم optional: true للأدوات ذات الآثار الجانبية أو متطلبات الملفات الثنائية الإضافية
• يمكن للمستخدمين تمكين كل أدوات Plugin بإضافة معرّف Plugin إلى tools.allow

​

تسجيل أوامر CLI

register(api) {
  api.registerCli(
    ({ program }) => {
      const demo = program
        .command("demo-plugin")
        .description("Run demo plugin commands");

      demo
        .command("ping")
        .description("Check that the plugin CLI is executable")
        .action(() => {
          console.log("demo-plugin:pong");
        });
    },
    {
      descriptors: [
        {
          name: "demo-plugin",
          description: "Run demo plugin commands",
          hasSubcommands: true,
        },
      ],
    },
  );
}

openclaw plugins inspect demo-plugin --runtime --json
openclaw demo-plugin ping

​

اصطلاحات الاستيراد

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";

• Anthropic: مغلفات بث Claude ومساعدات service_tier / beta
• OpenAI: بُناة المزوّد، ومساعدات النموذج الافتراضي، ومزوّدو الوقت الفعلي
• OpenRouter: باني المزوّد مع مساعدات الإعداد الأولي/التكوين

​

قائمة تحقق ما قبل الإرسال

​

اختبار إصدار beta

1. راقب وسوم إصدارات GitHub على openclaw/openclaw واشترك عبر Watch > Releases. تبدو وسوم beta مثل v2026.3.N-beta.1. يمكنك أيضا تفعيل الإشعارات لحساب OpenClaw الرسمي على X @openclaw لإعلانات الإصدارات.
2. اختبر Plugin الخاص بك مقابل وسم beta فور ظهوره. تكون النافذة قبل الإصدار المستقر عادة بضع ساعات فقط.
3. انشر في سلسلة Plugin الخاصة بك في قناة Discord المسماة plugin-forum بعد الاختبار، إما بعبارة all good أو بما تعطل. إذا لم تكن لديك سلسلة بعد، فأنشئ واحدة.
4. إذا تعطل شيء ما، فافتح مشكلة أو حدّثها بعنوان Beta blocker: <plugin-name> - <summary> وطبّق وسم beta-blocker. ضع رابط المشكلة في سلسلتك.
5. افتح PR إلى main بعنوان fix(<plugin-id>): beta blocker - <summary> واربط المشكلة في كل من PR وسلسلة Discord الخاصة بك. لا يستطيع المساهمون وسم PRs، لذلك يكون العنوان هو إشارة جهة PR للمشرفين والأتمتة. يتم دمج العوائق التي لديها PR؛ أما العوائق التي لا تملك واحدا فقد تُشحن على أي حال. يراقب المشرفون هذه السلاسل أثناء اختبار beta.
6. الصمت يعني أن كل شيء أخضر. إذا فاتتك النافذة، فمن المرجح أن يصل إصلاحك في الدورة التالية.

​

الخطوات التالية

​

ذو صلة

• معمارية Plugin - تعمق في المعمارية الداخلية
• نظرة عامة على SDK - مرجع SDK الخاص بـ Plugin
• البيان - تنسيق بيان Plugin
• Plugins القنوات - بناء Plugins القنوات
• Plugins المزوّدين - بناء Plugins المزوّدين