واجهة OpenResponses API في OpenClaw

واجهة OpenResponses هي باب HTTP الثاني إلى gateway في OpenClaw. تتشارك مع نقطة النهاية chat completions المنفذ نفسه، وقواعد المصادقة نفسها، وعقد النموذج نفسه الذي يضع الوكيل أولًا، لكنها تأخذ إدخالًا قائمًا على العناصر، وتعيد استدعاءات الدوال كعناصر إخراج، وتقبل الملفات. وإليك ما تقول الوثائق إنها تفعله، مع الحدود المطبقة.

تفعيلها والثقة بها

• يفعّل إعداد نقطة النهاية responses مسار responses على منفذ gateway، ومعه قائمة النماذج، والبحث عن نموذج واحد، والتضمينات (embeddings)؛ أما chat completions فتفعَّل بشكل منفصل، وكل طلب يعمل كتشغيل عادي لوكيل gateway، فيتطابق التوجيه والأذونات والإعدادات مع gateway.
• تتبع المصادقة وضع gateway: رمز bearer أو كلمة مرور في أوضاع السر المشترك، وترويسات خادم وسيط مدرك للهوية في trusted-proxy (تحتاج خوادم وسيطة loopback على المضيف نفسه إلى خيار loopback الصريح، مع رجوع مباشر إلى كلمة المرور حين لا توجد ترويسة forwarded)، ومن دون ترويسة في none على مدخل خاص؛ ونقطة النهاية تمنح وصول مشغّل كاملًا، وتتجاهل أوضاع السر المشترك ترويسة نطاق معلنة أضيق وتستعيد مجموعة نطاقات المشغّل الافتراضية، بينما تحترم الأوضاع الحاملة للهوية الترويسة عند وجودها.
• يختار الوكيل بضبط model على openclaw، أو openclaw/default، أو ⁨openclaw/⁩ متبوعًا بمعرّف الوكيل، أو عبر ترويسة agent-id؛ وتتجاوز ترويسة model نموذج الواجهة الخلفية (بصلاحية admin في المسارات الحاملة للهوية)، وتوجّه ترويسة session-key بشكل صريح وترفض بالرمز 400 في مساحات الأسماء المحجوزة subagent وcron وacp، وتضبط ترويسة message-channel قناة دخول اصطناعية.
• نقطة النهاية عديمة الحالة لكل طلب افتراضيًا؛ ويشتق نص user مفتاح جلسة ثابتًا، ويعيد previous_response_id استخدام جلسة الاستجابة السابقة حين يبقى الطلب ضمن نطاق الوكيل والمستخدم والجلسة المطلوبة نفسه، وتتم المطابقة بموضوع المصادقة ومعرّف الوكيل وترويسة session-key؛ ومواصلة جلسة incognito صراحةً تتطلب صلاحية admin فعلية، وإلا فتعيد 403 forbidden يخفي الهدف.

يفك محتوى الملف ويضاف إلى موجّه النظام، لا إلى رسالة المستخدم، فيبقى عابرًا (لا يحفظ في سجل الجلسة).

العناصر، والأدوات، والملفات

حقل input نص أو مصفوفة عناصر. تحمل عناصر الرسائل الأدوار system وdeveloper وuser وassistant: يلحق system وdeveloper بموجّه النظام، ويصبح أحدث عنصر user أو function_call_output الرسالة الحالية، والأدوار السابقة سجل. وتدمج التعليمات في موجّه النظام؛ والأدوات أدوات دوال من جهة العميل، ويقبل اختيار الأداة auto أو none أو required أو دالة مسماة، وسقف رموز الإخراج يطبَّق بأفضل جهد، وtemperature وtop_p تطبَّقان بأفضل جهد وتتجاهلهما الواجهة الخلفية Codex Responses المبنية على ChatGPT، أما سقف استدعاءات الأدوات وreasoning وmetadata وstore وtruncation فتقبل لكنها تتجاهل. وحين يستدعي الوكيل أداة، تعيد الاستجابة عنصر إخراج function_call، ويواصل العميل الدور بعنصر function_call_output يحمل معرّف الاستدعاء؛ والإخراج الفارغ يكمل الاستدعاء مع ذلك. والعملاء الذين يحتفظون بسجلهم الخاص يلحقون إخراج الاستجابة بالإدخال التالي من دون تغيير، أو يرسلون previous_response_id مع العناصر الجديدة فقط. واختيار الأداة required أو المثبت على أداة بعينها الذي لا ينتج استدعاءً مطابقًا يعيد 502 api_error، أو حدث استجابة failed عند البث.

الملفات، والصور، والحدود

• تقبل عناصر الصور مصادر base64 أو URL، مع السماح افتراضيًا بصيغ JPEG وPNG وGIF وWebP وHEIC وHEIF، و10 MB لكل صورة، وتحوَّل HEIC وHEIF إلى JPEG؛ وتقبل عناصر الملفات base64 أو URL، مع السماح افتراضيًا بالنص العادي وmarkdown وHTML وCSV وJSON وPDF، بحد 5 MB و60k حرف، ويفك النص بترميزه المكتشف، وتحلَّل ملفات PDF لاستخراج النص أولًا، ثم تحوَّل صفحاتها الأولى إلى صور نقطية حين يعثر على نص قليل (افتراضيًا 4 صفحات، و4 ملايين بكسل، وحد أدنى 200 حرف).
• يغلَّف نص الملف المفكوك كمحتوى خارجي غير موثوق بعلامات حدود صريحة وسطر مصدر قبل أن يدخل الموجّه، فتكون بايتات الملف بيانات لا تعليمات؛ وجلب عناوين URL مفعّل افتراضيًا للملفات والصور بحد 8 أجزاء URL لكل طلب، وتحميه عمليات حل DNS، وحظر العناوين الخاصة، وحدود إعادة التوجيه، والمهل الزمنية، وقوائم سماح اختيارية لأسماء المضيفين لكل نوع تقبل مضيفين محددين بدقة أو نطاقات فرعية بحرف بدل، وتطبق قبل الجلب وعند كل قفزة إعادة توجيه.
• الحد الأقصى لجسم الطلب 20 MB؛ ومع تفعيل البث تكون الأحداث محددة الأنواع (created، وin progress، وoutput item added، وcontent part added، وoutput text delta وdone، وoutput item done، وcompleted، وincomplete عند الاقتطاع بسبب ميزانية الإخراج، وfailed عند الخطأ) وتنتهي بالقيمة DONE؛ والرد الذي تقطعه ميزانية رموز الإخراج يعيد الحالة incomplete مع السبب max output tokens، ويملأ حقل usage حين يبلغ المزوّد عن الأعداد، والأخطاء هي 400، و401، و403 للنطاق المفقود، و405، و429 مع ترويسة إعادة المحاولة بعد عدد كبير من محاولات المصادقة الفاشلة.

واجهة HTTP API المتوافقة مع OpenAI في OpenClaw هي نقطة النهاية الشقيقة التي تعيد هذه النقطة استخدام عقد نموذجها، ولمجموعة النطاقات التي تستعيدها كلتاهما أو تضيّقها راجع نطاقات المشغّل في OpenClaw.

متى تلجأ إليها

يناسب نموذج العناصر العملاء الذين يحتفظون أصلًا بسجل محادثاتهم ويريدون إعادة تشغيله حرفيًا، أو الذين يحتاجون إلى تسليم ملفات وصور إلى وكيل من دون حفظها في الجلسة. أما نقطة النهاية chat completions فتناسب الأدوات التي لا تعرف إلا الشكل الأقدم. وكلتاهما تشغّلان التشغيل نفسه للوكيل في الأساس، فالاختيار يتعلق بالعميل لا بالوكيل. لواجهة gateway API الأوسع راجع واجهة OpenClaw API، ولما يفعله الوكيل نفسه بعناوين URL حين يصله طلب راجع جلب الويب في OpenClaw.

على Diali

على Diali يقع gateway خلف مدخل المنصة (ingress)، مع إعدادات وقت تشغيل تولَّد من لوحة التحكم وتستبدل مع كل إصدار، لذا فتفعيل أي من واجهتي HTTP قرار في الإعدادات لا منفذ يحتاج إلى فتح. للتعرف على المساعد المستضاف راجع OpenClaw المستضاف على Diali، وللخطط التي يأتي ضمنها راجع أسعار Diali.

• عناصر تدخل، واستدعاءات دوال تخرج، ونتائج تعود بوصفها function_call_output.
• الملفات تستقر في موجّه النظام كمحتوى غير موثوق.
• كما في chat completions: المنفذ نفسه، والمصادقة نفسها، وثقة مستوى المالك نفسها.