الانتقال إلى المحتوى الرئيسي

Documentation Index

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

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

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

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

سجّل مشغّل وكيل عندما تكون لعائلة نماذج بيئة جلسة أصلية خاصة بها وتكون وسيلة نقل موفّر OpenClaw العادية تجريداً غير مناسب. أمثلة:
  • خادم وكيل برمجة أصلي يملك الخيوط وCompaction
  • CLI محلي أو عفريت يجب أن يبث أحداث التخطيط/الاستدلال/الأدوات الأصلية
  • بيئة تشغيل نموذج تحتاج إلى معرّف استئناف خاص بها بالإضافة إلى سجل جلسة OpenClaw
لا تسجّل مشغّلاً لمجرد إضافة API جديدة لـ LLM. بالنسبة إلى APIs النماذج العادية عبر HTTP أو WebSocket، ابنِ provider plugin.

​
ما لا يزال القلب يملكه

قبل اختيار مشغّل، يكون OpenClaw قد حسم بالفعل:
  • الموفّر والنموذج
  • حالة مصادقة بيئة التشغيل
  • مستوى التفكير وميزانية السياق
  • ملف سجل/جلسة OpenClaw
  • مساحة العمل، sandbox، وسياسة الأدوات
  • ردود نداء القناة وردود نداء البث
  • سياسة الرجوع إلى نموذج بديل والتبديل الحي بين النماذج
هذا الفصل مقصود. يشغّل المشغّل محاولة مُحضّرة؛ ولا يختار الموفّرين، ولا يستبدل تسليم القناة، ولا يبدّل النماذج بصمت. تتضمن المحاولة المُحضّرة أيضاً 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 
import type { AgentHarness } from "openclaw/plugin-sdk/agent-harness";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

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 مشغّلاً بعد حسم الموفّر/النموذج:
  1. تفوز سياسة بيئة التشغيل ذات نطاق النموذج.
  2. تأتي بعدها سياسة بيئة التشغيل ذات نطاق الموفّر.
  3. يطلب auto من المشغّلات المسجلة ما إذا كانت تدعم الموفّر/النموذج المحسومين.
  4. إذا لم يطابق أي مشغّل مسجل، يستخدم OpenClaw PI ما لم يكن الرجوع إلى PI معطلاً.
تظهر إخفاقات مشغّلات Plugin كإخفاقات تشغيل. في وضع auto، لا يُستخدم الرجوع إلى PI إلا عندما لا يدعم أي مشغّل Plugin مسجل الموفّر/النموذج المحسومين. بعد أن يطالب مشغّل Plugin بتشغيل ما، لا يعيد OpenClaw تشغيل الدورة نفسها عبر PI لأن ذلك قد يغيّر دلالات المصادقة/بيئة التشغيل أو يكرر الآثار الجانبية. يتجاهل الاختيار تثبيتات بيئة التشغيل على مستوى الجلسة كلها أو الوكيل كله. يشمل ذلك قيم agentHarnessId القديمة في الجلسة، وagents.defaults.agentRuntime، وagents.list[].agentRuntime، وOPENCLAW_AGENT_RUNTIME. يعرض /status بيئة التشغيل الفعلية المختارة من مسار الموفّر/النموذج. إذا كان المشغّل المختار مفاجئاً، فعّل تسجيل التصحيح agents/harness وافحص سجل agent harness selected المنظّم في Gateway. يتضمن معرّف المشغّل المختار، وسبب الاختيار، وسياسة بيئة التشغيل/الرجوع، وفي وضع auto، نتيجة دعم كل مرشح Plugin. يسجل Plugin Codex المضمّن codex كمعرّف المشغّل الخاص به. يعامل القلب ذلك كمعرّف مشغّل Plugin عادي؛ أما الأسماء المستعارة الخاصة بـ Codex فمكانها في Plugin أو إعدادات المشغّل، لا في محدد بيئة التشغيل المشترك.

​
اقتران الموفّر والمشغّل

ينبغي لمعظم المشغّلات تسجيل موفّر أيضاً. يجعل الموفّر مراجع النماذج، وحالة المصادقة، وبيانات النموذج الوصفية، واختيار /model مرئية لبقية OpenClaw. ثم يطالب المشغّل بذلك الموفّر في supports(...). يتبع Plugin Codex المضمّن هذا النمط:
  • مراجع نموذج المستخدم المفضلة: openai/gpt-5.5
  • مراجع التوافق: تظل مراجع codex/gpt-* القديمة مقبولة، لكن يجب ألا تستخدمها الإعدادات الجديدة كمراجع موفّر/نموذج عادية
  • معرّف المشغّل: codex
  • المصادقة: توفر موفّر اصطناعي، لأن مشغّل Codex يملك تسجيل الدخول/الجلسة الأصلية الخاصة بـ Codex
  • طلب خادم التطبيق: يرسل OpenClaw معرّف النموذج الخام إلى Codex ويترك للمشغّل التحدث إلى بروتوكول خادم التطبيق الأصلي
Plugin Codex إضافي. تختار مراجع وكلاء openai/gpt-* العادية على موفّر OpenAI الرسمي مشغّل Codex افتراضياً. لا تزال مراجع codex/gpt-* الأقدم تختار موفّر Codex ومشغّله للتوافق. لإعداد المشغّل، وأمثلة بادئات النماذج، والإعدادات الخاصة بـ Codex فقط، راجع مشغّل Codex. يتطلب OpenClaw خادم تطبيق Codex بالإصدار 0.125.0 أو أحدث. يتحقق Plugin Codex من مصافحة تهيئة خادم التطبيق ويحظر الخوادم الأقدم أو غير المعرّفة بإصدار حتى يعمل OpenClaw فقط على سطح البروتوكول الذي اختُبر معه. يتضمن الحد الأدنى 0.125.0 دعم حمولة خطاف MCP الأصلي الذي وصل في Codex 0.124.0، مع تثبيت OpenClaw على الخط المستقر الأحدث المختبر.

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

يمكن للإضافات المضمّنة إرفاق وسيط نتائج أدوات محايد لبيئة التشغيل عبر api.registerAgentToolResultMiddleware(...) عندما يعلن manifest الخاص بها معرّفات بيئة التشغيل المستهدفة في contracts.agentToolResultMiddleware. هذا السطح الموثوق مخصص لتحويلات نتائج الأدوات غير المتزامنة التي يجب أن تعمل قبل أن يعيد PI أو Codex تغذية مخرجات الأداة إلى النموذج. لا تزال الإضافات المضمّنة القديمة قادرة على استخدام api.registerCodexAppServerExtensionFactory(...) لوسيط خاص بخادم تطبيق Codex فقط، لكن يجب أن تستخدم تحويلات النتائج الجديدة API المحايدة لبيئة التشغيل. أزيل خطاف Pi-only api.registerEmbeddedExtensionFactory(...)؛ يجب أن تستخدم تحويلات نتائج أدوات 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-*؛ تختار دورات وكلاء OpenAI مشغّل Codex افتراضياً. يجب إصلاح مسارات openai-codex/* القديمة باستخدام openclaw doctor --fix، وتظل مراجع نماذج codex/* القديمة أسماء مستعارة توافقية للمشغّل الأصلي. عندما يعمل هذا الوضع، يملك Codex معرّف الخيط الأصلي، وسلوك الاستئناف، وCompaction، وتنفيذ خادم التطبيق. لا يزال OpenClaw يملك قناة المحادثة، ومرآة السجل المرئي، وسياسة الأدوات، والموافقات، وتسليم الوسائط، واختيار الجلسة. استخدم agentRuntime.id: "codex" على مستوى الموفّر/النموذج عندما تحتاج إلى إثبات أن مسار خادم تطبيق Codex فقط يستطيع المطالبة بالتشغيل. تفشل بيئات تشغيل Plugin الصريحة بشكل مغلق؛ ولا يُعاد تجريب إخفاقات اختيار خادم تطبيق Codex أو إخفاقات بيئة التشغيل عبر PI.

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

افتراضياً، يستخدم OpenClaw سياسة بيئة تشغيل الموفّر/النموذج auto: يمكن للمشغّلات المسجلة في Plugin المطالبة بزوج موفّر/نموذج، ويتولى PI الدورة عندما لا يطابق أي منها. تُضبط مراجع وكلاء OpenAI على موفّر OpenAI الرسمي افتراضياً إلى Codex. استخدم بيئة تشغيل Plugin صريحة على مستوى الموفّر/النموذج مثل agentRuntime.id: "codex" عندما يجب أن يفشل غياب اختيار المشغّل بدلاً من التوجيه عبر PI. تفشل إخفاقات مشغّلات Plugin المختارة دائماً بشكل صارم. لا يمنع ذلك بيئة تشغيل صريحة على مستوى الموفّر/النموذج agentRuntime.id: "pi". لتشغيلات Codex المضمّنة فقط: 
{
  "models": {
    "providers": {
      "openai": {
        "agentRuntime": {
          "id": "codex"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.5"
    }
  }
}
إذا أردت خلفية CLI لنموذج قانوني واحد، فضع بيئة التشغيل على إدخال ذلك النموذج: 
{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-7",
      "models": {
        "anthropic/claude-opus-4-7": {
          "agentRuntime": {
            "id": "claude-cli"
          }
        }
      }
    }
  }
}
تستخدم التجاوزات لكل وكيل الشكل نفسه ذي نطاق النموذج: 
{
  "agents": {
    "list": [
      {
        "id": "codex-only",
        "model": "openai/gpt-5.5",
        "models": {
          "openai/gpt-5.5": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    ]
  }
}
تُتجاهل أمثلة بيئة التشغيل القديمة على مستوى الوكيل كله مثل هذا: 
{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}
مع بيئة تشغيل Plugin صريحة، تفشل الجلسة مبكراً عندما لا يكون المشغّل المطلوب مسجلاً، أو لا يدعم الموفّر/النموذج المحسومين، أو يفشل قبل إنتاج آثار جانبية للدورة. هذا مقصود لعمليات نشر Codex-only وللاختبارات الحية التي يجب أن تثبت أن مسار خادم تطبيق Codex مستخدم فعلاً. يتحكم هذا الإعداد فقط في مشغّل الوكيل المضمّن. ولا يعطل توجيه النماذج الخاص بالموفّرين للصور أو الفيديو أو الموسيقى أو TTS أو PDF أو غير ذلك.

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

قد يحتفظ المشغّل بمعرّف جلسة أصلي، أو معرّف خيط، أو رمز استئناف من جهة العفريت. أبقِ ذلك الربط مقترناً صراحة بجلسة OpenClaw، واستمر في عكس مخرجات المساعد/الأداة المرئية للمستخدم إلى سجل OpenClaw. يبقى سجل OpenClaw طبقة التوافق لـ:
  • تاريخ الجلسة المرئي في القناة
  • البحث في السجل وفهرسته
  • الرجوع إلى مشغّل PI المضمّن في دورة لاحقة
  • سلوك /new و/reset وحذف الجلسات العام
إذا كان مشغّلك يخزن ربطاً جانبياً، فنفّذ reset(...) حتى يتمكن OpenClaw من مسحه عندما تُعاد تهيئة جلسة OpenClaw المالكة.

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

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

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

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

​
ذو صلة