​

الإضافات (الامتدادات)

​

البدء السريع (هل أنت جديد على الإضافات؟)

1. انظر ما تم تحميله بالفعل:

openclaw plugins list

2. ثبّت إضافة رسمية (مثال: Voice Call):

openclaw plugins install @openclaw/voice-call

3. أعد تشغيل Gateway، ثم قم بالتهيئة ضمن plugins.entries.<id>.config.

​

الإضافات المتاحة (الرسمية)

• Microsoft Teams متاح عبر الإضافة فقط اعتبارًا من 2026.1.15؛ ثبّت @openclaw/msteams إذا كنت تستخدم Teams.
• Memory (Core) — إضافة بحث الذاكرة المجمّعة (مفعّلة افتراضيًا عبر plugins.slots.memory)
• Memory (LanceDB) — إضافة ذاكرة طويلة الأمد مجمّعة (استدعاء/التقاط تلقائي؛ اضبط plugins.slots.memory = "memory-lancedb")
• Voice Call — @openclaw/voice-call
• Zalo Personal — @openclaw/zalouser
• Matrix — @openclaw/matrix
• Nostr — @openclaw/nostr
• Zalo — @openclaw/zalo
• Microsoft Teams — @openclaw/msteams
• Google Antigravity OAuth (مصادقة الموفّر) — مضمّنة كـ google-antigravity-auth (معطّلة افتراضيًا)
• Gemini CLI OAuth (مصادقة الموفّر) — مضمّنة كـ google-gemini-cli-auth (معطّلة افتراضيًا)
• Qwen OAuth (مصادقة الموفّر) — مضمّنة كـ qwen-portal-auth (معطّلة افتراضيًا)
• Copilot Proxy (مصادقة الموفّر) — جسر محلي لـ VS Code Copilot Proxy؛ مميّز عن تسجيل الدخول المضمّن github-copilot للجهاز (مضمّن، معطّل افتراضيًا)

• أساليب Gateway RPC
• معالجات Gateway HTTP
• أدوات الوكيل
• أوامر CLI
• خدمات تعمل في الخلفية
• تحقق اختياري من التهيئة
• Skills (بإدراج أدلة skills في بيان الإضافة)
• أوامر الردّ التلقائي (تُنفَّذ دون استدعاء وكيل الذكاء الاصطناعي)

​

مساعدات وقت التشغيل

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

• يستخدم تهيئة النواة messages.tts (OpenAI أو ElevenLabs).
• يُرجِع مخزنًا صوتيًا PCM + معدل العيّنة. يجب على الإضافات إعادة أخذ العينات/الترميز للموفّرين.
• Edge TTS غير مدعوم للاتصال الهاتفي.

​

الاكتشاف والأولوية

1. مسارات التهيئة

• plugins.load.paths (ملف أو دليل)

2. امتدادات مساحة العمل

• <workspace>/.openclaw/extensions/*.ts
• <workspace>/.openclaw/extensions/*/index.ts

3. الامتدادات العامة

• ~/.openclaw/extensions/*.ts
• ~/.openclaw/extensions/*/index.ts

4. الامتدادات المجمّعة (المشحوذة مع OpenClaw، معطّلة افتراضيًا)

• <openclaw>/extensions/*

​

حِزم الحِزم (Package packs)

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

​

بيانات فهرس القنوات

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

معرفات الاضافات

• حِزم الحِزم: package.json name
• ملف مستقل: اسم قاعدة الملف (~/.../voice-call.ts → voice-call)

​

التهيئة

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

• enabled: مفتاح التشغيل الرئيسي (الافتراضي: true)
• allow: قائمة السماح (اختيارية)
• deny: قائمة الحظر (اختيارية؛ الحظر يتغلّب)
• load.paths: ملفات/أدلة إضافات إضافية
• entries.<id>: مفاتيح تشغيل/إيقاف لكل إضافة + التهيئة

• معرّفات إضافات غير معروفة في entries، allow، deny، أو slots هي أخطاء.
• مفاتيح channels.<id> غير المعروفة هي أخطاء ما لم يعلن بيان الإضافة معرّف القناة.
• يتم التحقق من تهيئة الإضافة باستخدام JSON Schema المضمّن في openclaw.plugin.json (configSchema).
• إذا كانت الإضافة معطّلة، تُحفَظ تهيئتها ويُصدَر تحذير.

​

فتحات الإضافات (فئات حصرية)

{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable memory plugins
    },
  },
}

​

واجهة التحكم (المخطط + التسميات)

• يضيف تسميات لكل إضافة لـ plugins.entries.<id> / .enabled / .config
• يدمج تلميحات حقول التهيئة الاختيارية التي توفّرها الإضافات ضمن: plugins.entries.<id>.config.<field>

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": { "type": "string" },
      "region": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true },
    "region": { "label": "Region", "placeholder": "us-east-1" }
  }
}

​

CLI

openclaw plugins list
openclaw plugins info <id>
openclaw plugins install <path>                 # copy a local file/dir into ~/.openclaw/extensions/<id>
openclaw plugins install ./extensions/voice-call # relative path ok
openclaw plugins install ./plugin.tgz           # install from a local tarball
openclaw plugins install ./plugin.zip           # install from a local zip
openclaw plugins install -l ./extensions/voice-call # link (no copy) for dev
openclaw plugins install @openclaw/voice-call # install from npm
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins doctor

​

إضافة API (نظرة عامة)

• دالة: (api) => { ... }
• كائن: { id, name, configSchema, register(api) { ... } }

​

خطافات الإضافات

​

مثال

import { registerPluginHooksFromDir } from "openclaw/plugin-sdk";

export default function register(api) {
  registerPluginHooksFromDir(api, "./hooks");
}

• تتبع أدلة الخطافات البنية المعتادة للخطافات (HOOK.md + handler.ts).
• تظل قواعد أهلية الخطافات سارية (متطلبات نظام التشغيل/الثنائيات/البيئة/التهيئة).
• تظهر الخطافات المُدارة عبر الإضافات في openclaw hooks list مع plugin:<id>.
• لا يمكنك تمكين/تعطيل الخطافات المُدارة عبر الإضافات عبر openclaw hooks؛ بدلاً من ذلك فعِّل/عطِّل الإضافة.

​

إضافات الموفّرين (مصادقة النماذج)

• openclaw models auth login --provider <id> [--method <id>]

api.registerProvider({
  id: "acme",
  label: "AcmeAI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // Run OAuth flow and return auth profiles.
        return {
          profiles: [
            {
              profileId: "acme:default",
              credential: {
                type: "oauth",
                provider: "acme",
                access: "...",
                refresh: "...",
                expires: Date.now() + 3600 * 1000,
              },
            },
          ],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
});

• يستقبل run كائن ProviderAuthContext مع مساعدات prompter، runtime، openUrl، و oauth.createVpsAwareHandlers.
• أعد configPatch عندما تحتاج إلى إضافة نماذج افتراضية أو تهيئة الموفّر.
• أعد defaultModel بحيث يتمكن --set-default من تحديث افتراضيات الوكيل.

​

تسجيل قناة مراسلة

const myChannel = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "demo channel plugin.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async () => ({ ok: true }),
  },
};

export default function (api) {
  api.registerChannel({ plugin: myChannel });
}

• ضع التهيئة ضمن channels.<id> (وليس plugins.entries).
• يُستخدم meta.label للتسميات في قوائم CLI/واجهة المستخدم.
• يضيف meta.aliases معرّفات بديلة للتطبيع وإدخالات CLI.
• يسرد meta.preferOver معرّفات القنوات التي يجب تخطي التمكين التلقائي عند تهيئة كليهما.
• يتيح meta.detailLabel و meta.systemImage لواجهات المستخدم عرض تسميات/أيقونات قنوات أغنى.

​

كتابة قناة مراسلة جديدة (خطوة بخطوة)

1. اختر معرّفًا + شكل التهيئة

• تعيش جميع تهيئة القنوات ضمن channels.<id>.
• فضّل channels.<id>.accounts.<accountId> لإعدادات الحسابات المتعددة.

2. عرّف بيانات القناة الوصفية

• تتحكم meta.label، meta.selectionLabel، meta.docsPath، meta.blurb في قوائم CLI/واجهة المستخدم.
• يجب أن يشير meta.docsPath إلى صفحة توثيق مثل /channels/<id>.
• يتيح meta.preferOver لإضافة استبدال قناة أخرى (يفضّل التمكين التلقائي).
• تُستخدم meta.detailLabel و meta.systemImage بواسطة واجهات المستخدم لنصوص/أيقونات التفاصيل.

3. نفّذ المحوّلات المطلوبة

• config.listAccountIds + config.resolveAccount
• capabilities (أنواع الدردشة، الوسائط، الخيوط، إلخ)
• outbound.deliveryMode + outbound.sendText (للإرسال الأساسي)

4. أضف محوّلات اختيارية حسب الحاجة

• setup (معالج)، security (سياسة الرسائل الخاصة)، status (الصحة/التشخيص)
• gateway (بدء/إيقاف/تسجيل الدخول)، mentions، threading، streaming
• actions (إجراءات الرسائل)، commands (سلوك الأوامر الأصلي)

5. سجّل القناة في إضافتك

• api.registerChannel({ plugin })

{
  channels: {
    acmechat: {
      accounts: {
        default: { token: "ACME_TOKEN", enabled: true },
      },
    },
  },
}

const plugin = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "AcmeChat messaging channel.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // deliver `text` to your channel here
      return { ok: true };
    },
  },
};

export default function (api) {
  api.registerChannel({ plugin });
}

​

أدوات الوكيل

​

تسجيل أسلوب Gateway RPC

export default function (api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { ok: true });
  });
}

​

تسجيل أوامر CLI

export default function (api) {
  api.registerCli(
    ({ program }) => {
      program.command("mycmd").action(() => {
        console.log("Hello");
      });
    },
    { commands: ["mycmd"] },
  );
}

​

تسجيل أوامر الردّ التلقائي

export default function (api) {
  api.registerCommand({
    name: "mystatus",
    description: "Show plugin status",
    handler: (ctx) => ({
      text: `Plugin is running! Channel: ${ctx.channel}`,
    }),
  });
}

• senderId: معرّف المُرسل (إن كان متاحًا)
• channel: القناة التي أُرسل فيها الأمر
• isAuthorizedSender: ما إذا كان المُرسل مستخدمًا مخوّلًا
• args: الوسائط المُمرّرة بعد الأمر (إذا كان acceptsArgs: true)
• commandBody: نص الأمر الكامل
• config: تهيئة OpenClaw الحالية

• name: اسم الأمر (دون البادئة /)
• description: نص المساعدة المعروض في قوائم الأوامر
• acceptsArgs: ما إذا كان الأمر يقبل وسيطات (الافتراضي: false). إذا كان false وتم تمرير وسيطات، فلن يتطابق الأمر وتسقط الرسالة إلى معالجات أخرى
• requireAuth: ما إذا كان يتطلب مُرسلًا مخوّلًا (الافتراضي: true)
• handler: دالة تُرجِع { text: string } (يمكن أن تكون async)

api.registerCommand({
  name: "setmode",
  description: "Set plugin mode",
  acceptsArgs: true,
  requireAuth: true,
  handler: async (ctx) => {
    const mode = ctx.args?.trim() || "default";
    await saveMode(mode);
    return { text: `Mode set to: ${mode}` };
  },
});

• تُعالَج أوامر الإضافات قبل الأوامر المضمّنة ووكيل الذكاء الاصطناعي
• تُسجَّل الأوامر عالميًا وتعمل عبر جميع القنوات
• أسماء الأوامر غير حسّاسة لحالة الأحرف (/MyStatus يطابق /mystatus)
• يجب أن تبدأ أسماء الأوامر بحرف وأن تحتوي فقط على أحرف وأرقام وواصلات وشرطات سفلية
• لا يمكن للإضافات تجاوز أسماء الأوامر المحجوزة (مثل help، status، reset، إلخ) لا يمكن تجاوزها بواسطة الإضافات لا يمكن تجاوزها بواسطة الإضافات
• سيؤدي تسجيل أوامر مكرّرة عبر إضافات متعددة إلى الفشل مع خطأ تشخيصي

​

تسجيل خدمات تعمل في الخلفية

export default function (api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

​

اتفاقيات التسمية

• أساليب Gateway: pluginId.action (مثال: voicecall.status)
• الأدوات: snake_case (مثال: voice_call)
• أوامر CLI: kebab أو camel، لكن تجنّب التعارض مع أوامر النواة

​

Skills

​

التوزيع (npm)

• الحزمة الرئيسية: openclaw (هذا المستودع)
• الإضافات: حزم npm منفصلة ضمن @openclaw/* (مثال: @openclaw/voice-call)

• يجب أن يتضمن package.json للإضافة openclaw.extensions مع ملف إدخال واحد أو أكثر.
• يمكن أن تكون ملفات الإدخال .js أو .ts (يحمل jiti TypeScript في وقت التشغيل).
• يستخدم openclaw plugins install <npm-spec> npm pack، ويستخرج إلى ~/.openclaw/extensions/<id>/، ويمكّنه في التهيئة.
• ثبات مفاتيح التهيئة: تُطبَّع الحزم ذات النطاق إلى المعرّف غير ذي النطاق لـ plugins.entries.*.

​

مثال إضافة: Voice Call

• المصدر: extensions/voice-call
• Skill: skills/voice-call
• CLI: openclaw voicecall start|status
• الأداة: voice_call
• RPC: voicecall.start، voicecall.status
• التهيئة (twilio): provider: "twilio" + twilio.accountSid/authToken/from (اختياري statusCallbackUrl، twimlUrl)
• التهيئة (dev): provider: "log" (بدون شبكة)

​

ملاحظات السلامة

• ثبّت فقط الإضافات التي تثق بها.
• فضّل قوائم السماح plugins.allow.
• أعد تشغيل Gateway بعد التغييرات.

​

اختبار الإضافات

• يمكن للإضافات داخل المستودع الاحتفاظ باختبارات Vitest ضمن src/** (مثال: src/plugins/voice-call.plugin.test.ts).
• يجب على الإضافات المنشورة بشكل منفصل تشغيل CI خاص بها (lint/build/test) والتحقق من أن openclaw.extensions يشير إلى نقطة الإدخال المبنية (dist/index.js).