النماذج المحلية: Ollama وvLLM وds4
حتى الدرس السابق، كان OpenClaw متصلًا بالكامل بواجهات API السحابية. في هذا الدرس نغيّر الطريقة: OpenClaw النماذج المحلية — الاستدلال يعمل على عتادك الخاص، دون رسوم API ودون مغادرة بايت واحد من بيانات المحادثات. في البنية الرسمية، النماذج وagent harness (Claude وCodex والنماذج المحلية) كلها إضافات قابلة للاستبدال، والواجهات الخلفية المحلية مواطن من الدرجة الأولى بشكل كامل: Ollama وvLLM وSGLang جميعها providers مدمجة، وLM Studio له عملية إرشاد مخصصة، وds4 (تشغيل DeepSeek V4 Flash محليًا على macOS Metal) يتصل بالإعداد فقط. تستغرق العملية بالكامل حوالي 10 دقيقة، وهذا الدرس مبني على الإصدار v2026.10.9.
ماذا ستستطيع أن تفعل بعد إتمام الدرس
- إدخال النماذج المحلية إلى OpenClaw باستخدام Ollama، مع عمل استدعاء الأدوات بشكل صحيح — بحيث يستطيع Claw إنجاز عمل حقيقي، لا مجرد الدردشة
- استضافة الأوزان مفتوحة المصدر ذاتيًا على خوادم GPU باستخدام vLLM / SGLang، مع OpenClaw اكتشاف دليل النماذج تلقائيًا
- تشغيل DeepSeek V4 Flash محليًا على macOS باستخدام ds4، مع ضبط مستويات thinking والإطلاق عند الحاجة
- التمييز بين سيناريوهات الواجهات الخلفية المحلية السبع وفق جدول الاختيار الرسمي، فلا تضيع حتى عند التثبيت الأول
- استخدام أوامر التشخيص المتدرجة للتمييز بين «النموذج يستطيع الرد» و«توجيه Gateway يعمل بشكل صحيح»، وضبط خطة مختلطة تفضّل المحلي مع السحابي كاحتياطي
🎒 الاستعدادات قبل البدء
- إتمام نظرة عامة على ربط النماذج: نظام provider وتبديل النماذج:
provider/modelقواعد الاستشهاد وخطوات «تثبيت الإضافة → ضبط بيانات الاعتماد → اختيار النموذج» الثلاث واضحة في ذهنك - OpenClaw مثبّت وGateway يعمل:
openclaw gateway statusيعطي مخرجات - امتلاك جهاز قادر على تشغيل النماذج — حتى أصغر وصفة استضافة رسمية لـ llama.cpp تتطلب 8 GiB من ذاكرة المضيف كحد أدنى (وصفة سياق 64K)، والاحتياج الفعلي يعتمد على أوزان النموذج والسياق ووقت التشغيل
- تثبيت واجهة خلفية واحدة على الأقل للاستدلال المحلي (Ollama / vLLM / SGLang / LM Studio / ds4 أيًا كانت)، أو اتبع الخطوات أدناه للتثبيت الآن
💡 لماذا تستخدم النماذج المحلية؟
ثلاثة أسباب قوية: مجاني — الاستدلال يحدث على CPU/GPU الخاص بك، دون فاتورة لكل token؛ دون اتصال — بعد تنزيل النموذج يعمل حتى مع انقطاع الإنترنت، مناسب للشبكات الداخلية والبيئات السرية؛ الخصوصية — المحادثات والذاكرة والملفات لا تغادر عتادك أبدًا. والثمن واضح أيضًا: الجودة والسرعة مقيدتان بالعتاد، والنماذج المحلية لا تحتوي على فلاتر الأمان من مزودي الاستضافة، لذا عليك تشديد صلاحيات الأدوات بنفسك (تفاصيل في الخطوة 1).
اتبع خطواتي
الخطوة 1: اختر الواجهة الخلفية — طابق نفسك مع جدول الاختيار الرسمي
لماذا: لكل واجهة خلفية محلية تخصصها، واختيار الواجهة الخاطئة يضاعف الجهد. يقدم دليل local-models الرسمي جدول اختيار، طابق نفسك معه أولًا:
| الواجهة الخلفية | متى تستخدمها | كيفية الاتصال |
|---|---|---|
| Ollama | تدفقات عمل CLI، مكتبة نماذج غنية، خدمة systemd بلا صيانة | provider مدمج (الخطوة 2) |
| vLLM / SGLang / MLX | استضافة ذاتية عالية الإنتاجية، نقطة HTTP متوافقة مع OpenAI | vLLM وSGLang providers مدمجة (الخطوة 3) |
| ds4 | تشغيل DeepSeek V4 Flash محليًا على macOS Metal، استدعاء أدوات متوافق مع OpenAI | بالإعداد فقط (الخطوة 4) |
| LM Studio | أول نشر محلي، محمّل بواجهة رسومية، Responses API أصلي | إرشاد onboarding (الخطوة 4) |
| llama.cpp (إضافة) | اختيار نموذج وفق العتاد، والتحقق من التنزيل، وOpenClaw إدارة server | بعد تثبيت إضافة llama.cpp openclaw onboard اختر Managed local server |
| llmman | سحب النماذج من مستودعات OCI + محركات llama.cpp/vLLM/MLX + توجيه هجين محلي/مُدار | مزوّد مستقل |
| LiteLLM / وسيط مخصص متوافق مع OpenAI | وضع طبقة أمامية تعترض واجهات API لنماذج أخرى | الدرس السابق تدفق custom |
ثلاث قواعد عامة ستُستخدم في كل خطوة لاحقة:
- المحوّل: عند كتابة
baseUrlفي مزوّد مخصص مع حذفapi، تكون القيمة الافتراضيةopenai-completions؛ ويمكن استخدامapi: "openai-responses"عندما تدعم الواجهة الخلفية Responses API (يدعمها LM Studio). أما Ollama فهي حالة خاصة — تستخدم المحوّل الأصلي (api: "ollama")، راجع تحذير /v1 في الخطوة 2. - حدّ العتاد: يعتمد متطلب الذاكرة على أوزان النموذج والسياق ووقت التشغيل والأحمال الأخرى على الجهاز؛ تستخدم وصفة llama.cpp الرسمية المُدارة سياق 64K، وحتى أصغرها يحتاج 8 GiB من ذاكرة المضيف كحد أدنى، ولا يُضمن أن يعمل، ولا يُضمن أن يكون سريعًا. اترك هامشًا كافيًا للـ prompt الكامل والأدوات (schema) والسجل والمخرجات الخاصة بـ OpenClaw.
- الأمان: النماذج المحلية لا توفر فلاتر الأمان الخاصة بمزوّدي الخدمات السحابية. يجب تشديد صلاحيات الأدوات ودفاعات حقن الـ prompt وفق قدرات النموذج — فكلما كان النموذج أضعف، زادت سهولة انحرافه بسبب تعليمات محقونة في صفحات الويب أو الملفات.
الخطوة 2: ربط Ollama (نقطة البداية الموصى بها للنماذج المحلية)
لماذا: Ollama هي أسهل طريق للنماذج المحلية — OpenClaw مزوّد مدمج، وسحب النماذج في Ollama يتم بأمر واحد، وبعد التثبيت تصبح خدمة خلفية لا تحتاج صيانة.
الطريقة A (موصى بها): عبر onboarding
ثبّت Ollama أولًا (ollama.com/download) واسحب نموذجًا:
ollama pull gemma4ثم شغّل المعالج:
openclaw onboardاختر Ollama، ثم اختر الوضع: Cloud + Local (نماذج محلية + نماذج سحابية :cloud عند تسجيل الدخول) أو Local only (محلي فقط).
المفترض أن ترى: يتحقق المعالج أولًا من مضيف Ollama الافتراضي أو المُعدّ؛ والاكتشاف التلقائي يتعرّف فقط على النماذج المحمّلة في الذاكرة (كما يُبلّغ عنها /api/ps)، ويتطلب دعم الأدوات + سياقًا لا يقل عن 16K (يتأكد /api/show). لا يُحفظ المسار المختار إلا بعد اجتياز completion حقيقي — ولا يقوم الاكتشاف أبدًا بسحب أو تحميل النماذج الخاملة. النماذج المثبّتة لكن غير المحمّلة لا تُكتشف تلقائيًا: في إصدار سطح المكتب، من خلال بطاقة Ollama في Model Setup انتقل إلى Choose connection → Local only، ويمكنك تجهيز نموذج خامل مثبّت لاجتياز فحص حيوي دون الحاجة إلى تحميله يدويًا أولًا. بعد الانتهاء، يستطيع openclaw models list --provider ollama سرد النماذج.
نسخة غير تفاعلية (يمكن حذف كلا المعاملين المخصصين):
openclaw onboard --non-interactive --accept-risk --skip-health \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b"احذف base URL لاستخدام المضيف المحلي الافتراضي؛ وعند حذف model ID، يُفضَّل اختيار نموذج مثبّت يدعم الأدوات وبسياق ≥16K (مع تفضيل النماذج غير الاستدلالية، ثم النماذج الصغيرة)، وإن لم يوجد ما يفي بالشروط فسيتم تجربة gemma4 الموصى به.
الطريقة B: إعداد يدوي
export OLLAMA_API_KEY="ollama-local" # 本地/LAN 主机任意值即可
openclaw models set ollama/gemma4أو اكتبه في ملف الإعدادات:
{
agents: {
defaults: {
model: { primary: "ollama/gemma4" },
},
},
}⚠️ لا تُضف /v1 إلى baseUrl الخاص بـ Ollama (عكس الواجهات الخلفية الأخرى)
يتعامل OpenClaw مع Ollama عبر /api/chat الأصلي، وليس عبر /v1 المتوافق مع OpenAI. يجب كتابة العنوان الأصلي baseUrl: "http://host:11434" — فإضافة /v1 ستؤدي إلى تعطيل استدعاءات الأدوات، إذ يُخرج النموذج JSON الخاص بـ tool-call كنص عادي. أما vLLM وSGLang وds4 وLM Studio فالعكس تمامًا، إذ يجب أن يتضمن baseUrl قيمة /v1.
قاعدة بيانات الاعتماد: عناوين Ollama من نوع loopback أو الشبكات الخاصة أو .local أو أسماء المضيفين المجردة لا تحتاج إلى رمز حقيقي، ويستخدمها OpenClaw مع علامة ollama-local؛ أما المضيفات البعيدة على الشبكة العامة وhttps://ollama.com فتتطلب OLLAMA_API_KEY حقيقيًا أو auth profile.
Ollama Cloud (اختياري): منظومة Ollama دون شغل العتاد المحلي
لا تريد تشغيل النماذج محليًا، لكنك تريد استخدام النماذج المُدارة في منظومة Ollama؟ المزوّد المستقل ollama-cloud يتصل مباشرة بـ https://ollama.com دون الحاجة إلى daemon محلي:
openclaw onboard --auth-choice ollama-cloudالنموذج الافتراضي في onboarding هو ollama-cloud/minimax-m2.7؛ ويشمل الدليل المُدار معرّفات مثل deepseek-v4-pro وglm-5.2 وkimi-k3 وminimax-m3 وgpt-oss:20b وغيرها. في الوضع الهجين، نفّذ ollama signin على المضيف المحلي، لتستخدم عبر مضيف Ollama نفسه النماذج المحلية والنماذج السحابية :cloud معًا (مثل minimax-m2.7:cloud وkimi-k3:cloud).
openclaw models list --provider ollamaيسرد نماذجك المحلية
الخطوة 3: ربط vLLM أو SGLang (استضافة ذاتية عالية الإنتاجية على GPU)
لماذا: لديك خادم GPU أو جهاز بذاكرة رسومية كبيرة وتريد استضافة ذاتية عالية الإنتاجية لأوزان مفتوحة المصدر (أوزان LongCat المفتوحة في الدرس السابق تنتمي إلى هذا النوع) — كلا vLLM وSGLang مزوّدان مدمجان، متوافقان مع OpenAI عبر /v1، ويدعمان الاكتشاف التلقائي للنماذج.
تشغيل vLLM في أربع خطوات. احفظ أولًا أربع خصائص: معرّف المزوّد vllm، وواجهة API openai-completions، والمصادقة VLLM_API_KEY، وbaseUrl الافتراضي http://127.0.0.1:8000/v1.
vllm serve <model-id> # 1. 起服务,模型 ID 换成你要托管的
export VLLM_API_KEY="vllm-local" # 2. 服务器不鉴权时任非空值,作为启用发现的 opt-in 信号// 3. 选模型
{
agents: {
defaults: {
model: { primary: "vllm/your-model-id" },
},
},
}openclaw models list --provider vllm # 4. 验证المفترض أن ترى: يسرد models list النماذج على vLLM — عند تعيين VLLM_API_KEY دون كتابة models.providers.vllm، يستعلم OpenClaw عبر GET http://127.0.0.1:8000/v1/models لإنشاء إدخالات النماذج تلقائيًا، كما يتعرف على نماذج الاستدلال من سلسلة DeepSeek V4 وNemotron 3 (بما فيها الأسماء المستعارة مثل yk_deepseek_v4). ملاحظة: بمجرد كتابة models.providers.vllm، لن يُعترف إلا بالنماذج التي كتبتها يدويًا — وللحفاظ على السلوك الديناميكي، أضف البدل "vllm/*": {} في agents.defaults.models.
أمر واحد غير تفاعلي (للنشر في CI / السكربتات):
openclaw onboard --non-interactive --accept-risk --skip-health \
--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 على جهاز/منفذ آخر، أو الحاجة إلى تثبيت معاملات السياق أو استخدام مفتاح حقيقي، اكتب إعدادًا صريحًا (مقتطف حرفي من المثال الرسمي):
{
models: {
providers: {
vllm: {
baseUrl: "http://127.0.0.1:8000/v1",
apiKey: "${VLLM_API_KEY}",
api: "openai-completions",
timeoutSeconds: 300, // 可选:给慢的本地模型延长请求超时
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,
},
],
},
},
},
}🔧 متقدم (اختياري): جدولة تفاعلية ذات أولوية
عندما يخدم vLLM واحد المحادثات التفاعلية ومهام الخلفية مثل cron / تنظيف الذاكرة معًا، فعّل أولًا جدولة الأولوية الأصلية على جانب الخادم:
vllm serve <model-id> --scheduling-policy priorityثم فعّل الخيار (opt-in) للنموذج المعني:
{
agents: {
defaults: {
models: {
"vllm/your-model-id": { params: { priorityScheduling: true } },
},
},
},
}تعيين الأولويات: الأدوار التفاعلية و/compact اليدوي تأخذ -100، والعمل المفوَّض أو غير المصنّف يأخذ 0، وcron / النبض / الذاكرة / إكمالات المساعدة البسيطة تأخذ 100 — تُجدول الأرقام الأصغر أولًا، وعند التنافس يُحسم التعادل بترتيب الوصول. هذا المفتاح متوقف افتراضيًا، ولا يسري إلا على النماذج vllm/* المحددة.
نفس الأسلوب مع SGLang (مدمج ومفعّل افتراضيًا، مع baseUrl الافتراضي http://127.0.0.1:30000/v1):
export SGLANG_API_KEY="sglang-local" # 服务器不鉴权时任非空值
openclaw onboard --auth-choice sglangالنموذج الافتراضي المؤقت في التهيئة هو sglang/Qwen/Qwen3-8B. عند تعيين SGLANG_API_KEY دون كتابة models.providers.sglang يتم الاكتشاف التلقائي بنفس الطريقة؛ لتثبيت المعاملات اكتب تكوينًا صريحًا، بشكل مطابق تمامًا لـ vLLM (استبدل vllm بـ sglang، وغيّر المنفذ إلى 30000).
💡 MLX أو أي خدمة محلية أخرى متوافقة مع OpenAI يمكن توصيلها أيضًا
أي خدمة محلية تكشف /v1/chat/completions بأسلوب OpenAI تقع ضمن النطاق: MLX (mlx_lm.server)، وLiteLLM، وOAI-proxy وغيرها. اتبع مسار custom من الدرس السابق، ومرّر --custom-provider-id مع معرّف محلي (مثل mlx). اكتب معرّف النموذج بالمفتاح الأصلي داخل المزوّد (مثل mlx-community/Qwen3-30B-A3B-6bit)، وعند الاستشهاد أضف البادئة: mlx/mlx-community/Qwen3-30B-A3B-6bit.
openclaw models list --provider vllm(أو--provider sglang) يعرض النماذج المستضافة
الخطوة 4: توصيل ds4 أو LM Studio (DeepSeek على macOS وواجهة رسومية للمبتدئين)
لماذا: خلفيتان مميزتان تغطيان نوعين آخرين من الاحتياجات — ds4 يمنح مستخدمي Mac طريقًا لتشغيل DeepSeek V4 Flash محليًا؛ وLM Studio يمنح من لا يريدون لمس سطر الأوامر واجهة رسومية.
ds4: DeepSeek V4 Flash محليًا على macOS Metal
لنوضح أولًا ما هو ds4: مشروع محلي من antirez (github.com/antirez/ds4)، يشغّل DeepSeek V4 Flash GGUF على خلفية macOS Metal ويكشف /v1 متوافقًا مع OpenAI. ليس خدمة سحابية ولا منتجًا رسميًا من DeepSeek؛ وعلى جانب OpenClaw لا توجد إضافة، بل توصيل بالتكوين فقط.
شغّل الخدمة (استبدل <DS4_DIR> بمسار نسخة ds4 لديك):
<DS4_DIR>/ds4-server \
--model <DS4_DIR>/ds4flash.gguf \
--host 127.0.0.1 \
--port 18000 \
--ctx 32768 \
--tokens 128يجب أن ترى: استجابة curl http://127.0.0.1:18000/v1/models تتضمن deepseek-v4-flash.
ثم اكتب تكوين OpenClaw (مقتطف من قسم التكوين الرسمي الكامل):
{
agents: {
defaults: {
model: { primary: "ds4/deepseek-v4-flash" },
models: { "ds4/deepseek-v4-flash": { alias: "DS4 local" } },
},
},
models: {
mode: "merge",
providers: {
ds4: {
baseUrl: "http://127.0.0.1:18000/v1",
apiKey: "ds4-local",
api: "openai-completions",
timeoutSeconds: 300,
models: [
{
id: "deepseek-v4-flash",
name: "DeepSeek V4 Flash (ds4)",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 32768,
maxTokens: 128,
compat: {
supportsUsageInStreaming: true,
supportsReasoningEffort: true,
maxTokensField: "max_tokens",
supportsStrictMode: false,
thinkingFormat: "deepseek",
supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
},
},
],
},
},
},
}نقطتان أساسيتان:
- ابدأ بـ
--ctx 32768: أدوار الـ agent في OpenClaw تحمل مخططات الأدوات وسياق مساحة العمل، ويمكن لـ--ctx 4096اجتياز اختبار curl المباشر، لكن أدوار الـ agent المُحمّلة بالكامل ستُرجع500 prompt exceeds context. طابقcontextWindowمع--ctx، وطابقmaxTokensمع--tokens. - Think Max يحتاج سياقًا كبيرًا: يُنشَّط فقط عند
ds4-server --ctx 393216مع طلبreasoning_effort: "max"؛ وعندها تتغير بيانات النموذج الوصفية تزامنيًا إلىcontextWindow: 393216، وmaxTokens: 384000، ويُضافsupportedReasoningEffortsبقيمة"max".
🔧 التشغيل عند الحاجة: اجعل OpenClaw يرفع ds4 فقط عند استخدامه
لا تريد أن يبقى ds4 مقيمًا يستهلك الذاكرة؟ أضف localService في نفس مدخل المزوّد، وسيقوم OpenClaw بتشغيل الخدمة تلقائيًا عند اختيار نموذج ds4/... (المثال الرسمي كما هو):
{
models: {
providers: {
ds4: {
baseUrl: "http://127.0.0.1:18000/v1",
apiKey: "ds4-local",
api: "openai-completions",
timeoutSeconds: 300,
localService: {
command: "<DS4_DIR>/ds4-server",
args: [
"--model",
"<DS4_DIR>/ds4flash.gguf",
"--host",
"127.0.0.1",
"--port",
"18000",
"--ctx",
"32768",
"--tokens",
"128",
],
cwd: "<DS4_DIR>",
healthUrl: "http://127.0.0.1:18000/v1/models",
readyTimeoutMs: 300000,
idleStopMs: 0,
},
models: [
{
id: "deepseek-v4-flash",
name: "DeepSeek V4 Flash (ds4)",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 32768,
maxTokens: 128,
compat: {
supportsUsageInStreaming: true,
supportsReasoningEffort: true,
maxTokensField: "max_tokens",
supportsStrictMode: false,
thinkingFormat: "deepseek",
supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
},
},
],
},
},
},
}لا تخطئ في الحقول الثلاثة: يجب أن يكون command هوالمسار التنفيذي المطلق (لا بحث في shell ولا توسيع لـ ~)؛ أعطِ readyTimeoutMs: 300000 ما يكفي من 5 دقائق — ds4 يمر بمرحلة إقامة Metal الباردة وتسخين النموذج، والطلب الأول بطيء فعلًا؛ واستخدم healthUrl بـ /v1/models لفحص الحيوية.
LM Studio: مُحمِّل بواجهة رسومية، مع تهيئة تلقائية بالكامل
يشغّل LM Studio نماذج llama.cpp (GGUF) أو MLX عبر واجهة رسومية، ولديه أيضًا daemon بلا واجهة هو llmster. بعد التثبيت ثلاث خطوات:
lms server start --port 1234 # 1. 起本地服务(headless 版用 lms daemon up)
export LM_API_TOKEN="your-lm-studio-api-token" # 2. LM Studio 开了认证才需要,没开就留空
openclaw onboard # 3. 选 LM Studio,在 Default model 提示里挑模型يجب أن ترى: تستعلم التهيئة أولًا عن /api/v1/models لجهاز LM Studio، ولا يُوصى تلقائيًا إلا بالنماذج التي يُبلّغ عنها LM Studio بأنها «مدربة على الأدوات + بسياق فعال لا يقل عن 16K» (تُحسب النماذج المُحمَّلة بسياق النسخة المحمّلة، لا بالقيمة القصوى المُعلنة)؛ وبعد الاختيار يُجرى اختبار إكمال حقيقي قبل الحفظ، والفحص التلقائي لا ينزّل النماذج مكانك أبدًا.
مفاتيح نماذج LM Studio بصيغة author/model-name (مثل qwen/qwen3.5-9b)، وعند الاستشهاد في OpenClaw أضف بادئة المزوّد: lmstudio/qwen/qwen3.5-9b. للاستعلام عن المفتاح الدقيق، أو تغيير الافتراضي، أو التحديث بعد تثبيت نماذج جديدة:
curl http://localhost:1234/api/v1/models # 看返回里的 key 字段
openclaw models set lmstudio/qwen/qwen3.5-9b
openclaw models list --provider lmstudio --refresh # 装了新模型后刷新目录في وضع merge الافتراضي، يضيف --refresh النماذج المكتشفة حديثًا ويحتفظ بالبيانات الوصفية لمدخلاتك المكتوبة يدويًا (الاسم، وحد السياق، إلخ). النسخة غير التفاعلية: openclaw onboard --non-interactive --accept-risk --skip-health --auth-choice lmstudio؛ ولتقديم كل المعاملات صراحةً أضف --custom-base-url http://localhost:1234/v1 --lmstudio-api-key "$LM_API_TOKEN" --custom-model-id qwen/qwen3.5-9b.
openclaw models list --provider ds4(أو--provider lmstudio) يعرض نماذجك
الخطوة 5: التحقق من السلسلة وتكوين الحل الاحتياطي الهجين
لماذا: حفظ التكوين على القرص ≠ قدرة الـ agent على العمل. «النموذج يستجيب» و«التوجيه في Gateway سليم» و«الأدوات تُنفَّذ فعلًا» ثلاث طبقات، وقدّمت الوثائق الرسمية أوامر تشخيص متدرجة — أي طبقة انقطعت تعرف أين تُصلح.
# 第一层:模型本身能不能回话(不带工具、不带 agent 上下文)
openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
# 第二层:Gateway 路由通不通(只发 prompt,跳过 transcript、工具与内置 MCP,
# 但仍走完整的 Gateway 路由、auth 与 provider 选择)
openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --jsonالطبقة الثالثة: اختبار دخان للأدوات، بتشغيل دور agent كامل (بأخذ ds4 كمثال):
openclaw agent \
--local \
--session-id ds4-tool-smoke \
--model ds4/deepseek-v4-flash \
--thinking off \
--message "Use the shell command pwd once, then reply exactly: tool-ok <output>" \
--json \
--timeout 240يجب أن ترى: executionTrace.winnerProvider هو ds4، وexecutionTrace.winnerModel هو deepseek-v4-flash، وtoolSummary.calls لا يقل عن 1، والرد المرئي يبدأ بـ tool-ok — الأدوات نُفِّذت فعلًا، ولم يقرأ النموذج JSON عليك.
بعد نجاح كل شيء، اجعل النموذج الأنسب هو الافتراضي اليومي:
openclaw models set <provider/model>إذا أردتتوفير المال دون انقطاع الخدمة، فأضف طبقة حل احتياطي هجين — الطريقة الموصى بها في دليل local-models الرسمي: المحلي أولًا والسحابة كاحتياط، وعند خطأ المزوّد ينتقل بالدور إلى الاحتياطي التالي (المثال الرسمي مشتق من عكس ترتيب primary/fallbacks):
{
agents: {
defaults: {
model: {
primary: "lmstudio/my-local-model", // 本地优先
fallbacks: ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"],
},
models: {
"anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
"lmstudio/my-local-model": { alias: "Local" },
"anthropic/claude-opus-4-6": { alias: "Opus" },
},
},
},
models: {
mode: "merge", // merge 保住云端模型目录,随时 /model 切换
providers: {
lmstudio: {
baseUrl: "http://127.0.0.1:1234/v1",
apiKey: "lmstudio",
api: "openai-responses",
models: [
{
id: "my-local-model",
name: "Local Model",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 196608,
maxTokens: 8192,
},
],
},
},
},
}لسحابة أولًا ومحلي كاحتياط، اعكس primary/fallbacks، مع إبقاء كتلة providers وmodels.mode: "merge" كما هي. لاحظ أن الاحتياطي تبديل بالدور «عند الخطأ فقط»؛ ومن يريد توجيهًاحسب الطلب يُبقي الطلبات الصغيرة محليًا ولا يصعد للسحابة إلا للطلبات الضخمة، أشارت الوثائق الرسمية إلى Hybrid inference في llmman.
- اجتياز التحقق الثلاثي الطبقات: مستويان
pong+ اختبار دخان للأدواتtoolSummary.calls≥ 1
نقطة تفتيش ✅
- اخترت الخلفية الصحيحة وفق جدول الاختيار الرسمي: Ollama (CLI) / vLLM وSGLang (إنتاجية GPU عالية) / ds4 (DeepSeek على macOS) / LM Studio (واجهة رسومية)
openclaw models list --provider <id>يستطيع عرض نماذجك المحلية- baseUrl الخاص بـ Ollama هو
http://host:11434(دون /v1)؛ أما vLLM / SGLang / ds4 / LM Studio فكلها تحمل/v1 openclaw infer model run --localو--gatewayكلاهما يعيدpong- في اختبار دخان الـ agent كان
toolSummary.calls≥ 1 — استدعاءات الأدوات نُفِّذت فعلًا، ولم يكن نص JSON مُخرجًا - تريد توفير المال دون انقطاع الخدمة: كوّنت مخططًا هجينًا بـ
fallbacks، وحافظmodels.mode: "merge"على دليل النماذج السحابية
تنبيهات من المزالق الشائعة
❌ baseUrl الخاص بـ Ollama يحمل /v1——تعطّل استدعاء الأدوات بالكامل
يعمل Ollama عبر محوّل /api/chat الأصلي، لذا يجب أن يكون baseUrl هو http://host:11434 (بدون /v1). إضافة /v1 تجعله يعمل بوضع توافق OpenAI، فيتعطل استدعاء الأدوات ويُخرج النموذج JSON الخاص بـ tool-call كنص عادي. وهذا عكس vLLM / SGLang / ds4 / LM Studio تمامًا (كلها تتطلب /v1)——إن لم تحفظها فاحفظ عبارة «Ollama يمشي على خلاف الجميع».
❌ ds4 --ctx 4096: نجاح curl، لكن جولة agent ترجع 500
سبب 500 prompt exceeds context: جولة agent في OpenClaw تحمل أدوات schema وسياق workspace، وهي أكبر بكثير من رسالة اختبار curl واحدة. استخدم ds4-server --ctx بقيمة 32768 على الأقل، وطابق models.providers.ds4.models[].contextWindow. أما Think Max فيحتاج --ctx 393216 كحد أدنى.
❌ النموذج المحلي «يرد على الكلام»، لكن استدعاءات الأدوات تظهر كنص JSON/XML خام
ابدأ بالتشخيص المتدرج في الخطوة 5. إذا نجح مستويا infer model run كلاهما لكن الجولة الكاملة اختلت، فافحص بالترتيب:
- نماذج Ollama المحلية و LM Studio والخدمات المحلية المستضافة تفعّل تلقائيًا Tool Search المنظّم عند عدم ضبط
tools.toolSearch(يؤخر إرسال schema ويحفظ القدرات)——لا تعطّله. - على مستخدمي vLLM أولًا التأكد من تشغيلها مع tool-call parser و chat template الصحيحين (توثيق vLLM الرسمي: Qwen2.5 يستخدم
hermes، و Qwen3-Coder يستخدمqwen3_xml). - إن استمرت المشكلة، يمكن لمدخلات النماذج المخصصة إضافة
params.extra_body.tool_choice: "required"لفرض استدعاء الأدوات——فقط للنماذج التي «يجب أن تستدعي أدوات في كل جولة»، ولا تجعله افتراضيًا عامًا. - الملاذ الأخير: عطّل الأدوات لهذا النموذج عبر
compat.supportsTools: false؛ أو فعّل الوضع المقتصدagents.defaults.experimental.localModelLean: true(يزيل الأدوات ذات schema الكبيرة مثل browser و automations و message و image_generate و music_generate و video_generate و tts و pdf).
❌ انتهاء مهلة النماذج البطيئة / الباردة
بطء أول token في النماذج المحلية الكبيرة، والتحميل البارد في LM Studio، والإحماء البارد في ds4 كلها أمور شائعة. اضبط timeoutSeconds لمدخل provider (مثل 300)——فهو يغطي الاتصال وترويسات الاستجابة وجسم البث والإجهاض الكلي، ويتقدم على تعديل agents.defaults.timeoutSeconds العام. أما الإقلاع البارد لـ ds4 فاضبط له localService.readyTimeoutMs: 300000 إضافيًا.
❌ WSL2 + Ollama + NVIDIA/CUDA: إعادة تشغيل متكررة للجهاز الافتراضي
مثبّت Ollama الرسمي لنظام Linux يفعّل خدمة systemd بـ Restart=always. في بيئة WSL2 مع GPU، يجعل الإقلاع التلقائي إعادة تحميل آخر نموذج وتثبيت ذاكرة المضيف، فيسحب جهاز WSL2 الافتراضي إلى حلقة إعادة تشغيل متكررة (صفحة استكشاف الأخطاء الرسمية تدرجها كـ WSL2 crash loop). لا تدع Ollama يحمّل النماذج تلقائيًا عند الإقلاع داخل WSL2.
❌ خطأ في تقدير ميزانية السياق: اقتطاع المخرجات، ولم يتبقَّ سوى token واحد قرب الحد
يجري OpenClaw فحصًا مسبقًا وفق نافذة النموذج: تحذير عند انخفاض الهامش عن 20% (بحد أدنى 8k)، وحجب صارم تحت 10% (بحد أدنى 4k). نماذج Ollama المحلية المكتشفة تلقائيًا لها حد مخرجات افتراضي 8,192 token (OpenClaw يرسل حد المخرجات كـ num_predict إلى Ollama الأصلي)؛ لاستعادة الافتراضي غير المحدود في Ollama اضبط params: { num_predict: -1 }. وفي مدخلات النماذج المخصصة اكتب contextWindow/maxTokens بالقيم الحقيقية، ولا تعتمد على الافتراضي الاحتياطي 200000.
❌ بعد تشغيل Gateway كخادم خفي، يبدو أن المفاتيح المُصدَّرة بـ export «لا تعمل»
تكرار لمزلة قديمة: خدمات launchd / systemd لا ترى متغيرات البيئة الخاصة بالـ shell التفاعلي. اكتب OLLAMA_API_KEY و VLLM_API_KEY و SGLANG_API_KEY و LM_API_TOKEN في ~/.openclaw/.env، أو زوّد تلك العملية بها عبر env.shellEnv في الإعدادات.
❌ التعامل مع النموذج المحلي كـ«بديل سحابي مجاني»، والاستلقاء أمنيًا بلا حماية
النماذج المحلية لا تملك مرشحات الأمان الخاصة بمزودي الخدمات، وكلما ضعف النموذج زادت سهولة انجرافه خلف تعليمات الحقن في الصفحات أو الملفات. ضيّق صلاحيات الأدوات، وأبقِ compaction مفعّلًا، وفكّر في sandbox لجلسات الدردشة الجماعية——بنص دليل local-models الرسمي: keep tool permissions and prompt-injection defenses appropriate for the model and task. للاطلاع على أساليب التحصين راجع التحصين الأمني (1): التحكم في الوصول والهوية.
الخطوة التالية
بهذا نختم فصل البدء السريع بالكامل: التثبيت، وربط النماذج (الحزمة الصينية الكاملة + الوسيط + النماذج المحلية) كلها تعمل. التالي:
- الفصل التالي الاستخدام اليومي: تعامل بكفاءة مع Claw الخاص بك: واجهة Control UI، وأوامر الدردشة، ونظام الذاكرة——اجعل Claw يندمج فعلًا في يومك
- النموذج المحلي يعمل على جهاز آخر؟ نشر الخادم: تشغيل 7×24 على Docker/VPS لنقل Gateway وخدمة الاستدلال معًا إلى الخادم
- تريد أن يتذكر Claw المحلي إياك؟ نظام الذاكرة: اجعل Claw يتذكرك——ملفات Markdown خالصة + فهرس SQLite، وبياناتك تبقى في يدك أيضًا
دروس ذات صلة
- مزيد من النماذج الصينية ونقاط الوسيط المخصصة——الدرس السابق: النماذج بلا مكون إضافي رسمي تستخدم نقطة custom؛ و LongCat بأوزان مفتوحة المصدر يعمل محليًا فيقع في هذا الدرس
- نظرة عامة على ربط النماذج: منظومة provider وتبديل النماذج——قواعد مرجع
provider/modelوأوامر تبديل النماذج - نشر الخادم: تشغيل 7×24 على Docker/VPS——نشر Gateway وخدمة الاستدلال المحلية على الخادم
- التحصين الأمني (1): التحكم في الوصول والهوية——النموذج المحلي بلا مرشحات أمان من المزود، فالصلاحيات مسؤوليتك