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.

​

البدء السريع

openclaw plugins list

# Search ClawHub plugins
openclaw plugins search "calendar"

# From ClawHub
openclaw plugins install clawhub:openclaw-codex-app-server

# From npm
openclaw plugins install npm:@acme/openclaw-plugin
openclaw plugins install npm-pack:./openclaw-plugin-1.2.3.tgz

# From git
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0

# From a local directory or archive
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

# If the plugin registered a CLI root, run one command from that root.
openclaw <plugin-command> --help

/plugin install clawhub:<package>
/plugin show <plugin-id>
/plugin enable <plugin-id>

​

ملكية مسار Plugin المحظور

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

sudo chown -R root:root /path/to/openclaw-config/npm

​

أنواع Plugin

​

نقاط دخول الحزمة

{
  "name": "@acme/openclaw-plugin",
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"]
  }
}

​

Plugins الرسمية

​

حزم npm المملوكة لـ OpenClaw أثناء الترحيل

​

Core (تُشحن مع OpenClaw)

​

الإعداد

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

​

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

​

قواعد التفعيل

• يعطّل plugins.enabled: false كل Plugins ويتخطى عمل اكتشاف/تحميل Plugins
• تكون الأولوية دائمًا لـ plugins.deny على السماح
• يعطّل plugins.entries.\<id\>.enabled: false ذلك Plugin
• Plugins ذات أصل مساحة العمل معطّلة افتراضيًا (يجب تفعيلها صراحة)
• تتبع Plugins المضمّنة مجموعة التشغيل الافتراضي المدمجة ما لم يتم تجاوزها
• يمكن للخانات الحصرية فرض تفعيل Plugin المحدد لتلك الخانة
• تُفعّل بعض Plugins المضمّنة الاختيارية تلقائيًا عندما تسمي الإعدادات سطحًا مملوكًا لـ Plugin، مثل مرجع نموذج مزود، أو إعداد قناة، أو وقت تشغيل harness
• يتم الاحتفاظ بإعدادات Plugin القديمة أثناء كون plugins.enabled: false نشطًا؛ أعد تفعيل Plugins قبل تشغيل تنظيف doctor إذا أردت إزالة المعرفات القديمة
• تحافظ مسارات Codex لعائلة OpenAI على حدود Plugin منفصلة: ينتمي openai-codex/* إلى OpenAI Plugin، بينما يتم اختيار Plugin خادم تطبيق Codex المضمّن بواسطة مراجع وكيل openai/* القياسية، أو agentRuntime.id: "codex" الصريحة للمزود/النموذج، أو مراجع نماذج codex/* القديمة

​

استكشاف أخطاء خطافات وقت التشغيل وإصلاحها

• شغّل openclaw gateway status --deep --require-rpc وتأكد أن عنوان URL الخاص بـ Gateway النشط، والملف الشخصي، ومسار الإعداد، والعملية هي التي تعدّلها.
• أعد تشغيل Gateway الحي بعد تغييرات تثبيت/إعداد/كود Plugin. في حاويات التغليف، قد يكون PID 1 مجرد مشرف؛ أعد تشغيل أو أرسل إشارة إلى عملية openclaw gateway run الفرعية.
• استخدم openclaw plugins inspect <id> --runtime --json لتأكيد تسجيلات الخطافات والتشخيصات. تحتاج خطافات المحادثة غير المضمّنة مثل before_model_resolve، وbefore_agent_reply، وbefore_agent_run، وllm_input، وllm_output، وbefore_agent_finalize، وagent_end إلى plugins.entries.<id>.hooks.allowConversationAccess=true.
• لتبديل النماذج، فضّل before_model_resolve. يعمل قبل حل النموذج لأدوار الوكيل؛ ولا يعمل llm_output إلا بعد أن تنتج محاولة نموذج مخرجات مساعد.
• لإثبات نموذج الجلسة الفعّال، استخدم openclaw sessions أو أسطح جلسة/حالة Gateway، وعند تصحيح حمولات المزود، ابدأ Gateway باستخدام --raw-stream --raw-stream-path <path>.

​

بطء إعداد أداة Plugin

openclaw config set logging.level trace
openclaw logs --follow

[trace:plugin-tools] factory timings ...

openclaw plugins inspect <plugin-id> --runtime --json

​

تكرار ملكية قناة أو أداة

• channel already registered: <channel-id> (<plugin-id>)
• channel setup already registered: <channel-id> (<plugin-id>)
• plugin tool name conflict (<plugin-id>): <tool-name>

• شغّل openclaw plugins list --enabled --verbose لرؤية كل Plugin مفعّل وأصله.
• شغّل openclaw plugins inspect <id> --runtime --json لكل Plugin مشتبه به و قارن channels وchannelConfigs وtools والتشخيصات.
• شغّل openclaw plugins registry --refresh بعد تثبيت أو إزالة حزم Plugin حتى تعكس البيانات الوصفية المستمرة التثبيت الحالي.
• أعد تشغيل Gateway بعد تغييرات التثبيت أو السجل أو الإعدادات.

• إذا كان أحد Plugins يستبدل آخر عن قصد لمعرف القناة نفسه، فيجب أن يعلن Plugin المفضّل channelConfigs.<channel-id>.preferOver مع معرف Plugin الأقل أولوية. راجع /plugins/manifest#replacing-another-channel-plugin.
• إذا كان التكرار عرضيًا، فعطّل أحد الجانبين باستخدام plugins.entries.<plugin-id>.enabled: false أو أزل تثبيت Plugin القديم.
• إذا فعّلت كلا Plugins صراحة، يحتفظ OpenClaw بهذا الطلب ويبلّغ عن التعارض. اختر مالكًا واحدًا للقناة أو أعد تسمية الأدوات المملوكة لـ Plugin حتى يكون سطح وقت التشغيل غير ملتبس.

​

خانات Plugin (فئات حصرية)

{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable
      contextEngine: "legacy", // or a plugin id
    },
  },
}

​

مرجع CLI

openclaw plugins list                       # compact inventory
openclaw plugins list --enabled            # only enabled plugins
openclaw plugins list --verbose            # per-plugin detail lines
openclaw plugins list --json               # machine-readable inventory
openclaw plugins search <query>            # search ClawHub plugin catalog
openclaw plugins inspect <id>              # static detail
openclaw plugins inspect <id> --runtime    # registered hooks/tools/CLI/gateway methods
openclaw plugins inspect <id> --json       # machine-readable
openclaw plugins inspect --all             # fleet-wide table
openclaw plugins info <id>                 # inspect alias
openclaw plugins doctor                    # diagnostics
openclaw plugins registry                  # inspect persisted registry state
openclaw plugins registry --refresh        # rebuild persisted registry
openclaw doctor --fix                      # repair plugin registry state

openclaw plugins install <package>         # install from npm by default
openclaw plugins install clawhub:<pkg>     # install from ClawHub only
openclaw plugins install npm:<pkg>         # install from npm only
openclaw plugins install git:<repo>        # install from git
openclaw plugins install git:<repo>@<ref>  # install from git ref
openclaw plugins install <spec> --force    # overwrite existing install
openclaw plugins install <path>            # install from local path
openclaw plugins install -l <path>         # link (no copy) for dev
openclaw plugins install <plugin> --marketplace <source>
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <spec> --pin      # record exact resolved npm spec
openclaw plugins install <spec> --dangerously-force-unsafe-install
openclaw plugins update <id-or-npm-spec> # update one plugin
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
openclaw plugins update --all            # update all
openclaw plugins uninstall <id>          # remove config and plugin index records
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json

# Verify runtime registrations after install.
openclaw plugins inspect <id> --runtime --json

# Run plugin-owned CLI commands directly from the OpenClaw root CLI.
openclaw <plugin-command> --help

openclaw plugins enable <id>
openclaw plugins disable <id>

​

نظرة عامة على واجهة Plugin API

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
    api.registerChannel({
      /* ... */
    });
  },
});

• before_tool_call: يكون { block: true } نهائيًا؛ تُتخطى المعالجات ذات الأولوية الأدنى.
• before_tool_call: يكون { block: false } بلا أثر ولا يمسح حظرًا سابقًا.
• before_install: يكون { block: true } نهائيًا؛ تُتخطى المعالجات ذات الأولوية الأدنى.
• before_install: يكون { block: false } بلا أثر ولا يمسح حظرًا سابقًا.
• message_sending: يكون { cancel: true } نهائيًا؛ تُتخطى المعالجات ذات الأولوية الأدنى.
• message_sending: يكون { cancel: false } بلا أثر ولا يمسح إلغاءً سابقًا.

​

ذات صلة

• بناء Plugins - أنشئ Plugin الخاص بك
• حزم Plugin - توافق حزم Codex/Claude/Cursor
• بيان Plugin - مخطط البيان
• تسجيل الأدوات - أضف أدوات الوكيل في Plugin
• تفاصيل Plugin الداخلية - نموذج القدرات ومسار التحميل
• ClawHub - اكتشاف Plugins تابعة لجهات خارجية