النماذج المحلية

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

الحد الأدنى للعتاد

​

اختر خلفية تشغيل

​

الموصى به: LM Studio + نموذج محلي كبير (Responses API)

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "lmstudio/my-local-model": { alias: "Local" },
      },
    },
  },
  models: {
    mode: "merge",
    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,
          },
        ],
      },
    },
  },
}

• ثبّت LM Studio: https://lmstudio.ai
• في LM Studio، نزّل أكبر بناء نموذج متاح (تجنب المتغيرات “الصغيرة”/المكمّمة بشدة)، وابدأ الخادم، وتأكد من أن http://127.0.0.1:1234/v1/models يعرضه.
• استبدل my-local-model بمعرّف النموذج الفعلي الظاهر في LM Studio.
• أبقِ النموذج محمّلًا؛ فالتحميل البارد يضيف زمن بدء.
• عدّل contextWindow/maxTokens إذا كان بناء LM Studio لديك مختلفًا.
• بالنسبة إلى WhatsApp، التزم بـ Responses API حتى يُرسل النص النهائي فقط.

​

تهيئة هجينة: أساسي مستضاف، ورجوع محلي

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["lmstudio/my-local-model", "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",
    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,
          },
        ],
      },
    },
  },
}

​

محلي أولًا مع شبكة أمان مستضافة

​

الاستضافة الإقليمية / توجيه البيانات

• توجد أيضًا متغيرات MiniMax/Kimi/GLM المستضافة على OpenRouter مع نقاط نهاية مثبّتة إقليميًا (مثلًا، مستضافة في الولايات المتحدة). اختر المتغير الإقليمي هناك لإبقاء حركة البيانات ضمن الولاية القضائية التي تختارها مع الاستمرار في استخدام models.mode: "merge" لمسارات الرجوع إلى Anthropic/OpenAI.
• يبقى المسار المحلي فقط هو أقوى مسار للخصوصية؛ أما التوجيه الإقليمي المستضاف فهو حل وسط عندما تحتاج ميزات المزوّد مع رغبتك في التحكم بتدفق البيانات.

​

وكلاء محليون آخرون متوافقون مع OpenAI

{
  agents: {
    defaults: {
      model: { primary: "local/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "sk-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 120000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

• models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
• agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"

• يتعامل OpenClaw معها كمسارات OpenAI-compatible بنمط الوكيل، لا كنقاط نهاية OpenAI أصلية
• لا ينطبق تشكيل الطلبات الخاص بـ OpenAI الأصلي هنا: لا service_tier، ولا Responses store، ولا تشكيل حمولة توافق الاستدلال في OpenAI، ولا تلميحات تخزين مؤقت للمطالبات
• لا تُحقن ترويسات إسناد OpenClaw المخفية (originator، وversion، وUser-Agent) في عناوين URL المخصصة هذه للوكيل

• تقبل بعض الخوادم فقط messages[].content كنص في Chat Completions، وليس مصفوفات أجزاء محتوى منظمة. اضبط models.providers.<provider>.models[].compat.requiresStringContent: true لهذه النقاط النهائية.
• تصدر بعض النماذج المحلية طلبات أدوات مستقلة بين أقواس كنص، مثل [tool_name] متبوعة بـ JSON و[END_TOOL_REQUEST]. يرقّي OpenClaw هذه إلى استدعاءات أدوات حقيقية فقط عندما يطابق الاسم بالضبط أداة مسجلة للدور؛ وإلا تُعامل الكتلة كنص غير مدعوم وتُخفى من الردود المرئية للمستخدم.
• إذا أصدر نموذج JSON أو XML أو نصًا بأسلوب ReAct يبدو كاستدعاء أداة لكن المزوّد لم يصدر استدعاءً منظمًا، يتركه OpenClaw كنص ويسجل تحذيرًا يتضمن معرّف التشغيل، والمزوّد/النموذج، والنمط المكتشف، واسم الأداة عند توفره. تعامل مع ذلك كعدم توافق استدعاء أدوات في المزوّد/النموذج، وليس كتسلسل أداة مكتمل.
• إذا ظهرت الأدوات كنص من المساعد بدلًا من التشغيل، مثل JSON خام، أو XML، أو صياغة ReAct، أو مصفوفة tool_calls فارغة في استجابة المزوّد، فتحقق أولًا من أن الخادم يستخدم قالب/محلل دردشة قادرًا على استدعاء الأدوات. بالنسبة إلى خلفيات Chat Completions المتوافقة مع OpenAI التي يعمل محللها فقط عندما يكون استخدام الأدوات مفروضًا، اضبط تجاوز طلب لكل نموذج بدلًا من الاعتماد على تحليل النص:
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  استخدم هذا فقط للنماذج/الجلسات التي يجب أن يستدعي فيها كل دور عادي أداة. إنه يتجاوز قيمة الوكيل الافتراضية في OpenClaw لـ tool_choice: "auto". استبدل local/my-local-model بمرجع المزوّد/النموذج الدقيق الذي يعرضه openclaw models list.
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• إذا كان نموذج OpenAI-compatible مخصص يقبل جهود استدلال OpenAI تتجاوز ملف التعريف المضمن، فأعلن عنها في كتلة توافق النموذج. إضافة "xhigh" هنا تجعل /think xhigh، ومحددات الجلسات، والتحقق في Gateway، والتحقق في llm-task تعرض المستوى لمرجع المزوّد/النموذج المهيأ ذلك:
  {
    models: {
      providers: {
        local: {
          baseUrl: "http://127.0.0.1:8000/v1",
          apiKey: "sk-local",
          api: "openai-responses",
          models: [
            {
              id: "gpt-5.4",
              name: "GPT 5.4 via local proxy",
              reasoning: true,
              input: ["text"],
              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
              contextWindow: 196608,
              maxTokens: 8192,
              compat: {
                supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
                reasoningEffortMap: { xhigh: "xhigh" },
              },
            },
          ],
        },
      },
    },
  }
  

​

خلفيات تشغيل أصغر أو أكثر صرامة

1. تأكد من أن النموذج المحلي نفسه يستجيب. بلا أدوات، وبلا سياق وكيل:
   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
   
2. تأكد من توجيه Gateway. يرسل الموجّه المقدّم فقط — ويتخطى النص، وتمهيد AGENTS، وتجميع محرك السياق، والأدوات، وخوادم MCP المضمّنة، لكنه لا يزال يختبر توجيه Gateway، والمصادقة، واختيار المزوّد:
   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
   
3. جرّب الوضع الخفيف. إذا نجح الفحصان لكن دورات الوكيل الحقيقية تفشل بسبب استدعاءات أدوات مشوّهة أو موجّهات مفرطة الحجم، ففعّل agents.defaults.experimental.localModelLean: true. يحذف أثقل ثلاث أدوات افتراضية (browser, cron, message) بحيث يصبح شكل الموجّه أصغر وأقل هشاشة. راجع الميزات التجريبية → وضع النموذج المحلي الخفيف للاطلاع على الشرح الكامل، ومتى تستخدمه، وكيف تؤكد أنه مفعّل.
4. عطّل الأدوات بالكامل كحل أخير. إذا لم يكن الوضع الخفيف كافياً، فاضبط models.providers.<provider>.models[].compat.supportsTools: false لإدخال ذلك النموذج. عندها سيعمل الوكيل دون استدعاءات أدوات على ذلك النموذج.
5. بعد ذلك، يكون عنق الزجاجة في المنبع. إذا استمرت الواجهة الخلفية في الفشل فقط في تشغيلات OpenClaw الأكبر بعد الوضع الخفيف و supportsTools: false، فغالباً ما تكون المشكلة المتبقية في النموذج أو سعة الخادم في المنبع — نافذة السياق، أو ذاكرة GPU، أو إخلاء kv-cache، أو خلل في الواجهة الخلفية. عند تلك النقطة، لا تكون المشكلة في طبقة النقل الخاصة بـ OpenClaw.

​

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

• هل يستطيع Gateway الوصول إلى الوكيل؟ curl http://127.0.0.1:1234/v1/models.
• هل نموذج LM Studio غير محمّل؟ أعد تحميله؛ فالبدء البارد سبب شائع لحالة “التعليق”.
• هل يقول الخادم المحلي terminated أو ECONNRESET أو يغلق الدفق في منتصف الدور؟ يسجل OpenClaw قيمة منخفضة التنوع model.call.error.failureKind بالإضافة إلى لقطة RSS/heap لعملية OpenClaw في التشخيصات. بالنسبة إلى ضغط الذاكرة في LM Studio/Ollama، طابق ذلك الطابع الزمني مع سجل الخادم أو سجل تعطل macOS / سجل jetsam لتأكيد ما إذا كان خادم النموذج قد أُنهي.
• يشتق OpenClaw حدود فحص نافذة السياق المسبق من نافذة النموذج المكتشفة، أو من نافذة النموذج غير المحدودة عندما يخفض agents.defaults.contextTokens النافذة الفعالة. يحذّر عند أقل من 20% مع حد أدنى 8k. تستخدم عمليات الحظر الصارمة عتبة 10% مع حد أدنى 4k، وتُقيّد بنافذة السياق الفعالة بحيث لا يمكن لبيانات تعريف نموذج مفرطة الحجم رفض سقف مستخدم صالح بخلاف ذلك. إذا واجهت ذلك الفحص المسبق، فارفع حد سياق الخادم/النموذج أو اختر نموذجاً أكبر.
• أخطاء السياق؟ خفّض contextWindow أو ارفع حد الخادم لديك.
• هل يعيد خادم متوافق مع OpenAI رسالة messages[].content ... expected a string؟ أضف compat.requiresStringContent: true على إدخال ذلك النموذج.
• هل يعيد خادم متوافق مع OpenAI رسالة validation.keys أو يقول إن إدخالات الرسائل لا تسمح إلا بـ role و content؟ أضف compat.strictMessageKeys: true على إدخال ذلك النموذج.
• هل تعمل استدعاءات /v1/chat/completions الصغيرة المباشرة، لكن يفشل openclaw infer model run --local على Gemma أو نموذج محلي آخر؟ افحص عنوان URL للمزوّد، ومرجع النموذج، وعلامة المصادقة، وسجلات الخادم أولاً؛ فـ model run المحلي لا يتضمن أدوات الوكيل. إذا نجح model run المحلي لكن فشلت دورات الوكيل الأكبر، فقلّل نطاق أدوات الوكيل باستخدام localModelLean أو compat.supportsTools: false.
• هل تظهر استدعاءات الأدوات كنص JSON/XML/ReAct خام، أو يعيد المزوّد مصفوفة tool_calls فارغة؟ لا تضف وكيلاً يحوّل نص المساعد عشوائياً إلى تنفيذ أدوات. أصلح قالب/محلّل دردشة الخادم أولاً. إذا كان النموذج لا يعمل إلا عند فرض استخدام الأدوات، فأضف تجاوز params.extra_body.tool_choice: "required" لكل نموذج أعلاه، واستخدم إدخال ذلك النموذج فقط للجلسات التي يُتوقع فيها استدعاء أداة في كل دور.
• السلامة: النماذج المحلية تتجاوز مرشحات جانب المزوّد؛ أبقِ الوكلاء محدودين والتكثيف مفعّلاً للحد من نطاق تأثير حقن الموجّهات.

​

ذو صلة

• مرجع التكوين
• تجاوز فشل النموذج