​

OpenAI Chat Completions (HTTP)

• 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"): مرّر الطلب عبر proxy واعٍ بالهوية ومكوّن، ودعه يحقن ترويسات الهوية المطلوبة
• مصادقة مفتوحة على ingress خاص (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 من مصدر trusted proxy غير loopback ومكوّن؛ ولا تفي proxies المحلية على المضيف نفسه بهذا الوضع.
• إذا كان gateway.auth.rateLimit مكوّنًا وحدث عدد كبير جدًا من إخفاقات المصادقة، فستعيد نقطة النهاية 429 مع Retry-After.

​

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

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

• 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 الموثوقة الحاملة للهوية (مثل trusted proxy auth أو gateway.auth.mode="none" على ingress خاص)
  • تصادق هوية موثوقة خارجية أو حد نشر موثوق
  • تحترم x-openclaw-scopes عند وجود الترويسة
  • تعود إلى مجموعة نطاقات المشغل الافتراضية العادية عند غياب الترويسة
  • لا تفقد دلالات المالك إلا عندما يضيّق المستدعي النطاقات صراحةً ويحذف operator.admin

​

عقد النموذج القائم على الوكيل

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

• x-openclaw-model: <provider/model-or-bare-id> يتجاوز النموذج الخلفي للوكيل المحدد.
• لا يزال x-openclaw-agent-id: <agentId> مدعومًا كتجاوز للتوافق.
• x-openclaw-session-key: <sessionKey> يتحكم بالكامل في توجيه الجلسة.
• 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]

​

إعداد سريع لـ 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

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",
    "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، وليس إلى الحقل model في OpenAI.
• يدعم /v1/embeddings القيمة input كسلسلة أو كمصفوفة سلاسل.