واجهة برمجة تطبيقات OpenResponses

يمكن لـ Gateway توفير نقطة نهاية POST /v1/responses متوافقة مع OpenResponses. وهي معطّلة افتراضيًا وتشارك منفذها مع Gateway (تعدد إرسال WS + HTTP): http://<gateway-host>:<port>/v1/responses.

تُنفّذ الطلبات كتشغيل وكيل عادي في Gateway (مسار الشفرة نفسه المستخدم في openclaw agent)، لذا تتطابق التوجيهات والأذونات والإعدادات مع Gateway لديك.

يمكن التمكين أو التعطيل باستخدام gateway.http.endpoints.responses.enabled. عند التمكين، توفر واجهة التوافق نفسها أيضًا GET /v1/models وGET /v1/models/{id} وPOST /v1/embeddings وPOST /v1/chat/completions.

المصادقة والأمان والتوجيه

يتطابق السلوك التشغيلي مع إكمالات محادثة OpenAI:

• يتطابق مسار المصادقة مع gateway.auth.mode: يستخدم السر المشترك (token/password) ترويسة Authorization: Bearer <token-or-password>؛ ويستخدم الوكيل الموثوق ترويسات وكيل مدركة للهوية (تتطلب وكلاء الاسترجاع المحلي على المضيف نفسه gateway.auth.trustedProxy.allowLoopback = true، مع رجوع مباشر على المضيف نفسه عبر gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD عند عدم وجود ترويسة Forwarded/X-Forwarded-*/X-Real-IP)؛ ولا يحتاج none عند الدخول الخاص إلى ترويسة مصادقة. راجع مصادقة الوكيل الموثوق.
• تعامل مع نقطة النهاية باعتبارها وصولًا كاملًا للمشغّل إلى مثيل Gateway.
• تتجاهل أوضاع مصادقة السر المشترك نطاقات x-openclaw-scopes الأضيق المعلنة عبر رمز الحامل، وتستعيد مجموعة نطاقات المشغّل الافتراضية الكاملة: operator.admin وoperator.approvals وoperator.pairing وoperator.read وoperator.talk.secrets وoperator.write. تُعامل أدوار المحادثة في نقطة النهاية هذه كأدوار مرسلة من المالك.
• تحترم أوضاع HTTP الموثوقة الحاملة للهوية (الوكيل الموثوق، أو gateway.auth.mode="none") نطاقات x-openclaw-scopes عند وجودها، وإلا فترجع إلى مجموعة نطاقات المشغّل الافتراضية. لا تُفقد دلالات المالك إلا عندما يضيّق المستدعي النطاقات صراحةً ويحذف operator.admin.
• حدّد الوكلاء باستخدام model: "openclaw" أو "openclaw/default" أو "openclaw/<agentId>" أو ترويسة x-openclaw-agent-id.
• استخدم x-openclaw-model لتجاوز نموذج الواجهة الخلفية للوكيل المحدد (يتطلب operator.admin في مسارات المصادقة الحاملة للهوية).
• استخدم x-openclaw-session-key للتوجيه الصريح للجلسة (يُرفض مع 400 invalid_request_error إذا استخدم نطاقًا محجوزًا: subagent: أو cron: أو acp:).
• استخدم x-openclaw-message-channel لسياق قناة دخول اصطناعية غير افتراضية.

للاطلاع على الشرح المرجعي لنماذج استهداف الوكلاء وopenclaw/default والتمرير المباشر للتضمينات وتجاوزات نموذج الواجهة الخلفية، راجع إكمالات محادثة OpenAI.

راجع نطاقات المشغّل والأمان.

سلوك الجلسة

تكون نقطة النهاية افتراضيًا عديمة الحالة لكل طلب (يُنشأ مفتاح جلسة جديد مع كل استدعاء).

إذا تضمّن الطلب سلسلة OpenResponses باسم user، يشتق Gateway منها مفتاح جلسة ثابتًا بحيث يمكن للاستدعاءات المتكررة مشاركة جلسة وكيل.

يعيد previous_response_id استخدام جلسة الاستجابة السابقة عندما يظل الطلب ضمن نطاق الوكيل/المستخدم/الجلسة المطلوبة نفسه (تجري المطابقة حسب موضوع المصادقة ومعرّف الوكيل وx-openclaw-session-key).

بنية الطلب

العناصر (الإدخال)

message

الأدوار: system وdeveloper وuser وassistant.

• يُلحق system وdeveloper بمطالبة النظام.
• يصبح أحدث عنصر user أو function_call_output هو «الرسالة الحالية».
• تُضمّن رسائل المستخدم/المساعد السابقة كسجل للسياق.

function_call_output (أدوات قائمة على الأدوار)

أرسل نتائج الأدوات إلى النموذج:

{  "type": "function_call_output",  "call_id": "call_123",  "output": "{\"temperature\": \"72F\"}"}

reasoning وitem_reference

مقبولان للتوافق مع المخطط، لكنهما يُتجاهلان عند إنشاء المطالبة.

الأدوات (أدوات دوال من جانب العميل)

وفّر الأدوات باستخدام tools: [{ type: "function", name, description?, parameters? }].

إذا استدعى الوكيل أداة، تُرجع الاستجابة عنصر إخراج function_call. أرسل طلب متابعة يتضمن function_call_output لمتابعة الدور.

بالنسبة إلى tool_choice: "required" وtool_choice المثبّت على دالة، تضيق نقطة النهاية مجموعة أدوات دوال العميل المكشوفة، وتوجّه وقت التشغيل إلى استدعاء أداة عميل قبل الاستجابة، وترفض الدور إذا لم يتضمن استدعاءً منظمًا مطابقًا لأداة عميل، بما يتطابق مع عقد /v1/chat/completions. تعيد الطلبات غير المتدفقة 502 مع api_error؛ وتصدر الطلبات المتدفقة حدث response.failed.

الصور (input_image)

يدعم مصادر base64 أو URL:

{  "type": "input_image",  "source": { "type": "url", "url": "https://example.com/image.png" }}

أنواع MIME المسموح بها (افتراضيًا): image/jpeg وimage/png وimage/gif وimage/webp وimage/heic وimage/heif. الحجم الأقصى (افتراضيًا): 10MB.

الملفات (input_file)

يدعم مصادر base64 أو URL:

{  "type": "input_file",  "source": {    "type": "base64",    "media_type": "text/plain",    "data": "SGVsbG8gV29ybGQh",    "filename": "hello.txt"  }}

أنواع MIME المسموح بها (افتراضيًا): text/plain وtext/markdown وtext/html وtext/csv وapplication/json وapplication/pdf. الحجم الأقصى (افتراضيًا): 5MB.

السلوك الحالي:

• يُفك ترميز محتوى الملف ويُضاف إلى مطالبة النظام، لا إلى رسالة المستخدم، ليظل مؤقتًا (ولا يُحفظ في سجل الجلسة).
• يُغلّف نص الملف المفكوك باعتباره محتوى خارجيًا غير موثوق قبل إضافته، بحيث تُعامل بايتات الملف كبيانات لا كتعليمات موثوقة. تستخدم الكتلة المُدخلة علامات حدود صريحة (<<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>>) وسطر بيانات وصفية Source: External. وتحذف عمدًا لافتة SECURITY NOTICE: الطويلة للحفاظ على ميزانية المطالبة؛ وتظل علامات الحدود والبيانات الوصفية مطبقة.
• تُحلل ملفات PDF لاستخراج النص أولًا. إذا عُثر على نص قليل، تُحوّل الصفحات الأولى إلى صور نقطية وتُمرر إلى النموذج، وتستخدم كتلة الملف المُدخلة العنصر النائب [PDF content rendered to images].

يوفّر Plugin المضمّن document-extract تحليل PDF، ويستخدم clawpdf وبيئة تشغيل PDFium WebAssembly المضمّنة معه لاستخراج النص وعرض الصفحات.

إعدادات جلب URL الافتراضية:

• files.allowUrl: true
• images.allowUrl: true
• maxUrlParts: 8 (إجمالي أجزاء input_file وinput_image المستندة إلى URL لكل طلب)
• تخضع الطلبات للحماية (تحليل DNS، وحظر عناوين IP الخاصة، وحدود إعادة التوجيه، والمهلات الزمنية).
• تُدعم اختياريًا قوائم السماح لأسماء المضيفين لكل نوع إدخال (files.urlAllowlist وimages.urlAllowlist): مضيف مطابق تمامًا ("cdn.example.com") أو نطاقات فرعية بأحرف بدل ("*.assets.example.com"، لا تطابق النطاق الجذر). تعني قوائم السماح الفارغة أو المحذوفة عدم وجود قيد لقائمة السماح بأسماء المضيفين.
• لتعطيل عمليات الجلب المستندة إلى URL بالكامل، عيّن files.allowUrl: false و/أو images.allowUrl: false.

حدود الملفات والصور (الإعدادات)

يمكن ضبط القيم الافتراضية ضمن gateway.http.endpoints.responses:

{  gateway: {    http: {      endpoints: {        responses: {          enabled: true,          maxBodyBytes: 20000000,          maxUrlParts: 8,          files: {            allowUrl: true,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "text/plain",              "text/markdown",              "text/html",              "text/csv",              "application/json",              "application/pdf",            ],            maxBytes: 5242880,            maxChars: 60000,            maxRedirects: 3,            timeoutMs: 10000,            pdf: {              maxPages: 4,              maxPixels: 4000000,              minTextChars: 200,            },          },          images: {            allowUrl: true,            urlAllowlist: ["images.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

القيم الافتراضية عند الحذف:

تُطبّع مصادر input_image بتنسيق HEIC/HEIF إلى JPEG قبل تسليمها إلى المزوّد عبر معالج الصور المشترك في OpenClaw ‏(Rastermill)، الذي يرجع إلى محوّل نظام (sips أو ImageMagick أو GraphicsMagick أو ffmpeg) للتنسيقات التي تحتاج إلى دعم برنامج ترميز خارجي.

ملاحظة أمنية: تُفرض قوائم السماح لعناوين URL قبل الجلب وعند قفزات إعادة التوجيه. لا يؤدي إدراج اسم مضيف في قائمة السماح إلى تجاوز حظر عناوين IP الخاصة/الداخلية. بالنسبة إلى بوابات Gateway المكشوفة للإنترنت، طبّق ضوابط خروج الشبكة بالإضافة إلى وسائل الحماية على مستوى التطبيق. راجع الأمان.

البث (SSE)

عيّن stream: true لتلقي الأحداث المرسلة من الخادم:

• Content-Type: text/event-stream
• كل سطر حدث هو event: <type> وdata: <json>
• ينتهي التدفق بـ data: [DONE]

أنواع الأحداث المُرسلة حاليًا: response.created، وresponse.in_progress، وresponse.output_item.added، وresponse.content_part.added، وresponse.output_text.delta، وresponse.output_text.done، وresponse.content_part.done، وresponse.output_item.done، وresponse.completed، وresponse.failed (عند حدوث خطأ).

الاستخدام

تُملأ usage عندما يبلّغ المزوّد الأساسي عن أعداد الرموز. يطبّع OpenClaw الأسماء البديلة الشائعة بأسلوب OpenAI قبل وصول هذه العدّادات إلى واجهات الحالة/الجلسة اللاحقة، بما في ذلك input_tokens / output_tokens وprompt_tokens / completion_tokens.

الأخطاء

تستخدم الأخطاء كائن JSON مثل:

{ "error": { "message": "...", "type": "invalid_request_error" } }

الحالات الشائعة: 400 نص طلب غير صالح، و401 مصادقة مفقودة/غير صالحة، و403 نطاق المشغّل مفقود، و405 أسلوب غير صحيح، و429 محاولات مصادقة فاشلة كثيرة جدًا (مع Retry-After).

أمثلة

من دون تدفق:

curl -sS http://127.0.0.1:18789/v1/responses \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-agent-id: main' \  -d '{    "model": "openclaw",    "input": "hi"  }'

مع التدفق:

curl -N http://127.0.0.1:18789/v1/responses \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-agent-id: main' \  -d '{    "model": "openclaw",    "stream": true,    "input": "hi"  }'

ذات صلة

• إكمالات محادثة OpenAI
• نطاقات المشغّل
• OpenAI