Plugins

Plugins إطار تشغيل الوكيل

يُعد مشغّل الوكيل المنفّذ منخفض المستوى لدورة واحدة مُحضّرة لوكيل OpenClaw. وهو ليس مزوّد نماذج، ولا قناة، ولا سجل أدوات. للنموذج الذهني الموجّه للمستخدم، راجع بيئات تشغيل الوكلاء.

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

متى تستخدم مشغّلًا

سجّل مشغّل وكيل عندما تكون لعائلة نماذج بيئة تشغيل جلسة أصلية خاصة بها، ويكون نقل مزوّد OpenClaw العادي هو التجريد غير المناسب.

أمثلة:

خادم وكيل برمجة أصلي يمتلك السلاسل وCompaction
CLI محلي أو عفريت يجب أن يبث أحداث الخطة/الاستدلال/الأدوات الأصلية
بيئة تشغيل نموذج تحتاج إلى معرّف استئناف خاص بها بالإضافة إلى نص جلسة OpenClaw

لا تسجّل مشغّلًا لمجرد إضافة واجهة LLM API جديدة. بالنسبة إلى واجهات نماذج HTTP أو WebSocket العادية، ابنِ Plugin مزوّد.

ما الذي لا يزال النواة تملكه

قبل اختيار مشغّل، يكون OpenClaw قد حلّ بالفعل:

المزوّد والنموذج
حالة مصادقة بيئة التشغيل
مستوى التفكير وميزانية السياق
ملف نص جلسة OpenClaw
مساحة العمل، وصندوق الرمل، وسياسة الأدوات
استدعاءات رد القناة واستدعاءات البث
سياسة الرجوع إلى نموذج بديل والتبديل الحي للنماذج

هذا الفصل مقصود. يشغّل المشغّل محاولة مُحضّرة؛ ولا يختار المزوّدين، ولا يستبدل تسليم القنوات، ولا يبدّل النماذج بصمت.

تتضمن المحاولة المُحضّرة أيضًا params.runtimePlan، وهي حزمة سياسات يملكها OpenClaw لقرارات بيئة التشغيل التي يجب أن تظل مشتركة بين PI والمشغّلات الأصلية:

runtimePlan.tools.normalize(...) و runtimePlan.tools.logDiagnostics(...) لسياسة مخطط الأدوات الواعية بالمزوّد
runtimePlan.transcript.resolvePolicy(...) لسياسة تنقية النص وإصلاح استدعاءات الأدوات
runtimePlan.delivery.isSilentPayload(...) للقمع المشترك لتسليم NO_REPLY والوسائط
runtimePlan.outcome.classifyRunResult(...) لتصنيف الرجوع إلى نموذج بديل
runtimePlan.observability لبيانات تعريف المزوّد/النموذج/المشغّل المحلولة

قد تستخدم المشغّلات الخطة لاتخاذ قرارات يجب أن تطابق سلوك PI، لكنها يجب أن تعاملها مع ذلك كحالة محاولة يملكها المضيف. لا تعدّلها ولا تستخدمها لتبديل المزوّدين/النماذج داخل دورة.

تسجيل مشغّل

الاستيراد: openclaw/plugin-sdk/agent-harness



const myHarness: AgentHarness = {
  id: "my-harness",
  label: "My native agent harness",

  supports(ctx) {
    return ctx.provider === "my-provider"
      ? { supported: true, priority: 100 }
      : { supported: false };
  },

  async runAttempt(params) {
    // Start or resume your native thread.
    // Use params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent, and the other prepared attempt fields.
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "My Native Agent",
  description: "Runs selected models through a native agent daemon.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});

سياسة الاختيار

يختار OpenClaw مشغّلًا بعد حل المزوّد/النموذج:

يفوز معرّف المشغّل المسجّل لجلسة موجودة، لذلك لا تؤدي تغييرات الإعدادات/البيئة إلى تبديل ذلك النص سريعًا إلى بيئة تشغيل أخرى.
يفرض OPENCLAW_AGENT_RUNTIME=<id> مشغّلًا مسجّلًا بذلك المعرّف للجلسات غير المثبّتة مسبقًا.
يفرض OPENCLAW_AGENT_RUNTIME=pi مشغّل PI المضمّن.
يطلب OPENCLAW_AGENT_RUNTIME=auto من المشغّلات المسجّلة ما إذا كانت تدعم المزوّد/النموذج المحلول.
إذا لم يطابق أي مشغّل مسجّل، يستخدم OpenClaw PI ما لم يكن الرجوع إلى PI معطّلًا.

تظهر إخفاقات مشغّل Plugin كإخفاقات تشغيل. في وضع auto، لا يُستخدم الرجوع إلى PI إلا عندما لا يدعم أي مشغّل Plugin مسجّل المزوّد/النموذج المحلول. بمجرد أن يطالب مشغّل Plugin بتشغيل ما، لا يعيد OpenClaw تشغيل الدورة نفسها عبر PI لأن ذلك قد يغيّر دلالات المصادقة/بيئة التشغيل أو يكرر الآثار الجانبية.

يُحفظ معرّف المشغّل المحدد مع معرّف الجلسة بعد تشغيل مضمّن. تُعامل الجلسات القديمة التي أُنشئت قبل تثبيت المشغّلات كأنها مثبّتة على PI بمجرد أن يكون لديها سجل نص. استخدم جلسة جديدة/معاد ضبطها عند التغيير بين PI ومشغّل Plugin أصلي. يعرض /status معرّفات المشغّل غير الافتراضية مثل codex بجانب Fast؛ يبقى PI مخفيًا لأنه مسار التوافق الافتراضي. إذا كان المشغّل المحدد مفاجئًا، فعّل تسجيل تصحيح agents/harness وافحص سجل agent harness selected المنظّم في Gateway. يتضمن معرّف المشغّل المحدد، وسبب الاختيار، وسياسة بيئة التشغيل/الرجوع، وفي وضع auto، نتيجة دعم كل مرشح Plugin.

يسجّل Plugin Codex المضمّن codex كمعرّف مشغّله. تتعامل النواة مع ذلك كمعرّف مشغّل Plugin عادي؛ تنتمي الأسماء البديلة الخاصة بـ Codex إلى Plugin أو إعدادات المشغّل، لا إلى محدد بيئة التشغيل المشترك.

إقران المزوّد والمشغّل

يجب أن تسجّل معظم المشغّلات مزوّدًا أيضًا. يجعل المزوّد مراجع النماذج، وحالة المصادقة، وبيانات تعريف النموذج، واختيار /model مرئية لبقية OpenClaw. ثم يطالب المشغّل بذلك المزوّد في supports(...).

يتبع Plugin Codex المضمّن هذا النمط:

مراجع نموذج المستخدم المفضلة: openai/gpt-5.5 بالإضافة إلى agentRuntime.id: "codex"
مراجع التوافق: تبقى مراجع codex/gpt-* القديمة مقبولة، لكن يجب ألا تستخدمها الإعدادات الجديدة كمراجع مزوّد/نموذج عادية
معرّف المشغّل: codex
المصادقة: توفر مزوّد اصطناعي، لأن مشغّل Codex يمتلك تسجيل دخول/جلسة Codex الأصلية
طلب خادم التطبيق: يرسل OpenClaw معرّف النموذج الصرف إلى Codex ويترك المشغّل يتحدث إلى بروتوكول خادم التطبيق الأصلي

Plugin Codex إضافي. تستمر مراجع openai/gpt-* العادية في استخدام مسار مزوّد OpenClaw العادي ما لم تفرض مشغّل Codex باستخدام agentRuntime.id: "codex". لا تزال مراجع codex/gpt-* الأقدم تختار مزوّد ومشغّل Codex للتوافق.

لإعداد المشغّل، وأمثلة بادئات النماذج، وإعدادات Codex فقط، راجع مشغّل Codex.

يتطلب OpenClaw خادم تطبيق Codex بالإصدار 0.125.0 أو أحدث. يتحقق Plugin Codex من مصافحة تهيئة خادم التطبيق ويحظر الخوادم الأقدم أو غير ذات الإصدار، حتى يعمل OpenClaw فقط على سطح البروتوكول الذي اختُبر معه. يتضمن حد 0.125.0 الأدنى دعم حمولة خطاف MCP الأصلي الذي وصل في Codex 0.124.0، مع تثبيت OpenClaw على خط مستقر أحدث ومختبر.

وسيط نتائج الأدوات

يمكن للـ Plugins المضمّنة إرفاق وسيط نتائج أدوات محايد لبيئة التشغيل عبر api.registerAgentToolResultMiddleware(...) عندما يصرّح بيانها بمعرّفات بيئة التشغيل المستهدفة في contracts.agentToolResultMiddleware. هذا السطح الموثوق مخصص لتحويلات نتائج الأدوات غير المتزامنة التي يجب أن تعمل قبل أن يعيد PI أو Codex تغذية مخرجات الأدوات إلى النموذج.

لا تزال Plugins المضمّنة القديمة قادرة على استخدام api.registerCodexAppServerExtensionFactory(...) لوسيط مخصص لخادم تطبيق Codex فقط، لكن يجب أن تستخدم تحويلات النتائج الجديدة API المحايد لبيئة التشغيل. أُزيل خطاف api.registerEmbeddedExtensionFactory(...) الخاص بـ Pi فقط؛ يجب أن تستخدم تحويلات نتائج أدوات Pi وسيطًا محايدًا لبيئة التشغيل.

تصنيف النتيجة النهائية

يمكن للمشغّلات الأصلية التي تملك إسقاط البروتوكول الخاص بها استخدام classifyAgentHarnessTerminalOutcome(...) من openclaw/plugin-sdk/agent-harness-runtime عندما تنتج دورة مكتملة بلا نص مساعد مرئي. يُرجع المساعد empty، أو reasoning-only، أو planning-only حتى تقرر سياسة الرجوع في OpenClaw ما إذا كانت ستعيد المحاولة على نموذج مختلف. وهو يترك عمدًا أخطاء المطالبة، والدورات قيد التنفيذ، والردود الصامتة المقصودة مثل NO_REPLY غير مصنّفة.

وضع مشغّل Codex الأصلي

مشغّل codex المضمّن هو وضع Codex الأصلي لدورات وكيل OpenClaw المضمّنة. فعّل Plugin codex المضمّن أولًا، وأدرج codex في plugins.allow إذا كانت إعداداتك تستخدم قائمة سماح تقييدية. يجب أن تستخدم إعدادات خادم التطبيق الأصلية openai/gpt-* مع agentRuntime.id: "codex". استخدم openai-codex/* لمصادقة Codex OAuth عبر PI بدلًا من ذلك. تبقى مراجع نموذج codex/* القديمة أسماء بديلة توافقية للمشغّل الأصلي.

عند تشغيل هذا الوضع، يمتلك Codex معرّف السلسلة الأصلي، وسلوك الاستئناف، وCompaction، وتنفيذ خادم التطبيق. لا يزال OpenClaw يمتلك قناة المحادثة، ومرآة النص المرئي، وسياسة الأدوات، والموافقات، وتسليم الوسائط، واختيار الجلسة. استخدم agentRuntime.id: "codex" عندما تحتاج إلى إثبات أن مسار خادم تطبيق Codex وحده يمكنه المطالبة بالتشغيل. تفشل بيئات تشغيل Plugin الصريحة بشكل مغلق؛ ولا يُعاد تشغيل إخفاقات اختيار خادم تطبيق Codex وإخفاقات بيئة التشغيل عبر PI.

صرامة بيئة التشغيل

افتراضيًا، يشغّل OpenClaw الوكلاء المضمّنين باستخدام OpenClaw Pi. في وضع auto، يمكن لمشغّلات Plugin المسجّلة المطالبة بزوج مزوّد/نموذج، ويتعامل PI مع الدورة عندما لا يطابق أي منها. استخدم بيئة تشغيل Plugin صريحة مثل agentRuntime.id: "codex" عندما يجب أن يفشل اختيار المشغّل المفقود بدلًا من التوجيه عبر PI. تفشل إخفاقات مشغّل Plugin المحدد دائمًا بشكل صارم. لا يمنع هذا agentRuntime.id: "pi" صريحًا أو OPENCLAW_AGENT_RUNTIME=pi.

لتشغيلات Codex المضمّنة فقط:

{
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.5",
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}

إذا أردت أن يطالب أي مشغّل Plugin مسجّل بالنماذج المطابقة وأن يستخدم PI في غير ذلك، فاضبط id: "auto":

{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "auto"
      }
    }
  }
}

تستخدم التجاوزات لكل وكيل الشكل نفسه:

{
  "agents": {
    "defaults": {
      "agentRuntime": { "id": "auto" }
    },
    "list": [
      {
        "id": "codex-only",
        "model": "openai/gpt-5.5",
        "agentRuntime": { "id": "codex" }
      }
    ]
  }
}

لا يزال OPENCLAW_AGENT_RUNTIME يتجاوز بيئة التشغيل المضبوطة.

OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run

مع بيئة تشغيل Plugin صريحة، تفشل الجلسة مبكرًا عندما لا يكون المشغّل المطلوب مسجّلًا، أو لا يدعم المزوّد/النموذج المحلول، أو يفشل قبل إنتاج آثار جانبية للدورة. هذا مقصود لعمليات نشر Codex فقط وللاختبارات الحية التي يجب أن تثبت أن مسار خادم تطبيق Codex قيد الاستخدام فعلًا.

يتحكم هذا الإعداد فقط في مشغّل الوكيل المضمّن. ولا يعطّل توجيه النماذج الخاص بالمزوّد للصور، أو الفيديو، أو الموسيقى، أو TTS، أو PDF، أو غير ذلك.

الجلسات الأصلية ومرآة النص

قد يحتفظ مشغّل بمعرّف جلسة أصلي، أو معرّف سلسلة، أو رمز استئناف على جانب العفريت. أبقِ هذا الربط مرتبطًا صراحةً بجلسة OpenClaw، واستمر في عكس مخرجات المساعد/الأدوات المرئية للمستخدم إلى نص OpenClaw.

يبقى نص OpenClaw طبقة التوافق من أجل:

سجل الجلسة المرئي للقناة
بحث النص وفهرسته
العودة إلى مشغّل PI المضمّن في دورة لاحقة
سلوك /new و/reset العام وحذف الجلسات

إذا كان مشغّلك يخزّن ربطًا جانبيًا، فنفّذ reset(...) حتى يتمكن OpenClaw من مسحه عند إعادة ضبط جلسة OpenClaw المالكة.

نتائج الأدوات والوسائط

تبني النواة قائمة أدوات OpenClaw وتمررها إلى المحاولة المُحضّرة. عندما ينفّذ مشغّل استدعاء أداة ديناميكيًا، أعد نتيجة الأداة عبر شكل نتيجة المشغّل بدلًا من إرسال وسائط القناة بنفسك.

يبقي هذا مخرجات النص، والصور، والفيديو، والموسيقى، وTTS، والموافقة، وأدوات المراسلة على مسار التسليم نفسه مثل التشغيلات المدعومة بـ PI.

القيود الحالية

مسار الاستيراد العام عامّ، لكن بعض الأسماء البديلة لأنواع المحاولة/النتيجة ما زالت تحمل أسماء Pi للتوافق.
تثبيت حاضنة تابعة لجهة خارجية تجريبي. فضّل Pluginات المزوّدين إلى أن تحتاج إلى وقت تشغيل جلسة أصلي.
تبديل الحاضنة مدعوم عبر الأدوار. لا تبدّل الحاضنات في منتصف دور بعد بدء الأدوات الأصلية أو الموافقات أو نص المساعد أو إرسال الرسائل.

Plugins إطار تشغيل الوكيل

متى تستخدم مشغّلًا

ما الذي لا يزال النواة تملكه

تسجيل مشغّل

سياسة الاختيار

إقران المزوّد والمشغّل

وسيط نتائج الأدوات

تصنيف النتيجة النهائية

وضع مشغّل Codex الأصلي

صرامة بيئة التشغيل

الجلسات الأصلية ومرآة النص

نتائج الأدوات والوسائط

القيود الحالية

ذات صلة

Ask OpenClaw

# متى تستخدم مشغّلًا

# ما الذي لا يزال النواة تملكه

# تسجيل مشغّل

# سياسة الاختيار

# إقران المزوّد والمشغّل

# وسيط نتائج الأدوات

# تصنيف النتيجة النهائية

# وضع مشغّل Codex الأصلي

# صرامة بيئة التشغيل

# الجلسات الأصلية ومرآة النص

# نتائج الأدوات والوسائط

# القيود الحالية

# ذات صلة

متى تستخدم مشغّلًا

ما الذي لا يزال النواة تملكه

تسجيل مشغّل

سياسة الاختيار

إقران المزوّد والمشغّل

وسيط نتائج الأدوات

تصنيف النتيجة النهائية

وضع مشغّل Codex الأصلي

صرامة بيئة التشغيل

الجلسات الأصلية ومرآة النص

نتائج الأدوات والوسائط

القيود الحالية

ذات صلة