Ollama

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

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

يتبع المزوّد المخصص الذي يحتوي على api: "ollama" القواعد نفسها. على سبيل المثال، يمكن لمزوّد ollama-remote موجّه إلى مضيف LAN خاص استخدام 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, // القيمة الافتراضية: 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، وتُمرَّر بوصفها /api/chat options أصلية: 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 هذه، ولذلك لا تُرسل إلى Ollama مطلقًا معاملات وقت التشغيل فقط مثل streaming. استخدم 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؛ ومع ذلك، يظل أمر وقت تشغيل غير معطّل مثل /think medium متجاوزًا له. لا يُرسل أبدًا طلب تفكير ذي قيمة صادقة إلى نموذج معلَّم صراحةً بالقيمة reasoning: false؛ بينما يُرسل طلب think: false دائمًا بصرف النظر عن ذلك.

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

ollama pull deepseek-r1:32b

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

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

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

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

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // القيمة الافتراضية لـ Ollama. ارفعها على المضيفات الأكبر إذا كانت إعادة الفهرسة بطيئة جدًا.          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  # اعرض النماذج المثبتةollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # أو نموذجًا آخر

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

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

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

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

يكون الموفّر عادةً في الوضع المتوافق مع 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 "أجب بالنص التالي فقط: 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 إذا استغرق التوليد وقتًا طويلًا جدًا.