بناء الإضافات

تضيف Plugins إلى OpenClaw قدرات جديدة: القنوات، ومزوّدي النماذج، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الفيديو، وجلب الويب، وبحث الويب، وأدوات الوكيل، أو أي توليفة منها.

لست بحاجة إلى إضافة Plugin الخاص بك إلى مستودع OpenClaw. انشره إلى ClawHub ويثبّته المستخدمون باستخدام openclaw plugins install clawhub:<package-name>. لا تزال مواصفات الحزم المجرّدة تُثبَّت من npm أثناء انتقال الإطلاق.

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

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

# ما نوع Plugin؟

بالنسبة إلى Plugin قناة لا يُضمن تثبيته عند تشغيل الإعداد/التهيئة الأولية، استخدم createOptionalChannelSetupSurface(...) من openclaw/plugin-sdk/channel-setup. ينتج ذلك زوجًا من محوّل إعداد + معالج إرشادي يعلن متطلب التثبيت ويفشل بإغلاق آمن عند عمليات كتابة الإعدادات الحقيقية إلى أن يُثبَّت Plugin.

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

ينشئ هذا الشرح Plugin بسيطًا يسجّل أداة وكيل. تتوفر أدلة مخصّصة للقنوات وPlugins المزوّدين في الروابط أعلاه.

{
"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"
  }
}
}

{
"id": "my-plugin",
"name": "My Plugin",
"description": "Adds a custom tool to OpenClaw",
"contracts": {
  "tools": ["my_tool"]
},
"activation": {
  "onStartup": true
},
"configSchema": {
  "type": "object",
  "additionalProperties": false
}
}

// 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

يمكن لـ Plugin واحد تسجيل أي عدد من القدرات عبر كائن api:

للاطلاع على واجهة API التسجيل الكاملة، راجع نظرة عامة على SDK.

يمكن لـ Plugins المضمّنة استخدام api.registerAgentToolResultMiddleware(...) عندما تحتاج إلى إعادة كتابة غير متزامنة لنتائج الأدوات قبل أن يرى النموذج المخرجات. أعلن أوقات التشغيل المستهدفة في contracts.agentToolResultMiddleware، على سبيل المثال ["pi", "codex"]. هذه وصلة موثوقة خاصة بـ Plugin مضمّن؛ ينبغي لـ Plugins الخارجية تفضيل خطافات Plugin العادية في OpenClaw ما لم يطوّر OpenClaw سياسة ثقة صريحة لهذه القدرة.

إذا سجّل Plugin الخاص بك طرق RPC مخصّصة لـ Gateway، فاجعلها على بادئة خاصة بـ Plugin. تبقى مساحات أسماء الإدارة الأساسية (config.*, exec.approvals.*, wizard.*, update.*) محجوزة وتُحل دائمًا إلى operator.admin، حتى إذا طلب 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 على مفاتيح البيانات الوصفية الخاصة بالقنوات.

يتعامل أمر /approve مع موافقات التنفيذ وPlugin معًا من خلال رجوع احتياطي محدود: عندما لا يُعثر على معرّف موافقة تنفيذ، يعيد OpenClaw محاولة المعرّف نفسه عبر موافقات Plugin. يمكن ضبط تمرير موافقات Plugin بشكل مستقل عبر approvals.plugin في الإعدادات.

إذا كانت بنية الموافقة المخصّصة تحتاج إلى اكتشاف حالة الرجوع الاحتياطي المحدودة نفسها، ففضّل isApprovalNotFoundError من openclaw/plugin-sdk/error-runtime بدلًا من مطابقة سلاسل انتهاء صلاحية الموافقة يدويًا.

راجع خطافات Plugin للاطلاع على الأمثلة ومرجع الخطافات.

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

الأدوات هي دوال مطبوعة يمكن لـ LLM استدعاؤها. يمكن أن تكون مطلوبة (متاحة دائمًا) أو اختيارية (يتطلب تفعيل المستخدم):

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 },
  );
}

يجب أيضًا إعلان كل أداة مسجّلة باستخدام api.registerTool(...) في بيان Plugin:

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

تلتقط OpenClaw الواصف المتحقق منه من الأداة المسجلة وتخزنه مؤقتا، لذلك لا تكرر Plugins بيانات description أو المخطط في البيان. لا يعلن عقد البيان إلا الملكية والاكتشاف؛ أما التنفيذ فما زال يستدعي تنفيذ الأداة الحي المسجل. اضبط toolMetadata.<tool>.optional: true للأدوات المسجلة باستخدام api.registerTool(..., { optional: true }) حتى تتمكن OpenClaw من تجنب تحميل وقت تشغيل ذلك Plugin إلى أن توضع الأداة صراحة في قائمة السماح.

يمكّن المستخدمون الأدوات الاختيارية في الإعدادات:

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

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

# تسجيل أوامر CLI

يمكن لـ Plugins إضافة مجموعات أوامر جذرية لـ openclaw باستخدام api.registerCli. وفّر descriptors لكل جذر أمر من المستوى الأعلى حتى تتمكن OpenClaw من عرض الأمر وتوجيهه دون تحميل كل أوقات تشغيل Plugins بشغف.

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

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

استورد دائما من مسارات openclaw/plugin-sdk/<subpath> المركزة:

// Wrong: monolithic root (deprecated, will be removed)

للاطلاع على مرجع المسارات الفرعية الكامل، راجع نظرة عامة على SDK.

داخل Plugin الخاص بك، استخدم ملفات البرميل المحلية (api.ts، runtime-api.ts) من أجل الاستيرادات الداخلية - لا تستورد أبدا Plugin الخاص بك عبر مسار SDK الخاص به.

بالنسبة إلى Plugins المزوّدين، أبقِ المساعدات الخاصة بالمزوّد في براميل جذر الحزمة تلك ما لم تكن الواجهة عامة حقا. أمثلة الحزمة الحالية:

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

إذا كان المساعد مفيدا فقط داخل حزمة مزوّد مضمّنة واحدة، فأبقِه على تلك واجهة جذر الحزمة بدلا من ترقيته إلى openclaw/plugin-sdk/*.

ما زالت بعض واجهات المساعدة المولدة openclaw/plugin-sdk/<bundled-id> موجودة لصيانة Plugins المضمنة عندما يكون لديها استخدام متتبع من المالك. تعامل مع هذه كسطوح محجوزة، لا كنمط افتراضي لـ Plugins الجديدة التابعة لجهات خارجية.

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

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s يحتوي package.json على بيانات openclaw الوصفية الصحيحة OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s بيان openclaw.plugin.json موجود وصالح OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s تستخدم نقطة الدخول defineChannelPluginEntry أو definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s تستخدم كل الاستيرادات مسارات plugin-sdk/<subpath> المركزة OPENCLAW_DOCS_MARKER:calloutClose: