Ollama

لا تحتاج عناوين URL الخاصة بـ Ollama التي تستخدم الاسترجاع المحلي أو الشبكات الخاصة أو .local أو اسم مضيف مجردًا إلى رمز حامل حقيقي. يستخدم OpenClaw العلامة ollama-local لهذه العناوين.

تتطلب المضيفات العامة البعيدة وhttps://ollama.com بيانات اعتماد حقيقية: OLLAMA_API_KEY أو ملف تعريف مصادقة أو apiKey الخاص بالمزوّد. للاستخدام المستضاف المباشر، يُفضّل مزوّد ollama-cloud.

يتبع المزوّد المخصص الذي يستخدم api: "ollama" القواعد نفسها. على سبيل المثال، يمكن لمزوّد ollama-remote الموجّه إلى مضيف خاص على الشبكة المحلية استخدام apiKey: "ollama-local"؛ وتحل الوكلاء الفرعية هذه العلامة عبر خطاف مزوّد Ollama بدلًا من اعتبارها بيانات اعتماد مفقودة. ويمكن أيضًا أن يشير agents.defaults.memorySearch.provider إلى معرّف مزوّد مخصص لكي تستخدم التضمينات نقطة نهاية Ollama تلك.

يخزّن auth-profiles.json بيانات اعتماد معرّف المزوّد؛ ضع إعدادات نقطة النهاية (baseUrl وapi والنماذج والرؤوس والمُهل الزمنية) في models.providers.<id>. الملفات المسطحة الأقدم، مثل { "ollama-windows": { "apiKey": "ollama-local" } }، ليست تنسيقًا لوقت التشغيل؛ ويعيد openclaw doctor --fix كتابتها إلى ملف تعريف أساسي لمفتاح API باسم ollama-windows:default مع إنشاء نسخة احتياطية. تُعد قيمة baseUrl في ذلك الملف القديم معلومات زائدة، وينبغي نقلها إلى إعدادات المزوّد.

تقتصر مصادقة الحامل لتضمينات ذاكرة Ollama على المضيف الذي أُعلنت له:

• لا يُرسل المفتاح على مستوى المزوّد إلا إلى مضيف ذلك المزوّد.
• لا يُرسل agents.*.memorySearch.remote.apiKey إلا إلى مضيف التضمين البعيد الخاص به.
• تُعامل قيمة بيئة OLLAMA_API_KEY المجرّدة باعتبارها اصطلاح سحابة Ollama، ولا تُرسل افتراضيًا إلى المضيفات المحلية أو ذاتية الاستضافة.

Ollama على الجهاز نفسه الذي يشغّل Gateway، ويُكتشف تلقائيًا:

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4

لا تضف كتلة models.providers.ollama إلا إذا كنت تحتاج إلى نماذج يدوية.

{  models: {    providers: {      ollama: {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 300,        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            reasoning: true,            input: ["text"],            params: {              num_ctx: 32768,              thinking: false,              keep_alive: "15m",            },          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/qwen3.5:9b" },    },  },}

contextWindow هي ميزانية السياق في OpenClaw؛ وتُرسل params.num_ctx إلى Ollama. حافظ على توافقهما عندما لا تستطيع الأجهزة تشغيل السياق المُعلن بالكامل للنموذج.

دون خدمة محلية، مع استخدام النماذج المستضافة مباشرةً:

export OLLAMA_API_KEY="your-ollama-api-key"

{  models: {    providers: {      ollama: {        baseUrl: "https://ollama.com",        apiKey: "OLLAMA_API_KEY",        api: "ollama",        models: [          {            id: "kimi-k2.5:cloud",            name: "kimi-k2.5:cloud",            reasoning: false,            input: ["text", "image"],            contextWindow: 128000,            maxTokens: 8192,          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/kimi-k2.5:cloud" },    },  },}

لاستخدام معرّف الموفّر المخصص ollama-cloud بدلًا من هذه البنية، راجع Ollama Cloud.

استخدم معرّفات موفّرين مخصصة عند تشغيل أكثر من خادم Ollama؛ إذ يحصل كل خادم على مضيف ونماذج ومصادقة ومهلة خاصة به.

{  models: {    providers: {      "ollama-fast": {        baseUrl: "http://mini.local:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [{ id: "gemma4", name: "gemma4", input: ["text"] }],      },      "ollama-large": {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 420,        contextWindow: 131072,        maxTokens: 16384,        models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }],      },    },  },  agents: {    defaults: {      model: {        primary: "ollama-fast/gemma4",        fallbacks: ["ollama-large/qwen3.5:27b"],      },    },  },}

يزيل OpenClaw بادئة الموفّر النشط (مع الرجوع إلى بادئة ollama/ المجردة) قبل استدعاء Ollama، ولذلك يصل ollama-large/qwen3.5:27b إلى Ollama بالصيغة qwen3.5:27b.

تتعامل بعض النماذج المحلية مع المطالبات البسيطة، لكنها تواجه صعوبة مع المجموعة الكاملة لأدوات الوكيل. قلّل الأدوات والسياق قبل تعديل إعدادات وقت التشغيل العامة:

{  agents: {    list: [      {        id: "local",        experimental: {          localModelLean: true,        },        model: { primary: "ollama/gemma4" },      },    ],  },  models: {    providers: {      ollama: {        baseUrl: "http://127.0.0.1:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [          {            id: "gemma4",            name: "gemma4",            input: ["text"],            params: { num_ctx: 32768 },            compat: { supportsTools: false },          },        ],      },    },  },}

استخدم compat.supportsTools: false فقط عندما يفشل النموذج أو الخادم بشكل موثوق مع مخططات الأدوات، إذ يستبدل ذلك بعض قدرات الوكيل بالاستقرار. يزيل localModelLean أدوات المتصفح وCron والرسائل وإنشاء الوسائط والصوت وPDF الثقيلة من السطح المباشر للوكيل ما لم تكن مطلوبة صراحةً، ويضع الكتالوجات الأكبر خلف البحث عن الأدوات. ولا يغيّر سياق وقت تشغيل Ollama أو وضع التفكير. استخدمه مع params.num_ctx وparams.thinking: false لنماذج التفكير الصغيرة المشابهة لـ Qwen التي تدخل في حلقات أو تستهلك ميزانيتها في الاستدلال المخفي.

اضبط api: "openai-completions" صراحةً لوكيل خلف /v1/chat/completions:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // default: true        apiKey: "ollama-local",        models: [...]      }    }  }}

قد لا يدعم هذا الوضع البث واستدعاء الأدوات في الوقت نفسه؛ وقد تحتاج إلى params: { streaming: false } في النموذج.

يحقن OpenClaw القيمة options.num_ctx افتراضيًا في هذا الوضع كي لا يرجع Ollama بصمت إلى سياق من 4096 رمزًا. إذا رفض وكيلك حقول options غير المعروفة، فعطّل ذلك:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: false,        apiKey: "ollama-local",        models: [...]      }    }  }}

بالنسبة إلى النماذج المكتشفة تلقائيًا، يستخدم OpenClaw نافذة السياق التي يبلّغ عنها /api/show، بما في ذلك قيم PARAMETER num_ctx الأكبر من ملفات Modelfile المخصصة؛ وإلا فإنه يرجع إلى نافذة سياق Ollama الافتراضية في OpenClaw.

تضبط contextWindow وcontextTokens وmaxTokens على مستوى الموفّر القيم الافتراضية لكل نموذج تابع لذلك الموفّر، ويمكن تجاوزها لكل نموذج. تمثل contextWindow ميزانية المطالبات وCompaction الخاصة بـ OpenClaw. تترك طلبات /api/chat الأصلية القيمة options.num_ctx غير مضبوطة ما لم تضبط params.num_ctx صراحةً، ولذلك يطبّق Ollama الإعداد الافتراضي الخاص بالنموذج أو OLLAMA_CONTEXT_LENGTH أو الإعداد المستند إلى VRAM؛ وتُتجاهل قيم params.num_ctx غير الصالحة أو الصفرية أو السالبة أو غير المحدودة. إذا كان إعداد قديم يستخدم contextWindow/maxTokens فقط لفرض سياق الطلب الأصلي، فشغّل openclaw doctor --fix لنسخها إلى params.num_ctx. ويستمر المحوّل المتوافق مع OpenAI في حقن options.num_ctx افتراضيًا من params.num_ctx أو contextWindow المُعدّة؛ عطّل ذلك باستخدام injectNumCtxForOpenAICompat: false إذا رفض المصدر الأعلى options.

تقبل إدخالات النماذج الأصلية أيضًا خيارات وقت تشغيل Ollama الشائعة ضمن params، وتُمرّر بصفتها options أصلية إلى /api/chat: وهي num_keep وseed وnum_predict وtop_k وtop_p وmin_p وtypical_p وrepeat_last_n وtemperature وrepeat_penalty وpresence_penalty وfrequency_penalty وstop وnum_batch وnum_gpu وmain_gpu وuse_mmap وnum_thread. وتُمرّر بعض المفاتيح (format وkeep_alive وtruncate وshift) كحقول طلب على المستوى الأعلى بدلًا من وضعها داخل options. لا يمرّر OpenClaw سوى مفاتيح طلب Ollama هذه، ولذلك لا تُرسل المعاملات الخاصة بوقت التشغيل فقط، مثل streaming، إلى Ollama مطلقًا. استخدم params.think (أو params.thinking) لضبط think على المستوى الأعلى؛ إذ تعطّل القيمة false التفكير على مستوى API لنماذج التفكير المشابهة لـ Qwen.

{  models: {    providers: {      ollama: {        contextWindow: 32768,        models: [          {            id: "llama3.3",            contextWindow: 131072,            maxTokens: 65536,            params: {              num_ctx: 32768,              temperature: 0.7,              top_p: 0.9,              thinking: false,            },          }        ]      }    }  }}

تعمل أيضًا agents.defaults.models["ollama/<model>"].params.num_ctx الخاصة بكل نموذج؛ ويفوز إدخال نموذج الموفّر الصريح إذا ضُبط كلاهما.

يمرّر OpenClaw التفكير كما يتوقعه Ollama: أي think على المستوى الأعلى، وليس options.think. تعرض النماذج المكتشفة تلقائيًا التي يبلّغ /api/show عن امتلاكها قدرة thinking الخيارات /think low و/think medium و/think high و/think max؛ بينما لا تعرض النماذج غير المفكّرة سوى /think off.

openclaw agent --model ollama/gemma4 --thinking offopenclaw agent --model ollama/gemma4 --thinking low

أو اضبط قيمة افتراضية للنموذج:

{  agents: {    defaults: {      models: {        "ollama/gemma4": {          thinking: "low",        },      },    },  },}

يمكن لإعدادَي params.think وparams.thinking الخاصَّين بكل نموذج تعطيل التفكير عبر API أو فرضه لنموذج معيّن. يحافظ OpenClaw على هذا الإعداد الصريح عندما لا يتضمن التشغيل النشط سوى القيمة الافتراضية الضمنية off؛ ومع ذلك، يظل أمر وقت التشغيل بقيمة غير off مثل /think medium متجاوزًا له. لا يُرسل طلب تفكير ذي قيمة صادقة مطلقًا إلى نموذج موسوم صراحةً بـ reasoning: false؛ بينما يُرسل طلب think: false دائمًا بصرف النظر عن ذلك.

تُعامل النماذج المسماة deepseek-r1 أو reasoning أو reason أو think على أنها قادرة على الاستدلال افتراضيًا — ولا يلزم أي إعداد إضافي:

ollama pull deepseek-r1:32b

يعمل Ollama محليًا ومجانًا، لذلك تكون جميع تكاليف النماذج 0 لكل من النماذج المكتشفة تلقائيًا والمحددة يدويًا.

يسجّل Plugin Ollama المضمّن موفّر تضمينات للذاكرة لاستخدامه في البحث في الذاكرة. ويستخدم عنوان URL الأساسي ومفتاح API المهيأين لـ Ollama، ويستدعي /api/embed، ويجمع عدة أجزاء من الذاكرة في طلب input واحد متى أمكن ذلك.

عندما يكون proxy.enabled=true، تستخدم طلبات التضمين الموجّهة إلى أصل local loopback المحلي للمضيف والمشتق بدقة من baseUrl المهيأ، المسار المباشر المحمي في OpenClaw بدلًا من الوكيل الأمامي المُدار. يجب أن يكون اسم المضيف المهيأ نفسه localhost أو عنوان IP حرفيًا للاسترجاع الحلقي — أما أسماء DNS التي لا تفعل سوى التحويل إلى عنوان استرجاع حلقي فتظل تستخدم مسار الوكيل المُدار. وتظل مضيفات Ollama الموجودة على الشبكة المحلية أو شبكة tailnet أو الشبكة الخاصة أو الشبكة العامة دائمًا على مسار الوكيل المُدار، كما أن عمليات إعادة التوجيه إلى مضيف أو منفذ آخر لا ترث الثقة. يوجّه proxy.loopbackMode: "proxy" حركة الاسترجاع الحلقي عبر الوكيل على أي حال؛ بينما يمنعها proxy.loopbackMode: "block" قبل الاتصال — راجع الوكيل المُدار.

تستخدم التضمينات في وقت الاستعلام بادئات الاسترجاع للنماذج التي تتطلبها أو توصي بها: nomic-embed-text وqwen3-embedding و mxbai-embed-large. وتظل دفعات المستندات دون تعديل، لذلك لا تحتاج الفهارس الحالية إلى ترحيل للتنسيق.

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Default for Ollama. Raise on larger hosts if reindexing is too slow.          nonBatchConcurrency: 1,        },      },    },  },}

عند استخدام مضيف بعيد للتضمينات، اجعل نطاق المصادقة مقتصرًا على ذلك المضيف:

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        model: "nomic-embed-text",        remote: {          baseUrl: "http://gpu-box.local:11434",          apiKey: "ollama-local",          nonBatchConcurrency: 2,        },      },    },  },}

يستخدم Ollama واجهة API الأصلية (/api/chat) افتراضيًا، وهي تدعم البث واستدعاء الأدوات معًا — ولا يلزم أي إعداد خاص.

بالنسبة إلى الطلبات الأصلية، يُمرَّر التحكم في التفكير مباشرةً: يرسل /think off وopenclaw agent --thinking off القيمة think: false في المستوى الأعلى، ما لم يكن params.think أو params.thinking مهيأً صراحةً؛ وترسل /think low|medium|high سلسلة مستوى الجهد المطابقة؛ بينما تُطابق /think max أعلى مستوى جهد في Ollama، وهو think: "high".

في WSL2 مع NVIDIA/CUDA، ينشئ مُثبّت Ollama الرسمي لنظام Linux وحدة systemd باسم ollama.service تحتوي على Restart=always. إذا بدأت هذه الخدمة تلقائيًا وحمّلت نموذجًا مدعومًا بوحدة معالجة رسومية أثناء إقلاع WSL2، فقد يحجز Ollama ذاكرة المضيف أثناء التحميل؛ ولا تستطيع آلية استرداد الذاكرة في Hyper-V دائمًا استعادة تلك الصفحات، مما قد يدفع Windows إلى إنهاء آلة WSL2 الافتراضية، ثم يعيد systemd تشغيل Ollama، وتتكرر الحلقة.

الدليل: عمليات إعادة تشغيل أو إنهاء متكررة لـ WSL2، واستخدام مرتفع لوحدة المعالجة المركزية في app.slice أو ollama.service مباشرةً بعد بدء WSL2، وإشارة SIGTERM من systemd بدلًا من أداة إنهاء العمليات عند نفاد الذاكرة في Linux.

يسجّل OpenClaw تحذيرًا عند بدء التشغيل عندما يكتشف WSL2، وأن ollama.service مفعّلة مع Restart=always، ووجود مؤشرات CUDA ظاهرة.

الإجراء التخفيفي:

sudo systemctl disable ollama

على جانب Windows، أضف ما يلي إلى %USERPROFILE%\.wslconfig، ثم شغّل wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

أو قلّل مدة إبقاء النموذج نشطًا، أو ابدأ Ollama يدويًا عند الحاجة فقط:

export OLLAMA_KEEP_ALIVE=5mollama serve

راجع ollama/ollama#11317.

تأكد من أن Ollama قيد التشغيل، وأن OLLAMA_API_KEY (أو ملف تعريف للمصادقة) مضبوط، وأن models.providers.ollama غير معرّف صراحةً:

ollama servecurl http://localhost:11434/api/tags

اسحب النموذج محليًا، أو عرّفه صراحةً في models.providers.ollama:

ollama list  # See what's installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

تحقّق من الجهاز وبيئة التشغيل نفسيهما اللذين يشغّلان Gateway:

openclaw gateway status --deepcurl http://ollama-host:11434/api/tags

الأسباب الشائعة:

• يشير baseUrl إلى localhost، لكن Gateway يعمل داخل Docker أو على مضيف آخر.
• يستخدم عنوان URL المسار /v1، مما يحدد السلوك المتوافق مع OpenAI بدلًا من سلوك Ollama الأصلي.
• يحتاج المضيف البعيد إلى تغييرات في جدار الحماية أو الربط بالشبكة المحلية.
• يوجد النموذج في الخدمة الخفية على حاسوبك المحمول، لكنه غير موجود في الخدمة البعيدة.

يكون الموفّر عادةً في وضع التوافق مع OpenAI، أو لا يستطيع النموذج معالجة مخططات الأدوات. يُفضّل استخدام الوضع الأصلي:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434",        api: "ollama",      },    },  },}

إذا استمر فشل نموذج محلي صغير في معالجة مخططات الأدوات، فاضبط compat.supportsTools: false في إدخال ذلك النموذج وأعد الاختبار.

تُعامل استجابات Kimi/GLM المستضافة التي تتكون من سلاسل طويلة من الرموز غير اللغوية على أنها استدعاء فاشل للموفّر بدلًا من رد ناجح، بحيث تتولى آليات إعادة المحاولة أو الانتقال الاحتياطي أو معالجة الأخطاء المعتادة المهمة بدلًا من حفظ نص تالف في الجلسة.

إذا تكرر ذلك، فالتقط اسم النموذج وملف الجلسة الحالي وما إذا كان التشغيل يستخدم Cloud + Local أو Cloud only، ثم جرّب جلسة جديدة ونموذجًا احتياطيًا:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --jsonopenclaw models set ollama/gemma4

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

{  models: {    providers: {      ollama: {        timeoutSeconds: 300,        models: [          {            id: "gemma4:26b",            name: "gemma4:26b",            params: { keep_alive: "15m" },          },        ],      },    },  },}

إذا كان المضيف نفسه بطيئًا في قبول الاتصالات، فإن timeoutSeconds تمدد أيضًا مهلة الاتصال المحمية لهذا الموفّر.

تعلن نماذج كثيرة عن سياقات أكبر مما يمكن لعتادك تشغيله بصورة مريحة. يستخدم Ollama الأصلي قيمة وقت التشغيل الافتراضية الخاصة به ما لم يُضبط params.num_ctx. ضع حدًا لكل من ميزانية OpenClaw وسياق طلب Ollama للحصول على زمن وصول متوقع لأول رمز:

{  models: {    providers: {      ollama: {        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            params: { num_ctx: 32768, thinking: false },          },        ],      },    },  },}

خفّض contextWindow إذا كان OpenClaw يرسل موجّهًا أكبر من اللازم. وخفّض params.num_ctx إذا كان سياق وقت تشغيل Ollama أكبر مما يستطيع الجهاز تحمّله. وخفّض maxTokens إذا استغرق التوليد وقتًا طويلًا جدًا.