إكمالات الدردشة من OpenAI

• POST /v1/chat/completions
• المنفذ نفسه مثل Gateway (تعدد إرسال WS + HTTP): http://<gateway-host>:<port>/v1/chat/completions

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/responses

​

المصادقة

• مصادقة السر المشترك (gateway.auth.mode="token" أو "password"): Authorization: Bearer <token-or-password>
• مصادقة HTTP الموثوقة الحاملة للهوية (gateway.auth.mode="trusted-proxy"): وجّه عبر الوكيل المهيأ والواعي بالهوية ودعه يحقن ترويسات الهوية المطلوبة
• مصادقة مفتوحة لدخول خاص (gateway.auth.mode="none"): لا يلزم وجود ترويسة مصادقة

• عند استخدام gateway.auth.mode="token"، استخدم gateway.auth.token (أو OPENCLAW_GATEWAY_TOKEN).
• عند استخدام gateway.auth.mode="password"، استخدم gateway.auth.password (أو OPENCLAW_GATEWAY_PASSWORD).
• عند استخدام gateway.auth.mode="trusted-proxy"، يجب أن يأتي طلب HTTP من مصدر وكيل موثوق مهيأ؛ وتتطلب وكلاء local loopback على المضيف نفسه ضبطًا صريحًا: gateway.auth.trustedProxy.allowLoopback = true.
• يمكن للمتصلين الداخليين على المضيف نفسه الذين يتجاوزون الوكيل استخدام gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD كخيار رجوع محلي مباشر. أي دليل في ترويسة Forwarded أو X-Forwarded-* أو X-Real-IP يُبقي الطلب على مسار الوكيل الموثوق بدلًا من ذلك.
• إذا كانت gateway.auth.rateLimit مهيأة وحدث عدد كبير جدًا من إخفاقات المصادقة، فترجع نقطة النهاية 429 مع Retry-After.

​

حد الأمان (مهم)

• مصادقة HTTP bearer هنا ليست نموذج نطاق ضيق لكل مستخدم.
• يجب التعامل مع رمز/كلمة مرور Gateway صالحة لنقطة النهاية هذه كاعتماد مالك/مشغّل.
• تمر الطلبات عبر مسار وكيل مستوى التحكم نفسه مثل إجراءات المشغّل الموثوق.
• لا يوجد حد أدوات منفصل لغير المالك/لكل مستخدم على نقطة النهاية هذه؛ بمجرد أن يجتاز المتصل مصادقة Gateway هنا، يعامل OpenClaw ذلك المتصل كمشغّل موثوق لهذا Gateway.
• في أوضاع مصادقة السر المشترك (token و password)، تستعيد نقطة النهاية الإعدادات الافتراضية الكاملة العادية للمشغّل حتى لو أرسل المتصل ترويسة x-openclaw-scopes أضيق.
• تحترم أوضاع HTTP الحاملة لهوية موثوقة (مثل مصادقة الوكيل الموثوق أو gateway.auth.mode="none") ترويسة x-openclaw-scopes عند وجودها، وإلا فتعود إلى مجموعة النطاقات الافتراضية العادية للمشغّل.
• إذا كانت سياسة الوكيل الهدف تسمح بأدوات حساسة، يمكن لنقطة النهاية هذه استخدامها.
• أبقِ نقطة النهاية هذه على loopback/tailnet/دخول خاص فقط؛ لا تعرضها مباشرة للإنترنت العام.

• gateway.auth.mode="token" أو "password" + Authorization: Bearer ...
  • يثبت امتلاك سر مشغّل 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
  • تتطلب operator.admin لعناصر تحكم الطلب على مستوى المالك مثل x-openclaw-model

​

متى تستخدم نقطة النهاية هذه

• فضّل هذا بدلًا من إضافة قناة مدمجة جديدة عندما يكون التكامل مجرد سطح مشغّل/عميل آخر لـ Gateway نفسه.
• بالنسبة لعملاء الهواتف المحمولة الأصليين الذين يتصلون مباشرة بـ Gateway بعيد، فضّل WebChat أو بروتوكول Gateway، ونفّذ تدفق تمهيد الجهاز المقترن/رمز الجهاز حتى لا يحتاج الجهاز إلى رمز/كلمة مرور HTTP مشتركة.
• ابنِ Plugin قناة بدلًا من ذلك عندما تدمج شبكة مراسلة خارجية لها مستخدموها أو غرفها أو تسليم Webhook أو نقل صادر خاص بها. راجع بناء Plugins.

​

عقد نموذج يضع الوكيل أولًا

• يوجّه model: "openclaw" إلى الوكيل الافتراضي المهيأ.
• يوجّه model: "openclaw/default" أيضًا إلى الوكيل الافتراضي المهيأ.
• يوجّه model: "openclaw/<agentId>" إلى وكيل محدد.

• يتجاوز x-openclaw-model: <provider/model-or-bare-id> نموذج الخلفية للوكيل المحدد. يمكن لمتصلي bearer بالسر المشترك استخدام هذه الترويسة. يحتاج المتصلون الحاملون للهوية، مثل طلبات الوكيل الموثوق أو الدخول الخاص بلا مصادقة مع x-openclaw-scopes، إلى operator.admin؛ ويتلقى المتصلون ذوو إذن الكتابة فقط 403 missing scope: operator.admin.
• يبقى x-openclaw-agent-id: <agentId> مدعومًا كتجاوز توافق.
• يتحكم x-openclaw-session-key: <sessionKey> صراحة في توجيه الجلسة. يجب ألا تستخدم القيمة مساحات أسماء جلسات داخلية محجوزة مثل subagent: أو cron: أو acp:؛ تُرفض تلك الطلبات مع 400 invalid_request_error.
• يضبط x-openclaw-message-channel: <channel> سياق قناة الدخول الاصطناعية للمطالبات والسياسات الواعية بالقناة.

• model: "openclaw:<agentId>"
• model: "agent:<agentId>"

​

تفعيل نقطة النهاية

{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: true },
      },
    },
  },
}

​

تعطيل نقطة النهاية

{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: false },
      },
    },
  },
}

​

سلوك الجلسة

​

لماذا هذا السطح مهم

• تتوقع معظم إعدادات Open WebUI وLobeChat وLibreChat وجود /v1/models.
• تتوقع كثير من أنظمة RAG وجود /v1/embeddings.
• يستطيع عملاء دردشة OpenAI الحاليون عادة البدء بـ /v1/chat/completions.
• يفضّل العملاء الأكثر قربًا من الوكلاء بشكل متزايد /v1/responses.

​

قائمة النماذج وتوجيه الوكيل

​

البث (SSE)

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

​

عقد أدوات الدردشة

​

حقول الطلب المدعومة

• tools: مصفوفة من { "type": "function", "function": { ... } }
• tool_choice: "auto" أو "none" أو "required" أو { "type": "function", "function": { "name": "..." } }
• أدوار متابعة messages[*].role: "tool"
• messages[*].tool_call_id لربط نتائج الأدوات باستدعاء أداة سابق
• max_completion_tokens: رقم؛ حد لكل استدعاء لإجمالي رموز الإكمال (بما في ذلك رموز الاستدلال). اسم حقل OpenAI Chat Completions الحالي؛ وهو المفضل عند إرسال كل من max_completion_tokens وmax_tokens.
• max_tokens: رقم؛ اسم مستعار قديم مقبول للتوافق مع الإصدارات السابقة. يتم تجاهله عند وجود max_completion_tokens أيضًا.
• temperature: رقم؛ درجة حرارة أخذ عينات بأفضل جهد تُمرر إلى المزود العلوي عبر قناة معاملات بث الوكيل.
• top_p: رقم؛ أخذ عينات نووية بأفضل جهد يُمرر إلى المزود العلوي عبر قناة معاملات بث الوكيل.
• frequency_penalty: رقم؛ عقوبة تكرار بأفضل جهد تُمرر إلى المزود العلوي عبر قناة معاملات بث الوكيل. النطاق المتحقق منه: -2.0 إلى 2.0. ترجع 400 invalid_request_error للقيم خارج النطاق.
• presence_penalty: رقم؛ عقوبة حضور بأفضل جهد تُمرر إلى المزود العلوي عبر قناة معاملات بث الوكيل. النطاق المتحقق منه: -2.0 إلى 2.0. ترجع 400 invalid_request_error للقيم خارج النطاق.
• seed: رقم (عدد صحيح)؛ بذرة بأفضل جهد تُمرر إلى المزود العلوي عبر قناة معاملات بث الوكيل. ترجع 400 invalid_request_error للقيم غير الصحيحة.
• stop: سلسلة أو مصفوفة تصل إلى 4 سلاسل؛ تسلسلات إيقاف بأفضل جهد تُمرر إلى المزود العلوي عبر قناة معاملات بث الوكيل. ترجع 400 invalid_request_error لأكثر من 4 تسلسلات أو لإدخالات غير نصية/فارغة.

​

المتغيرات غير المدعومة

• tools غير المصفوفية
• إدخالات أدوات ليست دوال
• غياب tool.function.name
• متغيرات tool_choice مثل allowed_tools وcustom
• قيم tool_choice.function.name التي لا تطابق tools المقدمة

​

شكل استجابة الأدوات غير المتدفقة

• إدخالات choices[0].finish_reason = "tool_calls"
• choices[0].message.tool_calls[] مع:
  • id
  • type: "function"
  • function.name
  • function.arguments (سلسلة JSON)

​

شكل استجابة الأدوات المتدفقة

• دلتا أولية لدور المساعد
• دلتا اختيارية لتعليقات المساعد
• جزء واحد أو أكثر من delta.tool_calls يحمل هوية الأداة وأجزاء الوسائط
• جزء نهائي مع finish_reason: "tool_calls"
• data: [DONE]

​

حلقة متابعة الأدوات

• رسالة استدعاء الأداة السابقة من المساعد
• رسالة واحدة أو أكثر بدور role: "tool" مع tool_call_id مطابق

​

إعداد Open WebUI سريع

• عنوان URL الأساسي: http://127.0.0.1:18789/v1
• عنوان URL الأساسي لـ Docker على macOS: http://host.docker.internal:18789/v1
• مفتاح API: رمز bearer الخاص بـ Gateway لديك
• النموذج: openclaw/default

• يجب أن يسرد GET /v1/models القيمة openclaw/default
• يجب أن يستخدم Open WebUI القيمة openclaw/default كمعرّف نموذج الدردشة
• إذا أردت مزوّدًا/نموذجًا خلفيًا محددًا لذلك الوكيل، فاضبط النموذج الافتراضي العادي للوكيل أو أرسل x-openclaw-model من مستدعٍ ذي سر مشترك أو مستدعٍ يحمل هوية مع operator.admin

curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

​

أمثلة

curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openclaw/default",
    "user": "conv:YOUR_CONVERSATION_ID",
    "messages": [{"role":"user","content":"Summarize my tasks for today"}]
  }'

curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openclaw/default",
    "messages": [{"role":"user","content":"hi"}]
  }'

curl -N http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-model: openai/gpt-5.4' \
  -d '{
    "model": "openclaw/research",
    "stream": true,
    "messages": [{"role":"user","content":"hi"}]
  }'

curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -sS http://127.0.0.1:18789/v1/embeddings \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-model: openai/text-embedding-3-small' \
  -d '{
    "model": "openclaw/default",
    "input": ["alpha", "beta"]
  }'

• يعيد /v1/models أهداف وكلاء OpenClaw، وليس كتالوجات المزوّد الخام.
• يكون openclaw/default حاضرًا دائمًا بحيث يعمل معرّف ثابت واحد عبر البيئات.
• تنتمي تجاوزات المزوّد/النموذج الخلفية إلى x-openclaw-model، وليس إلى حقل OpenAI model. في مسارات مصادقة HTTP الحاملة للهوية، يتطلب هذا الرأس operator.admin.
• يدعم /v1/embeddings قيمة input كسلسلة أو مصفوفة سلاسل.

​

ذو صلة

• مرجع التهيئة
• OpenAI