vLLM

يقدّم vLLM النماذج مفتوحة المصدر (وبعض النماذج المخصصة) عبر واجهة HTTP API متوافقة مع OpenAI. يتصل OpenClaw باستخدام API ‏openai-completions، ويمكنه اكتشاف النماذج تلقائيًا عند الاشتراك في ذلك باستخدام VLLM_API_KEY.

الخاصية	القيمة
معرّف المزوّد	`vllm`
API	`openai-completions` (متوافقة مع OpenAI)
المصادقة	متغير البيئة `VLLM_API_KEY`
عنوان URL الأساسي الافتراضي	`http://127.0.0.1:8000/v1`
استخدام البث	مدعوم (`stream_options.include_usage`)

بدء الاستخدام

بدء vLLM بخادم متوافق مع OpenAI

يجب أن يوفّر عنوان URL الأساسي نقاط نهاية /v1 (/v1/models و/v1/chat/completions). يعمل vLLM عادةً على:

http://127.0.0.1:8000/v1

تعيين متغير البيئة لمفتاح API

تصلح أي قيمة غير فارغة إذا كان خادمك لا يفرض المصادقة:

export VLLM_API_KEY="vllm-local"

اختيار نموذج

استبدله بأحد معرّفات نماذج vLLM لديك:

{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}

التحقق من توفر النموذج

openclaw models list --provider vllm

للإعداد غير التفاعلي (في CI أو البرمجة النصية)، مرّر عنوان URL الأساسي والمفتاح والنموذج مباشرةً:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice vllm \
  --custom-base-url "http://127.0.0.1:8000/v1" \
  --custom-api-key "vllm-local" \
  --custom-model-id "your-model-id"

اكتشاف النماذج (المزوّد الضمني)

عند تعيين VLLM_API_KEY (أو وجود ملف تعريف للمصادقة) وعدم تعريف models.providers.vllm، يستعلم OpenClaw من GET http://127.0.0.1:8000/v1/models ويحوّل المعرّفات المُعادة إلى إدخالات نماذج.

إذا عيّنت models.providers.vllm صراحةً، فسيستخدم OpenClaw النماذج التي صرّحت بها فقط. أضف "vllm/*": {} إلى agents.defaults.models لكي يستعلم OpenClaw أيضًا من نقطة النهاية /models لذلك المزوّد المُعدّ، ويضمّن جميع نماذج vLLM المُعلن عنها.

الإعداد الصريح

استخدم الإعداد الصريح عندما يعمل vLLM على مضيف أو منفذ مختلف، أو عندما تريد تثبيت قيمتَي contextWindow وmaxTokens، أو عندما يتطلب خادمك مفتاح API حقيقيًا، أو عندما تتصل بنقطة نهاية موثوقة عبر local loopback أو الشبكة المحلية أو Tailscale:

{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300, // Optional: extend request timeout for slow local models
        models: [
          {
            id: "your-model-id",
            name: "Local vLLM Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

لإبقاء المزوّد ديناميكيًا من دون إدراج كل نموذج، أضف حرف بدل إلى كتالوج النماذج المرئي:

{
  agents: {
    defaults: {
      models: {
        "vllm/*": {},
      },
    },
  },
}

الإعداد المتقدم

السلوك الشبيه بالوكيل

يُعامل vLLM بوصفه واجهة خلفية /v1 شبيهة بالوكيل ومتوافقة مع OpenAI، وليس نقطة نهاية أصلية لـ OpenAI:

السلوك	هل يُطبّق؟
تشكيل طلبات OpenAI الأصلية	لا
`service_tier`	لا يُرسل
`store` في الاستجابات	لا يُرسل
تلميحات ذاكرة التخزين المؤقت للموجّهات	لا تُرسل
تشكيل حمولة توافق الاستدلال مع OpenAI	لا يُطبّق
ترويسات الإسناد المخفية لـ OpenClaw	لا تُدرج في عناوين URL الأساسية المخصصة

عناصر التحكم في التفكير لنماذج Qwen

بالنسبة إلى نماذج Qwen، عيّن compat.thinkingFormat: "qwen-chat-template" في صف النموذج عندما يتوقع الخادم معاملات قالب محادثة Qwen. تعرض هذه النماذج ملف تعريف ثنائيًا لـ /think (off وon)، لأن التفكير في قالب محادثة Qwen عبارة عن علامة تشغيل/إيقاف، وليس سلّمًا لمستويات الجهد على نمط OpenAI.

{
  models: {
    providers: {
      vllm: {
        models: [
          {
            id: "Qwen/Qwen3-8B",
            name: "Qwen3 8B",
            reasoning: true,
            compat: { thinkingFormat: "qwen-chat-template" },
          },
        ],
      },
    },
  },
}

يربط OpenClaw الأمر /think off بما يلي:

{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "preserve_thinking": true
  }
}

ترسل مستويات التفكير غير off القيمة enable_thinking: true. إذا كانت نقطة النهاية لديك تتوقع بدلًا من ذلك علامات في المستوى الأعلى على نمط DashScope، فاستخدم compat.thinkingFormat: "qwen" لإرسال enable_thinking في جذر الطلب.

عناصر التحكم في التفكير لنماذج Nemotron 3

بالنسبة إلى نماذج vllm/nemotron-3-* مع إيقاف التفكير، يرسل Plugin المضمّن ما يلي:

{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "force_nonempty_content": true
  }
}

لتخصيص هذه القيم، عيّن chat_template_kwargs ضمن معاملات النموذج. إذا عيّنت أيضًا params.extra_body.chat_template_kwargs، فستكون لتلك القيمة الأولوية لأن extra_body هو آخر تجاوز لنص الطلب.

{
  agents: {
    defaults: {
      models: {
        "vllm/nemotron-3-super": {
          params: {
            chat_template_kwargs: {
              enable_thinking: false,
              force_nonempty_content: true,
            },
          },
        },
      },
    },
  },
}

ظهور استدعاءات أدوات Qwen كنص

تأكد أولًا من بدء vLLM باستخدام محلّل استدعاءات الأدوات وقالب المحادثة الصحيحين للنموذج. توثّق vLLM استخدام hermes لنماذج Qwen2.5 وqwen3_xml لنماذج Qwen3-Coder.الأعراض: لا تعمل Skills أو الأدوات مطلقًا، أو يطبع المساعد JSON/XML خامًا مثل {"name":"read","arguments":...}، أو يعيد vLLM مصفوفة tool_calls فارغة عندما يرسل OpenClaw ‏tool_choice: "auto".لا تعيد بعض تركيبات Qwen وvLLM استدعاءات أدوات منظّمة إلا عندما يستخدم الطلب tool_choice: "required". افرض ذلك لكل نموذج باستخدام params.extra_body:

{
  agents: {
    defaults: {
      models: {
        "vllm/Qwen-Qwen2.5-Coder-32B-Instruct": {
          params: {
            extra_body: {
              tool_choice: "required",
            },
          },
        },
      },
    },
  },
}

استبدل معرّف النموذج بالمعرّف الدقيق الناتج من openclaw models list --provider vllm، أو طبّق التجاوز نفسه من CLI:

openclaw config set agents.defaults.models '{"vllm/Qwen-Qwen2.5-Coder-32B-Instruct":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge

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

عنوان URL أساسي مخصص

إذا كان خادم vLLM يعمل على مضيف أو منفذ غير افتراضي، فعيّن baseUrl في إعداد المزوّد الصريح:

{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:9000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-custom-model",
            name: "Remote vLLM Model",
            reasoning: false,
            input: ["text"],
            contextWindow: 64000,
            maxTokens: 4096,
          },
        ],
      },
    },
  },
}

استكشاف الأخطاء وإصلاحها

بطء الاستجابة الأولى أو انتهاء مهلة الخادم البعيد

بالنسبة إلى النماذج المحلية الكبيرة، أو مضيفي الشبكة المحلية البعيدين، أو اتصالات شبكة tailnet، عيّن مهلة طلب على مستوى المزوّد:

{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [{ id: "your-model-id", name: "Local vLLM Model" }],
      },
    },
  },
}

ينطبق timeoutSeconds على طلبات HTTP الخاصة بنماذج vLLM فقط: إعداد الاتصال، وترويسات الاستجابة، وبث النص، والإلغاء الكلي لعملية الجلب المحمية. كما يرفع الحد الأقصى لمراقب خمول LLM أو البث فوق القيمة الافتراضية الضمنية البالغة نحو 120 ثانية لهذا المزوّد. يُفضّل هذا على زيادة agents.defaults.timeoutSeconds، التي تتحكم في تشغيل الوكيل بأكمله.

تعذر الوصول إلى الخادم

تحقق من أن خادم vLLM قيد التشغيل ويمكن الوصول إليه:

curl http://127.0.0.1:8000/v1/models

إذا ظهر خطأ في الاتصال، فتحقق من المضيف والمنفذ ومن بدء vLLM في وضع الخادم المتوافق مع OpenAI. يثق OpenClaw في الأصل المحدد بدقة في models.providers.vllm.baseUrl لطلبات النماذج المحمية عبر نقاط نهاية local loopback والشبكة المحلية وTailscale. تظل أصول بيانات التعريف أو الأصول المحلية للرابط محظورة دون اشتراك صريح. عيّن models.providers.vllm.request.allowPrivateNetwork: true فقط عندما يجب أن تصل طلبات vLLM إلى أصل خاص آخر، أو false لإلغاء الثقة في الأصل المطابق تمامًا.

أخطاء المصادقة في الطلبات

إذا فشلت الطلبات بسبب أخطاء في المصادقة، فعيّن قيمة حقيقية لـ VLLM_API_KEY تطابق إعداد خادمك، أو أعدّ المزوّد صراحةً ضمن models.providers.vllm.

إذا كان خادم vLLM لا يفرض المصادقة، فستصلح أي قيمة غير فارغة لـ VLLM_API_KEY بوصفها إشارة اشتراك صريح لـ OpenClaw.

لم يُكتشف أي نموذج

يتطلب الاكتشاف التلقائي تعيين VLLM_API_KEY. إذا عرّفت models.providers.vllm، فسيستخدم OpenClaw النماذج التي صرّحت بها فقط، ما لم يتضمن agents.defaults.models القيمة "vllm/*": {}.

عرض الأدوات كنص خام

إذا طبع نموذج Qwen صيغة أدوات JSON/XML بدلًا من تنفيذ إحدى Skills:

ابدأ vLLM باستخدام المحلّل والقالب الصحيحين لذلك النموذج.
تأكد من معرّف النموذج الدقيق باستخدام openclaw models list --provider vllm.
أضف تجاوزًا مخصصًا لكل نموذج بالقيمة params.extra_body.tool_choice: "required" فقط إذا ظل tool_choice: "auto" يعيد استدعاءات أدوات فارغة أو نصية فقط.

لمزيد من المساعدة: استكشاف الأخطاء وإصلاحها والأسئلة الشائعة.

ذو صلة

اختيار النموذج

اختيار المزوّدين ومراجع النماذج وسلوك تجاوز الفشل.

OpenAI

مزوّد OpenAI الأصلي وسلوك المسارات المتوافقة مع OpenAI.

OAuth والمصادقة

تفاصيل المصادقة وقواعد إعادة استخدام بيانات الاعتماد.

استكشاف الأخطاء وإصلاحها

المشكلات الشائعة وكيفية حلها.

Overview

Concepts and configuration

Providers

بدء الاستخدام

اكتشاف النماذج (المزوّد الضمني)

الإعداد الصريح

الإعداد المتقدم

استكشاف الأخطاء وإصلاحها

ذو صلة

اختيار النموذج

OpenAI

OAuth والمصادقة

استكشاف الأخطاء وإصلاحها

​بدء الاستخدام

​اكتشاف النماذج (المزوّد الضمني)

​الإعداد الصريح

​الإعداد المتقدم

​استكشاف الأخطاء وإصلاحها

​ذو صلة

اختيار النموذج

OpenAI

OAuth والمصادقة

استكشاف الأخطاء وإصلاحها

بدء الاستخدام

اكتشاف النماذج (المزوّد الضمني)

الإعداد الصريح

الإعداد المتقدم

استكشاف الأخطاء وإصلاحها

ذو صلة